docs(ai): 设计业务分析Agent

新增 Business Analysis Agent 设计稿，明确 Semantic Layer、Metric Catalog、Analysis Strategy、Analysis Plan Processor、Metric Engine、统一 ChartSpec、Insight/Report/Evidence/Follow-up 和 Apple Vision 图表规范。

同步记录关键架构决策，约束 AI 只提出分析计划建议，系统校验规范化后执行，且不得绕过权限或直接生成 SQL。

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

docs/decisions.md

@@ -694,3 +694,25 @@
 - 治理字典使用软删除或使用中禁止硬删，变更必须写审计。
 
 **理由**：适配器把协作治理模块的权限和审计接入点收束在一层，既能复用 V2.5 的服务端控制面，也给后续 JWT/NextAuth 和企业级角色体系留下替换点。稳定事件名和多态评论引用能避免后续模块继续扩散 ad-hoc 字段。
+
+## 53. Business Analysis Agent 采用语义层、指标目录和受控分析计划
+
+**问题**：下一阶段需要让用户用自然语言围绕产品、项目、版本、需求、部门和用户多维度提问，并自动生成图表与分析报告。如果只做“问题 -> 固定模板 -> 查询”，后续会被模板数量卡住；如果让 AI 直接决定查询或生成 ECharts option，则会带来权限绕过、口径不一致、不可复现和难以维护的问题。
+
+**决策**：
+- 新增独立 Business Analysis Agent，只读业务数据，不修改任何业务实体、不创建草案、不触发状态流转。
+- 自然语言先进入 Semantic Layer，把“忙 / 压力 / 风险 / 延期 / 效率 / 质量 / 需求完成”等业务说法映射到受控 `metricId`、`dimensionId`、`analysisType`、`timeIntent` 和 `scopeIntent`。
+- Semantic Layer 输出内部 `semanticConfidence`；前端只展示高/中/低置信，不展示伪精确百分比。数据充分性另用 `dataConfidence` 表达。
+- 建立 Metric Catalog，记录 metric `version`、公式、owner、支持维度、支持分析类型、默认图表、默认维度和默认时间口径。只要公式或计算口径变更，就提升 metric version；纯展示变化不升版本。
+- 分析策略分三层：Template Strategy 优先命中高频模板；Rule Composition Strategy 是确定性系统规则组合；AI Planning Strategy 只在前两者无法覆盖时生成 `AnalysisPlan` 建议。
+- AI 生成的 `AnalysisPlan` 必须只使用 Semantic Layer / Metric Catalog 暴露的指标、维度、筛选和聚合能力，并经过 Analysis Plan Processor 校验与规范化后才能执行。
+- Analysis Plan Processor 不只校验，也负责 Normalize，将模板、规则组合和 AI proposal 统一成标准 `AnalysisPlan`，Metric Engine 只消费统一格式。
+- Metric Engine 输出统一 `MetricResult`。ChartSpec Builder、Insight Engine、Report Builder 和 Follow-up Builder 并行消费同一份 MetricResult，避免图表和报告互相耦合。
+- ChartSpec 是平台统一契约，不是 ECharts option。前端第一版用 ECharts Renderer 渲染，未来可替换为其他图表引擎。
+- Evidence 不是纯 chips，而是可点击数据证据：包含 label、value、sourceDomain 和 drilldown filters。
+- Report 固定为 Summary / Key Findings / Evidence / Suggestions / Data Scope，避免不同分析回答格式漂移。
+- Follow-up 分为 question、drilldown、export。第一版只允许只读追问、明细跳转和导出，不允许创建会议、分配负责人等写操作。
+- 没有数据时走 No Data Strategy：说明请求、范围、缺少的数据和可替代分析，不让 AI 编造解释。
+- 权限红线：Analysis Agent 只能查询当前用户已有权限的数据，自然语言不能扩大范围；无权限时拒绝或返回授权范围内的空结果。
+
+**理由**：Semantic Layer 和 Metric Catalog 能把自然语言、业务口径和数据库字段解耦；metric version 和 result snapshot 能支撑历史分析复现；Analysis Plan Processor 保证 AI proposal 不直接变成系统执行；统一 ChartSpec 和 MetricResult 让 ECharts 只是当前 renderer，而不是长期数据契约。这样第一版可以靠固定模板稳定交付，后续又能通过确定性组合和受控 AI Planning 扩展能力。