# 追溯与增量同步规范

## 稳定设计 ID

| 类型 | 格式 | 例子 |
| :--- | :--- | :--- |
| 页面 | `PAGE-Fnn-nn` | `PAGE-F03-01` |
| 组件 | `CMP-Fnn-nn` | `CMP-F03-04` |
| 接口/契约 | `API-Fnn-nn` | `API-F03-02` |
| 数据实体 | `DATA-Fnn-nn` | `DATA-F03-01` |
| 时序/流程 | `SEQ-Fnn-nn` | `SEQ-F03-01` |
| 设计决策 | `DEC-nnn` | `DEC-008` |
| 修复点 | `FIX-BUG-nnn` | `FIX-BUG-001` |

发布后不重编号、不复用。语义变化递增 revision；拆分时旧 ID 标 retired，新 ID 写 supersedes。

## `设计追溯矩阵.md` 固定格式

```markdown
# 设计追溯矩阵

| Source ID | Source Revision | Design IDs | Artifact | Error/Invariant | Verification Surface | Status |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| AC-F03-01 | 1 | PAGE-F03-01, API-F03-02, SEQ-F03-01 | pages/阶段1_账号_注册.md; pages/阶段1_账号_注册.html; 技术方案.md §4 | duplicate_email → 明确错误；不得建重复记录 | component + integration + e2e | covered |
| AC-F08-01 | 1 | PAGE-F08-01, DEC-012 | 页面清单.md; 设计决策蓝图.md §4 | 阶段2依赖MVP账号主体ID保持稳定 | 阶段2启动时重新深设计与校验 | planned |
```

Feature 的 active `REQ/AC/NFR` 必须各至少一行；Bugfix 的 active `REPRO/CUR/EXP/UNCH/CON` 必须各至少一行。`Design IDs`、`Artifact`、`Error/Invariant`、`Verification Surface` 不得空白或 TBD。一个设计 ID 可以覆盖多个来源，但来源语义不得被合并丢失。

Feature 按阶段控制设计深度：

- `REQ` 的 `Stage` 含 `MVP` 时属于本期；`AC` 继承 Parent REQ 的阶段。
- `NFR` 若未声明 `Applies-to`，视为全局并进入 MVP；若声明，则只要关联任一 MVP REQ 就进入 MVP。
- MVP source 状态必须为 `covered` 或增量未变化的 `preserved`，并指向页面文档/高保真、技术方案、API/DATA/SEQ 等真实详细产物。凡 `Design IDs` 含 `PAGE-*`，`Artifact` 必须写该页面**实际存在**的 MD 与 HTML 路径，不得只写通配符或页面显示名称。
- 页面产物的规范位置是 `output/pages/` 直属目录，MD/HTML 主文件名相同；若历史产物路径或名称不规范，但 MD 元信息与 HTML `meta[name="page-id"]`（旧产物可退化为标题/正文）能唯一证明属于同一 PAGE ID，则记录实际路径与命名偏差后仍可 `covered`，不得仅因名字不同伪报缺失。零匹配、多匹配或内容身份冲突才阻塞。
- 后续阶段 source 可以为 `planned`：必须有稳定 Design ID，并指向 `页面清单.md`、`设计决策蓝图.md` 或 `技术方案.md` 的真实骨架、依赖或扩展预留；不得伪造已经完成的页面文档、高保真或接口。
- 后续阶段若因不可逆约束已经做了真实深度设计，可以标 `covered/preserved`，但不得为了让状态好看而提前扩张产物。
- Bugfix 没有“以后再设计”的安全空间，全部 active source 仍必须 `covered/preserved`。

MVP 关键业务流用 Mermaid sequence diagram 并分配 SEQ ID；状态型实体给出合法迁移、非法迁移与并发冲突；MVP NFR 必须映射测量点而非只写“技术方案已考虑”。后续 `planned` 项只记录会约束 MVP 的依赖和不可逆边界，等对应阶段启动时再补完整流程与测量点。

## 覆盖闸

1. 每条 active source ID 有真实设计落点：MVP 是施工级落点，后续阶段是可追踪的 planned 骨架。
2. 每个页面/API/数据实体能反向指出来源 ID；无来源项标 `design-derived` 并给必要性，不得伪造需求。
3. MVP 的所有错误与不变行为有明确实现面和验证面；后续阶段至少写清依赖或不可逆约束，以及何时重新深设计。
4. 任一 source `missing / TBD / stale` 都不合格；MVP 出现 `planned` 也不合格。后续阶段的合法 `planned` 不阻塞当前 MVP 进入 tdd-master。

## 增量同步

比较 source ID 的 revision，输出 `change-impact.md`：

```markdown
| Changed Source | Old→New Revision | Affected Design IDs | Artifacts | Action | Status |
| AC-F03-01 | 1→2 | API-F03-02, SEQ-F03-01 | 技术方案.md; 注册页.md | regenerate + review | stale |
```

只把直接映射和依赖闭包标 stale。未受影响设计 ID、已确认视觉决策与文件保持原状。修复并复核后更新矩阵 source revision：MVP 恢复为 `covered/preserved`，后续骨架恢复为 `planned`（已真实深设计的可为 `covered/preserved`）；禁止仅改 revision 数字而不检查行为。