wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2e595c7e72f1fa4afd07cefe5e198b85e5afb987
ftb-project-management/docs/roadmap.md
。 2e595c7e72
Some checks failed
Deploy Production / Build, push, deploy, verify (push) Has been cancelled
Details
refactor(data): 收口关系表运行时数据源 
- 移除已迁移业务 AppData 运行时 fallback，改走领域 API 和关系表快读
- 补齐需求产品负责人、版本计划任务 JSON 和成员 username 回填迁移
- 统一治理字典入口，并补充 AI provider、数据源契约和领域服务测试

Co-Authored-By: Codex GPT-5 <codex@openai.com>
2026-07-09 14:59:49 +08:00

34 KiB
Raw Blame History

开发路线图

当前阶段：V2.8 已完成 — 统一验证与生产交付收口

V2.8 已在既有生产 CI/CD 基线上补齐运维闭环：备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚 runbook、AppData 退场 runbook、小宝后台化 runbook 和生产 readiness 证据清单。本阶段不重新设计业务流程，专注把生产发布和故障处置做成可验证、可复盘、可回滚的标准流程。

V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表”。V2.5 已收口后端权限、审计、AppData 禁写和一致性核对，并移除正常业务运行时 AppData fallback。V2.6 已完成大数据性能增强、小宝风险后台化、AI 解读队列和运行时 Ops 看板。V2.7 已补齐企业协作和治理能力，且不新增 AppData 主存储。

