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
parent 1e6fb0c7aa
commit 2e595c7e72
98 changed files with 2938 additions and 1441 deletions
--- a/docs/agent-spec.md
+++ b/docs/agent-spec.md
@@ -136,7 +136,7 @@

 **输出**：`summary`、`why[]`、`forecast`、`recommendedReleaseWindow`、`suggestedActions[]`、`ownerHints[]`。

-**权限**：读规则结果和压缩证据；写 `xiaobao_risk_insights` 关系表缓存（历史兼容名 `xiaobao-risk-insights`）。不修改 Version、Requirement、DevTask、TestCase、Bug、Member。
+**权限**：读规则结果和压缩证据；写 `xiaobao_risk_insights` 关系表缓存。历史 AppData 兼容名 `xiaobao-risk-insights` 仅用于迁移/归档，不作为运行时写入目标。不修改 Version、Requirement、DevTask、TestCase、Bug、Member。

 **失败回退**：AI 不可用时保留规则预警，前端显示“规则预警已生成，AI 解读会在触发条件满足时自动补充”。AI 失败不影响快照保存和规则风险展示。

@@ -285,14 +285,16 @@ AI 草案在 DevTask / TestCase 列表中的视觉区分：
 - 用户在详情抽屉里编辑保存任意字段后，徽章和左边线自动消失
 - 无需求ID分组不额外显示“原型发现”等标记，只在分组标题中展示 `无需求ID · {requirementName}`

-## Business Analysis Agent（规划）
+## Business Analysis Agent（第一版已落地）

 Business Analysis Agent 是只读业务数据分析 Agent，不复用 Prototype Decompose Agent 的草案写入契约，也不复用 Risk Watch Agent 的单版本风险解释契约。

+第一版已接入 `/api/v1/ai/analysis`、`/wenfan-xiaobao` 和产品/项目/版本详情页上下文入口。当前支持 Template Strategy 和 Deterministic Rule Composition；AI Planning 只保留为受控计划建议边界，生成的 `AnalysisPlan` 必须经过 Analysis Plan Processor 校验和规范化后才能执行。图表契约为 Unified ChartSpec，前端通过 ECharts Renderer 渲染。
+
 入口：

- `/wenfan-xiaobao`：业务数据分析对话。
- 产品、项目、版本详情页：带当前上下文的智能分析入口。
+- `/wenfan-xiaobao`：业务数据分析对话，优先尝试业务分析，AI 分析不可用时保留内置帮助 fallback。
+- 产品、项目、版本详情页：带当前上下文的智能分析入口和只读分析 Drawer。

 核心链路：

@@ -316,5 +318,6 @@ Question + Context
 - 输出 ChartSpec 是平台统一契约，不是 ECharts option；前端第一版用 ECharts Renderer。
 - Metric Catalog 记录 metric version；公式或业务口径变化必须升版本。
 - 输出必须包含 Insight Card、图表、固定结构报告、可点击 Evidence 和只读 Follow-up。
+- 详情页入口只传 `surface` 和对应上下文 ID；后端基于当前用户和上下文再次收窄范围，不能只信任前端。

 视觉规范见 `docs/superpowers/specs/2026-07-08-business-analysis-agent-design.md` 的 AI Analysis Design System。
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -33,7 +33,7 @@ Requirement          Version               TestCase
 | 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 |
 | UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 |
 | 状态 | Zustand | 每个领域一个 store |
-| 持久化 | PostgreSQL 关系表领域主写 + AppData 兼容兜底（V2.4/V2.5） | 高增长领域直接写关系表；AppData 进入禁写、核对、归档退场阶段 |
+| 持久化 | PostgreSQL 关系表领域主写 + AppData 归档/配置例外 | 高增长和核心业务运行时走关系表；AppData 仅保留迁移归档与少量低频配置 |
 | 后端 | NestJS + Prisma + PostgreSQL（V2.5） | Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/TaskWorklog/Overtime/WorkActivity 均有领域 CRUD，V2.5 收口 RBAC/审计/一致性 |
 | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |

@@ -114,12 +114,12 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完

 ## 数据持久化

-**当前 V2.5 分层：** 领域 CRUD 主写 + AppData 禁写/核对/归档退场
+**当前 V2.5+ 分层：** 领域 CRUD 主写 + AppData 归档/配置例外

 领域主写层已经覆盖主要业务实体：
