Spec Writing

Spec 文档编写规范与生成规则

来源：2026-07-03 从 .trae/rules/spec创建规则.md 迁出,改为 skill。 触发：用户提到「立 spec」「写 spec」「评审 spec」「补 spec 三件套」「inventory」「matrix」「drift」「跑 PT」时,先读本 skill；涉及验证前读 tools/enablement.md。

0. 工具路由（bootstrap 装机，本 Skill 用法）

装机与 pre-commit 接线在 bootstrap(决策 v18:同 v17「按 Harness 提示自动接线」语义);本 Skill 只在目标项目 AGENTS.md 的「Spec 工具」表里登记 yes/no + 探测路径,不直接维护 Harness 专属 hook 配置样板。

1. 核心原则

• 文档即代码:Spec 文档与源代码存放在同一仓库,遵循相同的版本控制和评审流程。
• 唯一事实来源:Spec 是所有相关角色(产品、开发、测试)的唯一真相源。代码只是其实现。
• 机器可读优先:能用结构化语言(YAML、JSON、Gherkin、OpenAPI)描述的,绝不只依赖自然语言。纯文本仅作补充说明。
• 可执行可验证:文档中的每一个行为、规则、场景都必须能够转化为自动化测试或验证脚本。
• 不可变绑定:代码变更必须文档先行;文档变更也必须同步触发代码修改,CI 流水线强制执行这一绑定。
• 零自由发挥空间 no_implementation_latitude ⚠️ HIGHEST PRINCIPLE:spec 必须达到「拿走 spec 直接复刻代码」的精度。字段名 / 类型 / 必填性 / 默认值 / 校验器 / 枚举值 / 工厂方法签名 / 错误码 / 状态转换 / 测试用例 ID / CI 门禁规则——11 个维度必须全部钉死在 spec 正文,实施阶段不允许自创任何一条。违反 = spec 未完成,不允许进入实施阶段(详见 §6 / §7)。

2. 文件组织与命名规范

• 存放路径:所有 Spec 文档必须放在项目根目录下的 /specs/{领域}/{功能模块}/ 目录中。
  • 示例:/specs/auth/registration/
• 文件命名:
  • 主规范文档:spec.md (或 spec.yaml,若整个规范用结构化语言表达)
  • 机器可读契约（推荐）:inventory.yaml（与三件套同目录；counts + bindings，供 drift-inventory；见 tools/drift-inventory.md）
  • 可执行场景:features/{功能名}.feature (Gherkin)
  • API 契约:openapi.yaml
  • 数据模型:{实体名}.schema.json
  • 状态机:{实体名}_states.yaml
  • 行为不变量(推荐):properties.md（或写入 spec.md 的 Properties 小节）
• 代码关联:在 spec.md 的元数据部分必须明确关联的代码路径,例如:
  • 代码包路径:src/auth/registration/
  • API 路由文件:src/auth/routes/registration.ts
  • 数据库迁移文件:migrations/20260703_create_users.sql

3. 文档结构模板

所有 Spec 文档必须严格包含以下 10 个部分,不可缺失任何一部分;含关键业务行为的 Spec 推荐附加「第 5 部分附」Properties(共 11 个标题;Properties 不计入 10 段强制数,但属推荐升格)。

第 0 部分:文档头与元数据

• 规范标题:SPEC-{编号}: {特性名称}
• 状态:提议 | 已批准 | 开发中 | 已实现 | 已废弃
• 版本:严格遵循语义化版本,如 v1.0.0,与 Git Tag 对应。
• 负责人:PO: @someone | TL: @someone | QA: @someone
• 关联代码路径:至少列出代码包路径、API 路由文件、数据库迁移文件。
• 最后修改时间:由 Git 记录,文档中可标注 (见 Git 提交记录)。
• CI 门禁规则:简述关键绑定规则,如"本文件修改时必须同时修改对应代码路径"。

第 1 部分:术语表与统一语言

