# 通风数据解读 API 接口文档

> **服务器地址**: http://39.97.59.228:8070
> 
> **文档版本**: v1.0

---

## 目录

- [接口概览](#接口概览)
- [SSE 流式响应格式](#sse-流式响应格式)
- [点选巷道解读接口](#点选巷道解读接口)
- [点选设备解读接口](#点选设备解读接口)
- [对话式解读接口](#对话式解读接口)
- [聊天历史查询接口](#聊天历史查询接口)
- [会话列表接口](#会话列表接口)
- [删除会话接口](#删除会话接口)
- [工具清单](#工具清单)

---

## 接口概览

| 方法 | 路径 | 描述 | 类型 |
|------|------|------|------|
| POST | `/api/interpret/click/tun` | 点选/悬浮巷道数据解读 | SSE 流式 |
| POST | `/api/interpret/click/device` | 点选/悬浮设备数据解读 | SSE 流式 |
| POST | `/api/chat` | 对话式数据解读 / 需风量计算 | SSE 流式 |
| POST | `/api/vent/review/pdf` | 配风计划审查（PDF 上传） | SSE 流式 |
| GET | `/api/chat/history/{session_id}` | 查询聊天历史 | 常规 |
| GET | `/api/sessions` | 查询会话列表 | 常规 |
| DELETE | `/api/sessions/{session_id}` | 删除会话 | 常规 |

---

## SSE 流式响应格式

所有流式接口均采用 Server-Sent Events (SSE) 协议，返回 `text/event-stream` 类型。

### 通用响应头

```
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Session-Id: {session_id}
```

### 事件类型 (type 字段)

流式返回数据以 `data:` 开头，JSON 格式，核心字段定义如下：

| type | 描述 | 核心字段 |
|------|------|----------|
| `thinking` | AI 正在思考/推理 | `source`, `node`, `message` |
| `executing` | AI 正在执行工具调用 | `source`, `tools`, `message` |
| `tool_call` | 检测到工具调用 | `source`, `tool`, `message` |
| `tool_result` | 工具执行结果返回 | `source`, `tool`, `message` |
| `updated_todo_list` | Todo 列表更新 | `source`, `todos`, `message` |
| `token` | AI 生成的文本内容 | `source`, `content` |
| `done` | 流式响应结束 | `thread_id`, `session_id`, `message` |
| `error` | 发生错误 | `message` |

> **`message` 字段**（v1.3+）：所有事件均包含中文 `message` 字段，描述当前正在执行的操作，如 "正在分析您的问题..."、"查询巷道监测数据 完成"。前端可据此展示进度提示。

### 配风计划审查专属事件

配风计划 PDF 审查接口还会产生以下额外事件类型：

| type | 描述 | 核心字段 |
|------|------|----------|
| `progress` | 审查进度更新 | `message`, `agent`, `hash_id`, `download_url` |
| `agent_start` | 子智能体开始审查 | `agent`, `message` |
| `agent_thinking` | 子智能体正在分析 | `agent`, `message` |
| `agent_executing` | 子智能体执行工具 | `agent`, `message`, `tools` |
| `agent_todos` | 子智能体任务进度更新 | `agent`, `message`, `todos` |
| `agent_tool_result` | 子智能体工具执行完成 | `agent`, `message`, `tool` |
| `agent_done` | 子智能体审查完成 | `agent`, `message`, `preview`, `progress` |
| `agent_error` | 子智能体审查出错 | `agent`, `message`, `error` |
| `generating` | LLM 正在生成报告 | `source` |

### source 字段说明

| 值 | 含义 |
|----|------|
| `main` | 主代理（当前对话） |
| `subagent` | 子代理（被调用的工具代理） |

---

## 点选巷道解读接口

**POST** `/api/interpret/click/tun`

### 请求示例

```json
{
  "tun_id": "15216",
  "tun_name": "15216 辅运起坡段"
}
```

### 请求参数

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `tun_id` | string | 是 | 巷道 ID |
| `tun_name` | string | 是 | 巷道名称 |

### 响应示例

```
data: {"type": "thinking", "source": "main", "node": "model_request"}

data: {"type": "executing", "source": "main", "tools": ["query_knowledge_base"]}

data: {"type": "tool_call", "source": "main", "tool": "query_knowledge_base"}

data: {"type": "tool_result", "source": "main", "tool": "query_knowledge_base"}

data: {"type": "token", "source": "main", "content": "根据监测数据，该巷道当前风速为"}

data: {"type": "done", "thread_id": "xxx", "session_id": "xxx"}
```

---

## 点选设备解读接口

**POST** `/api/interpret/click/device`

### 请求示例

```json
{
  "device_id": "FAN-001",
  "device_name": "主通风机",
  "device_type": "fan"
}
```

### 请求参数

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `device_id` | string | 是 | 设备 ID |
| `device_name` | string | 是 | 设备名称 |
| `device_type` | string | 是 | 设备类型 |

### 响应格式

与巷道解读接口相同，返回该设备的数据解读报告。

---

## 对话式解读接口

**POST** `/api/chat`

### 请求示例

```json
{
  "message": "15216 辅运起坡段当前风速风量情况如何？",
  "session_id": "可选，已有会话ID",
  "thread_id": "可选，LangGraph线程ID"
}
```

### 请求参数

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `message` | string | 是 | 用户消息（自然语言） |
| `session_id` | string | 否 | 会话 ID，新会话可不传 |
| `thread_id` | string | 否 | LangGraph 线程 ID，用于恢复多轮对话状态 |

### 流式响应详解

#### thinking 事件

```json
{
  "type": "thinking",
  "source": "main",
  "node": "model_request"
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `thinking` |
| `source` | 事件来源：`main` 或 `subagent` |
| `node` | 当前执行节点名称 |

#### executing 事件

```json
{
  "type": "executing",
  "source": "main",
  "tools": ["write_todos", "query_knowledge_base"]
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `executing` |
| `source` | 事件来源 |
| `tools` | 即将执行的工具名称列表 |

#### tool_call 事件

```json
{
  "type": "tool_call",
  "source": "main",
  "tool": "query_knowledge_base"
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `tool_call` |
| `source` | 事件来源 |
| `tool` | 被调用的工具名称 |

#### tool_result 事件

```json
{
  "type": "tool_result",
  "source": "main",
  "tool": "query_knowledge_base"
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `tool_result` |
| `source` | 事件来源 |
| `tool` | 执行完成的工具名称 |

#### updated_todo_list 事件

```json
{
  "type": "updated_todo_list",
  "source": "main",
  "todos": [
    {"content": "查询巷道监测数据", "status": "in_progress"},
    {"content": "分析风速风量异常", "status": "pending"}
  ]
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `updated_todo_list` |
| `source` | 事件来源 |
| `todos` | Todo 列表数组 |

#### token 事件

```json
{
  "type": "token",
  "source": "main",
  "content": "根据监测数据，"
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `token` |
| `source` | 事件来源 |
| `content` | AI 生成的文本片段（逐步累积） |

#### done 事件

```json
{
  "type": "done",
  "thread_id": "a1b2c3d4-...",
  "session_id": "e5f6g7h8-..."
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `done` |
| `thread_id` | LangGraph 线程 ID |
| `session_id` | 会话 ID |

#### error 事件

```json
{
  "type": "error",
  "message": "查询超时，请重试"
}
```

| 字段 | 描述 |
|------|------|
| `type` | 固定为 `error` |
| `message` | 错误信息描述 |

---

## 配风计划审查接口（PDF 上传）

**POST** `/api/vent/review/pdf`

### 功能说明

上传配风计划 PDF 文件，系统自动进行三方面审查：
1. **基本形式审查** — 版本、签字、编制时间、计算过程完整性、语病逻辑
2. **数据一致性审查** — 用风地点完整性、瓦斯/CO₂数据、工作面参数、风速温度匹配
3. **计算核验** — 逐地点调用计算工具核验需风量

三个子智能体并行审查，汇总后流式返回结果，同时生成可下载的 Word 审查报告。

### 请求参数（multipart/form-data）

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `file` | file | 是 | 配风计划 PDF 文件 |
| `session_id` | string | 否 | 会话 ID，新会话可不传 |
| `message` | string | 否 | 附加消息/审查指令 |
| `force_refresh` | bool | 否 | 是否强制重新 OCR 提取（忽略缓存），默认 false |

### 流式响应示例

```
data: {"type":"progress","message":"正在保存上传的 PDF 文件...","agent":"system"}

data: {"type":"progress","message":"PDF 文件已保存，HashID: a1b2c3d4...，正在提取文本内容...","agent":"system","hash_id":"a1b2c3d4..."}

data: {"type":"progress","message":"PaddleOCR 正在扫描第 1/12 页...","agent":"system","ocr_progress":{"page":1,"total":12}}

data: {"type":"progress","message":"PDF 文本提取完成，共 45230 字符。正在初始化审查智能体...","agent":"system"}

data: {"type":"progress","message":"3个审查智能体已就绪，正在并行执行审查...","agent":"system"}

data: {"type":"agent_start","agent":"form-reviewer","message":"「基本形式审查」开始审查..."}
data: {"type":"agent_start","agent":"data-checker","message":"「数据一致性审查」开始审查..."}
data: {"type":"agent_start","agent":"calc-verifier","message":"「计算核验审查」开始审查..."}

data: {"type":"agent_thinking","agent":"form-reviewer","message":"「基本形式审查」正在分析..."}
data: {"type":"agent_executing","agent":"calc-verifier","message":"「计算核验审查」正在采煤面综合需风量计算...","tools":["calc_face_air_volume_max"]}
data: {"type":"agent_tool_result","agent":"calc-verifier","message":"「计算核验审查」采煤面综合需风量计算 完成","tool":"calc_face_air_volume_max"}

data: {"type":"agent_todos","agent":"data-checker","message":"「数据一致性审查」已更新任务进度","todos":[{"content":"查询采掘计划","status":"completed"},{"content":"对比用风地点","status":"in_progress"}]}

data: {"type":"agent_done","agent":"form-reviewer","message":"「基本形式审查」审查完成","preview":"## 基本形式审查结果...","progress":"1/3"}
data: {"type":"agent_done","agent":"data-checker","message":"「数据一致性审查」审查完成","preview":"## 数据一致性审查结果...","progress":"2/3"}
data: {"type":"agent_done","agent":"calc-verifier","message":"「计算核验审查」审查完成","preview":"## 计算核验结果...","progress":"3/3"}

data: {"type":"progress","message":"3个子智能体均已审查完成，正在汇总审查结果...","agent":"system"}

data: {"type":"progress","message":"正在生成最终审查报告...","agent":"system"}

data: {"type":"token","content":"# 最终审查报告\n\n## 审查概况..."}

data: {"type":"progress","message":"正在生成 Word 审查报告...","agent":"system"}

data: {"type":"progress","message":"Word 报告已生成，点击下载","agent":"system","download_url":"http://localhost:8000/static/reports/vent_review_abc123_20260713.docx"}

data: {"type":"done","session_id":"xxx","download_url":"http://localhost:8000/static/reports/vent_review_abc123_20260713.docx"}
```

### subagent 字段说明

| 值 | 含义 |
|----|------|
| `form-reviewer` | 基本形式审查子智能体 |
| `data-checker` | 数据一致性审查子智能体 |
| `calc-verifier` | 计算核验审查子智能体 |

### 审查进度事件详解

#### progress 事件
```json
{
  "type": "progress",
  "message": "正在提取 PDF 文本...",
  "agent": "system",
  "hash_id": "a1b2c3d4...",
  "ocr_progress": {"page": 3, "total": 12},
  "download_url": "http://..."
}
```
| 字段 | 描述 |
|------|------|
| `message` | 进度描述 |
| `agent` | `"system"` 表示系统级进度 |
| `hash_id` | PDF 文件哈希，用于缓存标识 |
| `ocr_progress` | OCR 扫描进度（仅 OCR 阶段出现） |
| `download_url` | Word 报告下载链接（报告生成完成时出现） |

#### agent_start / agent_done / agent_error 事件
```json
{
  "type": "agent_done",
  "agent": "form-reviewer",
  "message": "「基本形式审查」审查完成",
  "preview": "## 基本形式审查结果\n### 1. 版本审查...",
  "progress": "1/3"
}
```
| 字段 | 描述 |
|------|------|
| `agent` | 子智能体标识 |
| `message` | 状态描述 |
| `preview` | 审查结果预览（前 300 字，仅 agent_done） |
| `progress` | 完成进度，格式 `已完成/总数` |
| `error` | 错误详情（仅 agent_error） |

#### agent_thinking / agent_executing / agent_tool_result 事件
```json
{
  "type": "agent_executing",
  "agent": "calc-verifier",
  "message": "「计算核验审查」正在采煤面综合需风量计算...",
  "tools": ["calc_face_air_volume_max"]
}
```
| 字段 | 描述 |
|------|------|
| `agent` | 子智能体标识 |
| `message` | 操作描述 |
| `tools` | 正在执行的工具名称列表（仅 agent_executing） |
| `tool` | 完成的工具名称（仅 agent_tool_result） |

#### agent_todos 事件
```json
{
  "type": "agent_todos",
  "agent": "data-checker",
  "message": "「数据一致性审查」已更新任务进度",
  "todos": [
    {"content": "查询采掘计划", "status": "completed"},
    {"content": "对比用风地点完整性", "status": "in_progress"},
    {"content": "校验瓦斯数据", "status": "pending"}
  ]
}
```

---

## 聊天历史查询接口

**GET** `/api/chat/history/{session_id}`

### 请求参数（Query）

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `limit` | int | 100 | 返回条数上限 |
| `offset` | int | 0 | 偏移量 |

### 响应示例

```json
{
  "session_id": "abc123",
  "messages": [
    {
      "role": "user",
      "content": "15216 辅运起坡段当前风速风量情况如何？"
    },
    {
      "role": "assistant",
      "content": "根据监测数据，该巷道当前..."
    }
  ],
  "total": 10
}
```

### 响应字段

| 字段 | 描述 |
|------|------|
| `session_id` | 会话 ID |
| `messages` | 消息列表，每条包含 `role` 和 `content` |
| `total` | 消息总条数 |

---

## 会话列表接口

**GET** `/api/sessions`

### 请求参数（Query）

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `limit` | int | 20 | 返回条数上限 |
| `offset` | int | 0 | 偏移量 |

### 响应示例

```json
{
  "sessions": [
    {
      "session_id": "xxx",
      "title": "15216 辅运起坡段...",
      "message_count": 5,
      "created_at": "2024-01-15T10:30:00"
    }
  ],
  "total": 15
}
```

---

## 删除会话接口

**DELETE** `/api/sessions/{session_id}`

### 路径参数

| 参数 | 类型 | 描述 |
|------|------|------|
| `session_id` | string | 要删除的会话 ID |

### 响应示例

```json
{
  "status": "ok",
  "message": "会话 xxx 已删除"
}
```

---

## 工具清单

系统工具分为数据查询、知识库检索、需风量计算、MCP 远程查询四类。

### 数据查询工具（对话解读 / 点选解读）

| 工具名称 | 描述 |
|----------|------|
| `query_tun_data_by_id` | 根据巷道 ID 查询巷道监测数据（风速、风量、瓦斯、温度等） |
| `query_device_data_by_id` | 根据设备 ID 查询设备实时数据和报警信息 |
| `query_devices_by_tunnel` | 根据巷道名称查询关联设备列表 |
| `query_devices_by_tunnel_id` | 根据巷道 ID 查询已绑定设备 |
| `get_tun_list_by_modelid` | 根据模型 ID 获取巷道列表 |
| `query_knowledge_base` | 检索煤矿安全知识库（《煤矿安全规程》条款） |
| `write_todos` | 任务清单管理工具 |

### 需风量计算工具（需风量计算 / 配风计划审查）

| 工具名称 | 描述 |
|----------|------|
| `calc_face_by_gas` | 按瓦斯涌出量计算采煤面需风量 |
| `calc_face_by_workers` | 按人数计算采煤面需风量 |
| `calc_face_by_wind_speed` | 按风速验算采煤面需风量 |
| `calc_face_air_volume_max` | 采煤面需风量综合计算（取各方法最大值） |
| `calc_tunnel_by_gas` | 按瓦斯涌出量计算掘进面需风量 |
| `calc_tunnel_by_explosives` | 按炸药量计算掘进面需风量 |
| `calc_tunnel_by_workers` | 按人数计算掘进面需风量 |
| `calc_tunnel_by_wind_speed` | 按风速验算掘进面需风量 |
| `calc_tunnel_air_volume_max` | 掘进面需风量综合计算（取各方法最大值） |
| `calc_chamber_by_equipment` | 按设备发热量计算机电硐室需风量 |
| `calc_chamber_by_wind_speed` | 按风速验算硐室需风量 |
| `calc_other_by_wind_speed` | 按风速计算其他巷道需风量 |
| `calc_effective_area` | 计算工作面有效断面积 |
| `calc_total_air_volume` | 汇总矿井总需风量 |
| `get_needq_all_data` | 获取通防管控平台全部需风量数据（MCP） |

### MCP 配风计划审查工具（仅 PDF 审查）

| 工具名称 | MCP 服务端工具名 | 描述 |
|----------|-----------------|------|
| `query_mining_plan` | `query_monthly_mining_plan` | 查询煤矿月度采掘计划 |
| `query_face_procedure` | `query_working_face_procedure` | 查询工作面作业规程参数 |
| `query_gas_report` | `query_gas_identification_report` | 查询瓦斯等级鉴定报告 |
| `query_wind_report` | `query_ventilation_report` | 查询测风报表数据 |

### write_todos 工具响应

当调用 `write_todos` 时，会触发 `updated_todo_list` 事件：

```json
{
  "type": "updated_todo_list",
  "source": "main",
  "message": "任务进度已更新",
  "todos": [
    {"content": "查询巷道监测数据", "status": "pending"},
    {"content": "分析风速风量异常", "status": "in_progress"},
    {"content": "生成解读报告", "status": "pending"}
  ]
}
```

Todo 状态枚举：
- `pending`: 待执行
- `in_progress`: 执行中
- `completed`: 已完成

---

## 前端接入示例

### SSE 连接示例 (JavaScript)

```javascript
async function connectChat(message, sessionId = null) {
  const response = await fetch('http://39.97.59.228:8070/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, session_id: sessionId })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        handleSSEMessage(data);
      }
    }
  }
}

function handleSSEMessage(data) {
  switch (data.type) {
    case 'thinking':
      console.log('AI思考中...', data.node);
      break;
    case 'executing':
      console.log('执行工具:', data.tools);
      break;
    case 'token':
      appendContent(data.content);
      break;
    case 'done':
      console.log('完成', data.session_id);
      break;
  }
}
```

---

## 错误处理

### 常见错误码

| HTTP 状态码 | 含义 |
|-------------|------|
| 400 | 请求参数错误 |
| 404 | 会话不存在 |
| 500 | 服务器内部错误 |

### 错误响应格式

```json
{
  "type": "error",
  "message": "详细错误信息"
}
```

---

*文档生成时间: 2024年*