- 根数据：Product、Project、Version 直接写领域 API，`products-overview` 只作为兼容读取/兜底。
+- 根数据：Product、Project、Version 直接读写领域 API；正常业务运行时不再读取 `products-overview`，该文档只用于迁移、归档导出和人工核对。
 - 需求池：Requirement 直接按 `productId` 分区键写 `requirements`，列表/search/filter/sort 使用服务端分页。
- 版本详情：VersionPlan、DevTask、TestCase、Bug 直接按 `versionId` 分区键写关系表，并继续标脏 Xiaobao 摘要和写入工作活动证据。
+- 版本详情：VersionPlan、DevTask、TestCase、Bug 直接按 `versionId` 分区键读写关系表，并继续标脏 Xiaobao 摘要和写入工作活动证据。
 - 字典/成员/证据：Member 写 `users` 的成员身份字段；TaskCategory 写 `task_categories`；TaskWorklog、OvertimeRecord、WorkActivity 保持追加/证据型关系表写入。

 V2.5 控制面新增三类横切能力：
@@ -129,22 +129,22 @@ V2.5 控制面新增三类横切能力：
 - 一致性：`GET /api/v1/consistency` 与 `pnpm consistency:v25` 检查 counts、分区键、孤儿引用和审计覆盖。历史数据没有审计事件时只报 warning，不阻断关系表主源运行。

 兼容层仍保留通用服务端文档表 `app_data`：