• 以表格形式定义所有领域专有名词,必须包含以下列:
  • 术语 英文名 类型(聚合根/值对象/枚举/服务) 定义 代码映射 数据库映射 示例
• 强制要求:所有代码中的枚举、实体、列名必须来自本表格。
• 一致性保障:表中枚举值将用于代码生成和静态检查。

示例片段:

第 2 部分:用户故事与验收场景(可执行规范)

• 必须使用 Gherkin 语法(Given-When-Then)编写。
• 场景文件单独存放于 features/ 目录,主文档中仅列出关键场景概要,或直接嵌入核心特性文件内容。
• 场景必须可直接运行,如使用 Cucumber/SpecFlow 框架执行。
• 必须覆盖:正常路径、异常路径、边界情况、权限校验。
• 每个场景都应关联到具体的 API 接口。

示例:

功能: 用户邮箱注册
  场景: 成功注册新账户
    假设 邮箱 "newuser@example.com" 未被注册
    当 我向 POST /api/v1/auth/register 发送请求
      """
      { "email": "newuser@example.com", "password": "SecureP@ss1" }
      """
    那么 响应状态码应该是 201
    且 用户状态应为 "PENDING_VERIFICATION"
    且 系统应发送一封验证邮件到 "newuser@example.com"

第 3 部分:API 接口与契约(OpenAPI 3.1 同源)

• 必须提供完整的 OpenAPI 3.1 规格文件(或 gRPC proto / GraphQL SDL)。
• 文件存放于同目录下 openapi.yaml,并在主文档中引用。
• 规格文件需包含:
  • 每个端点精确的路径、方法、请求体、响应体、状态码、错误响应。
  • 所有 Schema 定义(请求体、响应体、枚举、错误结构)。
  • 统一的错误响应格式(如 error_code, message, details)。
  • 至少一个完整的请求/响应示例。
• 一致性保障:从此文件生成服务端接口骨架和客户端 SDK;通过契约测试工具(Dredd)验证真实 API 与文档完全一致。

示例片段(OpenAPI YAML):

paths:
  /api/v1/auth/register:
    post:
      summary: 邮箱注册
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: 注册成功
          headers:
            X-Spec-Version:
              schema: { type: string, example: v1.0.0 }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '409':
          $ref: '#/components/responses/Conflict'

第 4 部分:数据模型与校验规则

• 对每个核心实体提供 JSON Schema 定义,文件命名 {实体名}.schema.json。
• 在主文档中建立 映射关系表,将业务字段、JSON Schema、数据库列、代码属性一一对应。
• 字段必须包含:类型、格式、长度、正则、枚举值、默认值、是否必填。
• 一致性保障:运行时使用 JSON Schema 校验请求与响应;通过数据库 Schema 同步工具(如 Prisma)保证与 JSON Schema 一致。

示例:映射表

第 5 部分:业务规则与状态流转

• 状态流转必须用 状态机图 或 YAML 定义,描述实体所有可能的状态和转换事件。
• 复杂业务规则使用 决策表(条件-动作表)表达,消除歧义。
• 每一条规则必须能映射到具体的测试用例。
• 一致性保障:状态机定义直接导入代码生成状态对象;决策表通过属性测试(Property-based Testing)覆盖。

示例:状态机 YAML

stateMachine: UserLifecycle
initial: PENDING_VERIFICATION
states:
  PENDING_VERIFICATION:
    on:
      VERIFY: ACTIVE
      EXPIRE: DISABLED
  ACTIVE:
    on:
      DISABLE: DISABLED

示例:决策表(密码强度)

第 5 部分附: Properties 行为不变量（推荐 / Correctness）

推荐升格（非第 11 段强制）: 10 段骨架不变。凡含关键业务行为（注册、状态迁移、冲突、决策表）的 Spec,应增加 Properties,把 SHALL 写成可执行 ∀ 公式,供 Property-Based Testing 作 oracle。纯叙事 NFR / 假设段可不写性质。
沙箱说明: 发布仓可不跟踪 specs/；性质示例与装订片段见下文「推荐范例」。消费者项目按自身栈实现 PT-*，勿默认嵌入全仓 PBT。

