# Zfl Reqdoc

> 独立的需求方案文档 skill。Use when the user wants to单独撰写需求方案、输出 `reqdoc.md`、`demo.html`、整理需求文档、生成可评审的 Markdown 需求稿和可交互原型，或提到 `zfl-reqdoc`、`需求撰写`、`需求文档`、`reqdoc.md`、`demo.html`。

- Skill: `zengfanling/zfl-reqdoc` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zengfanling/zfl-reqdoc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zengfanling/zfl-reqdoc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ZengFanling (https://skillmd.com/u/zengfanling)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zengfanling/zfl-reqdoc

---


# ZFL Reqdoc

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

## 产物

产出两个核心文件：

| 文件 | 用途 | 说明 |
|------|------|------|
| `reqdoc.md` | 结构化需求方案文档 | **主产物**，用于编辑、版本对比、文本协作、评审签字 |
| `demo.html` | 可交互 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端，移动端尺寸为375*812；PC端尺寸为 1440*1024
- 输出时要明显突出"该需求研发需要优先查看、重点注意、容易漏掉、阻塞开发、影响联调和验收"的内容，而不是把所有信息写成平均密度的平铺说明

## 生成顺序

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

## 文件命名规范

| 文档类型 | 命名格式 | 示例 |
|----------|----------|------|
| 需求方案 | `【需求文档】项目名-需求方案.md` | `【需求文档】麦宝知识后台-需求方案.md` |
| 交互原型 | `demo.html` | `demo.html`（一般放在项目根目录） |
| 流程图 | `【流程图】项目名-模块名.drawio` | `【流程图】麦宝知识后台-核心流程.drawio` |
| 截图 | `images/页面说明-视图名.png` | `images/知识类别配置-列表页.png` |
| 截图指引 | `images/README.md` | 列明每张截图的截取位置和保存文件名 |

## reqdoc.md 固定结构

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

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

### 文档头部

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

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

> **版本**：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` 截图指引文件

#### 页面与视图写法规范

```markdown
> **界面原型**：参考 `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. 数据描述务必具体：百分比标注绝对数量、时间标注到年-月-日 时:分、接口超时标注具体秒数