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

docs/architecture.md

@@ -47,7 +47,7 @@ apps/web/
 │   ├── versions/        # 版本列表 + 详情
 │   ├── requirements/    # 需求池
 │   ├── workspace/       # 与我相关（聚合工作台）
-│   └── admin/           # 系统管理（任务类型字典等）
+│   └── admin/           # 系统管理（成员/角色/任务类型/审计/一致性/AI 配置）
 ├── components/
 │   ├── product/         # 产品组件
 │   ├── version/         # 版本组件（PlanTab, CapsuleStages, MemberChips...）
@@ -122,12 +122,18 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 - 版本详情：VersionPlan、DevTask、TestCase、Bug 直接按 `versionId` 分区键写关系表，并继续标脏 Xiaobao 摘要和写入工作活动证据。
 - 字典/成员/证据：Member 写 `users` 的成员身份字段；TaskCategory 写 `task_categories`；TaskWorklog、OvertimeRecord、WorkActivity 保持追加/证据型关系表写入。
 
+V2.5 控制面新增三类横切能力：
+
+- 权限：`apps/server/src/common/auth/` 提供当前用户解析、`@CurrentUser()`、`@RequirePermission()` 和 `PermissionGuard`。当前 V2.5 使用前端会话透传的 `x-ftb-user-*` 请求头作为服务端 auth adapter；正式 JWT/NextAuth 接入仍属于后续认证阶段。
+- 审计：`audit_events` 是 append-only 表，按 `created_at` 分区，领域 mutation 通过 `@ProtectedMutation()` 同时挂权限、资源作用域和 `AuditMutationInterceptor`。审计查询走 `GET /api/v1/audit`，需要 `audit:view`。
+- 一致性：`GET /api/v1/consistency` 与 `pnpm consistency:v25` 检查 counts、分区键、孤儿引用和审计覆盖。历史数据没有审计事件时只报 warning，不阻断关系表主源运行。
+
 兼容层仍保留通用服务端文档表 `app_data`：
-- 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`
+- 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`；V2.5 起所有业务 key 都由 `AppDataRetirementService` 标记为 `write_frozen` 或 `read_only_archive`，冻结写入返回 `409 APP_DATA_WRITE_FROZEN` 并给出替代领域 API。
 - 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
 - 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT`
-- 前端：各 Zustand store 保持现有 UI 数据形状，优先调用 `apps/web/lib/domain-api.ts`；领域 API 不可用时才通过 `apps/web/lib/server-data.ts` 读取或回退保存 AppData。
-- 仍留在 AppData 兼容配置中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。
+- 前端：各 Zustand store 保持现有 UI 数据形状，优先调用 `apps/web/lib/domain-api.ts`；`apps/web/lib/server-data.ts` 只保留兼容读取和冻结写入错误处理，不再作为业务保存 fallback。
+- 仍留在 AppData 历史形状中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。`members` 与 `overtime` AppData key 已禁写；这些配置的独立表/API 归 V2.7 管理治理阶段承接。
 - 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储
 
 关系表层包含 V2.2-V2.4 能力：
@@ -170,15 +176,17 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 
 生产数据库初始化使用 Prisma migration：`pnpm --filter server db:deploy`。本地开发仍可使用 `pnpm db:migrate`。
 
-## 权限模型（轻量）
+## 权限模型（V2.5）
 
-V1 仅做前端校验，无后端鉴权：
-- 版本 `members` 字段限定参与者
-- 版本列表/详情按 `members.contains(currentUser)` 过滤
-- 创建版本时自动加入创建者
-- 版本 `members` 为空时所有人可见（兼容旧数据）
+V2.5 后端 mutation API 已接入服务端 RBAC：
 
-V2 接入后端后改为基于 `ProjectMember` 表的 RBAC（Owner/Admin/Member/Viewer）。
+- 系统角色先按内置权限字典判断，`role-admin` 支持 wildcard `*`。
+- 带 `projectId` / `versionId` 的请求会解析资源作用域；项目成员角色按 Owner/Admin/Member/Viewer 授权。
+- 版本级资源如果能解析到项目，会优先用 `ProjectMember` 判断；具有系统权限的版本成员也可访问对应版本范围。
+- 未认证返回 401，已认证但无权限返回 403。
+- `@ProtectedMutation(permission, scope, audit)` 是领域写接口的统一入口，避免权限和审计在 controller 中分散实现。
+
+当前 auth context 仍是 V2.5 过渡 adapter：前端从 `ftb_auth_session` / `ftb_auth_persist` 读取当前用户并透传 `x-ftb-user-*` 头。JWT/NextAuth 服务端校验、企业级角色/部门/配置表属于 V2.7 之前需要协调的认证治理工作。
 
 ## AI Agent 层
 
@@ -308,8 +316,8 @@ The server also has lightweight observability for this phase: a global API timin
 Current source-of-truth boundary:
 
 - Product, Project, Version, Requirement, VersionPlan, DevTask, TestCase, Bug, Member, TaskCategory, TaskWorklog, OvertimeRecord, and WorkActivity now have public domain CRUD/write APIs.
-- Frontend stores use domain APIs as the primary mutation path. AppData reads and saves remain only as compatibility fallback while old deployments or partially migrated data are drained.
+- Frontend stores use domain APIs as the primary mutation path. AppData reads remain for archive/fallback inspection, but business AppData writes are frozen server-side and return `APP_DATA_WRITE_FROZEN`.
 - `products-overview` is no longer the product/project/version tree source of truth; it remains a compatibility document for fallback reads and rollback.
 - V2.2 read APIs and V2.3 relation sync remain compatibility infrastructure for fast reads, historical AppData imports, and rollback. They are no longer the main proof of data freshness for domains that now write relation tables directly.
 - `packages/shared` status contracts have been aligned with the current workflow statuses before the V2.4 write switch.
-- Conservative V2.4.5 boundary: Member identity fields are stored on `users`; departments, roles, password rules, and overtime reasons remain AppData compatibility/config until a dedicated RBAC/config schema phase.
+- V2.5 boundary: audit/RBAC/consistency are active on domain writes. Xiaobao risk snapshots/insights and warning read-state AppData keys are read-only archives pending V2.6 relation writer/backgrounding and V2.7 per-user read-state API.