产品供销存-后端
编辑 | blame | 历史 | 原始文档

财务智能体前端联调文档

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

请求体：

{
  "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 通用格式

{
  "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. 最后补会话历史与删除能力，形成完整对话闭环