- 后端：`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。
+- 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key` 给迁移、归档、配置例外使用；已迁移业务 key 由 `AppDataRetirementService` 标记为 `write_frozen` 或 `read_only_archive`，冻结写入返回 `409 APP_DATA_WRITE_FROZEN` 并给出替代领域 API。
 - 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
 - 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT`
- 前端：各 Zustand store 保持现有 UI 数据形状，优先调用 `apps/web/lib/domain-api.ts`；`apps/web/lib/server-data.ts` 只保留兼容读取和冻结写入错误处理，不再作为业务保存 fallback。
- 仍留在 AppData 历史形状中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。`members` 与 `overtime` AppData key 已禁写；这些配置的独立表/API 归 V2.7 管理治理阶段承接。
+- 前端：各 Zustand store 保持现有 UI 数据形状，正常业务读写优先调用 `apps/web/lib/domain-api.ts` 和 V2.2 快读 API；`apps/web/lib/server-data.ts` 不再作为业务运行时 fallback。
+- 仍留在 AppData 历史形状中的内容：部门、角色、密码规则、加班原因等尚未拆出独立 RBAC/配置表的低频配置。成员身份已由 `/api/v1/members` 主写关系表，`members` AppData 只保存配置字段，写入时不再夹带成员身份数组；加班记录已由 `/api/v1/overtime` 主写关系表，`overtime` AppData 只保存原因配置。
 - 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储

 关系表层包含 V2.2-V2.4 能力：
 - V2.2：高增长业务表使用分区表，并提供版本详情、需求池、工作台和小宝预警的快读 API。
 - V2.3：AppData 保存成功后触发关系表同步，让快读路径保持新鲜；同步失败只记日志，不阻塞用户保存。
- V2.4：领域 CRUD 成为主写入路径，AppData 写桥保留给历史数据和回滚兜底。不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
+- V2.4：领域 CRUD 成为主写入路径，AppData 写桥只服务历史迁移窗口。当前运行时不要恢复业务 AppData 或 localStorage fallback，避免线上部署后出现多端数据分叉。

 **目标主源（新方向）：** 业务主数据必须落到 PostgreSQL 领域关系表。
- `app_data` 不再作为长期事实源，只保留迁移、回填、兼容读取和故障排查价值。
+- `app_data` 不再作为长期事实源，只保留迁移、回填、归档导出、低频配置例外和故障排查价值。
 - 新增业务模块不得新增 AppData key 作为主存储；必须先设计关系表、Prisma model 和领域 CRUD API。
- 现有 AppData key 需要逐步完成一次性迁移、双读校验、关系表写入切换和 JSON fallback 移除。
+- 现有 AppData key 需要逐步完成一次性迁移、双读校验、关系表写入切换和运行时 JSON fallback 移除。
 - 前端 store 可以继续保留 Zustand 状态形状，但持久化入口要从 `saveServerData(key)` 迁到领域 API。
 - `app_data` 删除前必须有备份/导出和数据量核对，不能直接丢弃历史 JSON。

@@ -281,7 +281,7 @@ The rule surface stays in pure frontend engines:

 Managers with `xiaobao.warning:manage` can see all unfinished versions. Non-managers with `xiaobao.warning:view` can only see unfinished versions where the current user is in `version.members`.

-AI explains rule results only. It writes interpretation cache to `xiaobao-risk-insights` / `xiaobao_risk_insights` and never mutates Version, Requirement, DevTask, TestCase, Bug, or Member data. Risk snapshots are saved to `xiaobao-risk-snapshots` when the page is opened.
+AI explains rule results only. It writes interpretation cache to the relation table `xiaobao_risk_insights` and never mutates Version, Requirement, DevTask, TestCase, Bug, or Member data. Historical AppData keys `xiaobao-risk-insights` and `xiaobao-risk-snapshots` are read-only archive inputs for migration/export, not normal frontend runtime cache.

 V2.6 moves the current risk summary refresh to the server:

@@ -290,9 +290,9 @@ V2.6 moves the current risk summary refresh to the server:
 - Domain writes that produce work activity already mark the affected version dirty; V2.6 also enqueues a deduped refresh job. Plain update/delete paths for version plans, dev tasks, test cases, and bugs explicitly mark the version dirty as well.
 - `XiaobaoAiService` evaluates the refreshed summary and enqueues `xiaobao.ai.interpret` when policy allows. The worker reloads the latest summary, skips stale signatures, calls the existing `AiService.interpretRisk()` prompt path, and writes only `xiaobao_risk_insights`.
 - AI interpretation cache uses the summary `riskSignature`, exact cache reuse, a six-hour cooldown, and risk-level escalation bypass. Until the server has full daily trend snapshots, `attention` summaries trigger server-side AI only when release is within one day and unfinished work remains.
- Frontend `/xiaobao-warning` consumes V2.2 summary reads first. The V2.2 response includes the latest generated relation-table AI insight when available, and the frontend prefers that insight over legacy AppData insight cache. It only falls back to AppData risk calculation when summaries are empty or unavailable.
+- Frontend `/xiaobao-warning` consumes V2.2 summary reads first. The V2.2 response includes the latest generated relation-table AI insight when available, and the frontend prefers that relation insight. If summaries are empty or unavailable, the page asks the relation-backed stores/domain APIs for scoped data instead of reloading heavy business AppData documents.

-Per-user warning read state is saved to `xiaobao-warning-views`. The read marker stores `userId + versionId + risk signature`, so the sidebar can turn the Xiaobao badge blue when any visible risk has a completed unread update, then return to the red risk-count badge after the user opens every updated warning. AI interpretation that is still generating only shows the "updating" notice and must not produce the blue update badge yet.
+Per-user warning read state no longer writes `xiaobao-warning-views` AppData at runtime. Until a dedicated per-user read-state API lands, the frontend keeps this as browser-local UI state keyed by `userId + versionId + risk signature`, so the sidebar can turn the Xiaobao badge blue when any visible risk has a completed unread update, then return to the red risk-count badge after the user opens every updated warning. AI interpretation that is still generating only shows the "updating" notice and must not produce the blue update badge yet.
 ## V2.2 Partitioned Domain Data Layer (2026-07-03)

 V2.2 starts the move from AppData JSON documents to relation tables for high-volume domains. The first database foundation is partitioned from the start so future growth does not require a disruptive rewrite of primary keys, unique constraints, and foreign-key references.
@@ -346,11 +346,11 @@ The server also has lightweight observability for this phase: a global API timin
 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.
- 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.
- 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.
+- Frontend stores use domain APIs as the runtime mutation path. Migrated business stores do not call `loadServerData` / `saveServerData` for `products-overview`, `requirements`, `version-plans`, `dev-tasks`, `test-cases`, `bugs`, `task-categories`, `task-worklogs`, or `work-activities`.
+- `products-overview` is no longer the product/project/version tree source of truth and is not used for normal fallback reads. It remains only as a historical AppData document for migration rehearsal, archive export, and manual incident inspection.
+- V2.2 read APIs and V2.3 relation sync remain compatibility infrastructure for fast reads and historical AppData imports. Runtime data freshness for migrated domains is proven by relation-table domain writes and source-contract tests, not by AppData sync.
 - `packages/shared` status contracts have been aligned with the current workflow statuses before the V2.4 write switch.
- 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.
+- V2.5+ boundary: audit/RBAC/consistency are active on domain writes. AppData active exceptions are limited to `members` configuration (departments, roles, password rule) and `overtime` reason configuration; member identity and overtime records stay relation-backed. Xiaobao risk snapshots/insights and warning read-state AppData keys are historical archive inputs only and are not used by normal frontend runtime.

 ## V2.7 Enterprise Collaboration And Governance Layer (2026-07-08)

@@ -360,7 +360,8 @@ V2.7 adds enterprise collaboration capabilities on top of the relational source-
 - `comments`: polymorphic comments for `dev_task / test_case / bug / requirement / version_plan`, with mention metadata and soft deletion.
 - `project_members`: project-level Owner/Admin/Member/Viewer governance, now exposed through server-enforced APIs.
 - `audit_logs`: append-only governance and collaboration audit events.
- `governance_dictionaries`: centralized requirement type/platform/source dictionaries; task categories continue to use `task_categories`.
+- `governance_dictionaries`: centralized requirement type/platform/source dictionaries; the Requirement Pool consumes these dictionaries and no longer exposes local dictionary management drawers.
+- Task categories continue to use `task_categories`, but the visible admin entry is `/admin/governance` so development and testing task types are managed together with requirement dictionaries.

 V2.7 uses stable server adapters for collaboration and governance modules:

--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -442,7 +442,7 @@
 - AI 解读自动触发，不提供人工“AI 解读”按钮。缓存签名必须覆盖趋势、原因、静默风险、日报/活动证据、风险信号和置信度，避免复用过期解读。
 - 快照保存需要节流：同版本同日普通变化 10 分钟内不重复保存；风险等级变化、风险分变化达到阈值、关键 Bug/失败用例/阻塞/静默风险变化或预测日期明显变化时立即保存。
 - AI 解读需要 cooldown：同版本最近 6 小时内已有解读时不重复请求；如果风险等级升级，则允许绕过 cooldown。
- AI 只写入 `xiaobao-risk-insights` 缓存，不修改 Version、DevTask、TestCase、Bug、Requirement 或 Member。
+- AI 只写入 `xiaobao_risk_insights` 关系表缓存，不修改 Version、DevTask、TestCase、Bug、Requirement 或 Member；历史 `xiaobao-risk-insights` AppData 只保留归档/迁移价值。

 **理由**：规则结果可测试、可追溯、可复盘；AI 文案提升可读性，但不能替代系统事实判断。趋势、静默风险和置信度能弥补“当前风险等级”过于静态的问题。

@@ -569,14 +569,15 @@
 - 需求池列表/search/filter/sort 走服务端分页，避免加载全量 AppData 文档。
 - 版本详情实体按 `versionId` 分区键写入；Requirement 按 `productId` 分区键写入；追加型证据表保留追加语义，不从 AppData 快照反向删除历史。
 - `/workspace` 和 `/xiaobao-warning` 继续走关系表聚合/快读。领域写成功后通过工作活动和小宝 dirty 标记维持证据链。
- AppData 保留为兼容读取、失败回退、历史迁移和少量配置承载，不再作为已迁移领域的事实源。
- 成员迁移采用保守边界：`users` 存成员身份字段；部门、角色、密码规则暂不在本阶段发明完整 RBAC 表，仍作为 AppData 兼容配置。
+- AppData 在 V2.4 迁移窗口保留为兼容读取、失败回退、历史迁移和少量配置承载，不再作为已迁移领域的事实源。
+- 当前 V2.5+ 收口后，正常业务 UI 不再把 AppData 作为失败回退；已迁移业务 store 运行时不读写 `products-overview`、`requirements`、`version-plans`、`dev-tasks`、`test-cases`、`bugs`、`task-categories`、`task-worklogs` 和 `work-activities`。
+- 成员迁移采用保守边界：`users` 存成员身份字段；部门、角色、密码规则暂不在本阶段发明完整 RBAC 表，仍作为 AppData 配置。`members` AppData 不再作为成员身份来源，也不再写入当前成员数组。
 - 加班原因同样暂留 AppData 配置；加班记录本身写 `overtime_records`。

 **理由**：
 - 领域 CRUD 直接写关系表后，读写路径对齐，分页、筛选、聚合和风险预警不再依赖 AppData 同步是否及时。
 - 分区键进入每次领域写入，能维持 V2.2 分区表设计的查询边界。
- AppData fallback 让迁移可回滚、可兼容旧数据，但不再制造长期双事实源。
+- 迁移期 AppData fallback 让迁移可回滚、可兼容旧数据；当前收口后必须移除正常业务运行时 fallback，避免继续制造双事实源。
 - RBAC/配置表会影响权限模型和管理流程，单独成阶段更安全；V2.4.5 只收口当前高频业务写入，避免为了“全收口”临时设计不稳的权限 schema。

 ## 45. V2 后端关系化采用八阶段交付链路
@@ -614,13 +615,14 @@
 **问题**：V2.4 已经把主要领域写入迁到关系表，但 AppData 里仍保存历史 JSON、旧部署 fallback 和少量尚未领域化的配置形状。如果直接删除 `app_data` 或移除 `/data/:key`，会失去回滚、迁移核对和历史排查依据；如果继续允许写入，又会把双事实源问题拖进 V2.6。

 **决策**：
- 每个 AppData key 明确进入 `write_frozen` 或 `read_only_archive`，由 `AppDataRetirementService` 集中配置替代 API 和说明。
+- 每个 AppData key 由 `AppDataRetirementService` 集中声明退场状态、替代 API 和说明；已迁移业务 key 进入 `write_frozen` 或 `read_only_archive`，`members` 仅作为部门、角色、密码规则的临时配置文档保持 `active`，`overtime` 仅作为加班原因配置文档保持 `active`。
+- 正常业务前端不得从 AppData 读取已迁移业务 key；成员身份读取走 `/api/v1/members`，加班记录读取走 `/api/v1/overtime`。
 - 冻结 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。
+- Xiaobao risk snapshots/insights 的 AppData key 进入 `read_only_archive`，正常前端运行时不得读写；关系表写入和后台化归 V2.6。`xiaobao-warning-views` 同样只保留归档价值，当前前端已读状态在专用 API 落地前仅作为浏览器本地 UI 状态。

 **理由**：冻结写入能立即切断新的双主源风险，同时保留旧 JSON 的审计和回滚价值。把权限和审计合并到领域 mutation 装饰器，可以确保后续新增写接口默认带服务端 guard 和 audit event。审计覆盖对历史数据只告警，避免为了“补齐历史审计”伪造事件。auth header adapter 给 V2.5 一个可测试的服务端权限边界，但不把它包装成最终安全方案，后续 JWT/企业 RBAC 可以替换 adapter 而不改领域 controller 合同。

@@ -683,15 +685,14 @@

 ## 52. V2.7 协作治理先落稳定适配器，不硬编码临时权限

-**问题**：V2.7 需要通知、评论、项目成员治理、管理驾驶舱和治理字典。如果各 V2.7 模块直接写临时权限判断和审计插入，就会绕开 V2.5 已落地的服务端权限、审计和资源作用域边界，后续认证治理也会再次返工。
+**问题**：V2.7 需要通知、评论、项目成员治理和管理驾驶舱。如果各 V2.7 模块直接写临时权限判断和审计插入，就会绕开 V2.5 已落地的服务端权限、审计和资源作用域边界，后续认证治理也会再次返工。

 **决策**：
- 新增 `RbacService` 作为项目角色与全局权限断言适配器，Owner/Admin/Member/Viewer 的层级判断和 `management:view` / `governance:manage` 等全局权限入口集中在此处。
+- 新增 `RbacService` 作为项目角色与全局权限断言适配器，Owner/Admin/Member/Viewer 的层级判断和 `management:view` 等全局权限入口集中在此处。
 - 新增 `AuditService` 作为审计写入适配器，业务模块只提交 `actorId/action/resource/before/after`。
 - 通知事件类型固定为 `assignment / mention / risk_alert / overdue_item`，跨模块通过这些稳定语义发通知。
 - 通用评论使用 `entityType + entityId + entityVersionId` 的多态引用，不给每个业务表单独建评论表。
 - 管理驾驶舱只读关系表和 `xiaobao_risk_summaries`，不回读 AppData。
- 治理字典使用软删除或使用中禁止硬删，变更必须写审计。

 **理由**：适配器把协作治理模块的权限和审计接入点收束在一层，既能复用 V2.5 的服务端控制面，也给后续 JWT/NextAuth 和企业级角色体系留下替换点。稳定事件名和多态评论引用能避免后续模块继续扩散 ad-hoc 字段。

@@ -716,3 +717,17 @@
 - 权限红线：Analysis Agent 只能查询当前用户已有权限的数据，自然语言不能扩大范围；无权限时拒绝或返回授权范围内的空结果。

 **理由**：Semantic Layer 和 Metric Catalog 能把自然语言、业务口径和数据库字段解耦；metric version 和 result snapshot 能支撑历史分析复现；Analysis Plan Processor 保证 AI proposal 不直接变成系统执行；统一 ChartSpec 和 MetricResult 让 ECharts 只是当前 renderer，而不是长期数据契约。这样第一版可以靠固定模板稳定交付，后续又能通过确定性组合和受控 AI Planning 扩展能力。
+
+## 54. 任务类型与需求池字典统一进入治理设置
+
+**问题**：需求池类型/来源/支持端、开发任务类型和测试用例任务类型都属于可复用业务字典。如果分别在需求池、版本详情和治理设置维护，会出现多个入口、口径不一致和使用中 ID 难以追踪的问题。
+
+**决策**：
+- 恢复 `/admin/governance` 作为统一治理设置入口，由 `governance:manage` 控制。
+- 治理设置统一维护四类字典：`task_category`、`requirement_type`、`requirement_platform`、`requirement_source`。
+- 开发任务类型和测试用例任务类型继续落在 `task_categories`，但通过治理设置入口统一维护。
+- 需求池类型、来源和支持端优先读写 `/api/v1/governance/dictionaries`，不再通过需求池本地管理抽屉维护。
+- 后端治理列表运行时不再从旧 `requirements` AppData 回填字典。需求池字典以 `governance_dictionaries` 为准；任务类型为空时只种内置默认 `task_categories`，历史 AppData 回填只能作为显式迁移工具执行。
+- Business Analysis Agent 可以读取需求类型/来源作为分析维度，但不负责修改字典。
+
+**理由**：这些字典会被需求池、版本执行任务、测试用例和 AI 分析共同消费，放在治理设置能形成单一维护入口。运行时不再读取 AppData 回填字典，可以避免部署后旧 JSON 把关系表配置反向污染；历史兼容由迁移工具承担，而不是页面访问时隐式发生。
--- a/docs/roadmap.md
+++ b/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. 项目/版本完成趋势
--- a/docs/workflow.md
+++ b/docs/workflow.md
@@ -72,7 +72,7 @@
 - [ ] 是否需要在 `workspace-engine.ts` 加聚合？
 - [ ] 删除版本时是否需要清理这类数据？
 - [ ] 工作台 / 版本详情 / 项目详情三处的统计是否同步？
- [ ] 是否需要新增 `app_data` key（后端 `data-keys.ts` + 前端 `server-data.ts`）？
+- [ ] 是否需要新增关系表、Prisma model、领域 API、权限和审计？
 - [ ] 是否需要从旧浏览器数据做一次性迁移？（当前不做本地导入导出）

 ## Drawer（侧边详情）规范
@@ -131,9 +131,9 @@
 朋友拉新代码出现"显示问题"时，按顺序排查：

 1. 后端是否启动：`GET http://localhost:3001/api/v1/config/ai` 应返回 200
