wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
。
2026-07-08 17:10:10 +08:00
parent 988d659fcc
commit a1007fd33d
5 changed files with 123 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/architecture.md
View File

@@ -47,7 +47,7 @@ apps/web/
│ ├── versions/ # 版本列表 + 详情 │ ├── versions/ # 版本列表 + 详情
│ ├── requirements/ # 需求池 │ ├── requirements/ # 需求池
│ ├── workspace/ # 与我相关（聚合工作台） │ ├── workspace/ # 与我相关（聚合工作台）
│ └── admin/ # 系统管理（任务类型字典等） │ └── admin/ # 系统管理（成员/角色/任务类型/审计/一致性/AI 配置）
├── components/ ├── components/
│ ├── product/ # 产品组件 │ ├── product/ # 产品组件
│ ├── version/ # 版本组件（PlanTab, CapsuleStages, MemberChips...） │ ├── version/ # 版本组件（PlanTab, CapsuleStages, MemberChips...）
@@ -122,12 +122,18 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
- 版本详情：VersionPlan、DevTask、TestCase、Bug 直接按 `versionId` 分区键写关系表，并继续标脏 Xiaobao 摘要和写入工作活动证据。 - 版本详情：VersionPlan、DevTask、TestCase、Bug 直接按 `versionId` 分区键写关系表，并继续标脏 Xiaobao 摘要和写入工作活动证据。
- 字典/成员/证据：Member 写 `users` 的成员身份字段；TaskCategory 写 `task_categories`；TaskWorklog、OvertimeRecord、WorkActivity 保持追加/证据型关系表写入。 - 字典/成员/证据：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`： 兼容层仍保留通用服务端文档表 `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 - 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
- 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT` - 一致性：`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。 - 前端：各 Zustand store 保持现有 UI 数据形状，优先调用 `apps/web/lib/domain-api.ts`；`apps/web/lib/server-data.ts` 只保留兼容读取和冻结写入错误处理，不再作为业务保存 fallback。
- 仍留在 AppData 兼容配置中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。 - 仍留在 AppData 历史形状中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。`members` 与 `overtime` AppData key 已禁写；这些配置的独立表/API 归 V2.7 管理治理阶段承接。
- 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储 - 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储
关系表层包含 V2.2-V2.4 能力： 关系表层包含 V2.2-V2.4 能力：
@@ -170,15 +176,17 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
生产数据库初始化使用 Prisma migration：`pnpm --filter server db:deploy`。本地开发仍可使用 `pnpm db:migrate`。 生产数据库初始化使用 Prisma migration：`pnpm --filter server db:deploy`。本地开发仍可使用 `pnpm db:migrate`。
## 权限模型（轻量） ## 权限模型（V2.5）
V1 仅做前端校验，无后端鉴权： V2.5 后端 mutation API 已接入服务端 RBAC：
- 版本 `members` 字段限定参与者
- 版本列表/详情按 `members.contains(currentUser)` 过滤
- 创建版本时自动加入创建者
- 版本 `members` 为空时所有人可见（兼容旧数据）
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 层 ## AI Agent 层
@@ -308,8 +316,8 @@ The server also has lightweight observability for this phase: a global API timin
Current source-of-truth boundary: 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. - 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. - `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. - 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. - `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.

15
docs/decisions.md
View File

@@ -608,3 +608,18 @@
- 一次性同步脚本可以存在，但必须作为运维迁移工具管理，不能依赖提交 `.env` 或手工修改源码开关。 - 一次性同步脚本可以存在，但必须作为运维迁移工具管理，不能依赖提交 `.env` 或手工修改源码开关。
**理由**：系统未来要承载大量需求、任务、测试用例、Bug、活动和风险数据。关系表才能提供可验证的约束、事务、索引、分页、权限和审计能力。AppData 是低风险迁移桥，不是最终架构；继续扩大 JSON 主存储会把数据一致性和性能问题推迟到更难修的阶段。 **理由**：系统未来要承载大量需求、任务、测试用例、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 合同。

14
docs/deployment.md
View File

