需求规范

创建人员：Codex
文件职责：定义通用需求文档写法、需求审核流程、需求进入编码阶段的条件。
管理规范/模板：../../全局规范.md；需求规范.md；需求审核规范.md；需求文档范本.md。
引用文件：需求规范.md；需求审核规范.md；需求文档范本.md；../dev-doc/编码规范.md。
记录方式：全局需求写作规范；需求写法、需求审核流程或进入编码阶段的条件变化时更新。

统一依赖：本规范必须同时遵守 ../../全局规范.md 和 ../project-doc/项目规范.md；项目本地需求规范可补充流程，但不得违反全局规范、全局项目规范和本体系硬约束。

1. 目标

本规范用于约束管理体系下多个项目的需求文档写法。

需求文档的核心目标：

1. 说清楚要做什么。
2. 说清楚不做什么。
3. 说清楚输入、输出、流程、边界、验收。
4. 让代码实现者能按文档实现。
5. 让审核员能判断文档是否清楚、是否能进入编码阶段。

需求文档不是用来堆细节、堆 gate、堆校验项的。它要服务实现和验收，不能为了“看起来严谨”把模块设计得过重。

2. 适用范围

适用于：

1. 小工具需求。
2. 辅助脚本需求。
3. 单模块需求。
4. 多模块系统需求。
5. 数据处理需求。
6. 实验工具需求。
7. 校验、审计、归档辅助工具需求。

不适用于纯方法论文章、研究笔记、讨论记录。研究笔记如果要进入代码实现，必须整理成需求文档。

3. 总原则

3.1 需求必须准确

需求必须明确：

1. 目标。
2. 输入。
3. 输出。
4. 处理流程。
5. 边界。
6. 验收标准。

不允许用“自行判断”“大概”“尽量”“后续再说”作为正式需求口径。

3.2 不确定内容不得伪装成正式需求

如果需求还不确定，必须写成：

1. 待确认项。
2. 暂不实现项。
3. 后续实验项。
4. 仅供参考项。

不得把未确认内容写成实现必须遵守的正式规则。

3.3 一份需求只表达一个主对象

一般按一个模块、一类工具、一个流程或一个明确事项写一份需求。

不得在一份需求里混写多个互相独立的系统，导致实现者无法判断主位。

3.4 不要层层加码

需求文档必须避免以下问题：

1. 把诊断项写成主流程硬 gate。
2. 把发布级审计写进小样本或工具需求。
3. 把可选校验写成必过阻断。
4. 把建议项写成实现项。
5. 把边角料问题升级成核心需求。
6. 为了防所有可能错误而把模块设计得过重。

校验只服务核心正确性。复杂校验应优先放到只读 helper、审计报告或后续专项验收，不应默认卡住主流程。

3.5 审核通过才算需求完成

需求文档写完不等于完成。

需求必须经审核员审核通过，才算完成；审核不通过时必须修改需求文档，直到审核员确认目标、边界、接口、验收都清楚。

4. 两类需求流程

需求按规模分两类处理，不要把所有需求都套进重流程。

需求文档进入审核前，必须先判断上游需求流程：

1. 大量需求修改：必须先有需求方案文档，且需求审核通过。
2. 少量需求修改：可以直接改需求文档，但必须记录修改背景和一致性检查结论。
3. 第一版复杂需求交付：必须先有架构文档、模块说明文档、核心流程文档，且需求审核通过。
4. 第一版轻量需求交付：可以直接进入需求文档书写流程。

如果对应上游文档不存在，需求文档必须说明“不适用”和原因，不能假装已经参考。

4.1 小需求 / 工具需求流程

适用范围：

1. 小工具。
2. 一次性辅助脚本。
3. 文件整理、转换、统计、检查。
4. 只读 helper。
5. 单一输入、单一输出、无复杂状态流转的轻量模块。
6. 不影响正式主流程、不写核心业务主表、不改变公共合同的局部需求。

这类需求可以写得轻，但必须清楚。

流程：

1. 写清需求目标。
2. 写清输入路径、输入格式、关键字段。
3. 写清输出路径、输出格式、关键字段。
4. 写清处理规则。
5. 写清不做事项。
6. 写清最小验收方式。
7. 交审核员审核。
8. 审核员通过后，需求结束。
9. 审核不通过，按审核意见修改，再重新审核。

小需求最低内容：

1. 背景和目标。
2. 输入。
3. 输出。
4. 处理规则。
5. 边界和不做事项。
6. 验收方式。
7. 审核状态。

小需求不强制包含：

1. 完整架构图。
2. 完整状态机。
3. 复杂 manifest / receipt / fingerprint。
4. 发布级 gate。
5. 性能优化方案。
6. 重型数据校验方案。

除非这些内容确实是该工具正确运行的必要条件。

4.2 正式 / 系统需求流程

适用范围：

