feat(ai): complete v3.2 risk watch agent

docs/architecture.md

@@ -213,7 +213,7 @@ V2.5 后端 mutation API 已接入服务端 RBAC：
 
 详细规范见 `agent-spec.md`。要点：
 
-- AI Agent 不是一个独立服务，而是嵌在前端的"特定调用入口"。当前 V3.1 仅 Prototype Decompose Agent。
+- AI Agent 不是一个独立服务，而是嵌在前端/后台任务中的特定调用入口。当前 V3.1 Prototype Decompose Agent 与 V3.2 Risk Watch Agent 已落地。
 - Agent 写入数据时必须带 `aiDraft: true` 标记，列表中视觉区分（紫色边）。用户编辑后自动清除标记。
 - DevTask / TestCase 加入 `references[]` 字段，记录任务/用例的来源（需求 / 原型批注）。Agent 和人工创建均强制至少 1 条引用。
 - 原型中有明确功能但没有匹配到关联需求时，AI 可以生成无需求ID分组草案：写入任务/用例的 `requirementName`，不创建 Requirement，不加入关联需求列表。
@@ -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` 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 `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.
 
 V2.6 moves the current risk summary refresh to the server:
 
@@ -290,7 +290,7 @@ 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` still consumes V2.2 summary reads first and only falls back to AppData 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 insight over legacy AppData insight cache. It only falls back to AppData risk calculation when summaries are empty or unavailable.
 
 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.
 ## V2.2 Partitioned Domain Data Layer (2026-07-03)
@@ -370,3 +370,41 @@ V2.7 uses stable server adapters for collaboration and governance modules:
 When the later JWT/NextAuth server verification replaces the current header auth adapter, global permission sourcing should be swapped behind these auth/RBAC adapters; feature modules should keep depending on the adapter boundary.
 
 Management overview reads only relation tables and summaries. It intentionally avoids AppData so it reflects the target backend boundary rather than the compatibility document store.
+
+## V3 Business Analysis Agent Layer (planned)
+
+Business Analysis Agent is a read-only AI analysis layer for business data conversations and context-page analysis. It does not mutate Product, Project, Version, Requirement, VersionPlan, DevTask, TestCase, Bug, Member, WorkActivity, TaskWorklog, Overtime, or Xiaobao data.
+
+The analysis pipeline is:
+
+```
+User question + context
+  -> Analysis Planner
+  -> Semantic Layer
+  -> Permission Scope Resolver
+  -> Analysis Strategy
+       1. Template Strategy
+       2. Rule Composition Strategy (Deterministic)
+       3. AI Planning Strategy
+  -> Analysis Plan Processor (validate + normalize)
+  -> Metric Engine
+  -> Metric Result
+       -> ChartSpec Builder
+       -> Insight Engine
+       -> Report Builder
+       -> Follow-up Builder
+  -> UI Composition
+```
+
+Key boundaries:
+
+- AI may propose an `AnalysisPlan`, but the system validates and normalizes it before execution.
+- AI never writes SQL, never directly queries the database, and never widens user permissions.
+- The Semantic Layer maps business language such as "忙", "压力", "风险", "延期", "效率", and "质量" to Metric Catalog definitions.
+- Metric Catalog owns metric formula, owner, supported dimensions, supported analysis types, default time policy, and metric `version`. Formula changes require a metric version bump.
+- Metric Engine returns renderer-agnostic `MetricResult`. Chart, insight, report, evidence, follow-ups, export, and future dashboard cards consume this result in parallel.
+- Chart output uses a platform Unified ChartSpec. The first renderer is ECharts, but raw ECharts options are not the backend or Agent contract.
+- Evidence is clickable structured proof with label, value, source domain, and optional drilldown filters.
+- Reports have a fixed structure: Summary, Key Findings, Evidence, Suggestions, Data Scope.
+
+The first product surfaces are `/wenfan-xiaobao` business-data conversation and product/project/version detail analysis entries. Visual design follows the AI Analysis Design System: Apple Vision style, large whitespace, large radius, light shadow, translucent material, restrained color, number-first cards, smooth line-area charts, rounded horizontal bars, and no BI big-screen styling.