-2. 数据库是否启动并完成 Prisma 同步：`app_data` 表必须存在
-3. 对应 `app_data.key` 是否有值，例如 `products-overview` / `requirements` / `dev-tasks`
-4. 前端 store 是否已经调用对应 `fetch*` 方法
+2. 数据库是否启动并完成 Prisma migration：领域关系表必须存在
+3. 对应领域 API 是否有数据，例如 `/api/v1/products`、`/api/v1/v2.2/workspace`、`/api/v1/versions/:versionId/plans`
+4. 前端 store 是否已经调用对应 `fetch*` 方法，且是否传了正确的 `productId` / `versionId`
 5. 类型定义和实际 JSON 数据不一致（缺字段）
 6. 列宽溢出导致裁切
 7. 派生计算错误（filter 条件错）
@@ -147,10 +147,12 @@
 - 涉及 UI 改动：`curl http://localhost:3000/<path>` 检查 200
 - 不会自动跑 dev server，假定它已经运行

-## AppData 并发写入流程
+## AppData 归档/配置写入流程

- 前端通过 `loadServerData(key)` 读取业务文档时，必须缓存响应里的 `version`。
- 前端通过 `saveServerData(key, value)` 保存已读取过的 key 时，必须把最近一次成功读取/保存得到的 `version` 一起提交。
+- 正常业务 store 不再通过 `loadServerData(key)` / `saveServerData(key, value)` 读取或保存已迁移业务文档。
+- 仅允许低频配置例外使用 AppData：成员配置中的部门/角色/密码规则、加班原因。小宝历史缓存/已读状态只保留迁移与归档读取价值，正常页面运行时不得读写这些 AppData key。
+- 前端通过 `loadServerData(key)` 读取配置文档时，必须缓存响应里的 `version`。
+- 前端通过 `saveServerData(key, value)` 保存已读取过的配置 key 时，必须把最近一次成功读取/保存得到的 `version` 一起提交。
 - 后端只在 `key + updatedAt(version)` 匹配时更新；如果其他用户已经先保存，返回 `409 APP_DATA_CONFLICT`，响应包含当前服务端 `currentVersion` 和 `currentValue`。
 - 收到 `ServerDataConflictError` 时，不要自动重试覆盖。当前处理策略是阻止静默覆盖，后续 UI 冲突合并能力再单独补。

