wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f69ec831930a8b9b00704375099e1f5b9dca530c
ftb-project-management/docs/roadmap.md
。 f69ec83193 feat(v2.7): 收口治理权限适配器
2026-07-08 16:44:57 +08:00

19 KiB
Raw Blame History

开发路线图

当前阶段：V2.7 — 企业级协作能力 + 管理治理

V2.7 的目标是在关系表主源方向上补齐企业协作和治理能力：通知、评论与提及、项目成员治理、管理驾驶舱、治理字典、以及统一 RBAC/audit 适配器。当前执行前提为 V2.4 已由用户确认完成；V2.7 不再新增 AppData 主存储。

当前重点

  1. 协作通知：通知记录、已读状态、NotificationBell，并覆盖 assignment / mention / risk_alert / overdue_item 稳定事件类型。
  2. 通用评论：DevTask/TestCase/Bug/Requirement/VersionPlan 统一评论面板，支持 @成员名 和显式成员选择，创建/删除写 audit。
  3. 项目成员治理：Owner/Admin/Member/Viewer 服务端强校验，禁止移除最后 Owner，角色变更写 audit。
  4. 管理驾驶舱：只读关系表和 summary，聚合活跃版本、逾期、阻塞、风险和成员负载。
  5. 治理设置：集中维护 task category、requirement type/platform/source，使用中的字典不可硬删，支持导入导出。

历史阶段：V2.4 — 领域 CRUD 主写迁移

V2.4 的目标是把业务主数据源从 AppData JSONB 文档切换到 PostgreSQL 领域关系表。AppData 继续保留为迁移、回填、兼容读取和排查入口，但不再作为长期主写入源；新增业务能力必须优先设计关系表、领域 CRUD API、索引/分区键和权限边界。V2.4 做逐领域主写迁移，并随 CRUD 入口埋好基础权限、actorId 和审计事件骨架；完整 RBAC、审计覆盖和 AppData 退场收口放到 V2.5。

当前重点

  1. 领域写 API：按模块补齐 Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/Worklog/Overtime 的关系表写入 API。
  2. 前端持久化切换：Zustand store 保留状态管理，但保存入口从 saveServerData(key) 迁到领域 API；读取优先 V2.2/V2.3 关系表接口。
  3. AppData 迁移工具化：把 AppData → 关系表同步做成可重复运行、可计数校验、可回滚的运维脚本，不提交真实 .env。
  4. 主写切换闸门：每个领域完成双读核对后，先停止该领域 JSON 主写入，再进入 V2.5 的 fallback 移除和归档退场。
  5. 数据一致性校验：为每个迁移领域补 counts、抽样记录、孤儿引用、分区键完整性和唯一约束校验。
  6. 权限/审计骨架：领域 API 必须携带当前用户、产品/项目/版本作用域和审计事件入口，避免 V2.5 做 RBAC 时返工。

V2 分阶段交付链路

阶段 主题 边界
V2.1 AppData 服务端持久化 业务数据从浏览器 localStorage 迁到服务端 app_data，先解决清站点数据丢失问题。
V2.2 关系表 + 分区 + 快读 API 建高增长领域表、分区键、快读查询和小宝摘要读取，写入仍走 AppData。
V2.3 AppData 写入后同步关系表 AppData 仍是兼容期写入事实源，保存成功后非阻塞同步关系表和风险摘要脏标记。
V2.4 领域 CRUD 主写迁移 逐领域补写 API，前端保存迁到领域 API；同时埋权限、作用域、审计和分页/索引基础。
V2.5 AppData 分阶段退场 + RBAC/审计/一致性收口 禁写 AppData、移除 fallback、归档/导出旧 JSON，正式收紧权限、审计和一致性校验。
V2.6 大数据性能增强 + 小宝预警后台化 在关系表主源稳定后做压测、慢查询治理、缓存/摘要、后台任务、幂等重试和小宝定时预警。
V2.7 企业级协作能力 + 管理治理 补齐通知、协同、组织治理、管理视图、数据治理和企业级配置能力。
V2.8 生产硬化稳定版 + 运维闭环 在现有 CI/CD 基线上补备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚和运维手册。

阶段顺序不能倒置：权限/审计骨架从 V2.4 开始随领域 API 落地，V2.5 做全面收口；分页、索引、分区键查询从 V2.4 就必须进入 API 设计，V2.6 只做增强和压测治理；AppData 退场必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”推进，不能一次性删除历史 JSON。

