Zfl Reqdoc

ZFL Reqdoc

这是一个独立的"需求方案文档" skill，负责把需求整理成 Markdown 需求文档 + 可交互 HTML 原型，便于编辑、评审、版本对比和浏览器直接查看操作。

产物

产出两个核心文件：

如果需求涉及界面截图或流程图，还建议产出：

• images/ 目录：存放从 demo.html 中截取的关键界面图，供 reqdoc.md 引用
• 【流程图】项目名-模块名.drawio：流程图文件（Draw.io 格式），供 reqdoc.md 引用

默认要求：

• reqdoc.md 是权威文档，文字描述应完整自洽，不依赖 demo.html 即可理解全部需求
• demo.html 应与 reqdoc.md 的数据、字段、文案严格一致，互为补充
• demo.html 应为自包含的单个/两个 HTML 文件，使用内联 CSS 和 JavaScript，无需外部依赖即可在浏览器中直接打开，区分移动端与PC端，移动端尺寸为375812；PC端尺寸为 14401024
• 输出时要明显突出"该需求研发需要优先查看、重点注意、容易漏掉、阻塞开发、影响联调和验收"的内容，而不是把所有信息写成平均密度的平铺说明

生成顺序

1. 先出 reqdoc.md：用 reqdoc.template.md 作为结构骨架，填入真实需求内容
2. 再出 demo.html：参照 reqdoc.md 的页面结构、字段、数据，生成可交互原型。如果是PC端，视觉风格引入 DESIGN_RULES_BUNDLE.md 中的 PC 端管理后台规范
3. 迭代同步：用户反馈后，优先修改 reqdoc.md，再同步更新 demo.html；涉及界面截图时，从 demo.html 截图保存到 images/ 目录

文件命名规范

reqdoc.md 固定结构

reqdoc.md 的内容结构固定为以下 8 个一级部分，顺序不要变：

1. 需求背景与目标
2. 需求范围
3. 需求详情
4. 功能开发事项
5. 验收标准
6. 风险与处理策略
7. 非功能需求
8. 待确认问题

文档头部

reqdoc.md 必须以版本信息头部开头：

# 项目名 功能需求方案文档

> **版本**：v1.0
> **日期**：YYYY-MM-DD
> **适用系统**：系统名称
> **需求来源**：来源说明
> **优先级**：功能A（P0）、功能B（P1）

> **demo链接**：`路径/demo.html`

1. 需求背景与目标

• 项目背景
• 业务目标
• 用户目标
• 本轮要解决的问题
• 不在本轮解决的问题（如有）

2. 需求范围

必须包含两部分：

• 需求清单 表格：需求名称、优先级、适用角色、关键用户旅程、是否本期必做
• 核心流程：流程说明

核心流程要求：

• 不推荐在 Markdown 中使用 ASCII 流程图（┌─┐│└┘ 等字符），因为不同编辑器/浏览器显示容易乱码
• 如果流程较复杂，推荐：
  • 用 Draw.io 绘制并保存为 【流程图】项目名-模块名.drawio，在文档中引用文件路径
  • 在文档中用文字概述流程的关键节点、分支和异常路径
• 只要能让读者快速看清主流程、分支、判断条件、异常路径和结束结果即可

3. 需求详情

这一部分必须 按需求范围逐项展开，并且要结合 UI 图一起说明。

优先规则：

• 如果用户提供了 MasterGo 交互图、页面图、截图、导出图或可读取链接，优先结合这些材料输出
• 如果当前环境不能直接读取 MasterGo 原稿，不要假装读过；要明确说明，并改用用户提供的截图、导出图、页面说明或 ui.md
• 如果已有 ui.md，要把 ui.md 中的页面结构、交互、状态说明一起合并进这一部分

每条需求详情至少说明：

• 对应需求项
• 适用角色与权限
• 触发入口（必须明确主入口和辅助入口）
• 页面与视图（引用 demo.html，预留截图占位）
• 交互步骤
• 关键状态（建议用表格）
• 业务规则
• 数据输入输出
• 异常或边界情况
• 开发必看（高亮块）
• 重点注意（高亮块）
• 风险提醒（高亮块）

触发入口写法规范

必须明确区分主入口和辅助入口，禁止模糊表述（如"本期先做A，B作为P1"）。

正确示例：

**入口 1 — 批量同步（本期主入口）**：列表顶部「xxx」按钮，支持多选后批量触发
**入口 2 — 单条同步（辅助入口）**：列表操作列「同步」按钮，方便快速单条触发

UI 图占位规范

• 在 reqdoc.md 中预留图片引用：![描述](images/截图名称.png)
• 截图文件名与需求章节对应，如：images/知识类别配置-列表页.png、images/知识类别配置-新增编辑弹窗.png
• 截图从 demo.html 中截取，保存到 images/ 目录
• 建议创建 images/README.md 截图指引文件

页面与视图写法规范

> **界面原型**：参考 `demo.html` → 点击左侧「xxx」菜单查看。以下为关键界面说明：

**xxx 页面**：

![xxx-列表页](images/xxx-列表页.png)

- 页面标题：
- 操作按钮：
- 列表字段：
  | 字段 | 说明 |
  |------|------|
  | ... | ... |

字段一致性要求