@@ -159,14 +161,14 @@
 已迁移领域的 store 默认写入顺序：

 1. 本地状态先做乐观更新，保持 UI 响应速度。
-2. 优先调用 `apps/web/lib/domain-api.ts` 中的领域 API。
+2. 调用 `apps/web/lib/domain-api.ts` 中的领域 API。
 3. 领域 API 成功后，用服务端返回行替换本地临时行；若返回 `activities`，直接合并工作活动证据。
-4. 领域 API 不可用或旧环境未部署时，才使用 `loadServerData` / `saveServerData` 做 AppData 兼容兜底。
-5. 不新增长期双写逻辑；AppData fallback 只用于兼容、迁移和回滚，不作为已迁移领域的事实源。
+4. 领域 API 不可用时回滚乐观更新并提示 API/网络错误，不再写 AppData 兼容兜底。
+5. 不新增双写逻辑；迁移、归档、回滚工具可以读历史 AppData，但正常业务 UI 不把它当事实源。

 当前领域主写范围：

- Product / Project / Version：根数据主写，`products-overview` 仅兼容。
+- Product / Project / Version：根数据主写，正常运行时不读 `products-overview`。
 - Requirement：按 `productId` 写入，需求池列表走服务端分页、搜索、筛选、排序。
 - VersionPlan / DevTask / TestCase / Bug：按 `versionId` 写入，并维护工作活动和小宝 dirty 标记。
 - Member / TaskCategory：成员身份字段和任务类型字典主写关系表。
