TRS系统-功能设计文档编写

Overview

本Skill指导用户编写符合企业级标准的TRS系统功能设计文档。基于企业顾问团队标准，融合GitHub热门PRD模板最佳实践。

核心原则： 证据优于断言，验证先于结论。

Output Contract（输出约定）

最终交付的文档至少满足下面“最小可用规格”（信息不足允许先以假设补齐，但必须显式标注“假设/待确认”）：

范围：In Scope / Out of Scope / Non-goals
用户与价值：用户画像、使用场景、成功指标（SMART + 基线值 + 目标值 + 衡量方法 + 时间周期）
业务与流程：现状流程、目标流程（含异常流程/回退/补偿）
功能拆分：功能列表、用户故事、每个故事的验收标准（Given/When/Then 或清单式）
详细设计：页面/接口/数据项（字段、控件、必填、值列表、级联、默认值、校验、报错）

接口契约写法规范（面向业务+开发双读者）：

功能设计文档不是技术接口文档，接口契约章节应避免原始JSON代码，建议按以下结构撰写：

操作总览表（7列）：序号 / 操作名称 / 说明 / 调用时机

每个操作：用途说明 + 字段含义表（不用JSON）+ 业务校验规则（用自然语言）

不展示：HTTP方法、URL路径、原始JSON响应、技术响应码

技术细节（接口路径、参数类型、错误码）由后端工程师按接口规范自行补充。

非功能需求：性能、权限与数据安全、审计与留痕、兼容性、监控与日志
风险与依赖：系统依赖、数据依赖、外设依赖（扫码枪/打印机/采集设备）、关键风险与缓解
发布与验收：试点/灰度、回滚、培训、数据迁移（如有）、验收与复盘

红线：不得用“应该/尽量/支持/优化”等模糊词代替可验证标准；关键声明必须给出验证方法或证据来源。

When to Use

使用场景：

| 场景 | 说明 | 触发关键词 | |------|------|-----------| | 传统需求沟通 | 用户口头描述需求，通过5W1H深度挖掘 | "我需要一个XX功能" | | 原型驱动（推荐） | 用户提供HTML/图片等原型，先理解原型再写PRD | "给你原型"、"看这个设计" | | 文档优化 | 优化或重构现有功能设计文档 | "优化文档"、"改版" | | 模板查询 | 询问文档模板或编写规范 | "模板"、"怎么写" |

不适用于：

纯技术实现方案（使用专门的技术设计skill）
架构设计文档（使用架构设计skill）

The Iron Law

未经验证的文档声称完整 = 作弊，不是效率

Core Workflow

本skill支持两种工作模式：传统需求沟通 和 原型驱动（推荐）。

模式A：传统需求沟通

digraph workflow {
    rankdir=TB;
    "确认输出格式" -> "问题定义" -> "深度需求挖掘" -> "引导编写" -> "质量检查" -> "优化建议";
    "质量检查" -> "通过?" [shape=diamond];
    "通过?" -> "优化建议" [label="否"];
    "通过?" -> "完成" [label="是"];
}

适用于用户口头描述业务需求，通过5W1H框架深度挖掘。

模式B：原型驱动（推荐）⭐

适用于用户提供HTML/图片/Figma等原型设计。

digraph workflow {
    rankdir=TB;
    "接收原型" -> "分析原型结构" -> "输出理解摘要" -> "用户确认" -> "补充业务细节" -> "编写PRD" -> "质量检查" -> "完成";
    "用户确认" -> "继续询问" [label="有疑问", style=dashed];
    "继续询问" -> "输出理解摘要";
}

详细说明 → 见 reference/prototype-driven.md

如何选择模式

| 条件 | 推荐模式 | |------|---------| | 用户提供了原型文件 | 原型驱动 | | 用户口头描述需求 | 传统需求沟通 | | 用户说"给你原型先看看" | 原型驱动 | | 用户问"PRD模板怎么写" | 传统需求沟通 |

Step 0: 识别工作模式

首先判断用户属于哪种场景：

场景1：用户提供原型

触发：用户提供了HTML/图片/Figma文件，或说"给你原型"
动作：直接进入原型驱动流程（见下方）