V2.5-V2.8 完成范围

  1. RBAC 收口：领域 mutation API 已接入服务端权限校验、资源作用域和当前用户上下文。
  2. 审计事件：领域 mutation 通过 audit_events 写 append-only audit event，支持后台查询和敏感字段脱敏。
  3. AppData 禁写：业务 AppData key 已进入 write_frozen 或 read_only_archive，正常业务 UI 不再读取这些 key；GET 仅用于迁移、归档和人工核对，写返回明确替代领域 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 控制。
  7. 性能压测与热查询治理：已补 deterministic fixture、perf:check、perf:explain、热查询索引审计和性能预算文档。
  8. 后台任务运行时：已补 PostgreSQL-backed background_jobs、dedupe、lease、retry、失败记录和单步 worker。
  9. 小宝后台化：已补服务端 summary refresh、dirty/enqueue 桥接和 xiaobao.ai.interpret AI 解读队列。
  10. Ops 看板：已补 /admin/ops 与 GET /api/v1/ops/runtime，展示慢请求、慢查询、job 队列和 dirty summary 数。
  11. 协作通知：已补通知记录、已读状态和 NotificationBell，覆盖 assignment / mention / risk_alert / overdue_item 稳定事件类型。
  12. 通用评论：DevTask/TestCase/Bug/Requirement/VersionPlan 已接入统一评论面板，支持 @成员名、显式成员选择、删除和审计。
  13. 项目成员治理：已补项目成员 Owner/Admin/Member/Viewer 服务端治理，禁止移除最后 Owner，角色变更写审计。
  14. 管理驾驶舱：已补只读关系表和 summary 的管理概览，聚合活跃版本、逾期、阻塞、风险和成员负载。
  15. 治理设置：/admin/governance 统一维护任务类型、需求类型、支持端与需求来源；需求池消费治理字典，不再本地维护这些字典。
  16. 备份恢复自动化：已补 PostgreSQL dump、server_data volume 备份、fresh DB restore dry-run 和显式覆盖确认。
  17. 发布 smoke test：已补部署后 runtime version、前端根页、产品页、产品 API、V2.2 读路径和 AI 配置校验。
  18. 监控告警基线：已补 Prometheus/Grafana/Loki/Promtail 可选 profile，覆盖慢 API、慢 Prisma、任务失败、小宝摘要 stale、磁盘压力和 DB 可用性。
  19. 运维 runbook：已补迁移回滚、AppData 退场、小宝后台化处置步骤、决策点和数据风险。
  20. 生产 readiness 清单：已补 backup/restore、smoke、monitoring、audit、RBAC、consistency、performance 和 post-release verification 证据项。

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；渲染重的路径优先接入关系表快读，快读不可用时改走关系表领域 store，不再回读业务 AppData 文档。
  • 后端已落地 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、Notification、Comment、ProjectMember、GovernanceDictionary 等关系模型；高增长表的分区 migration 已落地。
  • 主写入源已经切到领域 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 留作迁移、历史核对与归档，不再服务正常业务 fallback。
  • 需求池已切到服务端分页、搜索、筛选、排序，不再要求加载全量 AppData 文档。
  • packages/shared 状态契约已统一为当前业务状态机。
  • V2.6/V2.7 协调边界：Xiaobao risk snapshots/insights 关系表写入和后台化归 V2.6；warning read-state API、部门/角色/密码规则/加班原因配置表归 V2.7。
  • V2.6.1 已新增 deterministic large-data fixture、HTTP performance harness 和性能预算文档。
  • V2.6.2 已新增 hot query explain/index audit 脚本、热查询索引迁移和 docs/performance-hot-queries.md。
  • V2.6.3 已新增 PostgreSQL-backed background_jobs 运行时、去重/lease/retry 语义和 jobs 单元测试。
  • V2.6.4 已新增服务端小宝风险 summary refresh、后台 job handler，以及领域写入 dirty/enqueue 桥接。
  • V2.6.5 已新增服务端小宝 AI 解读队列，summary 刷新后按 signature/cooldown/escalation policy 入队，只写 xiaobao_risk_insights 缓存。
  • 小宝历史 AppData 缓存/已读状态已从正常前端运行时移除；xiaobao-risk-snapshots、xiaobao-risk-insights、xiaobao-warning-views 只作为归档/迁移读取入口。
  • V2.6.6 已新增 /admin/ops 运行时看板和 GET /api/v1/ops/runtime，展示慢请求、慢查询、job 队列和 dirty summary 数。
  • V2.7.1 已新增通知和已读状态，前端 NotificationBell 可展示 assignment / mention / risk_alert / overdue_item。
  • V2.7.2 已新增通用评论和提及能力，覆盖 DevTask/TestCase/Bug/Requirement/VersionPlan。
  • V2.7.3 已新增项目成员治理 API 和项目页成员面板，服务端强校验 Owner/Admin/Member/Viewer 边界。
  • V2.7.4 已新增管理驾驶舱和治理设置，任务类型与需求池字典统一进入治理入口管理。
  • V2.7.5 已新增协作治理 RBAC/audit adapter，避免新增模块绕开服务端权限和审计边界。
  • V2.8 新增运维交付物集中在 scripts/、.github/workflows/deploy-production.yml、deploy/monitoring/、docs/runbooks/、docs/deployment.md 和 docs/production-readiness.md。
  • V3.1 Prototype Decompose Agent 已落地：后端 /api/v1/ai/decompose、前端产品方案 Tab 拆解入口、对账报告、去重、采纳草案、AI 估时、推荐负责人和无需求ID分组均已接入。
  • V3.2 Risk Watch Agent 已落地：服务端小宝 summary 刷新后按 policy 排入 xiaobao.ai.interpret，AI 解读只写 xiaobao_risk_insights，V2.2 小宝快读返回最新 generated insight，前端优先展示关系表 AI 解读。
  • V3.4 Business Analysis Agent 第一版已落地：共享分析契约、后端 /api/v1/ai/analysis、Semantic Layer、Metric Catalog、Metric Engine、Unified ChartSpec、ECharts Renderer、AI 助手业务分析对话，以及产品/项目/版本详情页上下文入口已接入。
  • AppData 退场、RBAC/审计、性能、小宝后台化、协作治理和生产发布都通过 production readiness 证据项追踪，避免把运维稳定版误当成一次性口头验收。

已完成（按时间倒序）

2026-07-09

  • V3.4 Business Analysis Agent 第一版落地：新增共享分析契约、后端只读分析管线、权限收窄、指标引擎、ECharts 渲染边界、AI 助手分析结果展示和产品/项目/版本详情页分析入口。