• 每条性质必须有:性质 ID（P-{域}-{序号}）回链（Gherkin / 状态机 / 错误码 / REQ-ID）量化式 生成器约定 自动化 ID（PT-…,可暂「未自动化」但须给期限）。
• 量化式须可判定真假:优先 ∀ … ⇒ …;禁止「体验良好」等不可观测结论。
• 覆盖矩阵（§7）允许增加 P-* / PT-* 行;类型可标「属性测试」。
• 一致性保障: 性质是行为契约;字段级零自由发挥（§4）仍要钉死。两者叠加:结构可复刻 + 行为可证伪。
• 语言不绑定: PT 用被测实现同语言的属性测试工具即可;本仓 pilot 用 Python 仅为示范。

最小表格模板:

Correctness 变更门（何时必须跑 PT）

分清两步：写 P-*（立/改 Spec）与 跑 PT-*（验证实现）。path-align / drift-lite 只做路径成对，从不自动等于 Correctness。

执行约定：

1. 只跑命中的 PT-*，禁止「每轮 stop 全仓扫一遍 PBT」。
2. 合并/CI：由项目自行决定是否把已声明「已自动化」的 PT-* 进门禁；Skill 不强制全仓绑定某一 PBT 库。
3. 未自动化的 PT-* 须在矩阵留期限；逾期未补 = Spec/门禁未完成（与 Q17 一致）。

第 6 部分:错误处理与日志规范

• 定义 错误码字典,表格列:错误码 HTTP 状态码 触发条件 日志级别。
• 所有 API 错误响应必须遵循统一格式(参照 OpenAPI 中的 Error schema)。
• 规定关键操作的日志等级和必须记录的字段(如 requestId, userId, action)。
• 一致性保障:错误码字典直接生成为常量类,业务代码只能引用这些常量;静态检查扫描任何硬编码错误码或异常。

示例:

第 7 部分:测试用例与需求覆盖矩阵

• 建立 需求追溯矩阵,表格列:需求来源 需求 ID 类型 测试用例 ID 自动化状态。
• 需求来源必须是本文档中的具体章节(如 Gherkin 场景、API 端点、状态机转换、业务规则、Properties)。
• 自动化状态 只有 已自动化 或 未自动化(未自动化必须给出理由和期限)。
• 允许行:TC-*(验收)、CT-*(契约)、UT-*(单元)、PT-* / P-*(属性 / 性质)。
• 一致性保障:通过代码注解(如 @spec("SPEC-001", "REQ-XX"))自动生成该矩阵,并作为 CI 覆盖率门禁。

示例:

第 8 部分:非功能性需求

• 必须量化指标,禁止使用"快速"、"稳定"等模糊词。
• 典型分类:性能、安全、可用性、可靠性、可观测性。
• 每项需求必须配套 验证方法(如压测脚本、安全扫描、集成测试断言)。
• 一致性保障:验证方法必须自动化,放入 CI 对应阶段(性能测试、安全扫描)。

示例:

第 9 部分:假设、约束与变更日志

• 假设:列出所有外部依赖和前提条件(如"数据库为 PostgreSQL 15"、"邮件服务可用")。
• 约束:技术选型限制、不可变规则(如"密码必须 bcrypt 散列"、"API 路径前缀 /api/v1/")。
• 变更日志:严格按 Git 提交记录自动生成,表格列:日期 版本 变更说明 关联 Commit。禁止手写变更日志。

示例:

4. 全局生成规则

