emcp/document/前后端启动说明.md

# 电气量测控平台前后端启动说明

## 1. 文档说明

本文档用于说明 `EMCP` 项目前后端的开发环境准备、依赖安装、启动步骤、访问地址以及常见问题处理方式。

项目目录：

- 根目录：`d:\Trae_space\EMCP`
- 后端目录：`d:\Trae_space\EMCP\backend`
- 前端目录：`d:\Trae_space\EMCP\frontend`
- 文档目录：`d:\Trae_space\EMCP\document`

---

## 2. 当前项目技术栈

### 2.1 后端

- 语言：`Python 3.8`
- 当前虚拟环境版本：`Python 3.8.10`
- 框架：`FastAPI`
- 服务启动：`Uvicorn`
- 配置存储：`JSON`
- 报警存储：`SQLite`
- 实时通信：`WebSocket`

### 2.2 前端

- 框架：`Vue 3`
- 构建工具：`Vite`
- HTTP 请求：`Axios`

---

## 3. 启动前准备

### 3.1 后端准备

后端目录已创建虚拟环境：

- 虚拟环境路径：`d:\Trae_space\EMCP\backend\.venv`

如虚拟环境不存在，可在 `backend` 目录重新创建：

```powershell
cd d:\Trae_space\EMCP\backend
py -3.8 -m venv .venv
```

激活虚拟环境：

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
```

### 3.2 前端准备

确保本机已安装：

- `Node.js`
- `npm`

进入前端目录后通过 `npm` 安装依赖。

---

## 4. 首次安装依赖

### 4.1 安装后端依赖

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
```

说明：

- 当前项目已包含 `setup.py` 与 `pyproject.toml`
- 若 `pip install -e .[dev]` 因环境兼容问题失败，可先升级 `pip` 后重试：

```powershell
python -m pip install --upgrade pip
pip install -e .[dev]
```

### 4.2 安装前端依赖

```powershell
cd d:\Trae_space\EMCP\frontend
npm install
```

---

## 5. 启动后端

### 5.1 启动命令

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload
```

### 5.2 启动成功标志

终端出现类似信息表示启动成功：

```text
Uvicorn running on http://127.0.0.1:8000
```

### 5.3 后端访问地址

- 健康检查：`http://127.0.0.1:8000/`
- 接口文档：`http://127.0.0.1:8000/docs`
- OpenAPI：`http://127.0.0.1:8000/openapi.json`

### 5.4 后端主要接口

- 实时数据：`GET /api/real-time-data`
- 设备状态：`GET /api/device-status`
- 设备配置：`POST /api/config/device`
- 通道配置：`POST /api/config/channel`
- 线路报警设置：`POST /api/config/line_alarm_setting`
- AI 报警设置：`POST /api/config/ai_alarm_setting`
- 系统设置：`POST /api/config/system`
- 报警历史：`GET /api/alarm/list`
- 控制指令：`POST /api/control/switch`

### 5.5 WebSocket 地址

- 实时数据：`ws://127.0.0.1:8000/ws/real-time`
- 报警推送：`ws://127.0.0.1:8000/ws/alarm`

### 5.6 后端 Debug 调试启动

开发阶段如果需要断点调试后端，推荐使用以下两种方式。

#### 方式一：在 IDE 中直接调试 `uvicorn`

适用于 `Trae / VS Code / Cursor` 一类支持 `launch.json` 的编辑器。

可在工作区创建或补充调试配置文件：

- `d:\Trae_space\EMCP\.vscode\launch.json`

示例配置：

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug FastAPI Backend",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "cwd": "d:\\Trae_space\\EMCP\\backend",
      "args": [
        "app.main:app",
        "--host",
        "127.0.0.1",
        "--port",
        "8000",
        "--reload"
      ],
      "jinja": true,
      "justMyCode": true
    }
  ]
}
```

使用方式：

1. 打开项目根目录 `d:\Trae_space\EMCP`
2. 选择 `Debug FastAPI Backend`
3. 启动调试
4. 在 `backend/app/` 下设置断点

说明：

- `cwd` 必须指向 `backend`，否则 `app.main:app` 可能导入失败
- 调试时建议使用后端虚拟环境解释器：`d:\Trae_space\EMCP\backend\.venv\Scripts\python.exe`
- 如果 `--reload` 导致断点命中不稳定，可临时去掉 `--reload`

#### 方式二：使用 `debugpy` 启动后再附加调试

先安装调试依赖：

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
pip install debugpy
```