• 如果在需求详情中新增、拆分或修改了字段（如将"FastGPT 文件夹"拆分为"名称+地址"），必须同步检查并更新文档中所有引用该字段的位置
• 需要同步更新的位置包括：列表字段表、表单字段表、唯一性校验规则、业务规则、数据输入输出说明、交互步骤示例、后端接口说明、验收场景、风险描述、待确认问题
• 不允许在文档中出现同一字段前后描述不一致的情况

4. 功能开发事项

从产品方案视角整理给研发的开发关注点，用表格呈现：

• 前端开发事项
• 后端开发事项
• AI 开发事项（若为 AI 需求）
• 接口或数据依赖
• 状态管理或流程编排事项
• 埋点、日志、消息、通知、权限等补充事项

5. 验收标准

按需求项或流程节点列出，用表格呈现：

AI 需求可额外增加「AI 评测集」列。

6. 风险与处理策略

用表格呈现，至少包含：

• 需求理解风险
• 交互或流程风险
• 技术依赖风险（含 ECM/外部接口并发、超时等）
• 数据一致性风险
• 排期风险
• 对应处理策略

7. 非功能需求

用表格呈现，至少覆盖适用项：

• 性能（含接口超时时间、列表查询时间等具体数值）
• 安全
• 稳定性
• 易用性
• 可维护性
• 兼容性
• 可观测性

8. 待确认问题

用表格呈现，必须包含"确认结果"列：

待确认问题的迭代规则：

• 当问题得到答案后，必须在"确认结果"列标注 **已确认：xxx**
• 确认后，必须同步更新需求详情中受影响的章节（如确认"本期做批量同步"，需同步修改 3.x 触发入口的描述、开发必看块、接口设计说明等）
• 确认结果不是装饰，是推动文档迭代的信号

demo.html 原型规范

demo.html 是一个可交互的 HTML 原型文件，用于直观展示需求界面和交互流程。

设计规范来源

生成 demo.html 时，优先读取同目录下的 DESIGN_RULES_BUNDLE.md 作为视觉规范基础：

• 品牌色：#2C68FF（主色）、#1F54D9（hover）、#1842AD（active）
• 背景色：页面 #F7F9FD，卡片 #FFFFFF
• 边框色：#DDE5F0
• 文字色：主文本 #0F172A，次文本 #475569，弱文本 #94A3B8
• 状态色：成功 #16A34A，警告 #F59E0B，危险 #DC2626
• 信息密度：中高信息密度，正文字号 14px 为基准
• 风格底线：大面积白底、浅灰底、弱描边、中等圆角；偏理性、可信、克制、高效

结构与交互

• 自包含的单个 HTML 文件（内联 CSS + JS），无需外部依赖
• 左侧导航菜单，点击可切换不同功能页面
• 每个页面展示完整界面布局：顶部操作栏、搜索/筛选区、数据表格、分页
• 支持弹窗（Modal）、抽屉（Drawer）等交互组件
• 按钮和链接可点击，有基本交互反馈（弹窗打开、页面切换、toast 提示）
• 弹窗内表单需覆盖全量字段，展示两列布局等真实排版

数据与文案一致性

• 表格数据、表单字段、下拉选项与 reqdoc.md 严格一致
• 统计图表数据使用合理的示例数据，百分比必须同时标注具体数量（如：质量 46%（12个））
• 提示文案、确认框文案与需求文档一致
• 不使用 Lorem ipsum 等占位文本，用真实场景数据

与 reqdoc.md 联动

• 当需求发生变更（新增字段、调整交互入口、修改数据展示方式）时，同步更新 demo.html
• 当需求方案中预留了界面截图占位时，按占位要求从 demo.html 截取对应界面保存到 images/ 目录
• 在 reqdoc.md 的"页面与视图"小节标注"参考 demo.html → 某菜单/按钮查看"

与 ui.md 的关系

如果 ui.md 已存在，更新 reqdoc.md / demo.html 时要同步修正页面、交互、状态说明，避免几份文档内容冲突。

迭代与修改规则

需求文档从 v1.0 开始，用户反馈驱动迭代。每次迭代遵循以下规则：

1. 先改 reqdoc.md，再同步 demo.html
2. 修改字段时做全局一致性检查：确认所有引用该字段的位置已同步更新
3. 确认问题后联动更新：待确认问题获答复后，在确认结果列记录，并同步修改受影响章节
4. 版本号递增：每次正式修改后更新版本号和日期
5. 截图同步：界面变更后，重新从 demo.html 截图替换 images/ 中的旧图

推荐落地方式

1. 先以 reqdoc.template.md 为骨架写出 reqdoc.md 结构化正文
2. 同步生成 demo.html 可交互原型，引入 DESIGN_RULES_BUNDLE.md 视觉规范
3. 把当前项目的真实需求内容填进去，用真实数据而非占位符
4. 如果用户提供了品牌样式、公司规范、截图、MasterGo、ui.md，在不打乱 8 个一级章节顺序的前提下补充
5. 如果需求较复杂，允许在一级章节下增加二级分组，但不要改动一级章节名称
6. 在 reqdoc.md 中优先增加以下高亮区域：
   • 开发必看
   • 重点注意
   • 风险提醒
7. 高亮不是装饰，要承载真实信息，不能只写空话或重复正文
8. 同步创建 images/ 目录和截图指引文件
9. 如果流程复杂，同步创建 .drawio 流程图文件，避免在 Markdown 中写 ASCII 流程图
10. 数据描述务必具体：百分比标注绝对数量、时间标注到年-月-日 时:分、接口超时标注具体秒数