SmartEDT/backend/api/api使用说明.md

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

请求：

{
  "username": "admin",
  "password": "Admin123!",
  "display_name": "系统管理员"
}

响应：

{
  "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

请求：

{
  "username": "admin",
  "password": "Admin123!"
}

响应：同 bootstrap（token + user）。

2.3 获取当前登录用户

• GET /api/auth/me
• Header：Authorization: Bearer <access_token>

响应：

{
  "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 前端请求封装（示例）

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

请求：

{
  "username": "teacher01",
  "display_name": "李老师",
  "password": "123456",
  "role_id": "teacher",
  "is_active": true,
  "extra": {}
}

3.4 更新用户

• PATCH /api/users/{user_id}

请求（示例：变更角色）：

{
  "role_id": "auditor"
}

3.5 禁用用户（软删除）

• DELETE /api/users/{user_id}

3.6 重置密码

• PUT /api/users/{user_id}/password

请求：

{
  "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}（禁用）

创建角色请求示例：

{
  "role_id": "trainer",
  "role_name": "教练",
  "role_desc": "训练教练角色",
  "is_active": true,
  "extra": {}
}

4.2 权限点

• GET /api/permissions
• POST /api/permissions
• DELETE /api/permissions/{perm_code}

创建权限点请求示例：

{
  "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（覆盖设置）

请求示例：

{
  "perm_codes": ["report:export", "report:view"]
}

5. 仿真控制（基础接口）

5.1 查询设备状态（示例）

• GET /api/devices

5.2 启动仿真

• POST /api/simulation/start

请求示例：

{
  "scenario": "紧急制动测试",
  "weather": "sunny",
  "time_period": "day",
  "max_speed_kmh": 120,
  "duration_minutes": 10,
  "driver": "张三",
  "extra": {}
}

响应：

{ "simulation_id": "SIM20260101120000ABCD" }

说明：

• 当前后端会在数据库中创建一条仿真任务记录，并启动本地 mock 设备采样。
• 若已启用 Unity Socket，启动/停止会自动下发 Command(action=start/stop)。

5.3 停止仿真

• POST /api/simulation/{simulation_id}/stop

响应：

{ "simulation_id": "SIM...", "status": "stopped" }

6. Unity 数据交互（仅管理员）

该模块用于将 InitConfig 与 Command 通过 Socket 转发给 Unity 程序（同时在数据库记录）。

6.1 发送 InitConfig（主控 → Unity）

• POST /api/unity/initconfig

请求：

{
  "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": "城市道路" }
  }
}

响应：

{ "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

请求示例：

{
  "payload": {
    "msgType": "command",
    "action": "start",
    "mode": { "type": "realtime" }
  }
}

响应：

{ "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 后的广播回显