docs(v25): 更新退场权限审计收口说明

docs/decisions.md

@@ -608,3 +608,18 @@
 - 一次性同步脚本可以存在，但必须作为运维迁移工具管理，不能依赖提交 `.env` 或手工修改源码开关。
 
 **理由**：系统未来要承载大量需求、任务、测试用例、Bug、活动和风险数据。关系表才能提供可验证的约束、事务、索引、分页、权限和审计能力。AppData 是低风险迁移桥，不是最终架构；继续扩大 JSON 主存储会把数据一致性和性能问题推迟到更难修的阶段。
+
+## 47. V2.5 用冻结、审计和一致性校验收口迁移期，而不是直接删除 AppData
+
+**问题**：V2.4 已经把主要领域写入迁到关系表，但 AppData 里仍保存历史 JSON、旧部署 fallback 和少量尚未领域化的配置形状。如果直接删除 `app_data` 或移除 `/data/:key`，会失去回滚、迁移核对和历史排查依据；如果继续允许写入，又会把双事实源问题拖进 V2.6。
+
+**决策**：
+- 每个 AppData key 明确进入 `write_frozen` 或 `read_only_archive`，由 `AppDataRetirementService` 集中配置替代 API 和说明。
+- 冻结 key 的 `PUT /api/v1/data/:key` 返回 `409 APP_DATA_WRITE_FROZEN`；`GET` 继续可用，用于历史读取、归档导出和人工核对。
+- Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/TaskWorklog/Overtime/WorkActivity 等领域 mutation 全部使用 `@ProtectedMutation()`，同一个装饰器组合权限、资源作用域和审计写入。
+- `audit_events` 采用 append-only 模型，按 `created_at` 分区；敏感字段由 AuditService 脱敏，查询接口需要 `audit:view`。
+- 一致性校验同时提供 `GET /api/v1/consistency` 和 `pnpm consistency:v25`，检查 counts、分区键、孤儿引用和审计覆盖。历史数据缺少审计事件只作为 warning，不把迁移前事实误判为当前写路径错误。
+- 当前 server auth context 先用 `x-ftb-user-*` 头作为稳定 adapter，前端从现有登录会话补齐这些头；正式 JWT/NextAuth 服务端验证留给后续认证治理阶段。
+- Xiaobao risk snapshots/insights 的 AppData key 进入 `read_only_archive`，关系表写入和后台化归 V2.6；`xiaobao-warning-views` 读状态 API 归 V2.7。
+
+**理由**：冻结写入能立即切断新的双主源风险，同时保留旧 JSON 的审计和回滚价值。把权限和审计合并到领域 mutation 装饰器，可以确保后续新增写接口默认带服务端 guard 和 audit event。审计覆盖对历史数据只告警，避免为了“补齐历史审计”伪造事件。auth header adapter 给 V2.5 一个可测试的服务端权限边界，但不把它包装成最终安全方案，后续 JWT/企业 RBAC 可以替换 adapter 而不改领域 controller 合同。