1. 新增系统模块。
2. 多模块流程。
3. 长流程调度。
4. 正式数据链路。
5. 会被多个项目或多个模块复用的公共能力。
6. 会进入编码方案的重型实现需求。
7. 会影响正式结果、归档结果、业务结论或外部交付的需求。

流程：

1. 写清背景、目标和主流程。
2. 拆清模块职责和上下游边界。
3. 写清输入、输出、字段、状态、错误处理。
4. 写清核心处理流程和不做事项。
5. 写清验收标准，区分主流程必过项和外部诊断项。
6. 对照需求方案或三大文档做一致性检查。
7. 检查需求之间是否存在冲突或重复定义。
8. 交审核员审核。
9. 审核员通过后，需求完成。
10. 若进入重型编码实现，后续必须按 common/dev-doc/编码规范.md 先写代码编写方案，并再次经审核员审核通过后才能编码。

正式需求最低内容：

1. 文档目标。
2. 背景和设计意图。
3. 模块职责。
4. 输入合同。
5. 输出合同。
6. 核心处理流程。
7. 边界与不做事项。
8. 异常和失败处理。
9. 验收标准。
10. 与上下游文档的一致性说明。
11. 审核状态。

5. 标准结构

需求文档建议按以下结构书写。

5.1 小需求 / 工具需求结构

1. 文档目标。
2. 使用场景。
3. 输入。
4. 输出。
5. 处理规则。
6. 不做事项。
7. 验收方式。
8. 审核记录。

5.2 正式 / 系统需求结构

1. 文档目标。
2. 背景和问题。
3. Design Intent。
4. 模块职责。
5. 上下游关系。
6. 输入合同。
7. 输出合同。
8. 核心处理流程。
9. 状态、枚举、错误码。
10. 边界与不做事项。
11. 数据校验与验收。
12. 重跑、恢复、归档。
13. 一致性检查。
14. 审核记录。

不是所有正式需求都必须写满每个章节。如果某章节不适用，可以写“不适用，原因是……”。不要为了形式填充无价值内容。

6. Design Intent 规则

复杂需求应包含 Design Intent。

Design Intent 只解释：

1. 为什么这样设计。
2. 想解决什么问题。
3. 为什么不用明显备选方案。
4. 哪些权衡是有意为之。

Design Intent 不得用来：

1. 偷渡未冻结规则。
2. 替代输入输出合同。
3. 替代验收标准。
4. 替代失败处理。
5. 引入新的二义性。

7. 输入合同

输入合同至少说明：

1. 输入文件、表、接口或参数。
2. 必填字段。
3. 可选字段。
4. 主键或唯一键。
5. 字段类型或枚举。
6. 缺失输入如何处理。
7. 缺失字段如何处理。
8. 是否允许空输入。

小工具可以简化，但不能省略输入来源和输入格式。

8. 输出合同

输出合同至少说明：

1. 输出文件、表、接口或报告。
2. 输出字段。
3. 主键或唯一键。
4. 输出状态。
5. 空结果如何表示。
6. 失败时是否输出报告。
7. 输出是否会被下游正式消费。

如果输出只是诊断报告，必须明确写清：该输出不得反向改写主流程结果。

9. 处理流程

处理流程要写清：

1. 先做什么。
2. 再做什么。
3. 哪些条件会分支。
4. 哪些条件会停止。
5. 哪些条件会降级。
6. 哪些结果进入输出。
7. 哪些结果只进入审计或日志。

流程不要求写成代码级伪代码，但必须足够让实现者不会走两条不同路线。

10. 边界和不做事项

每份需求必须写清不做事项。

典型不做事项：

1. 不做预测。
2. 不做正式发布。
3. 不改写上游数据。
4. 不写入业务主表。
5. 不参与主流程 gate。
6. 不处理某类异常输入。
7. 不兼容某类历史格式。

不做事项能防止实现者把轻需求做成重系统。

11. 验收标准

验收标准要能判断需求是否完成。

验收可以包括：

1. 文件是否生成。
2. 字段是否齐全。
3. 行数或样本数是否合理。
4. 关键例子是否符合预期。
5. 失败样本是否正确失败。
6. 日志或报告是否能追踪。
7. 与上游或下游是否能对接。

验收不应无限扩张。

11.1 主流程必过项

只有影响核心正确性的检查，才应写成主流程必过项。

例如：

1. 必需输入不存在。
2. 必需字段缺失。
3. 主键重复导致结果不可用。
4. 输出缺失导致下游无法运行。
5. 时间序列任务存在明确未来函数。
6. 状态流转违反需求核心规则。

11.2 外围诊断项

以下内容一般应作为外围诊断项，不应默认阻断小样本、工具需求或主流程：

1. 发布级完整证明。
2. 全量 artifact identity 复验。
3. root manifest 自 hash。
4. 复杂 fixed-point 证明。
5. 重型跨文件一致性审计。
6. 非关键性能优化。
7. 非阻断格式建议。

