# 问数结果 · 分析助手（文字 + 可选图表）设计

**日期：** 2026-09-12  
**状态：** 已实现（2026-09-12）  
**关联需求：** D-12 子集（问数页可视化）· 不实现 D-09 多轮 · NL2SQL 路径不变

---

## 1. 目标与边界

### 1.1 用户故事

分析员在问数工作台先 NL 问数得到表格；再打开**分析助手对话框**，用自然语言说明要什么——可能只要文字解读、只要可视化、或两者都要。大模型根据**当前表格结构 + 用户分析提示词**决定输出形态与图表类型（如时间序列 → 折线图），前端渲染可简单互动的图表。

### 1.2 必须覆盖的三类意图（分析阶段）

| 用户意图 | 问数阶段 | 分析对话框提交后 |
| --- | --- | --- |
| **只要表** | 点「问数」即可 | **不打开**分析助手；无额外 LLM |
| **只要分析（文字）** | 先有表 | `answer` 有内容，`chart=null` |
| **只要图** | 先有表 | `chart` 有 spec，`answer` 可为空或一句说明 |
| **要表 + 分析（文+图）** | 先有表 | `answer` + `chart` 同时存在 |

「表」指问数 SQL 执行结果表格，始终在问数成功后展示；分析助手**不再执行 SQL**。

### 1.3 明确不做（本期）

- D-09 多轮追问 / Redis 会话上下文
- 在主问数输入框里混合「画图」语句（避免误走 NL2SQL）
- 把 chart spec 沉淀为 D-11 资产
- D-12 看板卡片钻取进对话
- 替换行情详情页 `ProductNavChartPanel`（Chart.js）

---

## 2. 交互设计

### 2.1 问数工作台（`AnalystQueryPage.tsx`）

1. **主输入 +「问数」**：行为不变，`POST /api/analyst/chat`，`interpret=false`。
2. 成功/降级且有行时展示结果表格、SQL、溯源/转人工等现有能力。
3. 原「分析该数据」单按钮 → **「分析助手…」**，打开 **Modal**（或小 Drawer）：
   - 说明：基于**本轮问数问题 + 下方表格**，不会重新查库。
   - **分析提示词**（必填）：多行输入。
   - Placeholder 示例轮换：
     - 「用三句话总结这张表的关键结论」
     - 「把各产品按日期的净值趋势画成可悬停折线图」
     - 「总结要点并画一张适合这张表的图」
   - 主按钮：**「生成分析」**（loading 态）。
4. 提交后在表格下方新增区域（可与原「数据解读」Card 合并）：
   - 有 `answer` → 文字 Card + disclaimer
   - 有 `chart` → `ChartCard` + `AnalystResultChartPanel`
5. **新开一轮问数**时清空分析结果（与现清空 interpret 一致）。
6. **门禁**：`status ∈ {success, degrade}` 且 `table.rows.length > 0` 才可打开对话框；否则 Tooltip 提示先问数。

### 2.2 与「只要表」的关系

用户若仅需表格：**问数后不点分析助手**即可。无需新开关；顶栏 Alert 可补一句「需要解读或图表时点分析助手」。

---

## 3. API 契约

### 3.1 新增：`POST /api/analyst/analyze`

| 项 | 说明 |
| --- | --- |
| 鉴权 | 与 `/api/analyst/chat` 相同（`deps` + analyst RBAC） |
| 请求 | 扩展问数快照 + 分析提示词 |

```json
{
  "question": "上轮 NL 问数原问题",
  "analysis_prompt": "用户在对画框里输入的内容",
  "status": "success",
  "answer": "",
  "table": { "columns": [], "rows": [] },
  "sql": "...",
  "trace_id": "trace-...",
  "meta": { "row_count": 0, "...": "..." }
}
```

| 字段 | 约束 |
| --- | --- |
| `question` | 上轮问数问题（审计关联） |
| `analysis_prompt` | 1~2000 字，trim 后非空 |
| 其余 | 与现有 `InterpretRequest` 一致，客户端提交当前页快照 |

### 3.2 响应：扩展 `AnalystResponse`

新增字段：

```typescript
type ChartType = 'line' | 'bar' | 'column' | 'pie' | 'none'

type ChartSpec = {
  chart_type: ChartType
  title: string
  reason?: string          // 模型简述为何选此图型（展示在 subtitle）
  x_field: string | null   // pie 可为 null
  y_fields: string[]       // 一个或多个度量列
  series_field?: string | null  // 多系列折线/柱：系列维度列
}

// AnalystResponse 增：
analysis_kind: 'text' | 'chart' | 'both' | 'none'
chart: ChartSpec | null
```

| `analysis_kind` | 条件 |
| --- | --- |
| `text` | 有 `answer`，无有效 chart |
| `chart` | 有 chart，`answer` 可选短说明 |
| `both` | 同时有 |
| `none` | 失败/空（应极少；降级时用 `degrade` + message） |

`table` / `sql` / `meta`：原样回传客户端快照（便于前端不丢上下文）；**不**因分析而改表数据。

### 3.3 保留 `/api/analyst/interpret`

- 一期实现 **`/analyze` 后前端改走 analyze**；`/interpret` 保留兼容旧客户端，内部可委托 analyze（`analysis_prompt` 默认「请解读下表」）或标记 deprecated（文档说明即可）。

---

## 4. 后端逻辑（`analyst_agent.py`）

### 4.1 新入口 `analyze(req, auth) -> AnalystResponse`