@@ -177,7 +179,7 @@
 - 部门、角色、密码规则。
 - 加班原因。

-新增领域 store 时，先写 source contract 测试证明主写不是 `saveServerData('<key>')`，再实现领域 API 和 fallback。
+新增领域 store 时，先写 source contract 测试证明运行时不调用 `loadServerData('<key>')` / `saveServerData('<key>')`，再实现领域 API。

 ## V2.5 权限、审计与 AppData 退场流程

@@ -193,7 +195,7 @@ AppData key 退场遵循：

 1. 所有业务 key 先在 `AppDataRetirementService` 标注状态和替代路径。
 2. `write_frozen` / `read_only_archive` key 的写入返回 `409 APP_DATA_WRITE_FROZEN`；前端捕获 `ServerDataWriteFrozenError` 后提示改用领域 API。
-3. 读取仍可用，只用于历史数据核对、兼容导入、归档导出和故障排查。
+3. 读取仍可用，只用于历史数据核对、兼容导入、归档导出和故障排查；正常业务 UI 不应把读取结果当 fallback 数据源。
 4. 导出归档使用 `pnpm appdata:archive:export`，归档校验使用 `pnpm appdata:archive:verify -- --archive <file>`。
 5. 不新增 AppData key 作为主写；新业务先设计关系表、Prisma model、领域 API、权限和审计。

