# 问翻小宝第一阶段：静态帮助中心设计

## 背景

问翻小宝第一阶段用于解决新系统用户“不知道怎么用”的问题。它不是小宝预警的一部分，也不在第一阶段调用 AI 分析业务数据。所有答案来自内置静态帮助包，避免浪费 AI token，并保证操作说明稳定、可复查。

## 目标

- 在问翻小宝对话页中，根据用户输入关键词返回系统使用帮助。
- 帮助内容覆盖产品、项目、版本、需求池、调研、产品方案、AI 拆解、UI 设计、开发任务、测试用例、Bug、日志记录。
- 每篇帮助文章包含适用场景、入口路径、操作步骤、必填字段、状态流转、注意事项和真实页面配图。
- 配图通过打开本地系统页面截图生成，保存为静态图片资源。
- 第一阶段不调用 AI，不消耗模型 token。

## 非目标

- 不做 AI 自由问答。
- 不分析用户当前业务数据。
- 不做后台帮助文章维护。
- 不做移动端适配。
- 不让 AI 生成示意图，配图必须来自真实本地页面截图。

## 内容范围

第一批内置 12 篇帮助文章：

1. 产品：新建产品、产品字段、产品作为顶层容器的作用。
2. 项目：新建项目、项目归属产品、项目与版本/需求的关系。
3. 版本：新建版本、必填字段、版本号、预期发布日期、成员、版本状态。
4. 需求池：新建需求、需求字段、需求采纳、需求状态含义。
5. 版本纳入需求：从需求池把已采纳需求关联到版本。
6. 调研：创建调研计划、管理方向/进度、完成条件。
7. 产品方案：创建产品方案、关联需求覆盖、提交成果链接。
8. AI 拆解：入口、触发条件、开发任务拆解、测试用例拆解、采纳草稿。
9. UI 设计：创建 UI 设计计划、管理进度、提交成果。
10. 开发任务：新建任务、必填字段、领取与计划、开发中、自测、提测。
11. 测试用例与 Bug：新建测试用例、开始测试、通过/失败/阻塞、从失败用例创建 Bug、Bug 状态流转。
12. 日志记录：系统自动记录哪些行为、在哪里查看、活动记录和计划日志的区别。

## 帮助文章数据结构

帮助文章使用前端内置静态 TypeScript 数据：

```ts
export type HelpArticle = {
  id: string;
  title: string;
  category: string;
  keywords: string[];
  scenario: string;
  entry: string;
  steps: string[];
  requiredFields: string[];
  statusFlow: string[];
  notes: string[];
  images: HelpImage[];
  relatedIds: string[];
};

export type HelpImage = {
  src: string;
  alt: string;
  caption: string;
};
```

建议文件：

- `apps/web/lib/wenfan-help-articles.ts`：文章内容。
- `apps/web/lib/wenfan-help-search.ts`：关键词搜索和排序。
- `apps/web/lib/wenfan-help-search.test.ts`：关键词命中测试。
- `public/help/wenfan-xiaobao/`：帮助截图资源。

## 关键词触发设计

搜索只在本地执行。用户输入后按命中分数排序，返回最高分文章。

匹配信号：

- 标题命中：最高权重。
- 关键词命中：高权重。
- 类目命中：中高权重。
- 步骤、字段、注意事项命中：中权重。
- 相关模块命中：低权重，用于补充相关帮助。

关键词要做得厚一些，每篇文章至少包含这些类型：

- 模块词：产品、项目、版本、需求池、开发任务、测试用例、Bug。
- 动作词：新建、创建、编辑、采纳、关联、纳入、领取、开始、提测、提交、失败、通过、阻塞。
- 口语问法：怎么建、在哪建、怎么填、要填什么、怎么进入版本、怎么提 Bug、怎么提测。
- 同义词：采纳/通过，纳入/关联/加入版本，提测/提交测试，产品方案/原型/成果链接。
- 常见误写：bug、BUG、Bug，AI拆解、ai拆解、任务拆解。

未命中时不调用 AI，而是返回可点击的问题分类和示例问题。

## 对话展示设计

命中文章后，聊天区展示：

1. 标题。
2. 一句话适用场景。
3. 入口路径。
4. 操作步骤。
5. 必填字段。
6. 状态流转。
7. 注意事项。
8. 配图。
9. 相关帮助按钮。

回复文案以“帮助文章内容”为准，不生成开放式推理答案。第一阶段可以保留静态模拟对话，但发送后应能用本地搜索结果替换回复内容。

## 配图设计

配图来自真实本地页面截图：

- 使用本地开发服务打开对应页面。
- 用截图脚本生成桌面尺寸截图。
- 保存到 `public/help/wenfan-xiaobao/`。
- 文章通过相对路径引用图片。

建议新增脚本：

- `apps/web/scripts/capture-wenfan-help-screenshots.mjs`

脚本职责：

- 打开指定路由。
- 等待页面稳定。
- 截图保存。
- 后续可扩展为按选择器截关键区域。

第一阶段截图可以先覆盖关键页面和入口位置，不要求把每个弹窗里的每个字段都逐个截图；文章步骤里说明字段，截图负责帮助用户定位入口和页面区域。

## 数据流

```text
用户输入
  -> normalizeQuery
  -> searchHelpArticles
  -> 命中文章
  -> 渲染帮助答案
  -> 展示相关帮助
```

没有后端调用，没有 AI 调用，没有业务数据写入。

## 组件划分

- `WenfanXiaobaoPage`：页面容器、历史列表、对话区、输入框。
- `HelpAnswer`：渲染一篇帮助文章。
- `HelpRelatedActions`：渲染相关帮助按钮。
- `wenfan-help-search.ts`：纯函数搜索。
- `wenfan-help-articles.ts`：静态知识包。

## 验证计划

- 单元测试：关键词命中应返回正确文章。
- 单元测试：同义词和口语问法可命中对应文章。
- 单元测试：未命中时返回空结果或默认建议。
- 类型检查：`pnpm --filter web type-check`。
- Web 检查：`curl http://localhost:3000/wenfan-xiaobao` 返回 200。
- 截图脚本：确认能生成至少一张帮助图片。

## 后续扩展

- 如果帮助内容频繁变更，再做后台可维护帮助文章。
- 如果静态搜索覆盖不足，再考虑接入轻量 AI 仅用于“改写已命中文章”，但不让 AI 自由分析系统数据。
- 如果后续需要更强搜索，可引入本地全文索引或拼音匹配。