场景2：用户口头描述需求

触发：用户描述业务需求
动作：进入传统需求沟通流程（Step 0.5 → Step 1...）

PRD自检质控门（写作中实时评估）

在编写PRD的每个关键节点，AI主动触发自检评估。目标：写出清晰、无歧义、可执行的文档；识别自身无法填补的缺口，显式标注给产品经理。

触发时机

在完成以下章节后，自动触发自检，不必等用户提醒：

| 完成节点 | 触发时机 | |---------|---------| | 第2章用户与价值 | 用户画像/使用场景/成功指标写完后 | | 第3章业务背景与流程 | 现状流程/目标流程写完后 | | 第5章功能列表 | 功能清单全部列出后 | | 第7章详细设计 | 所有页面/接口/数据项写完后 | | 全文初稿 | 文档主体完成后、提交前 |

评估维度（5维度，各20分，满分100）

| 维度 | 评估问题 | 扣分触发条件 | |------|---------|------------| | ① 完整性 | 所有"最小可用规格"章节是否齐备？ | 任意必填章节缺失 → 该维度-10 | | ② 无歧义 | 字段描述、流程分支、状态值是否有二义性？ | 存在"可能"/"大概"/"视情况"等模糊词 → -5/处 | | ③ 可追踪 | 功能 → 验收标准 → 详细设计三者是否对齐？ | 功能在验收标准和详细设计中找不到对应项 → -10/处 | | ④ 一致性 | 跨章节字段名/状态值/操作名是否统一？ | 同名不同义或同义不同名 → -5/处 | | ⑤ 完整性-数据项 | 数据项表格的必输/新增/编辑列是否填写？值列表是否有来源？ | 任意行留空（"-"以外的空白）→ -5/行 |

评分等级

| 总分 | 等级 | 处置动作 | |------|------|---------| | 90-100 | 🟢 优秀 | 直接提交，可选标注"亮点章节" | | 70-89 | 🟡 良好 | AI自行修复所有"可自完善"项，修复后重评，剩余问题标注给PM | | 50-69 | 🟠 需改进 | 修复明显缺口，剩余问题全部写入"假设与待确认"表，告知PM | | < 50 | 🔴 不合格 | 先说明核心缺口在哪，列出补充方向，请PM提供信息后再继续 |

自完善 vs. 标注PM 的判断规则

AI自行修复（能修则修）：

字段描述歧义 → 用更精确的描述替换
字段名/状态值前后不一致 → 统一为最新出现的命名，并全局替换
数据项表格留空 → 联系上下文推断合理的默认值/校验规则，以假设形式补充并加注说明
缺少验收标准 → 根据功能描述自行推导3条Given/When/Then格式验收标准

必须标注PM（不能自填）：

涉及业务决策：如"优先级怎么定"、"由谁审批"、"超时阈值"
涉及外部依赖：第三方系统接口、数据来源不在团队内
涉及特殊权限：哪些角色能做/不能做未经明确授权的操作
业务规则无文档支撑：无法从上下文推断的数值/逻辑

标注格式（写入文档"假设与待确认"表）：

| 待确认项 | 章节 | 缺失原因 | 影响范围 | 优先级 |
|---------|------|---------|---------|--------|
| 优先级P0/P1/P2的划分标准是什么？ | 5.1功能列表 | 业务决策，需PM确认 | 影响开发排序 | 高 |
| 催收短信的发送频率上限？ | 7.4操作说明 | 外部合规要求，不在需求范围内 | 影响功能边界 | 中 |

质控门输出格式

每次自检完成后，在文档末尾追加质控报告（不删除历史报告，保留演进痕迹）：

## 质控报告（自动生成）

**自检时间：** YYYY-MM-DD HH:mm
**触发节点：** [章节名]
**评估总分：** X / 100（[等级]）
**本次自检修复：** [N] 项（详见下方列表）
**待PM确认：** [N] 项（已写入"假设与待确认"表）

#### 本次修复清单
- ① [修复项内容] → [修复方式]

#### 本次待确认清单
- ❓ [待确认问题] → [影响章节] → [优先级]