1. 文档语言:主体使用中文,术语、代码、技术标识使用英文。
2. 完整性检查:生成 Spec 后,必须自我检查 10 个部分是否全部涵盖,不能遗漏。
3. 示例驱动:每一部分至少包含一个具体示例(参考下文给出的示例片段)。
4. 可执行性声明:在文档头部注明"本规范中的 Gherkin 场景可执行,OpenAPI 文件可用于代码生成,状态机可导入代码;关键行为宜附 Properties 供 PBT",提醒使用者这是可运行制品。
5. 与示例风格保持一致:当遇到新领域时,类比示例"用户邮箱注册与验证"的详细程度和编排方式生成对应内容。
6. 落地前自检门禁 pre_implementation_gate ⚠️ MANDATORY:spec 三件套(spec.md / tasks.md / checklist.md)写完后,必须执行 §6「落地前自检」全部 15 题,外加 §6.4 Properties 2 题(共 17)。任一题答 ❌ → 回修补 spec → 重检 → 全部 ✅ 才允许进入实施阶段。禁止「先动手再补自检」「自检不通过先开着口子后续补」。无关键业务行为的纯文档 Spec,Properties 2 题可答「N/A(无关键行为)」并写明理由。
7. 零自由发挥铁律 zero_improvisation ⚠️ MANDATORY:实施阶段(写代码 / 写测试 / 改字段)发现 spec 漏了某条约束 → 暂停 → 回 §5 补 spec → §6 重检 → 再继续写代码。禁止「我先这样写,spec 后补」「这个字段 spec 没写我就按习惯来」「这点小事不用进 spec」。

5. 实施零自由发挥约束 (No-Free-Land Gate)

本节是 §1「零自由发挥空间」最高原则的具体落地清单。spec 落地前必须逐维度确认 11 个维度全部钉死;实施阶段必须逐条确认 8 类禁止行为未触发。

5.1 spec 必须钉死的 11 维度清单

下表「spec 哪段写」列中的 §N 指 spec 文档的段落编号(即 §3 文档结构模板定义的 10 段,§0 元数据 / §1 术语表 / §2 Gherkin / §3 API / §4 数据模型 / §5 业务规则 / §6 错误处理 / §7 覆盖矩阵 / §8 非功能 / §9 假设约束),不是本 skill 的章节编号。

5.2 实施阶段禁止行为清单(8 类自创动作)

本节统一约定:任意自创动作的「正确动作」均为「先回 spec 改 → §6 重检 → 再写代码」,不在代码侧就地补救。下表「修订动作」列直接给出 spec 该回哪段改,具体回写正文仍按 §6 15+2 题自检。

5.3 模糊词黑名单(spec 正文出现即视为未完成)

以下词汇在 spec.md / tasks.md / checklist.md 正文中出现 = spec 未完成,不允许进入实施阶段:

例外:假设 段 / 约束 段 / 变更日志 段允许出现时间性表述(如「v2 评估」),但v1 边界必须在 §0 元数据(状态 / 版本 / 责任人 / 关联代码路径)+ §8 非功能需求(可量化指标 + 验证方法)中钉死;含「v2 评估」字样的句子必须同时给出 v1 当前的可执行指标,不得只挂个「v2 评估」尾巴。

6. spec 落地前自检 (Mandatory Pre-Implementation Self-Audit)

本节是 §4 第 6 条「落地前自检门禁」的具体清单。spec 三件套写完 → 实施阶段开始前必答 15 题 + Properties 2 题(共 17);任一题 ❌ → 回修补 spec → 重检;全部 ✅(或 Properties 合法 N/A) → 才允许动代码。禁止「先动手再补自检」「自检不通过先开着口子」。

下表「失败处理」列中的「§N」指 spec 文档的段落编号(§0-§9,见 §3 文档结构模板),不是本 skill 的章节编号;「§5」特指本 skill 的 §5「实施零自由发挥约束」。

6.1 严格对齐自检(5 题)

6.2 细节遗漏自检(5 题)

6.3 自由发挥空间自检(5 题)

6.4 Properties 门禁(2 题，小步升格)

6.5 自检执行模板(粘贴到 spec 同目录 self-check.md)

# Spec 落地前自检(15+2) - {spec 编号}

> 执行时间: {YYYY-MM-DD HH:MM}
> 执行人: {agent / user}

