FinAgent 前端进度博客（六）｜站内使用说明书模块

系列说明：本系列按「首页 → 登录 → 各功能页」记录前端进度。本文为 第 6 篇：侧栏第六模块「使用说明书」与帮助文档产品化

日期：2026-06-08
模块：web → ManualPage / App.tsx 导航与路由 / styles.css

---

负责模块：前端与可视化（含帮助文档信息架构）

本周任务：在侧栏新增第六大模块「使用说明书」；将分散在 README、联调踩坑中的「第一次怎么用」收敛为可点击跳转的站内文档；与第 5 篇界面精简形成互补——页面内少说，说明集中在独立模块。

---

1. 背景与目标

第 5 篇完成报告阅读与界面精简后，各功能页顶栏、卡片下的 灰色说明文案被大量删除，界面更干净，但带来新问题：

• 新用户不知道先看哪：README 在仓库里，演示时老师/同学不会边用边翻 Markdown。
• 重复答疑：「摘要是空的算不算失败」「单股页下方有没有报告」「要不要去分析报告页才能看结果」「empty OHLCV 怎么办」——同类问题在联调中多次出现。
• 帮助文档与产品脱节：docs/guides/新成员-项目完整说明.md 面向开发者，缺少 已登录 Web 用户 视角的操作说明。

本次目标：

• 可发现：侧栏固定入口，与首页 / 单股 / 走势 / 报告 / 模拟交易并列，成为第六主模块。
• 可跳转：说明书内链到各路由（Link to="/single" 等），FAQ 覆盖真实踩坑。
• 可维护：纯前端静态页，不新增 API；说明内容集中在 /manual，不回流到各业务页标题下。

---

2. 改造概览

区域	本次升级
侧栏导航	新增第 6 项：/manual「使用说明书」，图标 ?
使用说明书页	ManualPage.tsx：Hero + 目录锚点 + 8 个章节卡片
章节内容	平台简介、快速开始、功能模块表、单股流程、读结果、报告与 PDF 说明、环境变量表、FAQ
站内跳转	功能模块表与正文使用 react-router-dom 的 Link
外链	/api/health、Swagger http://127.0.0.1:8000/docs（新标签打开）
样式	.manualPage、.manualToc、.manualFaq 等；titleIconManual；夜间目录链接 #93c5fd

---

3. 实现要点

3.1 信息架构：为什么放在侧栏第六项

主导航保持 业务模块优先（分析、看板、报告、交易），说明书放在最后：

• 不抢占主流程，但随时可查；
• 与第 5 篇删除的各页 homeSectionLead、副标题形成分工：页面内少说，说明书里说全；

未采用顶栏帮助按钮的原因：顶栏目前仅保留主题切换，56px 高度适合放全局控件；说明书内容较长，独立页面比下拉面板更合适。

3.2 ManualPage 结构

常量 SECTIONS 定义 8 节与锚点 id，顶部 <nav className="manualToc"> 渲染有序列表链接 #overview … #faq。

复用现有 UI 约定：

• 外层 container manualPage（最大宽度约 820px，便于长文阅读）；
• 每节 card manualSection + sectionTitle titleWithIcon titleIconManual；
• 列表 .manualList / .manualListOrdered，表格 .table manualTable，FAQ 用 <dl className="manualFaq">。

内部组件 ManualSection 统一包裹 id、title、children，避免八段重复 markup。

3.3 章节设计与 FAQ 来源

章节	要点
平台简介	LangGraph 流水线一句话、登录与 JWT、主题与个人中心入口
快速开始	.env → 启动 API / start-dev.bat → 5173 登录 → 单股分析
功能模块	五模块表格 + Link，明确各页职责
单股分析	代码格式、分析日期、进度与终止等操作说明（面向用户，非实现细节）
阅读分析结果	七 Tab 分工；强调 摘要 = RAG 记忆 非执行摘要；收盘 -- 说明
报告与 PDF	说明在单股页与报告页如何查看、导出（用户向指引）
环境配置	常用 .env 变量表，指向 config.py / README
常见问题	empty OHLCV、running 慢、401、摘要空、改 env 不生效

FAQ 条目来自联调真实反馈（含行情预检失败、.env 需重启 API 等），而非泛泛占位文案。

3.4 路由与导航接入（App.tsx）

{ to: '/manual', label: '使用说明书', icon: '?' }
<Route path="/manual" element={<ManualPage />} />

登录后与其他业务页相同，走 appShell 侧栏 + 顶栏布局；未登录用户仍跳转登录页，说明书不对匿名开放（与全站鉴权一致）。

3.5 样式与夜间模式

• titleIconManual::before { content: "?"; } 与系列 titleWithIcon 图标体系一致；
• 目录链接使用主题色，暗色下 .manualTocList a { color: #93c5fd; }；
• 正文 manualSectionBody 使用 var(--text-color)，与第 4、5 篇主题变量体系一致。

---

4. 涉及文件

文件	变更说明
web/src/pages/ManualPage.tsx	新增：站内使用说明书全文与目录锚点
web/src/App.tsx	侧栏第六项导航；路由 /manual
web/src/styles.css	manual* 系列样式；titleIconManual

---

5. 小结

本篇在界面精简（第 5 篇）之后补上 「帮助去哪里看」 的答案：侧栏第六模块「使用说明书」把快速开始、功能地图、读结果要点、环境变量与联调 FAQ 收进一个可锚点跳转的页面。整体策略是 主流程页面保持干净，说明文档产品化、可演示、可迭代，降低实训演示与同学自助上手的沟通成本。

---

（FinAgent 项目实训进度记录 · 使用说明书模块篇）