代码转需求文档

概述

Overview

本技能将"从已实现系统与依据性材料反推需求规格说明书"的写作流程标准化。其核心方法：

• 代码仓库是"实际怎么做"的直接来源——前端页面承载交互、字段与校验，后端接口/状态机/定时任务承载真正的业务规则；
• 示例文件（政策指引、旧版规格书、原型稿）是"应该怎么做"与文档形态的依据；
• 将两者比对、消除分歧后，按统一骨架组织文档，全程用业务语言撰写，产出结构完整、可导航的 Word(.docx) 规格说明书。

多轮迭代（内容细化、补流程图、产品化改写、版本合并）均发生在同一流程内，按 8 步工作流执行。

工作流程（8 步）

第 0 步：明确任务范围

动手前先确定：

• 新建文档还是迭代已有版本（迭代时版本号递增，沿用上一版格式与章节风格）；
• 覆盖范围：全系统、某个子系统还是单模块；
• 交付口径：默认"产品经理视角"（见 references/writing-guide.md），除非用户明确要偏工程的交付物；
• 目标读者：业务/产品评审方，还是研发实现方——决定技术细节的保留程度。

第 1 步：代码勘察（快而全）

前端与后端同时并行勘察，产出"模块素材卡"。加载 references/collection-workbook.md 使用其中的清单与模板。

前端勘察点（人机交互、字段、状态展示的直接来源）：

• 由路由/菜单/权限文件得到页面清单与入口路径，划分功能模块；
• 逐个查看列表页：查询/筛选条件、表格列、分页、操作按钮及各自的禁用/触发条件；
• 查看表单页/弹窗：字段类型、必填项、长度/格式/唯一性校验、上传限制（数量/格式/大小）、级联或默认值；
• 查看详情页与状态化视图：状态不同时展示差异、可见操作项；
• 记录关键提示文案与异常提示。

后端勘察点（业务规则与边界的真正来源，需找到对应后端工程/包，前端接口前缀可指引定位）：

• Controller 端点与权限标识 → 功能点清单、可用角色；
• 枚举/常量定义 → 业务状态全集、取值范围；
• Service 核心方法 → 校验规则、默认值、唯一性约束、状态迁移触发条件与前置限制、自动联动；
• 定时任务/消息 → 系统自动行为及其触发时机；
• 生成物（证书/报表/PDF/导出）的内容构成。

第 2 步：示例文件解析

• Word 政策/指引/旧版规格书：用 docx 技能或 python-docx/pandoc 抽取正文，提炼与系统相关的业务规定；
• 原型稿（墨刀导出 JSON/HTML）：还原页面清单、字段与交互顺序；
• 旧版规格书：重点提取章节组织、标题编号风格、撰写口径，识别其中"留空待补"的框架章节——这些通常就是本次要填充的目标位置。

第 3 步：三源比对与分歧处理

用三源比对表列出每个功能在"代码实现 / 示例文件要求 / 旧文档表述"下的差异，逐条给出处理结论：

• 示例文件（政策/规范）有明确业务规定的，优先作为"应然"写入业务规则，与代码不符处在文中或修订记录中标注差异原因；
• 代码独有而材料未提及的功能，按代码提炼后补入；
• 仍存疑的列"待用户确认"，写完后集中向用户提问，不阻塞主流程。

第 4 步：搭建文档骨架

加载 references/outline-template.md，按模板生成完整大纲（封面、修订记录、文档介绍、系统概述、功能性需求分章、非功能性需求、附录），把第 1~3 步的功能清单挂到各章各节下，形成"骨架 + 填充点"的写作底稿。

第 5 步：撰写正文（产品经理视角）

严格按 references/writing-guide.md 的口径写作：

• 每个功能节按"业务总体描述 → 功能描述（字段/筛选用表格）→ 业务规则 → 异常场景 → 权限说明"组织；
• 讲业务不讲实现：不出现接口名、字段英文名、表名、字典编码、状态码、框架名、定时任务实现细节；
• 描述系统自动行为时补齐"触发时机 + 处理结果 + 限制条件"。

第 6 步：绘制业务流程图

• 需要配图的位置：总体业务流程、核心业务状态机、多类型差异流程、长链条异常处理流程；
• 用 Mermaid 编写（flowchart / stateDiagram-v2），代码围栏 mermaid 包裹；
• Word 交付时以"等宽字体 + 浅灰底纹"代码块形式嵌入，图前加粗图注（如"【图 2-1】总体业务流程（Mermaid 代码）"），方便在支持 Mermaid 的工具中渲染查看。

第 7 步：生成 Word(.docx)

按 references/word-delivery.md 生成：封面、修订记录、Heading 1/2/3 层级使用 Word 内建样式（保证导航窗格可用）、统一表格样式。可先在 Markdown 组织正文，定稿后再转 Word。

第 8 步：校验与迭代

• 结构校验：章节完整、标题层级连续、表格内容非空、无孤儿图片资源；
• 内容校验：全文无实现词残留（用 references/writing-guide.md 的自检清单逐条核对），字段表与代码一致；
• 交付后收集用户反馈，按需回跳至对应步骤修改并递增版本号，重复执行直到定稿。

Bundled Resources

本技能的可复用资料按需加载：

• references/collection-workbook.md —— 模块素材卡、前后端勘察清单、三源比对表与各表格模板。第 1~3 步使用。
• references/outline-template.md —— 完整章节骨架模板（封面/修订记录/文档介绍/系统概述/功能性需求/非功能性需求/附录）。第 4 步使用。
• references/writing-guide.md —— 产品视角写作口径、"实现表达 → 业务表达"改写对照表与交付前自检清单。第 5、8 步使用。
• references/word-delivery.md —— docx 生成规范（结构要求、流程图嵌入方式、docx 库已知坑、结构性/内容性校验方法）。第 7、8 步使用。

协作技能

• 生成/解析 Word 时配合 docx 技能使用；
• 需要 PDF 材料时配合 pdf 技能使用；
• 大规模代码勘察（模块多、文件多）时可用 code-explorer 子代理分模块并行摸底，再回主流程做定向精读。