## 6.1 严格对齐(5 题)
- [ ] Q1 字段名: ✅/❌ {证据}
- [ ] Q2 函数签名: ✅/❌ {证据}
- [ ] Q3 枚举值: ✅/❌ {证据}
- [ ] Q4 测试用例 ID: ✅/❌ {证据}
- [ ] Q5 默认值/校验器/错误码: ✅/❌ {证据}

## 6.2 细节遗漏(5 题)
- [ ] Q6 10 段结构: ✅/❌ {缺失段}
- [ ] Q7 每段示例: ✅/❌ {缺失示例段}
- [ ] Q8 CI 门禁可执行: ✅/❌ {不可执行项}
- [ ] Q9 假设约束: ✅/❌ {遗漏项}
- [ ] Q10 变更日志: ✅/❌ {缺失字段}

## 6.3 自由发挥空间(5 题)
- [ ] Q11 黑名单模糊词: ✅/❌ {命中词 + 位置}
- [ ] Q12 Optional 触发条件: ✅/❌ {未明示字段}
- [ ] Q13 非功能需求验证方法: ✅/❌ {未给方法项}
- [ ] Q14 类比精确约束: ✅/❌ {未展开类比}
- [ ] Q15 实施必需动作声明: ✅/❌ {未声明动作}

## 6.4 Properties(2 题)
- [ ] Q16 关键行为有 P-* / 或 N/A: ✅/❌/N/A {证据或理由}
- [ ] Q17 P-* 回链 + PT-* 矩阵行: ✅/❌/N/A {证据}

## 结论
- 总计 ✅: {N}/17（N/A 计为通过并附理由）
- 总计 ❌: {N}/17
- 进入实施阶段: 是 / 否(否则回修补 spec → 重检)

7. 完整示例参考

以下示例不仅展示 10 段结构,还展示如何达到 §5「零自由发挥」标准——每个字段、每个错误码、每个测试用例 ID 都钉死到可逐字复刻。新领域写 spec 时应类比此示例的精度,而非仅类比结构。

下面给你一个完整的 Spec 文档示例,主题是 "用户邮箱注册与验证" 。这份文档严格按照前文所述的 10 个部分编写,并附 Properties 推荐范例;每一部分都会连带说明它 如何与代码保持高度一致。

SPEC-001: 用户邮箱注册与验证

规范状态: 已实现 版本: v1.0.0 负责人: PO: @amy | TL: @ben | QA: @cathy 代码包路径: src/auth/registration/ API 路由文件: src/auth/routes/registration.ts 数据库迁移文件: migrations/20260703_create_users.sql 最后修改: 2026-07-03 (Git 提交记录为准)

1. 规范元数据与治理 (同仓同源)

• 文件路径: /specs/auth/registration/spec.md
• 关联代码路径: /src/auth/registration/
• CI 门禁规则:
  • 本文件被修改时,对应的 src/auth/registration/ 或 API 测试文件必须同时被修改。
  • 当 API 版本号变更时,CI 会检查代码中返回的 X-Spec-Version 响应头是否与本文档的 info.version 一致。

2. 术语表与统一语言

一致性保障:

• UserStatus 枚举直接由本表格生成 TypeScript 类型和 Prisma 枚举。
• 任何代码中出现的用户状态字符串,必须通过 UserStatus 枚举引用,CI 中运行 grep 检查硬编码状态字符串的脚本。

3. 用户故事与验收场景 (可执行 Gherkin)

以下场景文件位于 /specs/auth/registration/features/registration.feature,由 Cucumber 框架直接执行。