@@ -221,6 +221,20 @@ pnpm appdata:archive:verify -- --archive backups/appdata-archive-20260708120000.
生产环境执行导出前需要确保 `DATABASE_URL` 指向当前 PostgreSQL。默认输出文件名为 `appdata-archive-<timestamp>.json`，该模式已加入 `.gitignore`；真实归档应放入服务器备份目录或对象存储，不提交到代码仓库。 生产环境执行导出前需要确保 `DATABASE_URL` 指向当前 PostgreSQL。默认输出文件名为 `appdata-archive-<timestamp>.json`，该模式已加入 `.gitignore`；真实归档应放入服务器备份目录或对象存储，不提交到代码仓库。
## V2.5 一致性校验
完成数据库 migration、AppData 写冻结和归档导出后，建议在发布窗口内运行一致性校验：
```bash
pnpm consistency:v25 -- --url http://localhost/api/v1/consistency
```
本地开发默认检查 `http://localhost:3001/api/v1/consistency`，也可以不传 `--url`。校验内容包括 counts、分区键、孤儿引用和审计覆盖：
- `error` 必须在发布前修复。
- `warn` 需要记录原因；历史数据没有审计事件属于预期 warning，不阻断 V2.5。
- 后台页面 `/admin/consistency` 展示同一份报告，需要当前用户具备 `consistency:view`。
## 升级流程 ## 升级流程
```bash ```bash

57
docs/roadmap.md
View File

