需求

server/.ai-specs/sys-specs/requirements-stage-spec.md

@@ -0,0 +1,107 @@
+# 需求草案阶段规范
+
+## 适用范围
+
+- 新增/修改 `.ai-specs/requirements/*.md` 前必须先读本文件。
+- 本文件只约束 `requirements` 文档，不替代 `doc-dict`、`doc-sql`、`doc-api` 和代码实现规范。
+
+## 阶段目标
+
+- `制定需求草案阶段`：只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档。
+- `归档阶段`：需求草案已稳定，可作为下游文档和实现依据；新增需求或未确认变更必须退回 `制定需求草案阶段`。
+- 两个阶段正文结构一致：涉及表时先写 `## 表`，再写 `## 需求描述`；不涉及表时只写 `## 需求描述`。
+
+## 强制规则
+
+- 文档路径固定：`.ai-specs/requirements/<topic>.md`
+- 文档标题固定：`# <主题> 需求草案`
+- 标题下方空一行后必须紧跟两行阶段元信息，格式固定为 `- **阶段** <阶段说明>` 和 `- **要求** <阶段要求>`。
+- 阶段元信息只能从下表选择一组，禁止混用、改名或自行扩写。
+
+| 阶段 | 阶段行 | 要求行 |
+|:---|:---|:---|
+| 制定需求草案阶段 | `- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档` | `- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路` |
+| 归档阶段 | `- **阶段** 当前阶段为需求归档，需求草案已稳定，可作为下游文档和实现依据，原则上不再追加未确认内容` | `- **要求** 只允许修正错误、消除歧义和同步已确认结论；新增需求或未确认变更必须退回制定需求草案阶段处理` |
+
+- 一个文档只描述一个业务主题。
+- 正文只允许出现 `## 表` 和 `## 需求描述` 两类二级标题。
+- `## 需求描述` 必须存在；`## 表` 按需存在，不涉及表时必须省略。
+- 禁止为了满足格式硬造表或保留空表区。
+- 有表时，每张表使用一个 `### <表名>`；字段统一写成 `- <字段名>：<字段说明>`。
+- 有表时，`## 表` 只写字段和极简业务含义；不写流程、规则、性能、实现判断。
+- 有表且字段涉及字典时，只引用字典码，例如“字典 `<dict-code>`”或“字典，需补 `<dict-code>`”；确认值域写到 `## 需求描述`。
+- 有表且字段本质上是多值、多对多或独立主体时，必须拆成独立表或关联表，禁止塞进主表字符串字段。
+- `## 需求描述` 下每个业务主题使用一个 `### <需求标题>`，只写规则、流程、边界、范围和例外。
+- `###` 下只允许 `-` 扁平列表；禁止四级标题、嵌套标题、编号大纲、代码块、图和表格。
+
+## 禁止事项
+
+- 禁止写 API 路径、Method、鉴权方式、请求响应结构。
+- 禁止写 Router、API、Service、定时任务、缓存、消息队列等实现设计。
+- 禁止写 SQL 建表语句、字段类型、索引、唯一约束、迁移脚本。
+- 禁止新增 `## 背景`、`## 范围`、`## 总览`、`## 关系图`、`## TODO` 等既定结构外标题。
+- 禁止把需求规则混写到 `## 表`，也禁止把字段清单重复抄到 `## 需求描述`。
+- 禁止无表业务为了套模板编造表、字段、关联关系或空的 `## 表`。
+- 禁止把未确认事项写成确定结论；未确认内容必须标记“需补”或“待确认”。
+- 禁止在 `归档阶段` 继续收集新需求；新增需求必须退回 `制定需求草案阶段`。
+
+## 文档结构
+
+- 有表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 表` → 多个 `### <表名>` → `## 需求描述` → 多个 `### <需求标题>`。
+- 无表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 需求描述` → 多个 `### <需求标题>`。
+- 有表时，`### <表名>` 使用业务表名，例如“书籍信息表”“书籍章节表”“订单支付记录表”，不要求等于最终数据库表名。
+- `### <需求标题>` 使用业务主题名，例如“数据来源与上传”“章节重建策略”“评论点赞”“当前范围”。
+- 没有合适标题的信息，归并到语义最近的 `### <需求标题>`；确需新增标题时，只能在 `## 需求描述` 下新增三级标题。
+
+## 输出模板
+
+无表业务模板：
+
+````md
+# <主题> 需求草案
+
+- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档
+- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路
+
+## 需求描述
+
+### <需求1>
+- <规则、边界或待确认事项>
+
+### <需求2>
+- <规则、例外或范围>
+````
+
+有表业务模板：
+
+````md
+# <主题> 需求草案
+
+- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档
+- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路
+
+## 表
+
+### <表1>
+- <字段1>：<说明>
+- <字段2>：<说明或需补>
+- <字段3>：字典 `<dict-code>`
+
+### <表2>
+- <字段1>：<说明>
+
+## 需求描述
+
+### <需求1>
+- <规则、边界或待确认事项>
+
+### <需求2>
+- <规则、例外或范围>
+````
+
+## 与后续文档的关系
+
+- `requirements` 是 `doc-dict`、`doc-sql`、`doc-api` 和代码实现的上游输入，不是替代物。
+- 出现状态、类型、级别、来源、模式、分类等值域时，下一步先补 `.ai-specs/doc-dict/*.md`。
+- 涉及表、字段、关系且已稳定后，下一步补 `.ai-specs/doc-sql/*.md`；无表需求不强制补 `doc-sql`。
+- 默认链路：`requirements(制定需求草案阶段 -> 归档阶段) -> doc-dict / doc-sql -> Model -> Service -> API -> Router`。