1. 权限：`assert_analyst_query_access`（与 interpret 相同）。
2. 终态 `clarify/deny/error/escalate`：echo 快照，不调用 LLM。
3. 空表：返回 `degrade`，`answer` 说明无数据可分析。
4. 行数上限：**500 行**（可配置 `ANALYST_CHART_MAX_ROWS`）；超出 → `degrade`，提示缩小问数范围或加条件。
5. 构造 LLM 消息：
   - System：角色 + JSON schema + 图表类型选择规则 + 禁止编造未出现在表中的数值。
   - User：`question`、`analysis_prompt`、列名、行数、`data_as_of`、SQL 一行、表格 **前 30 行 TSV**（超 30 行注明「仅展示样本」）。
6. LLM 输出 **单 JSON 对象**（temperature=0）；解析失败 → 重试 1 次 → 仍失败 `escalate` / `INTERPRET_ERROR`。
7. **`validate_chart_spec(spec, columns, row_count)`**（新模块或 `analyst_chart.py`）：
   - `chart_type` 枚举内；`none` 表示不要图。
   - 所有 field 名 ∈ `columns`（大小写按列名精确匹配）。
   - `y_fields` 非空（当 chart 非 none）；pie 时 `y_fields.length === 1` 且需 `series_field` 或 x 为分类。
   - 可选：检测 x 列是否日期型（≥80% 可 parse）→ 建议 line + time，但 **最终 chart_type 以模型为准**，校验只拦非法映射。
8. 文字解读：若用户 prompt 明显要文字或 `both`，生成/保留 `answer`；若仅要图，`answer` 可为 `reason` 一句。
9. **数字护栏**：若 `answer` 含数字，复用现有 `_generate_verified_answer` / guard 逻辑（与 interpret 同路径）；纯 chart 无 prose 数字可跳过 guard。
10. 审计：`log_audit(event_type=analyst_analyze, input_summary={question, analysis_prompt, analysis_kind, chart_type}, trace_id)`。

### 4.2 LLM 图表选择规则（写入 system prompt 摘要）

- 日期/时间 + 数值 → 优先 **line**
- 分类 + 单指标比较 → **bar** / **column**
- 占比、少量分类 → **pie**（分类 ≤ 12）
- 无法安全绑列 → `chart_type: none` + `answer` 解释需要什么列
- 用户明确说「不要图」→ `none`
- 用户明确图型时优先遵从，若与数据结构严重不符则在 `reason` 说明并选最接近合法类型

### 4.3 NL2SQL

**不修改** `run()` 的模板/LLM SQL 生成、sql_guard、execute 路径。

---

## 5. 前端实现

### 5.1 API 层（`web/src/api/analyst.ts`）

- `postAnalystAnalyze(token, payload)` → `AnalystChatResponse & { analysis_kind, chart }`
- 类型 `ChartSpec` 与后端一致

### 5.2 组件

| 中文职责 | 路径 |
| --- | --- |
| 分析助手 Modal + 结果区编排 | `AnalystQueryPage.tsx` |
| ChartSpec + table → @ant-design/charts | `AnalystResultChartPanel.tsx` |
| 列类型推断、长表 series  pivot | `web/src/utils/analystChartSpec.ts` |

### 5.3 图表库

- 使用 **`@ant-design/charts`**（与 Dashboard 一致）。
- 互动：**tooltip**、**legend** 切换；折线支持 smooth optional。
- x 为日期字符串时：parse 为 Date，axis formatter `MM-DD` / 自动。

### 5.4 布局规则

| `analysis_kind` | UI |
| --- | --- |
| `text` | 仅文字 Card |
| `chart` | 仅 ChartCard（title + reason） |
| `both` | 文字在上或左，图在下（移动端纵向堆叠） |

---

## 6. 错误与降级

| 场景 | status | 用户可见 |
| --- | --- | --- |
| chart spec 校验失败 | `degrade` | 文字说明 + 仍展示原表 |
| LLM JSON 无效 | `escalate` | 与现 interpret 失败一致 |
| 行数 > 500 | `degrade` | 提示缩小问数 |
| 客户角色 self 域 | 同 interpret | disclaimer + AI 风险提示 |

---

## 7. 测试计划

### 7.1 pytest

- `validate_chart_spec`：合法 line / 非法列名 / pie 多 y / 空 y
- `analyze()` mock LLM：返回 text-only、chart-only、both；guard 误杀 degrade
- API route 401/403 与 chat 一致

### 7.2 Vitest

- `analystChartSpec.ts`：宽表 pivot、日期 x、多 series
- 可选：Panel smoke render with fixture table

### 7.3 手工 Demo

1. 问数：「各产品最近 30 天每日净值」→ 表有 `nav_date` + `nav` + `product_name`
2. 分析助手：「画趋势折线，按产品分系列」→ 多系列折线 + tooltip
3. 「三句话总结」→ 仅文字
4. 「总结并画图」→ both
5. 问数后不点助手 → 仅表

---

## 8. 文档与 memory（实现后）

- `MEMORY.md` / `FRAMEWORK.md`：问数页增 analyze + chart
- `docs/答辩/DEMO-SOP-问数.md`：加 30 秒可视化演示步骤
- `REQUIREMENTS`：可挂 D-12 子能力脚注（非完整看板钻取）

---

## 9. Spec 自检（2026-09-12）

- [x] 无 TBD 占位
- [x] 「只要表」= 不问 analyze，与「只要图/文/both」不矛盾
- [x] NL2SQL 与 analyze 边界清晰
- [x] 单迭代可交付（API + agent + 页 + 校验 + 测试）

---

**请评审本文件。** 确认或修改后回复，将进入 **writing-plans** 生成实现任务清单（仍不自动 commit，除非你要求）。