增加了API接口调用说明

backend/api/api使用说明.md

@@ -0,0 +1,322 @@
+# SmartEDT 后端 API 使用说明（Web 前端）
+
+本文档面向 Web 前端调用方，按当前后端代码实现汇总接口清单、鉴权方式、请求/响应示例与常见错误。
+
+## 1. 基本约定
+
+- 服务地址：`http://<host>:5000`
+- JSON 请求：
+  - Header：`Content-Type: application/json`
+  - Body：UTF-8 JSON
+- 鉴权：
+  - 需要登录的接口统一使用 Header：`Authorization: Bearer <access_token>`
+- 返回错误：
+  - `401`：未登录 / token 缺失或无效
+  - `403`：无权限（当前多数管理接口仅允许管理员 `role_id=admin`）
+  - `404`：资源不存在
+  - `409`：资源冲突（例如唯一键冲突、系统已初始化）
+
+## 2. 鉴权（Auth）
+
+### 2.1 首次初始化（创建首个管理员）
+
+仅当系统还没有任何用户时可调用；成功后返回 token 与用户信息。
+
+- `POST /api/auth/bootstrap`
+
+请求：
+```json
+{
+  "username": "admin",
+  "password": "Admin123!",
+  "display_name": "系统管理员"
+}
+```
+
+响应：
+```json
+{
+  "token": {
+    "access_token": "v1....",
+    "token_type": "bearer",
+    "expires_in": 3600
+  },
+  "user": {
+    "user_id": "user_...",
+    "username": "admin",
+    "display_name": "系统管理员",
+    "role_id": "admin",
+    "role_name": "系统管理员",
+    "is_active": true,
+    "last_login_at": null,
+    "created_at": "2026-01-01T00:00:00+00:00",
+    "updated_at": "2026-01-01T00:00:00+00:00",
+    "extra": null
+  }
+}
+```
+
+### 2.2 登录获取 token
+
+- `POST /api/auth/login`
+
+请求：
+```json
+{
+  "username": "admin",
+  "password": "Admin123!"
+}
+```
+
+响应：同 `bootstrap`（`token + user`）。
+
+### 2.3 获取当前登录用户
+
+- `GET /api/auth/me`
+- Header：`Authorization: Bearer <access_token>`
+
+响应：
+```json
+{
+  "user": {
+    "user_id": "user_...",
+    "username": "admin",
+    "display_name": "系统管理员",
+    "role_id": "admin",
+    "role_name": "系统管理员",
+    "is_active": true,
+    "last_login_at": "2026-01-01T00:00:00+00:00",
+    "created_at": "2026-01-01T00:00:00+00:00",
+    "updated_at": "2026-01-01T00:00:00+00:00",
+    "extra": null
+  }
+}
+```
+
+### 2.4 前端请求封装（示例）
+
+```js
+async function apiFetch(path, { token, method = "GET", body } = {}) {
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(`http://127.0.0.1:5000${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(await res.text());
+  return await res.json();
+}
+```
+
+## 3. 用户管理（仅管理员）
+
+### 3.1 用户列表
+- `GET /api/users`
+
+### 3.2 用户详情
+- `GET /api/users/{user_id}`
+
+### 3.3 创建用户
+- `POST /api/users`
+
+请求：
+```json
+{
+  "username": "teacher01",
+  "display_name": "李老师",
+  "password": "123456",
+  "role_id": "teacher",
+  "is_active": true,
+  "extra": {}
+}
+```
+
+### 3.4 更新用户
+- `PATCH /api/users/{user_id}`
+
+请求（示例：变更角色）：
+```json
+{
+  "role_id": "auditor"
+}
+```
+
+### 3.5 禁用用户（软删除）
+- `DELETE /api/users/{user_id}`
+
+### 3.6 重置密码
+- `PUT /api/users/{user_id}/password`
+
+请求：
+```json
+{
+  "new_password": "NewPass123!"
+}
+```
+
+## 4. 角色/权限管理（仅管理员）
+
+### 4.1 角色
+- `GET /api/roles`
+- `GET /api/roles/{role_id}`
+- `POST /api/roles`
+- `PATCH /api/roles/{role_id}`
+- `DELETE /api/roles/{role_id}`（禁用）
+
+创建角色请求示例：
+```json
+{
+  "role_id": "trainer",
+  "role_name": "教练",
+  "role_desc": "训练教练角色",
+  "is_active": true,
+  "extra": {}
+}
+```
+
+### 4.2 权限点
+
+- `GET /api/permissions`
+- `POST /api/permissions`
+- `DELETE /api/permissions/{perm_code}`
+
+创建权限点请求示例：
+```json
+{
+  "perm_code": "report:export",
+  "perm_name": "报表导出",
+  "perm_group": "report",
+  "perm_desc": "允许导出报表"
+}
+```
+
+### 4.3 给角色配置权限点
+
+- `GET /api/roles/{role_id}/permissions`
+- `PUT /api/roles/{role_id}/permissions`（覆盖设置）
+
+请求示例：
+```json
+{
+  "perm_codes": ["report:export", "report:view"]
+}
+```
+
+## 5. 仿真控制（基础接口）
+
+### 5.1 查询设备状态（示例）
+- `GET /api/devices`
+
+### 5.2 启动仿真
+- `POST /api/simulation/start`
+
+请求示例：
+```json
+{
+  "scenario": "紧急制动测试",
+  "weather": "sunny",
+  "time_period": "day",
+  "max_speed_kmh": 120,
+  "duration_minutes": 10,
+  "driver": "张三",
+  "extra": {}
+}
+```
+
+响应：
+```json
+{ "simulation_id": "SIM20260101120000ABCD" }
+```
+
+说明：
+- 当前后端会在数据库中创建一条仿真任务记录，并启动本地 mock 设备采样。
+- 若已启用 Unity Socket，启动/停止会自动下发 `Command(action=start/stop)`。
+
+### 5.3 停止仿真
+- `POST /api/simulation/{simulation_id}/stop`
+
+响应：
+```json
+{ "simulation_id": "SIM...", "status": "stopped" }
+```
+
+## 6. Unity 数据交互（仅管理员）
+
+该模块用于将 `InitConfig` 与 `Command` 通过 Socket 转发给 Unity 程序（同时在数据库记录）。
+
+### 6.1 发送 InitConfig（主控 → Unity）
+
+- `POST /api/unity/initconfig`
+
+请求：
+```json
+{
+  "payload": {
+    "msgType": "init",
+    "timestamp": 1737388800000,
+    "session": {
+      "sessionId": "sess_20250120_143000_001",
+      "taskId": "task_brake_001",
+      "taskName": "紧急制动测试",
+      "createTime": "2025-01-20 14:30:00",
+      "syncTimestamp": 1737388800000
+    },
+    "driver": { "driverId": "D20250001", "name": "张三" },
+    "vehicle": { "vehicleId": "V003", "model": "改装教学车A型" },
+    "scene": { "sceneId": "scene_03", "sceneName": "城市道路" }
+  }
+}
+```
+
+响应：
+```json
+{ "simulation_id": "task_brake_001" }
+```
+
+说明：
+- 后端会把 `payload` 存入 `sim_tasks.init_config`，并记录 `init_sent_at`。
+- `simulation_id` 当前等于 `payload.session.taskId`（若该值长度不合规则会自动生成）。
+
+### 6.2 发送 Command（主控 → Unity）
+
+- `POST /api/unity/command`
+
+请求示例：
+```json
+{
+  "payload": {
+    "msgType": "command",
+    "action": "start",
+    "mode": { "type": "realtime" }
+  }
+}
+```
+
+响应：
+```json
+{ "ok": true }
+```
+
+说明：
+- 如果请求体未传 `timestamp/seqId`，后端会自动补齐。
+
+## 7. 文件下载
+
+- `GET /files/{file_path}`
+
+说明：
+- `file_path` 必须是相对路径，后端会做目录穿越校验。
+
+## 8. WebSocket（服务端推送）
+
+- 地址：`ws://<host>:5000/ws`
+- 当前实现：无需鉴权；连接建立后服务端会主动广播各类事件。
+
+常见消息类型（`message.type`）：
+- `server.metrics`：服务器监控指标
+- `simulation.status`：仿真状态变化（running/stopped）
+- `vehicle.signal`：车辆信号数据（采样 + 广播）
+- `simulation.init_config`：调用 `/api/unity/initconfig` 后的广播回显
+- `simulation.command`：调用 `/api/unity/command` 后的广播回显
+