# API 清单

统一前缀：`/api/v1`

## 系统

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/system/info` | 平台、数据库和 Agent 信息 |
| GET | `/system/health` | 业务数据库健康检查 |
| GET | `/health` | 服务级健康检查 |

## 驾驶舱与矿井

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/dashboard/overview` | 驾驶舱 KPI 与模块汇总 |
| GET | `/mines` | 矿井列表 |
| POST | `/mines` | 新增矿井 |
| GET | `/mines/{id}` | 矿井详情 |
| GET | `/mines/{id}/areas` | 采区列表 |
| GET | `/mines/{id}/work-faces` | 工作面列表 |
| GET | `/mines/{id}/roadways` | 巷道列表 |

## 业务资料

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/documents` | 分页、分类和关键词检索 |
| GET | `/documents/categories` | 分类统计 |
| GET | `/documents/templates` | 按 PDF、Word、Excel 查询抽取模板 |
| POST | `/documents` | 创建资料元数据 |
| POST | `/documents/upload` | 上传资料文件并自动进入解析、抽取工作流 |
| GET | `/documents/{id}` | 资料及结构化字段详情 |
| PATCH | `/documents/{id}` | 更新资料 |
| DELETE | `/documents/{id}` | 删除资料 |
| GET | `/documents/{id}/processing` | 查看 MinerU 解析和模型抽取进度 |
| POST | `/documents/{id}/process` | 重新执行解析和抽取 |
| POST | `/documents/{id}/extractions` | 新增结构化字段 |

上传表单支持 `parse_mode`：

| 值 | 模式 | MinerU API | 限制 |
|---|---|---|---|
| `lightweight` | 轻量解析 | `/api/v1/agent/parse/file` | 10 MB / 20 页 |
| `precision` | 精准解析 | `/api/v4/file-urls/batch` | 200 MB / 200 页 |

## 数据感知

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/monitoring/overview` | 数据源、传感器、设施和告警汇总 |
| GET | `/monitoring/sources` | 数据源 |
| GET | `/monitoring/sensors` | 传感器 |
| GET | `/monitoring/sensors/{id}/readings` | 最近监测值 |
| POST | `/monitoring/readings` | 写入实时监测值 |
| GET | `/monitoring/facilities` | 通风设施 |
| GET | `/monitoring/alarms` | 告警 |

## 知识中心

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/knowledge` | 知识列表 |
| POST | `/knowledge` | 新增知识 |
| POST | `/knowledge/search` | 关键词检索和排序 |
| GET | `/knowledge/overview` | 远端知识库状态、知识条目和分类统计 |
| GET | `/knowledge/catalog` | 远端知识目录，支持分类、标签和关键词筛选 |
| GET | `/knowledge/catalog/{note_id}` | 远端知识条目详情和完整内容 |
| POST | `/knowledge/ask` | 面向页面问答的检索、来源追溯和摘要回答 |
| POST | `/knowledge/rag` | RAG 问答，检索知识库并调用大模型生成带引用回答 |
| POST | `/knowledge/rag/stream` | RAG 问答 SSE 流式接口，逐段返回模型生成内容 |
| GET | `/knowledge/rag/stream` | EventSource 流式接口，参数为 `question` 和 `top_k` |
| WS | `/knowledge/rag/ws` | WebSocket 流式接口，客户端发送问题，服务端逐帧推送结果 |
| GET | `/knowledge/graph` | 基于知识标签生成风险关联关系图 |

知识中心通过 `KNOWLEDGE_SERVICE_BASE` 接入远端 Obsidian Vault 检索服务。
远端未启用向量模型时，后端会自动将 `semantic`/`hybrid` 请求降级为 `keyword`，
并对中文整句自动提取“局部通风机、瓦斯超限、风量”等领域关键词后多路检索。
`/knowledge/ask` 默认调用 RAG 生成，也可将 `generate_answer` 设为 `false` 只返回检索摘要。
`/knowledge/rag` 始终启用大模型生成。生成阶段会把编号后的检索片段作为上下文，
要求模型只依据资料回答并标注 `[1]`、`[2]` 来源编号；模型不可用时自动降级为检索摘要。
寒暄、自我介绍和能力咨询会先经过意图路由，不进入知识检索，直接由大模型简洁回复。

`/knowledge/rag/stream` 返回 `text/event-stream`，事件顺序为：

1. `meta`：问题、检索模式、来源列表和检索耗时。
2. `thinking`：模型返回的推理过程增量内容。
3. `delta`：模型正式回答的逐段内容。
4. `warning`：流式生成异常时的非阻断告警。
5. `done`：完整回答、最终状态、模型名和生成耗时。

页面优先使用 WebSocket，避免部分浏览器或代理对 SSE 响应进行整体缓冲；
WebSocket 不可用时自动回退到 EventSource 或 `fetch` 流。
前端将 `thinking` 放入可折叠容器，回答内容按 Markdown 渲染，来源在回答结束后显示。

## 缺陷诊断

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/diagnosis/rules` | 诊断规则 |
| GET | `/diagnosis/tasks` | 诊断任务 |
| GET | `/diagnosis/tasks/{id}` | 结果和证据链 |
| POST | `/diagnosis/run` | 执行规则诊断 |

## 综合评价

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/evaluations/indicators` | 评价指标 |
| POST | `/evaluations/indicators` | 新增指标 |
| GET | `/evaluations/runs` | 评价批次 |
| GET | `/evaluations/runs/{id}` | 评价和指标得分 |
| POST | `/evaluations/run` | 执行综合评价 |

## 闭环处置

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/work-orders` | 整改任务 |
| POST | `/work-orders` | 新建任务 |
| GET | `/work-orders/{id}` | 任务详情 |
| PATCH | `/work-orders/{id}` | 更新任务状态 |
| GET | `/work-orders/{id}/events` | 任务轨迹 |
| POST | `/work-orders/{id}/events` | 添加处理事件 |

## DeepAgent

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/ai/capabilities` | Agent 和工作流状态 |
| POST | `/ai/workflows/run` | 运行诊断、评价、问答或资料分析工作流 |
| POST | `/ai/chat?stream=false` | 知识问答 JSON 响应 |
| POST | `/ai/chat?stream=true` | 知识问答 SSE 响应 |