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

docs/workflow.md

@@ -130,8 +130,9 @@
 
 ## 测试 / 验证流程
 
-- 改动后必须 `npx tsc --noEmit` 通过
-- 涉及服务端数据持久化：`pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
+- 改动后必须 `pnpm type-check` 通过
+- 涉及服务端数据持久化：`DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ftb_pm pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
+- 涉及 V2.5 后端权限/审计/AppData/一致性：至少运行 `pnpm --filter server test`
 - 涉及 UI 改动：`curl http://localhost:3000/<path>` 检查 200
 - 不会自动跑 dev server，假定它已经运行
 
@@ -167,6 +168,37 @@
 
 新增领域 store 时，先写 source contract 测试证明主写不是 `saveServerData('<key>')`，再实现领域 API 和 fallback。
 
+## V2.5 权限、审计与 AppData 退场流程
+
+新增或修改领域 mutation endpoint 时，必须使用统一合同：
+
+1. Controller mutation 使用 `@ProtectedMutation(permission, scope, audit)`，不要只在前端做权限判断。
+2. `scope` 必须能从 param/body 中解析 `productId`、`projectId` 或 `versionId`，版本资源优先传 `versionId`。
+3. Service 写入需要保留 `actorId`、`resourceScope` 或可推导的产品/项目/版本上下文，便于审计与一致性校验。
+4. 成功 mutation 必须写 `audit_events`；审计详情中不得暴露密码、token、secret、API key 等敏感字段。
+5. 查询审计走 `/admin/audit` 或 `GET /api/v1/audit`，需要 `audit:view`。
+
+AppData key 退场遵循：
+
+1. 所有业务 key 先在 `AppDataRetirementService` 标注状态和替代路径。
+2. `write_frozen` / `read_only_archive` key 的写入返回 `409 APP_DATA_WRITE_FROZEN`；前端捕获 `ServerDataWriteFrozenError` 后提示改用领域 API。
+3. 读取仍可用，只用于历史数据核对、兼容导入、归档导出和故障排查。
+4. 导出归档使用 `pnpm appdata:archive:export`，归档校验使用 `pnpm appdata:archive:verify -- --archive <file>`。
+5. 不新增 AppData key 作为主写；新业务先设计关系表、Prisma model、领域 API、权限和审计。
+
+一致性检查流程：
+
+1. 本地或部署环境先确保 server 可访问并完成 migration。
+2. 运行 `pnpm consistency:v25`，默认检查 `http://localhost:3001/api/v1/consistency`。
+3. `error` 必须修复后才能继续发布；`warn` 需要记录原因。历史数据缺少审计事件属于 warning，不阻断 V2.5。
+4. 后台页面 `/admin/consistency` 由 `consistency:view` 控制，展示 counts、分区键、孤儿引用和审计覆盖。
+
+跨阶段协调点：
+
+- `xiaobao-risk-snapshots` / `xiaobao-risk-insights` 已进入只读归档；V2.6 负责关系表写入、后台任务和重试。
+- `xiaobao-warning-views` 已进入只读归档；V2.7 负责 per-user read-state API。
+- 成员身份写 `users`，但部门、角色、密码规则和加班原因的正式配置 schema 仍属 V2.7 管理治理。
+
 ## 与我相关（Workspace）数据流
 
 ```