---

注意事项

质控门是写作者的内部质量动作，不替代PM的正式审阅
不要在质控报告中重复文档已有的内容，只报告缺口和修复结果
评分不是目的，让文档可执行才是目的；遇到拿不准的，宁可多标注、少猜测

快速开始：原型驱动流程

当用户提供原型时，按以下步骤执行：

快速流程图

接收原型 → 读取分析 → 输出理解摘要 → 用户确认 → 补充细节 → 编写PRD

Step P1: 接收并读取原型

读取规则：

HTML文件：读取完整源码（HTML+CSS+JS）
图片文件：描述看到的UI元素、布局、文字
标注：字段名、按钮文字、状态值、颜色含义

Step P2: 分析并输出理解摘要

必须输出的内容：

## 原型理解摘要

### 页面关系
（列出所有页面的跳转关系）

### 功能清单
（用表格列出识别到的功能点，标注确认状态）

### 不确定项
（原型无法确定的内容，用❓标记）

不理解的内容，必须标注❓，不得跳过

Step P3: 向用户确认

必须询问的问题：

业务背景：这套系统的业务目的是什么？
功能边界：原型中跳转/按钮的具体行为？
状态逻辑：状态变更后的处理逻辑？
异常处理：边界条件和错误情况？

询问原则：

优先问"会改变设计"的问题
每轮不超过5个问题
用开放式问题

Step P4: 补充业务细节

基于用户回答，补充：

成功指标
异常处理
集成关系
审计留痕

Step P5: 编写PRD文档

按照标准模板编写，标注来源：

原型已体现 → 标注"见原型"
询问补充 → 标注"用户确认"

Step 0: 确认输出格式（仅传统流程）

询问用户选择输出格式：

| 格式 | 适用场景 | 特点 | |------|---------|------| | Markdown格式 | 直接查看、GitHub展示 | 标准表格，简洁 | | Word友好格式 | 最终导出Word | 避免复杂嵌套 |

Step 0.5: 先收集“最小输入集”（避免空写）

在进入正文编写前，优先收集下面信息（缺少则记录为“假设 + 待确认问题”，并在相关章节引用）：

业务与边界：业务域/工厂/组织范围、涉及产品/物料范围、追溯粒度（批次/箱/件/序列号）、时间范围
主链路：正向/反向追溯链路、关键节点（采购/入库/生产/检验/包装/出库/客户）
数据与编码：批次/条码/序列号规则、标签打印与贴标规则、扫码采集点位与频率
系统集成：ERP/MES/WMS/QMS/PLM 的主数据与事件数据来源、接口方式（API/文件/消息）、责任方
合规与审计：审计留痕要求、记录保留年限、数据更正机制、权限与职责分离
目标与指标：召回演练时限（例如 X 分钟出具谱系与出货清单）、准确率/覆盖率/时效

Step 1: 问题定义与价值验证（V2.0新增）

使用5W1H框架深度挖掘：

Why (为什么)    → 业务背景、痛点、数据支撑
What (是什么)   → 核心问题、影响范围
Who (谁)        → 提出者、使用者、影响者
When (何时)     → 使用场景、频率、期望上线
Where (在哪里)  → 系统、设备
How (如何)      → 解决方案、替代方案

必问要素：

用户画像（角色、痛点、典型场景）
成功指标（符合SMART原则）
数据支撑（错误率、处理时间等）

Step 2: 深度需求挖掘

核心功能询问：

查询/新增/编辑/删除/导出/上传
每个子功能的字段、控件、校验

TRS系统领域补充（必须覆盖其一或明确“不适用”）：

追溯谱系（Lot Genealogy）：拆分/合并/转产/返工/报废的多对多关系与口径
召回与演练（Mock Recall）：影响范围计算、库存/在制/在途/已出货清单、证据包导出
质量放行/冻结：检验结论与状态流转、隔离区、解冻审批
条码/标签：码制、校验、打印模板、补打/作废、盘点与对账
审计留痕：谁在何时因何更改了什么（含前后值）、更正/冲销机制
集成与一致性：主数据、事件数据、幂等/重放、延迟与补偿

