source-to-product-doc

name	source-to-product-doc
description	从全栈项目源码梳理业务能力并生成面向运营、商户运营和产品人员的 Markdown 产品文档。用户要求阅读源码、反推产品逻辑、编写运营手册或产品说明书时使用；适用于含前端、后端、数据库、异步任务、配置或既有文档的仓库。

源码生成产品文档

将代码实现转换为可供业务人员阅读的产品说明。优先保证规则真实、范围明确；不要将目录、接口或推测包装成产品能力。

输出与范围

• 默认输出简体中文 Markdown；遵循用户指定的语言、读者、文件位置和范围。
• 默认读者是运营、商户运营和产品人员。说明“谁能做什么、满足什么条件、结果如何”。
• 输出当前实现说明，不替代需求规格、接口文档或发布说明。
• 不在正文展示路由、控制器、表名、接口参数或源码路径，除非用户明确要求技术附录。
• 无法确认是否对外开放的功能不是已上线能力。

事实表达规则

先为每条重要结论判断证据类型，再选择措辞。不要将实现意图、默认值或偶发分支写成绝对产品规则。

• 硬性约束：只有服务端校验、数据库约束或不可绕过的状态机明确阻止某操作时，才使用“仅可”“必须”“不可”等绝对措辞。
• 条件行为：代码存在阈值、格式、开关、配置或分支时，必须写出触发条件。例如写“图片超过尺寸/体积阈值时会压缩”，不要写“上传时自动压缩”。
• 初始化不变量：启动、认证或任务入口会自动补齐的数据（例如系统默认分类）应写为初始化机制；不要把正常用户路径不可达的缺失状态写成运营异常边界。
• 前台能力与底层可能性：区分“当前后台没有提供某入口”与“系统绝不支持”。数据模型或内部接口存在但前台未开放时，不将其描述为正式产品能力或绝对限制。
• 大模型与外部输出：提示词、模型建议或第三方返回不是业务保证。写“系统要求模型/尝试提取……，结果需人工复核”；只有经本系统校验并保存的字段，才能写成“系统保存/展示”。
• 默认与配置覆盖：环境默认值、可配置项和线上实际值分别表述。存在配置入口时写“默认……，可配置为……”，不要把默认供应商或模型写成唯一实现。

工作流

1. 盘点仓库

先执行定向、只读的盘点。识别：

• 应用与端：前台、管理后台、移动端、小程序、服务端、worker。
• 入口与导航：页面注册、路由、菜单、权限守卫、功能开关。
• 业务实现：API 路由、服务/控制器、模型、迁移或 schema、事件与消息。
• 异步和外部依赖：定时任务、队列、回调、支付、物流、通知、第三方身份服务。
• 现有 README、产品文档、测试及仓库内指令。

按业务能力而非目录命名候选业务域，并列出每域涉及的角色、端、主要流程和共享能力。此阶段只输出简短盘点与候选清单，不得开始正式产品文档。

2. 确认大纲与事实边界

为候选业务域给出一级、二级大纲；标明每域的角色、端和依赖。先向用户集中提出少量阻塞问题，并等待答复，出现以下任一情况时不要继续定稿：

• 代码、测试、配置或已有文档对范围、规则或状态描述冲突。
• 页面、路由或接口可达，但无法确认是否对外开放、灰度或遗留。
• 金额、时限、权限、状态值或外部系统返回值没有足够业务语义。
• 用户指定范围与仓库实际功能不一致。

问题必须说明冲突的业务含义、可选范围与需要用户确认的决定；不要用“待确认”代替必须回答的问题。

3. 分域核验

对确认后的每个业务域单独阅读，按以下链路交叉验证：

用户/后台动作 → 权限与前置条件 → 服务端校验 → 数据或状态变化 → 任务、回调或通知 → 可见结果

• 先读该域的入口与调用链，再读服务端和数据层；不要从单个页面或 API 推断完整规则。
• 对订单、审批、售后、库存、支付等状态机，至少确认触发条件、状态出口、异常/超时路径与操作者。
• 对资金、时间、库存和权限规则，确认数值/条件来自代码或配置；配置值无业务含义时提问。
• 对图片处理、默认数据、模型识别和第三方服务，按“事实表达规则”复核每个绝对词和每个异常边界。
• 一个业务域完成后，压缩为“已确认的业务结论 + 仍需确认项”，再进入下一域；不要持续携带原始代码细节。

4. 跨域一致性检查

在最终成文前，单独对照共享能力：角色与数据可见性、账号/认证、支付/结算、库存、通知、状态命名、定时任务和外部回调。统一术语，消除重复，确保一个模块的结论不与另一模块冲突。

5. 成文

在所有阻塞问题解决后，读取 产品文档模板，按项目实际能力裁剪章节并写入正式文档。

• 只写已确认或可由完整调用链验证的规则。
• 使用业务语言解释限制和结果；必要时以表格呈现角色差异、状态流转、时间窗口和规则对比。
• 省略无对应实现的章节；不把空目录、孤立接口或注释当作产品功能。
• 外部系统仅描述本项目调用所实现的行为和限制，不推测第三方承诺、后台配置或线上开通状态。

大型仓库策略

满足任一条件时强制按“盘点 → 大纲确认 → 分域核验 → 跨域汇总 → 成文”执行：多个应用、至少四个主要业务域、复杂异步流程，或预估文档超过约 30 页。

小型仓库可以合并盘点与大纲阶段，但仍必须先确认范围与冲突。不要一次读取全部源码后直接写长文。

交付前检查

• 产品范围、角色和业务域均已明确。
• 每个核心流程包含前置条件、主路径、结果和关键限制。
• 每个关键状态表包含状态、触发、操作者和异常/超时出口。
• 资金、时间、库存、权限与外部依赖的结论没有越过可验证证据。
• 所有“仅/必须/不可/自动/始终”等绝对词均有硬性约束证据；所有条件行为均写明条件。
• 大模型规则区分“提示或尝试”和“已校验、已保存的结果”；默认值与可配置值均未混写。
• 初始化机制不被误写成普通运营异常，前台能力不被误写成底层绝对限制。
• 代码/文档冲突、灰度范围和缺失业务语义均已由用户确认。