# 财务智能体前端联调文档

## 1. 模块说明

财务智能体后端已新增统一入口 `financial-ai`，用于业财一体化分析，覆盖：

- 智能成本核算
- 订单利润分析
- 库存资金分析
- 应收应付与现金流预测
- 经营异常预警
- AI 经营驾驶舱
- 日报/周报自动生成
- 财务知识检索（轻量 RAG 上下文）

接口采用 **SSE 流式输出**，工具命中时返回结构化 JSON 字符串。

## 2. 接口清单

### 2.1 对话接口（SSE）

- `POST /financial-ai/chat`
- `Content-Type: application/json`
- `Accept: text/stream;charset=utf-8`

请求体：

```json
{
  "memoryId": "finance-uuid-001",
  "message": "查询近30天亏损订单"
}
```

字段说明：

- `memoryId`：会话唯一标识（前端生成 UUID，单会话复用）
- `message`：自然语言问题

---

### 2.2 会话列表

- `GET /financial-ai/history/sessions`

---

### 2.3 会话消息

- `GET /financial-ai/history/messages/{memoryId}`

---

### 2.4 删除会话

- `DELETE /financial-ai/history/{memoryId}`

## 3. SSE 返回处理规范

### 3.1 返回形态

- 普通问答：流式文本片段
- 工具命中：完整 JSON 字符串（通常一次性输出，也可能分片）

前端建议处理流程：

1. 将 SSE 分片按顺序拼接成 `rawText`
2. 对 `rawText` 尝试 `JSON.parse`
3. 若可解析，按 `type` 分发渲染图表/表格
4. 若不可解析，按普通文本展示

### 3.2 结构化 JSON 通用格式

```json
{
  "success": true,
  "type": "financial_order_profit_analysis",
  "description": "已完成订单利润分析",
  "summary": {},
  "data": {},
  "charts": {}
}
```

字段说明：

- `type`：结果类型（前端渲染分发键）
- `summary`：头部指标
- `data`：表格明细/建议列表
- `charts`：ECharts `option` 数据

## 4. type 与前端页面映射

建议按 `type` 建立渲染策略：

- `financial_cost_accounting`：成本核算页
- `financial_order_profit_analysis`：订单利润页
- `financial_inventory_capital_analysis`：库存资金页
- `financial_cashflow_forecast`：现金流页
- `financial_business_anomaly_warning`：风险预警页
- `financial_business_cockpit`：经营驾驶舱
- `financial_operation_report`：日报周报页
- `financial_rag_knowledge`：知识检索/口径说明卡片

## 5. 关键数据字段（联调重点）

### 5.1 成本/利润类

- `data.orders[]`：
  - `salesContractNo`
  - `customerName`
  - `revenue`
  - `materialCost`
  - `laborCost`
  - `depreciationCost`
  - `scrapCost`
  - `totalCost`
  - `profit`
  - `profitRate`
  - `riskLevel`
  - `reasons`
  - `suggestion`

### 5.2 库存资金类

- `data.items[]`：
  - `productName`
  - `model`
  - `quantity`
  - `inventoryValue`
  - `stagnantDays`
  - `overstock`
  - `riskLevel`

### 5.3 现金流类

- `data.actualMonthly[]` / `data.forecastMonthly[]`：
  - `month`
  - `income`
  - `expense`
  - `netFlow`
- `data.receivableRiskTop[]` / `data.payablePressureTop[]`

### 5.4 异常预警类

- `data.items[]`：
  - `riskLevel`
  - `type`
  - `message`
  - `detail`

### 5.5 报告类

- `data.headline`
- `data.conclusions[]`
- `data.riskSuggestions[]`
- `data.orderProfitTop[]`

## 6. 图表联调规范

`charts` 内字段均为 ECharts `option`，可直接喂给图表组件。

常见字段：

- 柱状图：`orderProfitBarOption` / `processCostBarOption` / `inventoryValueTopOption`
- 饼图：`costCompositionPieOption` / `inventoryAgingPieOption` / `anomalyLevelPieOption`
- 趋势图：`cashFlowTrendOption`
- 仪表盘：`fundGapGaugeOption` / `inventoryTurnoverGauge`

## 7. 推荐前端问句（回归测试）

1. `查看本月经营驾驶舱`
2. `查询近30天亏损订单`
3. `分析近30天库存资金占用`
4. `预测未来3个月现金流`
5. `生成本周经营周报`
6. `为什么利润下降`
7. `哪个客户最赚钱`
8. `哪个工序成本最高`

## 8. 异常与兜底处理

- `memoryId` 为空：返回文本 `memoryId不能为空`
- `message` 为空：返回文本 `message不能为空`
- 无数据场景：`success=true` 且 `data.items=[]`，前端按空态展示
- 非 JSON 流返回：按普通聊天文本展示

## 9. 联调建议

1. 先做 `type` 分发器（保证所有结构化结果可落地）
2. 再做摘要卡片（`summary`）+ 表格（`data`）+ 图表（`charts`）
3. 最后补会话历史与删除能力，形成完整对话闭环