2026-07-08

  • V3.2 completed Risk Watch Agent read closure: /api/v1/v2.2/xiaobao-warning now attaches the latest generated relation-table AI insight, and the frontend uses relation-backed insights without returning to legacy AppData insight cache.
  • V3.1 status corrected to completed: prototype decomposition already has backend AI calls, frontend decomposition buttons, report modal, dedupe, adoption, AI estimates, assignee recommendations, and no-requirement grouping.
  • V2.8 added PostgreSQL backup, fresh DB restore with explicit overwrite confirmation, and server_data volume backup automation.
  • V2.8 added release smoke suite and wired GitHub Actions deployment verification to runtime version, frontend root, products, V2.2 read path, and AI config checks.
  • V2.8 added optional monitoring profile with Prometheus, Grafana, Loki, Promtail, postgres-exporter, node-exporter, cAdvisor, and blackbox-exporter.
  • V2.8 added migration rollback, AppData retirement, Xiaobao background jobs runbooks, and production readiness evidence checklist.
  • V2.7.5 added shared collaboration/governance RBAC and audit adapters so notification, comment, project-member, management, and governance modules keep a single permission/audit boundary.
  • V2.7.4 added management and governance admin pages for relation-backed overview metrics and dictionary governance.
  • V2.7.3 added project-member governance APIs and project member panel with Owner/Admin/Member/Viewer safeguards.
  • V2.7.2 added polymorphic comments, mention parsing, and comment panels for core work entities.
  • V2.7.1 added notification records, read-state APIs, frontend notification store, and NotificationBell.
  • V2.6.6 added the Ops runtime dashboard with ops:view, redacted slow request/query buffers, background job queue summary, failed job list, and dirty Xiaobao summary count.
  • V2.6.5 moved Xiaobao AI interpretation behind the background job runtime, reusing AiService.interpretRisk() and writing only insight cache rows.
  • V2.6.4 moved deterministic Xiaobao risk summary refresh into the server, registered the xiaobao.summary.refresh background job handler, and enqueue refresh jobs from dirty domain writes.
  • V2.6.3 added DB-backed background jobs with active dedupe keys, lease-based claiming, expired lock recovery, retry/terminal-failure handling, and a small handler worker.
  • V2.6.2 added perf:explain, hot query explain targets, index audit documentation, and V2.6 hot-path indexes for workspace, Xiaobao warning/dirty queues, project/version lists, and evidence scans.
  • V2.6.1 added deterministic small/medium/large fixture generation, perf:check, and docs/performance.md for hot API p50/p95 budgets.
  • 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; current runtime no longer falls back to products-overview.
  • 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.3 switched VersionPlan and DevTask writes to version-scoped domain APIs, with work activity evidence and Xiaobao dirty marking.
  • V2.4.4 switched TestCase and Bug writes to version-scoped domain APIs, preserving round-copy and bug workflow behavior.
  • V2.4.5 switched Member, TaskCategory, TaskWorklog, OvertimeRecord, and WorkActivity writes to domain APIs. AppData remains only for low-frequency config such as departments, roles, password rules, and overtime reasons; member identity and overtime records stay relation-backed.
  • Added focused source-contract tests proving migrated frontend stores use domain APIs as primary writes rather than AppData document saves.
  • Added runtime source-contract coverage proving migrated business stores and auth do not read/write AppData business documents.

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-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.

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.8 统一验证与发布收口：合并后集中跑类型、测试、Prisma、部署、runbook、备份恢复和 smoke 验证。
  • 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）

V2 — 后端接入

NestJS + Prisma + PostgreSQL 已推进到 V2.8。第一阶段用 app_data JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步；第三阶段 V2.4 已逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD 主写；第四阶段 V2.5 已冻结 AppData 业务写入并收口服务端 RBAC、审计和一致性校验；第五阶段 V2.6 已完成大数据性能和小宝后台化；第六阶段 V2.7 已补齐协作治理能力；第七阶段 V2.8 已补齐生产运维、备份恢复、监控告警和回滚手册。