@@ -1,19 +1,19 @@
# 开发路线图 # 开发路线图
## 当前阶段：V2.5 — AppData 分阶段退场 + RBAC/审计/一致性收口 ## 当前阶段：V2.5 已完成 — 下一阶段 V2.6 大数据性能增强 + 小宝预警后台化
V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。 V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。
V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性核对。AppData 不能直接删除，必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”的顺序推进。 V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性核对。AppData 不能直接删除，必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”的顺序推进。
### 当前重点 ### V2.5 完成范围
1. **RBAC 收口**：领域 mutation API 接入服务端权限校验、资源作用域和当前用户上下文。 1. **RBAC 收口**：领域 mutation API 已接入服务端权限校验、资源作用域和当前用户上下文。
2. **审计事件**：所有领域 mutation 写 append-only audit event，支持后台查询和敏感字段脱敏。 2. **审计事件**：领域 mutation 通过 `audit_events` 写 append-only audit event，支持后台查询和敏感字段脱敏。
3. **AppData 禁写**：业务 AppData key 进入 `write_frozen` 或 `read_only_archive`，读仍可用，写返回明确替代领域 API。 3. **AppData 禁写**：业务 AppData key 已进入 `write_frozen` 或 `read_only_archive`，读仍可用，写返回明确替代领域 API。
4. **导出归档**：提供 AppData archive export/verify 脚本，包含 checksum、key list 和应用版本元数据。 4. **导出归档**：已提供 AppData archive export/verify 脚本，包含 checksum、key list 和应用版本元数据。
5. **一致性校验**：提供 counts、partition key、orphan refs、audit coverage 的本地脚本和后台页面。 5. **一致性校验**：已提供 counts、partition key、orphan refs、audit coverage 的本地脚本和后台页面。
6. **管理端可视化**：补 `/admin/audit` 与 `/admin/consistency`，并由 `audit:view` / `consistency:view` 控制。 6. **管理端可视化**：已补 `/admin/audit` 与 `/admin/consistency`，并由 `audit:view` / `consistency:view` 控制。
## V2 分阶段交付链路 ## V2 分阶段交付链路
@@ -36,14 +36,23 @@ V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性
- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。 - 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。
- 后端已落地 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime、WorkActivity 领域 CRUD/write API。 - 后端已落地 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime、WorkActivity 领域 CRUD/write API。
- Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、TaskWorklog、Overtime、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。 - Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、TaskWorklog、Overtime、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
- 主写入源已经切到领域 API：前端 store 优先调用 `apps/web/lib/domain-api.ts`，AppData 只保留兼容读取、失败回退和少量配置。 - 主写入源已经切到领域 API：前端 store 优先调用 `apps/web/lib/domain-api.ts`，AppData 只保留兼容读取、历史核对和少量旧配置形状。
- V2.5 后端服务端权限、审计和一致性控制面已启用：领域 mutation 使用 `@ProtectedMutation()`，审计写 `audit_events`，后台查询需要 `audit:view` / `consistency:view`。
- 所有业务 AppData key 已明确冻结或只读归档；`PUT /api/v1/data/:key` 对这些 key 返回 `APP_DATA_WRITE_FROZEN`，`GET` 留作历史核对与归档。
- 需求池已切到服务端分页、搜索、筛选、排序，不再要求加载全量 AppData 文档。 - 需求池已切到服务端分页、搜索、筛选、排序，不再要求加载全量 AppData 文档。
- `packages/shared` 状态契约已统一为当前业务状态机。 - `packages/shared` 状态契约已统一为当前业务状态机。
- V2.4.5 保守边界：成员身份写 `users`；部门、角色、密码规则、加班原因暂留 AppData 配置，等待后续 RBAC/配置表阶段。 - V2.6/V2.7 协调边界：Xiaobao risk snapshots/insights 关系表写入和后台化归 V2.6；warning read-state API、部门/角色/密码规则/加班原因配置表归 V2.7。
### 已完成（按时间倒序） ### 已完成（按时间倒序）
**2026-07-08** **2026-07-08**
- V2.5.0 added server auth context, current-user decorator, permission decorator/guard/service, wildcard super admin support, project/version-member scope checks, and guard/service tests.
- V2.5.1 added append-only `audit_events`, audit service/controller/query DTO, sensitive-field redaction, `audit:view`, and audit service/controller tests.
- V2.5.2 protected V2.4 domain mutation APIs with server-side permission metadata and audit writes through `@ProtectedMutation()`.
- V2.5.3 froze AppData business writes through `AppDataRetirementService`, returning `APP_DATA_WRITE_FROZEN` while preserving reads and replacement-path hints.
- V2.5.4 added AppData archive export/verify scripts and package scripts with checksum, key list, and app version metadata.
- V2.5.5 added consistency module/controller/script for counts, partition keys, orphan refs, and audit coverage; historical audit gaps are warnings.
- V2.5.6 added `/admin/audit` and `/admin/consistency` pages plus frontend API helpers and permission entries.
- V2.4.0 completed shared domain status contract alignment for Requirement, VersionPlan, DevTask, TestCase, Bug, and Version. - V2.4.0 completed shared domain status contract alignment for Requirement, VersionPlan, DevTask, TestCase, Bug, and Version.
- V2.4.1 switched Product / Project / Version root mutations to domain APIs and left `products-overview` as compatibility fallback. - V2.4.1 switched Product / Project / Version root mutations to domain APIs and left `products-overview` as compatibility fallback.
- V2.4.2 switched Requirement writes to relation-table CRUD and added server-side pagination, search, filters, sorting, and cursor support for the requirement pool. - V2.4.2 switched Requirement writes to relation-table CRUD and added server-side pagination, search, filters, sorting, and cursor support for the requirement pool.
@@ -134,12 +143,12 @@ V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性
### 进行中 ### 进行中
- V2.4 领域 CRUD 主写迁移：从 AppData JSONB 主写入切换到关系表 API，并随 API 落基础权限、审计和查询性能边界。 - V2.6 大数据性能增强与小宝预警后台化：压测、慢查询治理、后台任务、Xiaobao relation writer、幂等与失败重试。
- 项目详情页 VersionCard 状态胶囊数据联动（部分已完成） - 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）
## V2 — 后端接入 ## V2 — 后端接入
NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步；第三阶段 V2.4 已逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD 主写。 NestJS + Prisma + PostgreSQL 已推进到 V2.5。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步；第三阶段 V2.4 已逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD 主写；第四阶段 V2.5 已冻结 AppData 业务写入并收口服务端 RBAC、审计和一致性校验。
### 关键任务 ### 关键任务
@@ -148,10 +157,10 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSON
3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表 3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地） 4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地）
5. **领域 CRUD 主写入**：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表（V2.4 已完成） 5. **领域 CRUD 主写入**：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表（V2.4 已完成）
6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口 6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口（V2.5 已收口）
7. **AppData 主路径移除**：完成迁移核对后逐模块删除 JSON fallback 和 `/data/:key` 主写入依赖 7. **AppData 主路径移除**：业务写入已冻结；后续按核对结果逐模块删除 JSON fallback 和 `/data/:key` 依赖
8. **认证**：NextAuth.js + JWT 8. **认证**：当前为 V2.5 header auth adapter；正式 NextAuth.js + JWT 服务端校验待后续治理
9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别 9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别（V2.5 服务端 guard 已启用，企业级配置表待 V2.7）
10. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层 10. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
### 数据迁移策略 ### 数据迁移策略
@@ -171,6 +180,19 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSON
V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只用于 fallback、历史迁移和少量配置。部门、角色、密码规则、加班原因仍作为兼容配置保留，后续由 RBAC/配置表阶段单独收口。 V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只用于 fallback、历史迁移和少量配置。部门、角色、密码规则、加班原因仍作为兼容配置保留，后续由 RBAC/配置表阶段单独收口。
## V2.5 — AppData 退场 + RBAC/审计/一致性收口（已完成）
V2.5 在 V2.4 领域 CRUD 主写基础上完成横切收口：
1. Server auth context、`@CurrentUser()`、`@RequirePermission()`、`PermissionGuard` 和 `PermissionService` 已落地。
2. `@ProtectedMutation()` 成为领域写接口统一入口，同时挂权限、资源作用域和审计 metadata。
3. `audit_events` append-only 表、审计查询接口和 `/admin/audit` 页面已落地。
4. `AppDataRetirementService` 集中声明每个 AppData key 的 `write_frozen` / `read_only_archive` 状态与替代路径。
5. AppData archive export/verify 脚本已落地，归档包含 checksum、key list 和 app version metadata。
6. Consistency module、`pnpm consistency:v25` 和 `/admin/consistency` 页面已落地。
V2.5 完成后的保留边界：`GET /api/v1/data/:key` 仍可读历史 JSON；Xiaobao risk archive、warning read state、部门/角色/密码规则和加班原因配置表分别交给 V2.6/V2.7，不在 V2.5 临时发明不稳定 schema。
## V3 — AI Agent 集成 ## V3 — AI Agent 集成
详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。 详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
@@ -239,7 +261,6 @@ V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只
|------|------| |------|------|
| V1 业务流程打磨 | 进行中 | | V1 业务流程打磨 | 进行中 |
| V1 朋友试用反馈 | 持续中 | | V1 朋友试用反馈 | 持续中 |
| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；RBAC/认证仍待后续阶段） | | V2 后端接入 | 进行中（V2.5 RBAC/审计/AppData 退场已完成；V2.6/V2.7 待推进） |
| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；V2.5 RBAC/审计/AppData 退场进行中） |
| V3 AI 集成 | 等 V2 数据沉淀 | | V3 AI 集成 | 等 V2 数据沉淀 |
| 公开发布 | TBD | | 公开发布 | TBD |

36
docs/workflow.md
View File

@@ -130,8 +130,9 @@
## 测试 / 验证流程 ## 测试 / 验证流程
- 改动后必须 `npx tsc --noEmit` 通过 - 改动后必须 `pnpm type-check` 通过
- 涉及服务端数据持久化：`pnpm --filter server exec prisma validate --schema prisma/schema.prisma` - 涉及服务端数据持久化：`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 - 涉及 UI 改动：`curl http://localhost:3000/<path>` 检查 200
- 不会自动跑 dev server，假定它已经运行 - 不会自动跑 dev server，假定它已经运行
@@ -167,6 +168,37 @@
新增领域 store 时，先写 source contract 测试证明主写不是 `saveServerData('<key>')`，再实现领域 API 和 fallback。 新增领域 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）数据流 ## 与我相关（Workspace）数据流
``` ```