# SDD 治理规则（Governance）

本文件定义 NEX Docus SDD 中心的**编号、审批、变更与追踪**规则，保证「产品意图 → 架构决策 → 功能规格 → 实施任务 → 验证证据」始终处于同一条可追踪链路。

## 1. 编号体系

| 前缀 | 含义 | 格式 | 范围 |
| --- | --- | --- | --- |
| PO | Product Outcome（价值主张） | PO-N | 稳态常量，变更需评审 |
| ADR | Architecture Decision Record | ADR-NNNN | 持久架构决策，一决策一文件 |
| NFR | Non-Functional Requirement | NFR-N | 非功能需求，依附规格 |
| FR | Functional Requirement | FR-N | 功能需求，依附 DV 规格 |
| DV | Delivered Value（功能/变更单元） | DV-NNNN-shot-name | 一个功能或变更单元 |
| TS | Task（实施切片） | TS-N | 实施任务，从属于 DV |
| VER | Verification（验证证据） | VER-N | 验收证据，从属于 DV |

编号由 sdd 维护人统一分配；申请人不得自行占用 DV/ADR 编号。

## 2. 文档生命周期

```text
草稿(Draft) → 评审(Review) → 批准(Approved) → 已实现(Implemented) → 已验收(Verified) → 归档(Archived)
```

- **Draft**：spec.md 初稿，仅供讨论。
- **Review**：进入评审；架构影响大的须同时评审 ADR。
- **Approved**：批准为规格基线，可据此实现。
- **Implemented**：tasks.md 所有切片完成。
- **Verified**：verification.md 证据齐全且通过。
- **Archived**：功能下线/重构，移入归档，不再作为基线。

## 3. 审批矩阵

| 变更类型 | 需审批方 | 说明 |
| --- | --- | --- |
| 新增/修改 PO | 产品负责人 | 价值主张变化 |
| 新增/修改 ADR | 架构负责人 + 技术负责人 | 跨文件刚性承诺 |
| 新增 DV 规格 | 功能负责人 + 架构评审（涉架构时） | 新功能入口 |
| 修改已批准 spec/design | 相应 DV 负责人 | 变更影响追踪 |
| 只改 tasks/verification | DV 负责人 | 实施与验收细节 |
| 发布 | 发布负责人 | 见 releases/ |

## 4. 追踪规则（Traceability）

- **强制反向可追踪**：每一条实施切片（TS）必须引用一个或多个规格（FR/ADR/NFR）；每一条验收证据（VER）必须引用其证明的规格与任务。
- **双向矩阵**：`specs/README.md` 维护「规格 ↔ 任务 ↔ 证据」索引；`architecture/decisions/README.md` 维护「ADR ↔ 规格」映射。
- **变更即更新**：任何 spec/design 改动或布局改动，须同步更新关联的 tasks 与 verification，保持链路不断签。
- **孤儿项处理**：新增代码若无规格/任务支撑，属「未登记变更」，应在当次 SDD 评审中补登记或回滚。

## 5. 变更工作流

1. 在本中心提出变更（写明受影响 DV/ADR/NFR）。
2. 按审批矩阵过审。
3. 更新对应 spec/design/tasks/verification。
4. 回填索引（specs/README、decisions/README）。
5. 若变更跨越发布边界，登记到 releases/。

## 6. 当前开放问题（Open Items）

| 编号 | 类型 | 内容 | 关联 | 状态 |
| --- | --- | --- | --- | --- |
| OI-1 | 安全 | `security.py`/`deps.py` 存在 SECRET_KEY 前缀、JWT 载荷、token 前缀等敏感日志，需脱敏 | NFR-9, DV-0001/TS-12 | 待整改 |
| OI-2 | 部署 | 统一官方化 Docker Compose v2 部署路径（升级 compose-plugin、移除外层 v1 工具链依赖/说明） | NFR-6, ADR-0008 | 待整改 |
| OI-3 | 测试 | 后端测试仅覆盖引用/模型配置/检索三处，缺集成与 E2E 测试 | DV-* verification | 待增强 |
| OI-4 | 迁移 | 未引入 Alembic，迁移依赖幂等 ALTER；大规模结构变更缺少回放/回滚机制 | ADR-000?（见 ADR-07） | 已记录，待评估 |

## 7. 维护约定

- 本目录变更遵循「小步提交」：一次合并只动一个逻辑单元。
- 每个新建 DV 单元必须包含完整的四文件（spec/design/tasks/verification），缺一不可。
- 每次功能合并，默认要求补齐对应 verification 证据或明确标注“将由 OI-3 覆盖”。