关键任务

  1. 服务端文档层：app_data + /api/v1/data/:key（第一阶段已实现）
  2. localStorage → API 切换：业务主数据不再写浏览器（第一阶段已实现）
  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 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口（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 统一收束到规则层

数据迁移策略

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

V2.4 — 领域 CRUD 迁移（已完成）

目标是让关系表从“快读 + AppData 同步副本”升级为主写入路径。V2.4 按以下顺序完成：

  1. V2.4.0：统一 packages/shared 状态枚举与当前前端业务口径。
  2. V2.4.1：Project / Version 替代 products-overview 中的项目和版本主写入；当前产品树正常运行时直接读领域 API，不再回读该文档。
  3. V2.4.2：Requirement 按 productId 分区键主写，并支持需求池服务端分页、搜索、筛选、排序。
  4. V2.4.3：VersionPlan / DevTask 按 versionId 分区键主写，写入后继续复用小宝 dirty 策略和工作活动记录。
  5. V2.4.4：TestCase / Bug 按 versionId 分区键主写，保留测试轮次和缺陷闭环。
  6. V2.4.5：Member / TaskCategory / TaskWorklog / Overtime / WorkActivity 主写关系表，证据型数据保留追加语义。

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 的退场状态与替代路径；已迁移业务 key 进入 write_frozen / read_only_archive，members 仅因部门、角色、密码规则临时配置保持 active，overtime 仅因加班原因配置保持 active。
  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，但正常业务运行时不再使用已迁移业务 key；Xiaobao risk archive、warning read state、部门/角色/密码规则和加班原因配置表分别交给后续治理，不在 V2.5 临时发明不稳定 schema。

V3 — AI Agent 集成

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

V3.1 — Prototype Decompose Agent（已完成）

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

已完成：

  • DevTask / TestCase 加 references[] + aiDraft + aiDraftAt
  • 创建表单加「原型批注」字段
  • 列表中 AI 草案视觉区分（紫色边 + 徽章）
  • 编辑后自动清除 aiDraft 标记
  • agent-spec.md / glossary.md 文档落地
  • 约定：原型链接 = 产品方案 (VersionPlan type=product) 已完成计划的 resultUrl，不在 Version 上独立存储
  • V2.4 已完成 DevTask/TestCase/Bug 的 versionId 版本主归属和领域主写，AI 写入可直接走版本级领域 API。
  • 后端 AiGateway / AiService.decompose / POST /api/v1/ai/decompose 已落地。
  • 前端产品方案 Tab 已有「AI 拆解开发任务 / AI 拆解测试用例」入口。
  • 对账报告弹窗、重复草案过滤、用户确认后批量创建 DevTask/TestCase 草案已落地。
  • AI 估时、推荐负责人、无需求ID分组和任务类型自动入库策略已落地。
  • AiLog 表已建；调用级日志目前通过返回 meta、计划日志和运维慢请求/队列监控追踪，后续若要完整审计每次 AI 调用再单独接写入。

MVP 范围限制：

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

V3.2 — 小宝预警 / Risk Watch Agent（已完成）

小宝预警以版本发版风险为核心，先通过规则引擎计算风险分、趋势、静默风险、预计可发日期和置信度，再由 Risk Watch Agent 自动解释高风险版本。

当前完成边界：

  • 领域写入标记版本风险 summary dirty，并排入 xiaobao.summary.refresh 后台任务。
  • XiaobaoRiskService.refreshSummary() 从关系表重算确定性风险结果，并交给 XiaobaoAiService.evaluateSummary() 按 policy 判断是否入队。
  • xiaobao.ai.interpret worker 重新读取当前 summary，跳过过期 signature，调用 AiService.interpretRisk()，只写 xiaobao_risk_insights 缓存。
  • 触发策略：on_track 不触发；at_risk、likely_delayed、blocked 自动触发；attention 当前服务端只在临近发版且仍有未完成工作时触发。
  • 缓存策略：exact signature 复用、6 小时 cooldown、风险等级升级可绕过 cooldown。
  • V2.2 小宝快读返回最新 generated insight，前端优先展示关系表 AI 解读，不再兼容运行时旧 AppData insight cache。

