nex_docus/docs/sdd/governance.md

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. 文档生命周期

草稿(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 覆盖”。