docs(问翻小宝): 设计静态帮助中心
This commit is contained in:
Script Generator
@@ -0,0 +1,168 @@
|
||||
# 问翻小宝第一阶段：静态帮助中心设计
|
||||
|
||||
## 背景
|
||||
|
||||
问翻小宝第一阶段用于解决新系统用户“不知道怎么用”的问题。它不是小宝预警的一部分，也不在第一阶段调用 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 自由分析系统数据。
|
||||
- 如果后续需要更强搜索，可引入本地全文索引或拼音匹配。
|
||||
Reference in New Issue
Block a user