然后使用以下命令启动：

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m debugpy --listen 5678 -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

启动后可在 IDE 中使用“附加到进程/Attach”方式连接：

- 主机：`127.0.0.1`
- 端口：`5678`

如果不需要热重载，也可以使用更稳定的命令：

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m debugpy --listen 5678 -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

#### Debug 调试建议

- 需要稳定断点时，优先关闭 `--reload`
- 排查接口逻辑时，建议在以下位置打断点：
  - `backend/app/api/routes/`
  - `backend/app/services/platform_service.py`
  - `backend/app/adapters/device_client.py`
- 如果要调试模拟采集链路，可重点查看：
  - `backend/app/tasks/polling.py`
  - `backend/app/cache/memory_store.py`
  - `backend/app/ws/manager.py`

---

## 6. 启动前端

### 6.1 启动命令

```powershell
cd d:\Trae_space\EMCP\frontend
npm run dev -- --host 127.0.0.1 --port 5173
```

### 6.2 启动成功标志

终端出现类似地址表示启动成功：

```text
Local: http://127.0.0.1:5173/
```

### 6.3 前端访问地址

- 前端页面：`http://127.0.0.1:5173/`

---

## 7. 推荐启动顺序

建议按以下顺序启动：

1. 先启动后端
2. 再启动前端
3. 浏览器打开前端地址进行联调

原因：

- 前端默认请求后端接口：`http://127.0.0.1:8000/api`
- 前端默认连接后端 WebSocket：
  - `ws://127.0.0.1:8000/ws/real-time`
  - `ws://127.0.0.1:8000/ws/alarm`

前端接口配置位置：

- `frontend/src/api/http.ts`

默认请求头中已携带：

- `X-API-Token: admin123`

---

## 8. 模拟系统说明

当前项目后端默认启用模拟设备采集。

后端配置位置：

- `backend/app/core/config.py`

当前关键配置：

```python
use_mock_device: bool = True
poll_interval_seconds: float = 0.5
```

说明：

- `use_mock_device = True` 表示使用模拟设备数据源
- 后端会按 `0.5` 秒周期采集模拟数据
- 前端可用于联调实时数据、设备状态、报警历史、控制指令、配置保存等功能

---

## 9. 当前已打通页面

当前前端页面均已可以进入，已完成联调的页面如下：

- 实时数据
- 设备状态
- 设备配置
- 通道配置
- 报警设置
- 报警历史
- 控制指令
- 系统设置

其中：

- `设备状态` 支持手动刷新
- `报警历史` 支持分页和刷新
- `设备配置 / 通道配置 / 报警设置` 已接通真实后端提交接口

---

## 10. 常用开发命令

### 10.1 后端测试

```powershell
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m pytest
```

### 10.2 前端构建

```powershell
cd d:\Trae_space\EMCP\frontend
npm run build
```

---

## 11. 常见问题

### 11.1 后端启动失败，提示类型注解错误

如果出现类似报错：

```text
TypeError: 'type' object is not subscriptable
```

原因通常是 Python 版本不兼容。当前项目要求使用：

- `Python 3.8`

请确认虚拟环境版本是否正确。

### 11.2 前端页面打不开

请检查：

- 前端服务是否已启动
- 地址是否为 `http://127.0.0.1:5173/`
- `npm install` 是否已执行成功

### 11.3 前端有页面但接口不通

请检查：

- 后端服务是否已启动
- 后端地址是否为 `http://127.0.0.1:8000`
- `frontend/src/api/http.ts` 中 `baseURL` 是否正确

### 11.4 页面能打开但实时数据不更新

请检查：

- 后端是否正常运行
- 后端轮询任务是否已启动
- WebSocket 是否可连
- 若 WebSocket 未连通，前端当前会自动回退到 HTTP 轮询读取实时数据

### 11.5 保存接口返回 401 或 403

请检查请求头中是否包含：

```text
X-API-Token: admin123
```

---

## 12. 关闭服务

在各自终端中按：

```text
Ctrl + C
```

即可停止前端或后端服务。

---

## 13. 建议

日常开发建议保持两个独立终端：

- 终端 1：后端 `uvicorn`
- 终端 2：前端 `vite`

如果需要后续交付或部署，可在本说明基础上继续补充：

- 生产环境启动说明
- Windows 开机自启说明
- Ubuntu / RK3568 部署说明
- Nginx 反向代理说明