refactor(data): 收口关系表运行时数据源

- 移除已迁移业务 AppData 运行时 fallback，改走领域 API 和关系表快读
- 补齐需求产品负责人、版本计划任务 JSON 和成员 username 回填迁移
- 统一治理字典入口，并补充 AI provider、数据源契约和领域服务测试

Co-Authored-By: Codex GPT-5 <codex@openai.com>

docs/roadmap.md

@@ -4,13 +4,13 @@
 
 V2.8 已在既有生产 CI/CD 基线上补齐运维闭环：备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚 runbook、AppData 退场 runbook、小宝后台化 runbook 和生产 readiness 证据清单。本阶段不重新设计业务流程，专注把生产发布和故障处置做成可验证、可复盘、可回滚的标准流程。
 
-V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.5 已收口后端权限、审计、AppData 禁写和一致性核对。V2.6 已完成大数据性能增强、小宝风险后台化、AI 解读队列和运行时 Ops 看板。V2.7 已补齐企业协作和治理能力，且不新增 AppData 主存储。
+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`，读仍可用，写返回明确替代领域 API。
+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` 控制。
@@ -22,7 +22,7 @@ V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步
 12. **通用评论**：DevTask/TestCase/Bug/Requirement/VersionPlan 已接入统一评论面板，支持 `@成员名`、显式成员选择、删除和审计。
 13. **项目成员治理**：已补项目成员 Owner/Admin/Member/Viewer 服务端治理，禁止移除最后 Owner，角色变更写审计。
 14. **管理驾驶舱**：已补只读关系表和 summary 的管理概览，聚合活跃版本、逾期、阻塞、风险和成员负载。
-15. **治理设置**：已补 task category、requirement type/platform/source 等治理字典能力，使用中的字典不可硬删，支持导入导出。
+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 可用性。
@@ -47,12 +47,12 @@ V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步
 ### 当前状态快照（2026-07-08）
 
 - 项目已经不是早期骨架。前端业务功能已覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要管理端路由。
-- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。
+- 版本详情已有需求、调研、产品方案、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 只保留兼容读取、历史核对和少量旧配置形状。
+- 主写入源已经切到领域 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 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。
@@ -61,21 +61,26 @@ V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步
 - 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.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 merges relation-backed insights ahead of legacy AppData insight cache.
+- 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.
@@ -100,12 +105,13 @@ V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步
 - 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.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 compatibility fallback and low-frequency config such as departments, roles, password rules, and overtime reasons.
+- 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`.
@@ -204,7 +210,7 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.8。第一阶段用 `app_data` JSON
 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` 依赖
+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 统一收束到规则层
@@ -218,13 +224,13 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.8。第一阶段用 `app_data` JSON
 目标是让关系表从“快读 + AppData 同步副本”升级为主写入路径。V2.4 按以下顺序完成：
 
 1. V2.4.0：统一 `packages/shared` 状态枚举与当前前端业务口径。
-2. V2.4.1：Project / Version 替代 `products-overview` 中的项目和版本主写入，产品树文档保留兼容读取。
+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.4 完成后的当前边界：AppData 不再是上述领域的事实源，也不再作为正常业务 fallback；只用于历史迁移、归档核对和少量配置。部门、角色、密码规则、加班原因仍作为临时配置保留，后续由 RBAC/配置表阶段单独收口。
 
 ## V2.5 — AppData 退场 + RBAC/审计/一致性收口（已完成）
 
@@ -233,11 +239,11 @@ 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` 状态与替代路径。
+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；Xiaobao risk archive、warning read state、部门/角色/密码规则和加班原因配置表分别交给 V2.6/V2.7，不在 V2.5 临时发明不稳定 schema。
+V2.5 完成后的保留边界：`GET /api/v1/data/:key` 仍可读历史 JSON，但正常业务运行时不再使用已迁移业务 key；Xiaobao risk archive、warning read state、部门/角色/密码规则和加班原因配置表分别交给后续治理，不在 V2.5 临时发明不稳定 schema。
 
 ## V3 — AI Agent 集成
 
@@ -276,7 +282,7 @@ V2.5 完成后的保留边界：`GET /api/v1/data/:key` 仍可读历史 JSON；X
 - `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。
+- V2.2 小宝快读返回最新 generated insight，前端优先展示关系表 AI 解读，不再兼容运行时旧 AppData insight cache。
 
 当前不继续做后台定时巡检或额外主动推送；已有 `risk_alert` 通知保持现状。若后续需要“主动每日巡检 + 消息推送”，另起阶段，不塞进 V3.2。
 
@@ -290,7 +296,7 @@ V2.5 完成后的保留边界：`GET /api/v1/data/:key` 仍可读历史 JSON；X
 2. 健康度智能解读（数据指标 → 自然语言报告）
 3. 需求转任务（需求采纳后一键生成 DevTask 草稿）
 
-### V3.4 — Business Analysis Agent（下一阶段设计已确认）
+### V3.4 — Business Analysis Agent（已完成第一版）
 
 **目标**：把 `/wenfan-xiaobao` 从内置帮助问答升级为业务数据分析对话，并在产品、项目、版本详情页提供带上下文的智能分析入口。用户可以围绕产品、项目、版本、需求、部门和成员进行单维或多维提问，系统返回 Insight Card、图表、分析报告、可点击证据和连续追问。
 
@@ -304,6 +310,14 @@ V2.5 完成后的保留边界：`GET /api/v1/data/:key` 仍可读历史 JSON；X
 - 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. 项目/版本完成趋势