功能: 用户邮箱注册
  作为一名网站访客
  我想要使用我的邮箱注册一个新账户
  以便能登录并使用网站功能

  背景:
    假设 系统处于正常运行状态

  场景: 成功注册新账户
    假设 邮箱 "newuser@example.com" 未被注册
    当 我向 POST /api/v1/auth/register 发送以下请求
      """
      {
        "email": "newuser@example.com",
        "password": "SecureP@ss1"
      }
      """
    那么 响应状态码应该是 201
    且 响应体应包含一个用户 ID
    且 用户状态应为 "PENDING_VERIFICATION"
    且 系统应发送一封验证邮件到 "newuser@example.com"
    且 响应头 X-Spec-Version 应为 "v1.0.0"

  场景: 使用已注册的邮箱注册
    假设 邮箱 "duplicate@example.com" 已被注册且状态为 "ACTIVE"
    当 我向 POST /api/v1/auth/register 发送以下请求
      """
      {
        "email": "duplicate@example.com",
        "password": "AnotherP@ss1"
      }
      """
    那么 响应状态码应该是 409
    且 错误码为 "EMAIL_ALREADY_REGISTERED"

  场景大纲: 使用无效格式的邮箱或密码
    当 我向 POST /api/v1/auth/register 发送以下请求
      """
      {
        "email": "<邮箱>",
        "password": "<密码>"
      }
      """
    那么 响应状态码应该是 422
    且 错误码为 "VALIDATION_ERROR"
    且 响应体 details 应包含字段 "<字段>"

    例子:
      | 邮箱              | 密码         | 字段    |
      | invalid           | SecureP@ss1  | email   |
      | user@example      | SecureP@ss1  | email   |
      | good@example.com  | 123         | password |

一致性保障:

• 本文件即为自动化测试套件。所有场景必须在 CI 中 100% 通过。
• 测试步骤中的 发送请求 直接调用真实 API,系统应发送一封验证邮件 这一步会检查邮件发送服务是否被调用(通过 mock 验证)。

4. API 接口与契约 (OpenAPI 3.1 同源)

文件路径:/specs/auth/registration/openapi.yaml。该文件是接口的 唯一事实来源。

openapi: 3.1.0
info:
  title: 用户注册服务
  version: v1.0.0
paths:
  /api/v1/auth/register:
    post:
      summary: 邮箱注册
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: 注册成功,等待邮箱验证
          headers:
            X-Spec-Version:
              schema:
                type: string
                example: v1.0.0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v1/auth/verify-email:
    post:
      summary: 邮箱验证
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                  description: 注册后通过邮件收到的验证令牌
      responses:
        '200':
          description: 验证成功,账户激活
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "邮箱验证成功,账户已激活"
        '410':
          $ref: '#/components/responses/Gone'

components:
  schemas:
    RegisterRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
          maxLength: 254
          description: 用户邮箱
        password:
          type: string
          minLength: 8
          maxLength: 128
          pattern: '^(?=.*[a-zA-Z])(?=.*\d).+$'
          description: 密码,至少8位,包含字母和数字
      example:
        email: "newuser@example.com"
        password: "SecureP@ss1"

    RegistrationResponse:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/UserStatus'
      example:
        user_id: "550e8400-e29b-41d4-a716-446655440000"
        status: "PENDING_VERIFICATION"

    UserStatus:
      type: string
      enum: [PENDING_VERIFICATION, ACTIVE, DISABLED]

  responses:
    Conflict:
      description: 资源冲突
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: "EMAIL_ALREADY_REGISTERED"
            message: "该邮箱已被注册"

    ValidationError:
      description: 请求参数校验失败
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'

    Gone:
      description: 资源已过期
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: "VERIFICATION_TOKEN_EXPIRED"
            message: "验证令牌已过期,请重新注册"

    Error:
      type: object
      required: [error_code, message]
      properties:
        error_code:
          type: string
        message:
          type: string

    ValidationErrorBody:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            details:
              type: array
              items:
                type: object
                properties:
                  field: { type: string }
                  reason: { type: string }

一致性保障:

• 服务端代码生成: 使用 OpenAPI Generator 生成 Express 路由接口和 DTO 类,开发人员只能实现业务逻辑。
• 契约测试: CI 中运行 Dredd,用真实请求比对 API 返回是否与该文档完全一致,包括状态码、错误体结构。
• 消费者驱动契约: 前端团队提供 Pact 文件,验证注册 API 满足他们期望的字段,存放于 /pacts/registration-web.json,CI 中运行 Pact 验证。
• 差异检查: 任何 PR 修改本文件时,运行 openapi-diff 与主干比较,如有 Breaking Change 则必须人工审批。