当前状态快照（2026-07-08）

  • 项目已经不是早期骨架。前端业务功能已覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要管理端路由。
  • 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入 V2.2 关系表快读，并保留 AppData fallback。
  • 后端已落地 Product、Requirement 领域 CRUD，DataModule AppData 乐观锁，V2.2 快读 API，V2.3 AppData 写后同步关系表，AI Provider 抽象和健康版本接口。
  • Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
  • 主写入源仍处在兼容窗口：多数前端 store 继续通过 apps/web/lib/server-data.ts 的 loadServerData / saveServerData 写 AppData；useProductStore 仍以 products-overview 文档作为产品/项目/版本树主写入。
  • Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等领域写 API 尚未完整替代 AppData Store。若后续称为 V2.4，应理解为“领域 CRUD 迁移阶段”，不是 V2.3 已完成内容。
  • packages/shared 中仍保留早期枚举口径；切换领域 API 时需要统一为当前前端业务状态机。

已完成（按时间倒序）

2026-07-06

  • Added production CI/CD flow: GitHub Actions builds web and server Docker images, pushes immutable commit-SHA tags to GHCR, deploys by SSH, pulls images on the server, runs pnpm --filter server db:deploy, restarts Compose, and verifies /api/v1/health/version.
  • Added runtime version metadata: backend GET /api/v1/health/version, Docker build args/env, and a frontend refresh banner when browser assets are older than the server runtime.
  • Added pnpm deploy:check-runtime and expanded pnpm deploy:verify so deployment artifacts include workflow, image metadata, and runtime version checks.

2026-07-03

  • V2.3 AppData write-side bridge added: successful PUT /api/v1/data/:key calls now trigger AppDataV23SyncService relation-table sync after optimistic-lock AppData writes.
  • Relation sync reuses the V2.2 mapper and replaces current-state rows by partition scope: requirements by product_id, version plans/dev tasks/test cases/bugs by version_id.
  • Append-only evidence tables continue to use duplicate-skipping inserts for work activities, worklogs, overtime, Xiaobao snapshots, and Xiaobao insights.
  • Xiaobao summaries now refresh from risk snapshots and are marked dirty=true when version risk inputs change.
  • Added lightweight observability: slow API request logging through a global Nest interceptor and slow Prisma query logging through query events.
  • V2.2 partitioned domain schema foundation added: requirements uses HASH partitioning by product_id; dev_tasks, test_cases, and bugs use HASH partitioning by version_id.
  • Partitioned table primary keys and business unique constraints now include partition keys, for example (id, version_id) and (version_id, code).
  • Xiaobao precompute storage foundation added: xiaobao_risk_summaries stores the current version risk, and xiaobao_risk_snapshots stores historical snapshots.
  • Prisma schema now includes the V2.2 relational model skeleton, and the legacy RequirementService now uses the (id, product_id) composite key.
  • AppData V2.2 migration mapper and preview service added, so legacy JSON can be rehearsed into relation-table rows with counts and skipped-record diagnostics before inserts are enabled.
  • V2.2 scoped read API added for version detail, requirement pool, workspace, and Xiaobao warning summaries.
  • Version detail, requirement pool, workspace, sidebar badges, version list Xiaobao indicators, and Xiaobao warning page now prefer V2.2 fast-read data and fall back to AppData only for compatibility.
  • Requirement pool V2.2 queries require productId, avoiding accidental full-table scans against annual hundreds-of-thousands-row data.
  • Xiaobao warning now consumes precomputed xiaobao_risk_summaries before loading heavy AppData task/test/bug/activity documents.
  • V2.2 completion boundary: read hot paths are complete; writes remain on AppData until the relation-table write APIs are enabled.

2026-07-02

  • app_data 读写增加乐观锁版本：GET 返回 version，前端保存携带最近版本，后端用 key + updatedAt 原子更新
  • stale version / create race 返回 409 APP_DATA_CONFLICT，阻止多人同时编辑时的静默覆盖
  • 新增后端 AppData 并发写入回归测试和前端 server-data 版本缓存测试

2026-07-01

  • 补齐云服务器生产部署基线：Dockerfile.web、Dockerfile.server、docker-compose.prod.yml、Nginx 反代模板和 .env.production.example
  • 补齐本地服务器/局域网部署基线：docker-compose.local.yml、.env.local-server.example、deploy:local:* 脚本
  • 新增生产数据库初始化 migration，并提供 pnpm db:deploy / pnpm --filter server db:deploy
  • 新增 pnpm deploy:verify 校验生产部署文件完整性
  • 新增 docs/deployment.md，覆盖本地开发、云服务器部署、升级、备份和排查流程