字段设计询问框架：

1. 字段名称？
2. 控件类型？（文本、下拉、日期、数值）
3. 必填？
4. 值列表来源？（取表/快码/手工）
5. 级联关系？（选A后B取什么）
6. 校验规则？（格式、长度、重复）
7. 报错信息？（明确字段+修改建议）

数据项表格规范（最佳实践）：

数据项表格必须使用以下11列格式，禁止简化列头：

| 序号 | 字段名 | 控件类型 | 数值类型 | 长度 | 必输 Y/N | 新增 Y/N | 编辑 Y/N | 值列表说明 | 默认值 | 校验规则 | 其他说明 |

字段类型命名规范（统一使用中文）：

| 数据库类型 | PRD写法 | 附加要求 | |-----------|--------|---------| | VARCHAR / NVARCHAR | 字符 | 必须标注长度，如：字符(200) | | INT / BIGINT | 整数 | 标注是否有范围，如：整数（≥0）| | DECIMAL / FLOAT | 小数 | 标注精度，如：小数（保留2位）| | DATE | 日期 | 必须注明格式，如：日期（YYYY-MM-DD）| | DATETIME / TIMESTAMP | 日期时间 | 必须注明格式，如：日期时间（YYYY-MM-DD HH:mm:ss）| | BOOLEAN / TINYINT(1) | 布尔 | 值列表写"是/否"或"Y/N" | | TEXT / CLOB | 长文本 | 注明长度上限（若有）|

新增 Y/N、编辑 Y/N 列的填写规则：

只读页面（详情页、查询结果页）：新增=N，编辑=N
新建表单：新增=Y，编辑=N
编辑表单：新增=N，编辑=Y（或 Y/灰显）
创建后不可改：新增=Y，编辑=N（备注：创建后只读）

界面流转图规范：

纯文字 ASCII 流转图仅用于草稿；正式文档必须使用 HTML 文件或截图
HTML流转图保存为独立文件（如 assets/flow-diagram.html），在文档中以引用形式注明
表格说明来源页面、目标页面、触发方式、备注（是否外部跳转、传参等）

Word导出字号规范（微软雅黑）：

| 样式 | 字号 | half-points | 字重 | 备注 | |------|------|------------|------|------| | H1 一级标题 | 18pt | 36 | 加粗 | 章节标题 | | H2 二级标题 | 14pt | 28 | 加粗 | 子章节标题 | | H3 三级标题 | 12pt | 24 | 加粗 | 详细小节 | | 正文内容 | 10pt | 20 | 常规 | 段落正文 | | 表格内容 | 小五（9pt） | 18 | 常规 | 表格内文字 | | 页眉/页脚 | 小五（9pt） | 18 | 常规 | 页眉/页脚 | | 说明：Word导出使用 reference.docx 模板（见 templates.md 模板10），Typora 导出 Word 时勾选"使用 pandoc 模板"并指定该文件路径 |

Word表格规范：

全包黑色框线（top/right/bottom/left/insideH/insideV 全部 SINGLE）
表头背景色：浅蓝（#D9E2F3）
参考模板：reference.docx（位于 skills 根目录，导出时指定路径即可）

Step 3: 引导编写

按照文档结构逐章引导：

章节 | 必填/可选 | 关键点
-----|----------|--------
1. 文档控制 | 必填 | 版本、审核、状态
2. 问题定义 | 必填 | 5W1H、用户画像
3. 业务背景 | 必填 | 四段式结构
4. 总体设计 | 必填 | 流程图、功能列表
5. 详细设计 | 必填 | 数据项、校验、交互
6. 非功能需求 | 建议 | 性能、安全、兼容
7. 发布计划 | 可选 | 上线、回滚、验收
8. 协作管理 | 可选 | 决策、变更、问题

详细章节结构 → 见 reference/document-structure.md

交互协议（建议遵循）：