5. 数据模型与校验规则 (JSON Schema + 数据库映射)

用户实体 JSON Schema 定义:/specs/auth/registration/user.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email", "maxLength": 254 },
    "password_hash": { "type": "string" },
    "status": { "enum": ["PENDING_VERIFICATION", "ACTIVE", "DISABLED"] },
    "created_at": { "type": "string", "format": "date-time" },
    "verified_at": { "type": ["string", "null"], "format": "date-time" }
  },
  "required": ["id", "email", "password_hash", "status", "created_at"]
}

数据库 Schema (Prisma) 直接从上述文档生成,文件 prisma/schema.prisma 中相关部分由工具保证同步:

enum UserStatus {
  PENDING_VERIFICATION
  ACTIVE
  DISABLED
}

model User {
  id            String     @id @default(uuid())
  email         String     @unique @db.VarChar(254)
  passwordHash  String     @map("password_hash")
  status        UserStatus @default(PENDING_VERIFICATION)
  createdAt     DateTime   @default(now()) @map("created_at")
  verifiedAt    DateTime?  @map("verified_at")
  @@map("users")
}

一致性保障:

• 运行时校验: 在 API Controller 中,使用 ajv 编译该 JSON Schema 作为请求体二次校验(即使已经生成类型,但防御性检查仍有必要)。
• 快照测试: 单元测试中序列化一个新创建的用户对象,断言其 JSON 结构与 user.schema.json 中的 example 一致。
• 数据库迁移自动生成: Prisma 的文件由 prisma generate 从 Schema 生成,而 Schema 的变更规则是:必须与 JSON Schema 同步修改。

6. 业务规则与状态流转

用户状态机 (YAML): /specs/auth/registration/user_states.yaml

stateMachine: UserLifecycle
initial: PENDING_VERIFICATION
states:
  PENDING_VERIFICATION:
    on:
      VERIFY: ACTIVE
      EXPIRE: DISABLED   # 注册后超过24小时未验证
  ACTIVE:
    on:
      DISABLE: DISABLED
  DISABLED:
    type: final

决策表:密码强度规则

一致性保障:

• 状态机代码生成: 使用 xstate 导入 YAML,实际业务逻辑的状态转换必须经过该状态机对象,非法转换会抛出错误。
• 基于属性的测试: 根据密码决策表编写属性测试,随机生成符合/不符合规则的字符串,断言 isValidPassword() 结果与决策表一致。
• 集成测试状态流转: 模拟调用邮箱验证接口,断言数据库状态从 PENDING_VERIFICATION 变为 ACTIVE,并检查状态机是否允许。

Properties（推荐范例 / Correctness）

状态: 推荐范例（小步升格）。不是第 11 段强制结构;有关键业务行为的 Spec 应按「第 5 部分附」书写同类小节。
文件建议: /specs/auth/registration/properties.md（或本文件子节）。发布 Skill 仓可不入库 specs/。
生成器约定: valid_email = 满足 JSON Schema format:email 且 maxLength≤254；valid_password = 满足 minLength≥8 且 pattern「至少一字母一数字」；UserStatus / Event 枚举取自本 Spec 正文。

P-REG-01 — 新邮箱注册必进入待验证态

∀ email ∈ valid_email, ∀ password ∈ valid_password,
当 email 未被占用时：
  r = register(email, password)
  ⇒ r.http == 201
  ∧ r.body.user_id 存在且为 UUID
  ∧ r.user.status == PENDING_VERIFICATION
  ∧ r.user.email == email

P-REG-02 — 已占用邮箱注册必冲突且不改写用户

∀ email ∈ valid_email, ∀ password_old, password_new ∈ valid_password,
∀ status ∈ {PENDING_VERIFICATION, ACTIVE, DISABLED},
当 email 已以 status 存在时：
  before = snapshot(email)
  r = register(email, password_new)
  ⇒ r.http == 409
  ∧ r.error_code == "EMAIL_ALREADY_REGISTERED"
  ∧ snapshot(email) == before