2026-06-24

  • 新增 NestJS DataModule + Prisma AppData，提供 GET/PUT /api/v1/data/:key
  • 产品/项目/版本树、需求池、调研/产品方案/UI、开发任务、测试用例、Bug 改为服务端持久化
  • 成员/角色/部门、任务类型、任务工时日志、加班记录改为服务端持久化
  • 登录改为读取服务端成员数据；浏览器只保留登录会话

2026-06-16

  • 项目模块顶部卡片（总版本数/已开发/需求数/Bug 总数）
  • 项目模块版本记录与版本详情数据联动（耗时 + 状态胶囊）
  • 4 份核心文档：architecture / decisions / workflow / roadmap

2026-06-15

  • 与我相关：产品/项目/版本树筛选 + 红色待办徽标
  • 与我相关：点击卡片打开 Drawer（PlanDetailDrawer 新建，DevTask/TestCase/Bug 复用）
  • 全局 Drawer 阴影统一 shadow-2xl + 顶部上下文条
  • 测试用例提 Bug 流程：drawer 内点击 → BugCreateModal
  • DevTask + TestCase 转交功能（人员离职场景）
  • 需求池：录入人员自动取当前用户 + 状态列改名（业务状态 / 实际进度）
  • 产品页面：去掉规划中、项目名/版本胶囊可点击跳转

2026-06-14

  • 需求变更模块：变更人员/原因/概述/详细 + 概览统计（变更人员排名 + 原因占比饼图）
  • 计划任务转交（未开始/进行中可转交，从参与人员选）
  • 关联需求增强：描述列 hover 完整内容、需求类型/变更原因/添加日期列
  • 计划时间精确到分钟（datetime-local）+ 到期自动开始
  • 阶段耗时 + 个人耗时排名（涵盖调研/产品/UI/开发/测试 5 类工作）

2026-06-13

  • DevTask 状态简化：去掉 done，submitted 是终态
  • 实际工时改为精确时间戳计算（精确到 0.5h）
  • TestCase 主归属版本，requirement 改为可选标签
  • Bug 直接挂版本（versionId 字段）
  • linkage-engine（需求 ↔ DevTask 派生）
  • workspace-engine（统一 WorkItem 聚合）

2026-06-12 及更早

  • 完整模块：需求池/版本管理/计划任务（调研/产品/UI）/开发任务/测试用例/Bug
  • 加班记录 + 排名 + 原因占比饼图
  • 健康度计算 + 风险标签
  • 版本执行态自动推导

进行中

  • V2.4 领域 CRUD 主写迁移：从 AppData JSONB 主写入切换到关系表 API，并随 API 落基础权限、审计和查询性能边界。
  • 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）

V2 — 后端接入

NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 app_data JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。当前 V2.4 才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD；AppData 后续只保留为迁移兼容层。

关键任务

  1. 服务端文档层：app_data + /api/v1/data/:key（第一阶段已实现）
  2. localStorage → API 切换：业务主数据不再写浏览器（第一阶段已实现）
  3. 运行 Prisma 同步/迁移：本地和服务器数据库都需要创建 app_data 与 V2.2/V2.3 关系表
  4. 关系化拆表：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型和同步桥已落地，领域写 API 仍待迁移）
  5. 领域 CRUD 主写入：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表
  6. 基础权限/审计骨架：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口
  7. AppData 主路径移除：完成迁移核对后逐模块删除 JSON fallback 和 /data/:key 主写入依赖
  8. 认证：NextAuth.js + JWT
  9. 权限：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
  10. 版本规则引擎收敛：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层

数据迁移策略

当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。

V2.4 — 领域 CRUD 迁移（当前阶段）

目标是让关系表从“快读 + AppData 同步副本”逐步升级为主写入路径。迁移顺序应优先选择写入频率高、实体边界清晰、已经在 V2.2 mapper 中稳定的领域：

  1. Project / Version：替代 products-overview 中的项目和版本主写入，保留产品树兼容读取。
  2. VersionPlan / DevTask / TestCase / Bug：按 versionId 分区键提供领域写 API，写入后继续复用现有小宝 dirty 策略和工作活动记录。
  3. Member / TaskCategory：替代 members、task-categories AppData 文档，统一权限、人员和任务类型字典来源。
  4. TaskWorklog / Overtime / WorkActivity：保留追加型写入语义，避免从当前 AppData 快照反向删除历史证据。
  5. 前端 store 分批切换：每切一个领域，都要保留兼容读取和回滚路径，直到 AppData 对应 key 不再是事实源。