如果确实要作为硬 gate，必须说明为什么它直接影响核心正确性。

12. 数据校验口径

数据校验要轻重分层。

主需求里只写核心校验：

1. 输入存在。
2. schema 基本正确。
3. key 基本合法。
4. 输出可读。
5. 核心行数合理。
6. 核心状态不矛盾。

复杂校验优先写成只读 helper：

1. helper 只读已落盘产物。
2. helper 输出 summary/report/readout。
3. helper 不改写主表。
4. helper 不改写 manifest。
5. helper 不覆盖主流程状态。

不要把数据校验设计成一堆层层叠加的 gate，导致需求本身变成验证系统。

13. 唯一实现解释

正式需求进入编码前，应让审核员判断代码实现者是否只能得出一个合理实现。

重点检查：

1. 主键是否唯一。
2. 分组键是否唯一。
3. 字段名是否有 canonical 口径。
4. legacy alias 是否有映射。
5. 状态枚举是否互斥。
6. 输入输出边界是否清楚。
7. sample / subset 是否会破坏业务结构。
8. 诊断项和正式项是否分开。
9. 失败时是 fail、降级还是跳过。

如果实现者可能按两种方式理解，就还不是合格需求。

13A. 需求上游一致性检查

无论新写需求还是修改需求，都必须做需求上游一致性检查。

检查对象：

1. 需求方案文档：有就参考，没有就说明不适用。
2. 架构文档：有就参考，没有就说明不适用。
3. 模块说明文档：有就参考，没有就说明不适用。
4. 核心流程文档：有就参考，没有就说明不适用。
5. 需求总纲里的目标、背景、边界和关键聊天要求。
6. 相关旧需求文档。

检查结论必须能回答：

1. 需求是否和需求方案一致。
2. 需求是否和架构、模块说明、核心流程一致。
3. 是否有冲突。
4. 是否漏写必须实现的需求。
5. 是否引入需求文档没有授权的新口径。
6. 是否把小需求写成重型系统。

推荐在需求文档中增加“需求上游一致性检查”小节。轻量需求也要写，但可以很短。

14. 公式、规则和阈值

简单阈值可以直接写在需求里。

复杂公式、跨模块共用公式、会进入多个模块的规则，应单独沉淀到公共方法、公共规则或公式文档中，并在需求里引用。

不要在多个需求文档里重复写同一公式，避免后续版本漂移。

15. 公共字段和公共表

多个模块共用的数据结构应进入公共文档。

需求文档中可以引用公共字段或公共表，但不得平行发明另一套冲突结构。

如果必须保留旧字段：

1. 写清 canonical 字段。
2. 写清 legacy alias。
3. 写清读取优先级。
4. 写清是否要求二者一致。
5. 写清何时可以废弃旧字段。

16. 审核规则

审核员审核需求时，重点看真问题。

必须审：

1. 目标是否清楚。
2. 输入输出是否清楚。
3. 流程是否能唯一实现。
4. 边界是否清楚。
5. 验收是否够用但不过重。
6. 是否存在未来函数或时间口径问题。
7. 是否把诊断项误写成硬 gate。
8. 是否遗漏会导致实现分叉的关键字段。

不应把以下内容当成阻断问题：

1. 文档措辞不够漂亮，但不会影响实现。
2. 内部变量名和需求字段名不同，但输出合同清楚。
3. 非关键格式建议。
4. 可后续优化的低影响项。
5. 不影响主流程的小型诊断字段缺失。

审核结论必须明确：

1. 通过。
2. 不通过，需修改。
3. 暂缓，需要补确认或补实验。

17. 需求完成标准

需求完成必须同时满足：

1. 需求文档已写完。
2. 审核员已审核。
3. 审核意见已处理。
4. 审核结论为通过。
5. 不存在会导致实现分叉的模糊点。
6. 不存在把轻任务做重的过度 gate。

需求完成后，才能进入对应编码流程。

如果是重型实现，还必须按 common/dev-doc/编码规范.md 先写代码编写方案并通过审核，再进入代码编写。

18. 禁止事项

禁止：

1. 需求不清就交给代码实现。
2. 把讨论稿当正式需求。
3. 把建议项写成必须实现项。
4. 把诊断项写成主流程硬 gate。
5. 小工具需求套完整发布级规范。
6. 用 Design Intent 代替正式合同。
7. 多个模块平行定义同一字段。
8. 不写不做事项。
9. 审核未通过就进入代码阶段。
10. 为了防所有可能错误而无限加校验。

19. 一句话

需求文档要做到：目标清楚、输入输出清楚、流程边界清楚、验收够用但不过重；小需求走轻流程，正式需求走完整流程；所有需求都必须审核通过后才算结束，重型实现还要再经过编码方案审核后才能写代码。