先问再写：每轮提问不超过 10 个问题，优先问会改变设计分支的问题（范围、粒度、链路、编码、集成、审计）。
写的时候也标注不确定性：将缺失信息集中放入“假设与待确认（Assumptions & Open Questions）”表，并在相关章节引用。
验收优先：每个子功能至少 3 条验收标准；追溯/召回相关功能必须包含“可演练、可导出、可审计”的验收项。

硬约束（Must-Do，任何时候都不能跳过）

1) 假设表格式必须固定

关键点无法从用户话语/资料中确认时，输出“假设表”（表头固定、至少1行）：

| 假设ID | 假设内容 | 影响的章节/字段 | 待确认问题 | 风险等级（高/中/低） |
|--------|----------|------------------|------------|------------------|
| A-001  | ...       | ...               | ...        | 高/中/低         |

2) 值列表与校验不允许编造

对“值列表5要素”（取数来源/级联关系/默认规则/展示要求/支持搜索）与“校验3要素”（时机/条件/报错信息）：
- 若用户已明确：按用户内容写
- 若用户未明确：只能写“占位 + 假设 + 风险”，不得用泛化经验代替

3) 追溯领域补充项必须“覆盖其一/明确不适用”

追溯谱系、召回与演练、质量放行/冻结、条码/标签、审计留痕、集成与一致性中：
- 至少要命中 1 项，并把对应内容写进文档
- 若用户说“不涉及”，必须在相关段落写“明确不适用原因”

4) 输入门禁（阻断项）

在开始正文“详细设计”之前，必须至少确认下面 4 类信息中每类有 1 条可落地结论（允许为假设，但必须出现在假设表里）：
- 粒度：批次/箱/件/序列号（至少选其一）
- 链路：正向/反向中的关键节点（至少列出 2 个节点）
- 编码/取数：至少给出 1 个字段的“值列表取数来源规则/码制规则”
- 审计：是否需要留痕与更正/冲销机制（需要或明确不需要）

5) 输出门禁（完成度门禁）

文档可判定“可交付”的最小标准：
- 章节：1-7章必须出现；8章非功能需求与9章发布计划与验收必须出现（简版即可，显式标注“假设/待确认”）
- 复杂度：10章或11章至少保留其一
- 验收：每个子功能至少 3 条验收标准；追溯/召回子功能必须包含“可演练、可导出、可审计”
- 报错：不得出现“操作失败/请检查输入/数据错误”等模糊报错；必须给字段级报错模板

范围裁剪决策树（只裁剪“展开深度”，不裁剪“硬字段”）

根据用户确认的复杂度，把 8/9/10/11 的写法裁剪到以下档位之一：

A档（小型）：不涉及谱系拆分/合并、召回演练、审计更正/冲销、离线/弱网补传、跨多系统；仅需完成基本 CRUD 与字段级校验。

8/9：简版即可；10/11可不写

B档（中型）：涉及上述能力中的 1-2 项，或至少存在“值列表/校验/报错”以外的关键业务链路。

8/9：标准版；10建议写；11可选

C档（大型）：涉及上述能力中的 >=2 项，或明确跨 ERP/MES/WMS/QMS/PLM，多系统一致性/幂等/重放、或必须包含外设采集策略。

8/9：标准或更细；10/11至少写一个

最小问题集（MVP Questions）

为避免“问得不够但又硬写”，每次提问按下面最小集合执行：

Step 0.5（必问 6 项） 追溯粒度（批次/箱/件/序列号，至少1）、关键节点（>=2）、扫码点位与频率（>=1例）、码制/条码规则（允许待确认）、集成系统（或明确“不适用”）、审计留痕/更正机制（需要/不需要/待确认）

Step 1（必问 3 项） 核心问题（1-2句）、成功指标（>=2条，SMART+基线/目标/方法/周期）、用户画像（>=1角色+典型场景）

Step 2（必问 2 项） 追溯领域补充项（>=1命中/明确不适用）、至少1个关键字段的值列表取数来源规则

反失败纠偏脚本（针对用户施压短语）

当用户出现以下短语时，Agent 必须按脚本执行，禁止“听懂但跳过”：