@@ -206,8 +208,8 @@ AppData key 退场遵循：

 跨阶段协调点：

- `xiaobao-risk-snapshots` / `xiaobao-risk-insights` 已进入只读归档；V2.6 负责关系表写入、后台任务和重试。
- `xiaobao-warning-views` 已进入只读归档；V2.7 负责 per-user read-state API。
+- `xiaobao-risk-snapshots` / `xiaobao-risk-insights` 已进入只读归档；正常前端运行时不再读取或写入这些 AppData key，V2.6 关系表和后台任务负责 summary/insight。
+- `xiaobao-warning-views` 已进入只读归档；正常前端运行时不再写该 AppData key，当前页面已读状态仅作为浏览器本地 UI 状态，后续由 per-user read-state API 承接。
 - 成员身份写 `users`，但部门、角色、密码规则和加班原因的正式配置 schema 仍属 V2.7 管理治理。

 ## 与我相关（Workspace）数据流
@@ -350,9 +352,9 @@ Implementation convention:
 - `xiaobao.warning:manage`：查看所有未结束版本的预警。
 - `xiaobao.warning:view`：仅查看当前用户在 `version.members` 中的未结束版本。

-V2.6/V3.2 后小宝当前 summary 由服务端后台刷新：领域写入标记 `xiaobao_risk_summaries.dirty=true` 并排入 `xiaobao.summary.refresh`，worker 从版本下的计划、开发任务、测试用例、Bug、日报和工作活动重新计算风险。页面仍可用前端 `buildXiaobaoWorkItems` 做兼容聚合和快照保存，但默认优先读取 V2.2 summary。
+V2.6/V3.2 后小宝当前 summary 由服务端后台刷新：领域写入标记 `xiaobao_risk_summaries.dirty=true` 并排入 `xiaobao.summary.refresh`，worker 从版本下的计划、开发任务、测试用例、Bug、日报和工作活动重新计算风险。页面仍可用前端 `buildXiaobaoWorkItems` 做兼容聚合，但不再把快照或解读保存到 AppData，默认优先读取 V2.2 summary。