当前不继续做后台定时巡检或额外主动推送；已有 risk_alert 通知保持现状。若后续需要“主动每日巡检 + 消息推送”，另起阶段，不塞进 V3.2。

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

多 Agent 协作设计：本次不执行。等未来确实引入排期 Agent 后再设计编排策略。

V3.3 — 其他场景候选（暂不执行）

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

V3.4 — Business Analysis Agent（已完成第一版）

目标：把 /wenfan-xiaobao 从内置帮助问答升级为业务数据分析对话，并在产品、项目、版本详情页提供带上下文的智能分析入口。用户可以围绕产品、项目、版本、需求、部门和成员进行单维或多维提问，系统返回 Insight Card、图表、分析报告、可点击证据和连续追问。

设计边界：

  • 只读 Agent，不修改业务实体、不创建草案、不触发状态流转。
  • 使用 Semantic Layer 和 Metric Catalog 承接自然语言到业务指标的映射。
  • Metric Catalog 必须记录 metric version，便于未来算法口径变化后复现历史分析。
  • Analysis Strategy 分为 Template Strategy、Rule Composition Strategy（Deterministic）和 AI Planning Strategy。
  • AI Planning 只生成 AnalysisPlan 建议；Analysis Plan Processor 校验并规范化后，Metric Engine 才能执行。
  • Metric Engine 输出 MetricResult，ChartSpec Builder、Insight Engine、Report Builder、Follow-up Builder 并行消费。
  • ChartSpec 为平台统一契约，前端第一版用 ECharts Renderer，不把 ECharts option 暴露为后端契约。
  • AI Analysis Design System 采用 Apple Vision 风格：大留白、大圆角、轻阴影、半透明材质、数字优先、折线面积渐变、横向圆角柱状、少颜色、无大屏炫光。

第一版已完成：

  • 共享分析契约：AnalysisPlan、MetricResult、EvidenceItem、AnalysisReport、FollowUp 和 UnifiedChartSpec。
  • 后端分析接口：POST /api/v1/ai/analysis 接入 Semantic Layer、Analysis Strategy、Analysis Plan Processor、Permission Scope Resolver、Metric Engine 和响应构建器。
  • 指标目录和指标引擎：第一版支持版本风险、完成趋势、逾期分布、需求状态/来源、部门/成员负载、Bug 严重度、测试通过率和加班相关指标。
  • 图表渲染边界：后端返回平台统一 ChartSpec，前端通过 ECharts Renderer 转换，避免把 ECharts option 作为后端契约。
  • AI 助手业务分析对话：/wenfan-xiaobao 优先请求业务分析，展示 Insight Card、图表、报告、Evidence 和只读 Follow-up；分析接口不可用时保留内置帮助 fallback。
  • 产品/项目/版本上下文入口：详情页可打开只读分析 Drawer，按当前 surface 和上下文 ID 发起分析。

MVP 模板候选：

  1. 版本风险排行
  2. 项目/版本完成趋势
  3. 逾期事项分布
  4. 产品需求状态分布
  5. 需求完成趋势
  6. 需求来源/类型占比
  7. 部门负载排行
  8. 成员待办排行
  9. 成员投入排行
  10. Bug 严重度分布
  11. 测试通过率趋势
  12. 加班原因占比 / 加班排行

完整设计见 docs/superpowers/specs/2026-07-08-business-analysis-agent-design.md。

落地约束

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

不在路线图（明确不做）

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

关键里程碑

节点 状态
V1 业务流程打磨 进行中
V1 朋友试用反馈 持续中
V2 后端接入 V2.1-V2.8 已完成，等待统一验证与发布授权
V3 AI 集成 等 V2 数据沉淀
公开发布 TBD