“这功能简单/不用问”：
- 行为：仍执行 Step 0.5 + 选 1 个关键字段写值列表5要素（假设需标风险）
“时间紧/先写大概/后面补充”：
- 行为：只交“最小可交付骨架 + 验收 + 字段级报错占位”，其余写入假设表
“8/9不用写/非功能和发布计划先不写”：
- 行为：仍输出 8/9 简版（可验证要求+回滚/退出/成功指标检查），其余写入假设表
“跳过质量检查/不需要验收标准”：
- 行为：必须补齐验收（每子功能>=3）；否则停止要求补齐清单
“值列表不用那么详细/不用5要素”：
- 行为：仍写5要素；用户缺失则假设表标“高风险”
“值列表来源别问/你自己编一个”：
- 行为：不编造；值列表来源用占位写入假设表，并向用户确认“允许按假设继续”
“报错别写具体/随便一句”：
- 行为：必须改成字段级报错模板（字段名+修改建议）
“审计留痕不重要/不要考虑更正”：
- 行为：给出“留痕/更正是否需要”选项；坚持不做则审计章节写“明确不适用原因+风险等级”

Step 4: 质量检查

使用三段式验证：

1. 结构检查 → 章节完整、编号正确
2. 内容检查 → 字段完整、校验明确
3. 细节检查 → 报错信息、术语一致

检查清单 → 见 CHECKLIST_V2.0.md 追溯领域模板 → 见 reference/traceability-domain.md

Quick Reference

值列表5要素

| 要素 | 询问问题 | |------|---------| | 取数来源 | 取哪个表/快码？ | | 级联关系 | 选A后B取什么？ | | 默认规则 | 单值是否默认带出？ | | 展示要求 | 显示名称还是值？ | | 支持搜索 | 需要模糊搜索？ |

校验规则3要素

| 要素 | 示例 | |------|------| | 时机 | 保存时/实时/关闭时 | | 条件 | XX字段不允许为空 | | 报错 | "[XX]不能为空，请填写后保存" |

报错信息规范

✅ 正确： "[文件名称]不能为空，请填写后保存"
❌ 错误： "请填写完整信息"

✅ 正确： "[编码]已存在，请重新命名"
❌ 错误： "数据重复"

Anti-Patterns

常见错误 | 正确做法 ------------|----------- 直接开始写，不问需求 | 先用5W1H深度挖掘只写格式校验 | 包含时机+条件+报错模糊的报错信息 | 明确字段+修改建议忽略值列表的级联 | 明确"选A后B取什么" 忘记成功指标 | 用SMART原则量化把“追溯”当普通CRUD写 | 明确追溯粒度、谱系关系、多对多、拆分/合并/返工/报废只写功能点不写验收 | 每个子功能至少3条验收标准；追溯/召回必须“可演练、可导出、可审计” 忽略外设与现场采集 | 明确扫码点位、离线/弱网、补扫/补打、误扫处理

File Structure

追溯系统-功能设计文档编写/
├── SKILL.md                    # 主文件（加载此文件）
├── CHECKLIST_V2.0.md           # 质量检查清单
├── README.md                   # 使用说明
├── CHANGELOG.md                # 更新日志
├── VISUAL_README.html          # 可视化全览图（浏览器打开）
├── reference.docx              # Word导出模板（微软雅黑 + 全包框线）
└── reference/
    ├── templates.md            # 11个文档模板
    ├── prototype-driven.md     # ⭐原型驱动详细指南
    ├── traceability-domain.md  # 追溯领域专用模板
    ├── document-structure.md  # 各章节详细内容说明
    ├── examples.md            # 完整文档示例
    └── tools.md                # 10个实用工具

Additional Resources

原型驱动指南 → reference/prototype-driven.md ⭐
模板库 → reference/templates.md
工具集 → reference/tools.md
示例库 → reference/examples.md
章节详情 → reference/document-structure.md
追溯领域模板 → reference/traceability-domain.md
测试场景 → testing/pressure-scenarios.md

The Bottom Line

没有捷径可走。

深度询问 → 结构化编写 → 逐项检查 → 持续优化

这不是可选的"最佳实践"，这是最低标准。

Skill版本： 1.0 更新日期： 2026-04-11 说明： 首次公开发布版本（公测）