docs(v25): 更新退场权限审计收口说明
This commit is contained in:
。
@@ -1,19 +1,19 @@
|
||||
# 开发路线图
|
||||
|
||||
## 当前阶段：V2.5 — AppData 分阶段退场 + RBAC/审计/一致性收口
|
||||
## 当前阶段：V2.5 已完成 — 下一阶段 V2.6 大数据性能增强 + 小宝预警后台化
|
||||
|
||||
V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。
|
||||
|
||||
V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性核对。AppData 不能直接删除，必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”的顺序推进。
|
||||
|
||||
### 当前重点
|
||||
### V2.5 完成范围
|
||||
|
||||
1. **RBAC 收口**：领域 mutation API 接入服务端权限校验、资源作用域和当前用户上下文。
|
||||
2. **审计事件**：所有领域 mutation 写 append-only audit event，支持后台查询和敏感字段脱敏。
|
||||
3. **AppData 禁写**：业务 AppData key 进入 `write_frozen` 或 `read_only_archive`，读仍可用，写返回明确替代领域 API。
|
||||
4. **导出归档**：提供 AppData archive export/verify 脚本，包含 checksum、key list 和应用版本元数据。
|
||||
5. **一致性校验**：提供 counts、partition key、orphan refs、audit coverage 的本地脚本和后台页面。
|
||||
6. **管理端可视化**：补 `/admin/audit` 与 `/admin/consistency`，并由 `audit:view` / `consistency:view` 控制。
|
||||
1. **RBAC 收口**：领域 mutation API 已接入服务端权限校验、资源作用域和当前用户上下文。
|
||||
2. **审计事件**：领域 mutation 通过 `audit_events` 写 append-only audit event，支持后台查询和敏感字段脱敏。
|
||||
3. **AppData 禁写**：业务 AppData key 已进入 `write_frozen` 或 `read_only_archive`，读仍可用，写返回明确替代领域 API。
|
||||
4. **导出归档**：已提供 AppData archive export/verify 脚本，包含 checksum、key list 和应用版本元数据。
|
||||
5. **一致性校验**：已提供 counts、partition key、orphan refs、audit coverage 的本地脚本和后台页面。
|
||||
6. **管理端可视化**：已补 `/admin/audit` 与 `/admin/consistency`，并由 `audit:view` / `consistency:view` 控制。
|
||||
|
||||
## V2 分阶段交付链路
|
||||
|
||||
@@ -36,14 +36,23 @@ V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性
|
||||
- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。
|
||||
- 后端已落地 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 已落地。
|
||||
- 主写入源已经切到领域 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 文档。
|
||||
- `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**
|
||||
- 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.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.
|
||||
@@ -134,12 +143,12 @@ V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性
|
||||
|
||||
### 进行中
|
||||
|
||||
- V2.4 领域 CRUD 主写迁移：从 AppData JSONB 主写入切换到关系表 API，并随 API 落基础权限、审计和查询性能边界。
|
||||
- V2.6 大数据性能增强与小宝预警后台化：压测、慢查询治理、后台任务、Xiaobao relation writer、幂等与失败重试。
|
||||
- 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）
|
||||
|
||||
## 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 关系表
|
||||
4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地）
|
||||
5. **领域 CRUD 主写入**：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表（V2.4 已完成）
|
||||
6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口
|
||||
7. **AppData 主路径移除**：完成迁移核对后逐模块删除 JSON fallback 和 `/data/:key` 主写入依赖
|
||||
8. **认证**：NextAuth.js + JWT
|
||||
9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
|
||||
6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口（V2.5 已收口）
|
||||
7. **AppData 主路径移除**：业务写入已冻结；后续按核对结果逐模块删除 JSON fallback 和 `/data/:key` 依赖
|
||||
8. **认证**：当前为 V2.5 header auth adapter；正式 NextAuth.js + JWT 服务端校验待后续治理
|
||||
9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别（V2.5 服务端 guard 已启用，企业级配置表待 V2.7）
|
||||
10. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
|
||||
|
||||
### 数据迁移策略
|
||||
@@ -171,6 +180,19 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSON
|
||||
|
||||
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 集成
|
||||
|
||||
详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
|
||||
@@ -239,7 +261,6 @@ V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只
|
||||
|------|------|
|
||||
| V1 业务流程打磨 | 进行中 |
|
||||
| V1 朋友试用反馈 | 持续中 |
|
||||
| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；RBAC/认证仍待后续阶段） |
|
||||
| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；V2.5 RBAC/审计/AppData 退场进行中） |
|
||||
| V2 后端接入 | 进行中（V2.5 RBAC/审计/AppData 退场已完成；V2.6/V2.7 待推进） |
|
||||
| V3 AI 集成 | 等 V2 数据沉淀 |
|
||||
| 公开发布 | TBD |
|
||||
|
||||
Reference in New Issue
Block a user