# 架构说明

## 分层边界

### API 层

负责 HTTP 参数、状态码、分页和响应模型，不直接编写 SQL，不保存业务状态。所有路由统一挂载在 `/api/v1`。

### 服务层

负责业务规则和事务编排：

- `diagnosis_service`：基于监测、设施和工作面数据执行规则诊断
- `evaluation_service`：计算五维指标、综合得分和等级
- `work_order_service`：生成任务编号并记录状态迁移
- `knowledge_service`：检索和排序知识条目
- `knowledge_hub_service`：接入远端 Vault 知识检索、目录聚合、问答和风险图谱
- `knowledge_hub_service` RAG 流程：多路召回 → 去重排序 → 上下文裁剪 →
  DeepAgent 生成 → 来源编号回传；模型失败时返回抽取式摘要
- 知识中心支持 SSE 流式 RAG，先返回来源元数据，再逐段推送模型 token，最后发送完成事件
- 页面优先通过 WebSocket 接收 RAG token，SSE 与 fetch 作为兼容回退

### Repository 层

负责 SQLAlchemy 查询和持久化。未来切换数据源时，API 与服务层不需要修改。

### Agent 层

DeepAgent 只增强以下能力：

- 诊断根因和耦合关系解释
- 综合评价解释和优化建议
- 基于检索结果的知识问答
- 业务资料字段分析

数值计算、风险等级和数据库写入由确定性服务完成。模型失败时返回规则引擎结果，不阻断业务。

## 数据流

```text
数据源 / 业务资料 / 监测数据
        │
        ▼
数据接入与结构化存储
        │
        ├── 知识条目与检索
        ├── 缺陷规则与诊断结果
        ├── 评价指标与评价批次
        └── 告警与整改工单
        │
        ▼
DeepAgent 解释、归纳、问答和建议
```

## 并发与一致性

- 普通 CRUD 使用同步 SQLAlchemy Session，FastAPI 在线程池执行同步依赖。
- DeepAgent 工作流使用异步模型调用。
- 诊断和评价的计算结果先落库，再调用模型生成解释。
- 工单状态迁移记录 `work_order_events`，保留完整轨迹。

## 生产扩展

- 高频监测数据建议迁移到 TDengine、InfluxDB 或同类时序数据库。
- 文件建议迁移到 MinIO 或对象存储。
- 知识向量迁移到 Milvus、pgvector 或 Elasticsearch。
- 知识中心当前接入远端 Obsidian Vault 检索服务；远端仅负责召回，平台负责分类、
  来源追溯、可选生成式回答和页面数据聚合。
- 用户鉴权、RBAC 和矿井级数据隔离需要在上线前补齐。
- 单机部署可直接运行；高并发场景应拆分 API、Agent Worker 和采集服务。