V2.4 推进前必须先统一 packages/shared 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 draft/reviewing/approved 或 todo/in_review/done/closed 状态重新带回系统。

V3 — AI Agent 集成

详细 Agent 规范见 agent-spec.md。本节只列规划，不重复 Agent 实现细节。

V3.1 — Prototype Decompose Agent（首个 Agent）

目标：从产品方案的原型 + 关联需求，拆解出开发任务草案 + 测试用例草案；原型中明确可拆但没有匹配到关联需求的内容，按无需求ID分组进入任务/用例，不补需求池。

已完成的数据底座（2026-06）：

  • DevTask / TestCase 加 references[] + aiDraft + aiDraftAt
  • 创建表单加「原型批注」字段
  • 列表中 AI 草案视觉区分（紫色边 + 徽章）
  • 编辑后自动清除 aiDraft 标记
  • agent-spec.md / glossary.md 文档落地
  • 约定：原型链接 = 产品方案 (VersionPlan type=product) 已完成计划的 resultUrl，不在 Version 上独立存储

待实现：

  1. 后端 AiGateway + PrototypeDecomposeService（NestJS module）
  2. 前端「AI 拆解任务和用例」按钮（产品方案 Tab）
  3. 对账报告组件（弹窗呈现：完美对应 / 需求未见原型 / 无需求ID分组 / 含糊）
  4. 用户确认后批量创建 DevTask + TestCase 草案
  5. DevTask 增加 versionId，requirementId 改为可选，兼容旧数据通过需求反查版本
  6. AiLog 表（调用记录、token 计量、用时）

MVP 范围限制：

  • 不自动分配 assignee（留给用户在草案上手填）
  • 不做"上一版基准 diff"（按 decisions.md #17 决议）
  • 单 Agent 单 Round，不做多 Agent 编排

V3.2 — 小宝预警 / Risk Watch Agent

小宝预警以版本发版风险为核心，先通过规则引擎计算风险分、趋势、静默风险、预计可发日期和置信度，再由 Risk Watch Agent 自动解释高风险版本。第一版已落地页面触发模式：打开 /xiaobao-warning 时保存当天快照，并在满足触发条件时自动生成 AI 解读。

当前不做后台定时 Agent。后续如果需要主动通知，再在已有 xiaobao-risk-snapshots 和 xiaobao-risk-insights 基础上增加定时巡检与消息推送。

Schedule Suggest Agent：基于成员负载和历史耗时，建议下一阶段任务分配，仍作为后续候选。

多 Agent 协作设计：等 Risk Watch 与 Schedule Suggest 都稳定后再设计编排策略。

V3.3 — 其他场景候选

  1. 需求智能分类（自动归档到产品 / 项目）
  2. 健康度智能解读（数据指标 → 自然语言报告）
  3. 需求转任务（需求采纳后一键生成 DevTask 草稿）

落地约束

  • 不直接动数据：所有 Agent 写入必须带 aiDraft: true，用户编辑后才转正
  • 必须有引用：所有 AI 产物带 references，用户能追溯到源头
  • 必须有对账报告：拆解类 Agent 输出前端展示结构化报告，让用户决策
  • 不补需求池：无需求ID分组只进入 DevTask/TestCase，不创建 Requirement，不加入关联需求列表
  • 可降级：原型不可达 / 输入数据不全 / 模型超时，明确告知用户失败原因，不写入任何数据

不在路线图（明确不做）

  • Jira/TAPD 替代品：定位是产品/项目经理视角，不是开发任务管理
  • 测试套件/测试计划：测试用例是版本验收手段，不做完整测试管理
  • Gantt 甘特图：现有的胶囊状态条 + 阶段耗时已经够用
  • 看板视图：DevTask 列表 + 筛选 + 状态流转已够用
  • 回归测试：测试用例不做版本间复用
  • 客户/合同管理：超出研发管理边界

关键里程碑

节点 状态
V1 业务流程打磨 进行中
V1 朋友试用反馈 持续中
V2 后端接入 进行中（V2.1/V2.2/V2.3 已完成，V2.4 主写迁移中）
V3 AI 集成 等 V2 数据沉淀
公开发布 TBD
2026-06-26
  • Workspace daily report upgraded from manual worklog summary to mixed activity aggregation.
  • Added work-activities AppData key and a typed activity factory for VersionPlan, DevTask, TestCase, and Bug actions.
  • /workspace daily report now groups delivery/progress/creation/risk/progress-note records and flags in-progress work that needs today's progress update.