# 矿山通防智能管控平台后端

独立于 `vent_agent_2.0` 的新后端框架，使用：

- FastAPI：HTTP 服务、OpenAPI、依赖注入和 SSE
- SQLAlchemy 2.0：业务数据库 ORM
- Alembic：数据库迁移
- MySQL / SQLite：生产与本地开发双数据库支持
- DeepAgent + LangGraph：智能体、知识问答、诊断解释、评价优化和业务工作流

## 架构定位

普通业务数据使用 REST API 管理，DeepAgent 不直接负责数据库增删改查。诊断与评价先由确定性规则引擎计算，再由 DeepAgent 补充根因分析、解释和优化建议。未配置模型或未安装 Agent 依赖时，系统自动降级，业务 API 仍然可用。

```text
API 层
  dashboard / documents / monitoring / video-platform / knowledge
  diagnosis / evaluations / work-orders / ai

服务层
  业务规则 / 诊断引擎 / 评价引擎 / 工单状态机 / DeepAgent 工作流

数据层
  SQLAlchemy ORM / Repository / MySQL / SQLite / Alembic
```

## 目录

```text
app/
  api/v1/endpoints/    HTTP 接口
  agents/              DeepAgent 运行时、上下文和工作流
  core/                配置、日志、异常和中间件
  db/models/           数据库模型
  db/repositories/     数据访问层
  schemas/             请求与响应模型
  services/            业务服务层
alembic/               数据库迁移
docs/                  架构、数据库和接口文档
scripts/               初始化、种子数据
tests/                 自动化测试
```

详细设计见 [架构说明](docs/architecture.md)、[数据库设计](docs/database-design.md) 和 [API 文档](docs/api.md)。

## 本地启动

要求 Python 3.12。

```powershell
cd D:\PycharmProjects\vent_platform_backend
python -m venv .venv
.\.venv\Scripts\python -m pip install -U pip
.\.venv\Scripts\python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python scripts\seed_demo.py
.\.venv\Scripts\python -m uvicorn app.main:app --reload --port 8090
```

浏览器访问：

- Swagger：`http://127.0.0.1:8090/docs`
- 健康检查：`http://127.0.0.1:8090/health`
- API 前缀：`http://127.0.0.1:8090/api/v1`

默认使用 SQLite。生产环境建议使用 MySQL：

```dotenv
DATABASE_DIALECT=mysql
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=vent_platform
```

也可以直接启动 MySQL：

```powershell
docker compose up -d mysql
```

## DeepAgent

在 `.env` 中配置 OpenAI 兼容模型：

```dotenv
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.deepseek.com
DEEPAGENT_MODEL=deepseek-flash
```

没有配置模型时：

- `/api/v1/ai/capabilities` 会显示智能体未启用
- 诊断、评价、业务 CRUD 和知识检索仍可运行
- AI 工作流返回规则引擎生成的降级说明

## 数据库迁移

```powershell
.\.venv\Scripts\alembic upgrade head
.\.venv\Scripts\alembic revision --autogenerate -m "change description"
```

初始迁移 `0001_initial` 创建当前全部表。后续结构变化应生成显式增量迁移。

## 工业视频平台演示数据

页面“工业视频平台”的后端数据保存在 `video_channels`、`video_snapshots`、
`video_analysis_events`、`video_records` 四张表中，覆盖风门、局部风机、主风机及配电室三个模块：
通道与设备树、分屏预览、状态总览、识别抓拍、通行与操作记录、视频分析事件。

视频与图像文件不入库，表字段保存磁盘绝对路径，媒体根目录由 `VIDEO_MEDIA_ROOT` 指定
（默认 `D:/workspace/js/gate_analysis_system`，即风门/局扇/主扇识别演示系统的公开资源目录）。
接口 `/api/v1/video-platform/channels/{id}/stream` 按库中路径流式返回视频并支持 Range 拖动，
`/api/v1/video-platform/snapshots/{id}/image` 返回抓拍原图。

已有数据库补种视频平台演示数据（幂等，可重复执行）：

```powershell
.\.venv\Scripts\python scripts\seed_video_platform.py
```

## 测试

```powershell
.\.venv\Scripts\python -m pytest
```