P-REG-03 — 状态机闭包（仅允许表内迁移）

Allowed = {
  (PENDING_VERIFICATION, VERIFY) → ACTIVE,
  (PENDING_VERIFICATION, EXPIRE) → DISABLED,
  (ACTIVE, DISABLE) → DISABLED
}

∀ status ∈ UserStatus, ∀ event ∈ {VERIFY, EXPIRE, DISABLE}:
  若 (status, event) ∈ Allowed
    ⇒ apply(status, event) == Allowed[(status, event)]
  否则
    ⇒ apply(status, event) 抛出领域错误（不得静默保持或迁到表外状态）

装订示例（Hypothesis；工具可选，oracle 必填）:

# 示意：消费者项目用同语言属性测试工具装订；非发布仓 CI 门禁。
@given(valid_email(), valid_password())
def test_P_REG_01(email, password, fresh_db):
    assume(not email_exists(email))
    r = register(email, password)
    assert r.status_code == 201
    assert r.user.status == "PENDING_VERIFICATION"

ALLOWED = {
    ("PENDING_VERIFICATION", "VERIFY"): "ACTIVE",
    ("PENDING_VERIFICATION", "EXPIRE"): "DISABLED",
    ("ACTIVE", "DISABLE"): "DISABLED",
}

@given(st.sampled_from(USER_STATUSES), st.sampled_from(EVENTS))
def test_P_REG_03(status, event):
    if (status, event) in ALLOWED:
        assert apply_transition(status, event) == ALLOWED[(status, event)]
    else:
        with pytest.raises(DomainError):
            apply_transition(status, event)

范例要点:

• Gherkin 单例邮箱 → 性质需补 输入空间（生成器）与 assume。
• 冲突场景只写了 ACTIVE → 性质要求 ∀ UserStatus，比原场景更强。
• 状态机 YAML → Allowed 表即唯一迁移 oracle；非法边必须有失败语义（本范例钉死为抛错）。

7. 错误处理与日志规范

错误码字典:

一致性保障:

• 统一异常类: 所有抛出的业务异常必须使用 BusinessError 类,其构造参数 errorCode 必须为上述字典中的值。在 CI 中,使用静态分析扫描 throw new BusinessError('SOME_STRING'),若字符串不在字典中则编译失败。
• 响应体验证: 契约测试中针对每个错误场景,严格比对 error_code 和状态码,不允许返回自定义消息或 500 堆栈。

8. 测试用例与需求覆盖矩阵 (自动生成)

此矩阵由测试运行时注解自动生成,不手工维护。

一致性保障:

• 覆盖率门禁: CI 中运行需求覆盖率报告,所有 REQ-REG-* 必须有对应的自动化测试通过,否则不允许合并。
• 自动关联: 在测试代码中使用 @spec("SPEC-001", "REQ-REG-01") 装饰器,脚本扫描测试代码生成上述矩阵。
• Properties: P-REG-* / PT-REG-101..103 为推荐范例；关键行为须过自检 Q16/Q17。Hypothesis 为可选工具,不以全仓 CI 强制依赖为门槛。

9. 非功能性需求

一致性保障:

• 上述验证方法均编写为自动化测试/脚本,放入 CI 对应阶段。
• 性能基线文件 benchmarks/register_threshold.json 与 Spec 同步更新。

10. 假设、约束与变更日志

假设:

• 系统运行在 Node.js 20 LTS 环境。
• 数据库为 PostgreSQL 15,支持 uuid-ossp 扩展。
• 邮件发送服务 email-service 可用,调用其 sendVerificationEmail 接口,成功率 99.9%。

约束:

• 密码必须 bcrypt 散列存储,轮数为 12。
• JWT 验证令牌使用 RS256 算法,过期时间 24 小时。
• 所有 API 路径前缀 /api/v1/ 不得改变。

变更日志 (由 semantic-release 基于 Git 提交自动生成):