-AI 解读不由人工按钮触发。服务端 summary 刷新后按 policy 排入 `xiaobao.ai.interpret`：`at_risk`、`likely_delayed`、`blocked` 自动触发；`attention` 当前服务端只在临近发版且仍有未完成工作时触发，页面完整趋势策略仍保留作为兼容。缓存命中时复用解读；同版本最近 6 小时内已有解读时进入 cooldown，不重复请求，风险等级升级时可绕过；缓存保存时间使用服务端写入时间，不信任模型返回的 `generatedAt` 作为缓存新鲜度。V2.2 小宝快读会带出当前版本最新 generated 关系表解读，前端优先展示这份解读，再兼容旧 `xiaobao-risk-insights` AppData 缓存。
+AI 解读不由人工按钮触发。服务端 summary 刷新后按 policy 排入 `xiaobao.ai.interpret`：`at_risk`、`likely_delayed`、`blocked` 自动触发；`attention` 当前服务端只在临近发版且仍有未完成工作时触发。缓存命中时复用解读；同版本最近 6 小时内已有解读时进入 cooldown，不重复请求，风险等级升级时可绕过；缓存保存时间使用服务端写入时间，不信任模型返回的 `generatedAt` 作为缓存新鲜度。V2.2 小宝快读会带出当前版本最新 generated 关系表解读，前端优先展示这份解读，不再回读旧 `xiaobao-risk-insights` AppData 缓存。

 静默风险包括长期无更新、无日报、无活动、进行中事项无人处理等信号。日报和工作活动是风险解释的重要证据，必须进入 AI 解读输入。

@@ -362,19 +364,21 @@ AI 解读不由人工按钮触发。服务端 summary 刷新后按 policy 排入

 - `assignment`：负责人或处理人被分配工作。
 - `mention`：评论中 `@成员名` 或显式选择成员。
- `risk_alert`：小宝预警保存高风险快照后提醒管理者。
+- `risk_alert`：小宝风险摘要/高风险事件触发后提醒管理者。
 - `overdue_item`：逾期事项提醒。

 评论统一使用 `CommentPanel`，支持 DevTask、TestCase、Bug、Requirement 和 VersionPlan。创建/删除评论必须写 audit；提及成员必须生成 mention 通知。

 项目成员治理走 `/projects/:projectId/members` 服务端接口。角色为 Owner/Admin/Member/Viewer，Owner/Admin 可管理成员；服务端禁止移除或降级最后一个 Owner。版本成员可见性继续兼容旧 `version.members` 展示，但治理来源应逐步收敛到 ProjectMember。

-管理驾驶舱 `/admin/management` 只查关系表和小宝 summary，不读取 AppData，并通过 RBAC adapter 校验 `management:view`。治理设置 `/admin/governance` 集中维护任务类型与需求字典；使用中的字典不可硬删，字典变更必须写 audit，并通过 RBAC adapter 校验 `governance:manage`。
+管理驾驶舱 `/admin/management` 只查关系表和小宝 summary，不读取 AppData，并通过 RBAC adapter 校验 `management:view`。治理设置 `/admin/governance` 统一维护任务类型、需求类型、支持端与需求来源，并由 `governance:manage` 控制。需求池只消费治理字典，不再提供本地类型/来源/支持端管理抽屉；AI 分析读取这些字段作为维度，不负责修改字典。

-## Business Analysis Agent 工作流（规划）
+## Business Analysis Agent 工作流（第一版已接入）

 Business Analysis Agent 用于 AI 助手业务数据对话，以及产品/项目/版本详情页的上下文分析入口。它只读关系表和 summary，不写业务数据。

+业务分析请求走 `POST /api/v1/ai/analysis`。前端必须传入 `surface` 和可用上下文 ID；后端基于当前用户、服务端权限和页面上下文再次收窄范围，不能只信任前端传入的权限或自然语言意图。
+
 标准流程：

 1. 用户在 `/wenfan-xiaobao` 或详情页输入问题。