diff --git a/software/前后端对接文档.md b/software/前后端对接文档.md deleted file mode 100644 index f7d78d2b..00000000 --- a/software/前后端对接文档.md +++ /dev/null @@ -1,727 +0,0 @@ -# 智途投送系统 — 前后端对接文档 - -> 版本：v1.0 -> 服务器：阿里云 ECS `121.41.216.243` -> 系统：Ubuntu 24.04 -> 数据库：SQLite（文件 `/opt/zhitu/zhitu.db`） - ---- - -## 一、服务器信息 - -| 项目 | 值 | -|------|-----| -| 公网 IP | `121.41.216.243` | -| 访问方式 | `http://121.41.216.243`（Nginx 80 端口） | -| 直连后端 | `http://121.41.216.243:5000`（Gunicorn） | -| 通信协议 | HTTP（明文，未配置 HTTPS） | - -**推荐**：所有接口统一走 `http://121.41.216.243/api/xxx`，无需加 `:5000`。 - ---- - -## 二、认证说明 - -### 2.1 Token 机制 - -- 登录成功后，后端返回 `token` 字符串 -- 后续所有需要认证的接口，需在请求头中携带： - -```http -X-Auth-Token: -``` - -或在 URL 参数中携带（调试用）： - -```http -GET /api/task/current?soldier_id=xxx&token= -``` - -### 2.2 免认证接口（无需 Token） - -以下接口可直接访问，无需登录： - -| 接口 | 说明 | -|------|------| -| `GET /api/ping` | 存活检测 | -| `GET /api/auth/accounts` | 查看所有账号 | -| `GET /api/demands` | 查看所有需求 | - ---- - -## 三、API 接口总览 - -### 3.1 账号系统 - -#### ① 注册账号 - -```http -POST /api/auth/register -Content-Type: application/json -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "password": "123456", - "name": "张三", - "unit": "第3步兵师/1连", - "role": "狙击手" -} -``` - -**响应**： - -```json -// 成功 -{ "ok": true, "message": "注册成功" } - -// 失败 -{ "ok": false, "error": "该士兵编号已注册" } // 409 -{ "ok": false, "error": "士兵编号、密码、姓名不能为空" } // 400 -``` - ---- - -#### ② 登录 - -```http -POST /api/auth/login -Content-Type: application/json -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "password": "123456" -} -``` - -**响应**： - -```json -// 成功 -{ - "ok": true, - "token": "a1b2c3d4e5f6...", - "soldier_id": "soldier_001", - "name": "张三", - "unit": "第3步兵师/1连", - "role": "狙击手" -} - -// 失败 -{ "ok": false, "error": "士兵编号不存在" } // 404 -{ "ok": false, "error": "密码错误" } // 401 -``` - ---- - -#### ③ 查看当前登录用户 - -```http -GET /api/auth/me -X-Auth-Token: -``` - -**响应**： - -```json -{ - "ok": true, - "user": { - "soldier_id": "soldier_001", - "name": "张三", - "unit": "第3步兵师/1连", - "role": "狙击手" - } -} -``` - ---- - -#### ④ 查看所有账号（免认证） - -```http -GET /api/auth/accounts -``` - -**响应**： - -```json -{ - "accounts": [ - { "soldier_id": "soldier_001", "name": "张三", "unit": "...", "role": "..." }, - { "soldier_id": "soldier_002", "name": "李四", "unit": "...", "role": "..." } - ] -} -``` - ---- - -### 3.2 士兵位置 - -#### ① 上报位置（需认证） - -```http -POST /api/soldier/location -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "id": "soldier_001", - "name": "张三", - "lat": 30.1234, - "lng": 120.5678 -} -``` - -**响应**： - -```json -{ "ok": true } -``` - ---- - -#### ② 获取所有士兵位置（免认证） - -```http -GET /api/soldiers -``` - -**响应**： - -```json -{ - "soldiers": [ - { - "soldier_id": "soldier_001", - "name": "张三", - "lat": 30.1234, - "lng": 120.5678, - "updated_at": "2026-05-23 12:00:00" - } - ] -} -``` - ---- - -### 3.3 物资需求 - -#### ① 上报需求（需认证） - -```http -POST /api/demand -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "soldier_name": "张三", - "type": "弹药", - "quantity": 20, - "unit": "发", - "urgency": "紧急", - "drop_point": { "lat": 30.1234, "lng": 120.5678 } -} -``` - -> `drop_point` 可为空或字符串，后端会自动从 `soldiers` 表补全当前位置。 - -**响应**： - -```json -{ "ok": true, "id": "REQ-001" } -``` - ---- - -#### ② 查看需求列表（免认证） - -```http -GET /api/demands?soldier_id=soldier_001 -``` - -**参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `soldier_id` | string | 否 | 指定士兵 ID，不填则返回所有"待处理"需求 | - -**响应**： - -```json -{ - "demands": [ - { - "id": "REQ-001", - "soldier_id": "soldier_001", - "soldier_name": "张三", - "type": "弹药补给", - "items": "弹药 × 20发", - "quantity": 20, - "unit": "发", - "urgency": "紧急", - "status": "待处理", - "lat": 30.1234, - "lng": 120.5678, - "created_at": "2026-05-23 12:00:00" - } - ] -} -``` - ---- - -#### ③ 查看单个需求（需认证） - -```http -GET /api/demands/REQ-001 -X-Auth-Token: -``` - -**响应**： - -```json -{ "demand": { ... } } -``` - ---- - -### 3.4 任务调度 - -#### ① 派发任务（需认证） - -```http -POST /api/task/dispatch -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "soldier_name": "张三", - "type": "弹药投送", - "demand_id": "REQ-001", - "start_name": "后方阵地", - "target_name": "A区街角12号", - "start_lat": 30.0, - "start_lng": 120.0, - "end_lat": 30.1234, - "end_lng": 120.5678, - "safety_score": 90 -} -``` - -**响应**： - -```json -{ - "ok": true, - "task": { - "id": "#001", - "soldier_id": "soldier_001", - "type": "弹药投送", - "status": "执行中", - "progress": 0, - "eta": "计算中...", - "remain_time": "计算中...", - "start_name": "后方阵地", - "target_name": "A区街角12号", - "start_lat": 30.0, - "start_lng": 120.0, - "end_lat": 30.1234, - "end_lng": 120.5678, - "safety_score": 90, - "created_at": "2026-05-23 12:00:00" - } -} -``` - -> 派发任务后，对应需求 `REQ-001` 的 `status` 会自动更新为 `"已调度"`。 - ---- - -#### ② 获取当前任务（需认证） - -```http -GET /api/task/current?soldier_id=soldier_001 -X-Auth-Token: -``` - -**响应**： - -```json -{ - "task": { - "id": "#001", - "status": "执行中", - "progress": 50, - "eta": "2分钟", - ... - } -} - -// 无任务时 -{ - "task": { - "id": "#--", "status": "无任务", "progress": 0, - "eta": "--", "remain_time": "--", - "start_name": "--", "target_name": "--", "safety_score": 0 - } -} -``` - ---- - -#### ③ 更新任务进度（需认证） - -```http -POST /api/task/update -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "progress": 75, - "status": "执行中", - "eta": "1分钟", - "remain_time": "60秒" -} -``` - -**响应**： - -```json -{ "ok": true, "task": { ... } } -``` - ---- - -### 3.5 投放点 - -#### ① 获取投放点列表（免认证） - -```http -GET /api/drop-points -``` - -**响应**： - -```json -{ - "drop_points": [ - { "id": 1, "name": "A区街角12号", "lat": 30.1234, "lng": 120.5678 } - ] -} -``` - ---- - -#### ② 添加投放点（需认证） - -```http -POST /api/drop-point -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "name": "B区道路", - "lat": 30.2345, - "lng": 120.6789 -} -``` - -**响应**： - -```json -{ "ok": true } -``` - ---- - -### 3.6 危险区域 - -#### ① 查看危险区域（免认证） - -```http -GET /api/danger-zones -``` - -**响应**： - -```json -{ - "danger_zones": [ - { - "id": 1, - "lat": 30.1234, - "lng": 120.5678, - "radius": 100, - "description": "士兵求救: 张三", - "created_at": "2026-05-23 12:00:00" - } - ] -} -``` - ---- - -#### ② 添加危险区域（需认证） - -```http -POST /api/danger-zones -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "lat": 30.1234, - "lng": 120.5678, - "radius": 100, - "description": "B区道路（危险区域）" -} -``` - -**响应**： - -```json -{ "ok": true, "id": 1 } -``` - ---- - -### 3.7 SOS 求救 - -#### ① 发送求救（需认证） - -```http -POST /api/sos -Content-Type: application/json -X-Auth-Token: -``` - -**请求体**： - -```json -{ - "soldier_id": "soldier_001", - "soldier_name": "张三", - "lat": 30.1234, - "lng": 120.5678 -} -``` - -**响应**： - -```json -{ "ok": true } -``` - -> 发送求救后，系统会自动在危险区域表中添加一个以士兵位置为中心、半径 100 米的危险区域。 - ---- - -### 3.8 无人机状态（演示数据） - -#### ① 获取无人机状态（免认证） - -```http -GET /api/drone/status -``` - -**响应**： - -```json -{ - "status": { - "battery": 85, - "altitude": 120, - "speed": 15, - "position": { "lat": 30.1234, "lng": 120.5678 } - } -} -``` - ---- - -#### ② 获取无人机日志（免认证） - -```http -GET /api/drone/logs -``` - -**响应**： - -```json -{ - "logs": [ - { "time": "12:25:30", "message": "到达投放点" }, - { "time": "12:20:45", "message": "接收任务指令" }, - { "time": "12:10:00", "message": "任务分配" } - ] -} -``` - ---- - -### 3.9 系统状态 - -#### ① 存活检测（免认证） - -```http -GET /api/ping -``` - -**响应**： - -```json -{ "ok": true, "message": "智途投送后端运行正常" } -``` - ---- - -## 四、数据库表结构 - -### 4.1 accounts（账号表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `soldier_id` | TEXT PK | 士兵编号 | -| `password_hash` | TEXT | Werkzeug 哈希密码 | -| `name` | TEXT | 姓名 | -| `unit` | TEXT | 单位 | -| `role` | TEXT | 角色 | -| `created_at` | TEXT | 注册时间 | - -### 4.2 tokens（登录令牌表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `token` | TEXT PK | 随机 Token | -| `soldier_id` | TEXT | 士兵编号 | -| `name` | TEXT | 姓名 | -| `unit` | TEXT | 单位 | -| `role` | TEXT | 角色 | -| `created_at` | TEXT | 生成时间 | - -### 4.3 demands（物资需求表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | TEXT PK | 需求编号（如 REQ-001） | -| `soldier_id` | TEXT | 上报士兵 | -| `soldier_name` | TEXT | 士兵姓名 | -| `type` | TEXT | 物资类型（如"弹药补给"） | -| `items` | TEXT | 物资描述（如"弹药 × 20发"） | -| `quantity` | INTEGER | 数量 | -| `unit` | TEXT | 单位 | -| `urgency` | TEXT | 紧急程度 | -| `status` | TEXT | 状态：待处理/已调度/已完成 | -| `lat` | REAL | 纬度 | -| `lng` | REAL | 经度 | -| `created_at` | TEXT | 创建时间 | - -### 4.4 tasks（任务表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | TEXT PK | 任务编号（如 #001） | -| `soldier_id` | TEXT | 目标士兵 | -| `soldier_name` | TEXT | 士兵姓名 | -| `type` | TEXT | 任务类型 | -| `status` | TEXT | 状态 | -| `progress` | INTEGER | 进度 0-100 | -| `eta` | TEXT | 预计到达时间 | -| `remain_time` | TEXT | 剩余时间 | -| `start_name/target_name` | TEXT | 起止点名称 | -| `start_lat/lng` | REAL | 起点坐标 | -| `end_lat/lng` | REAL | 终点坐标 | -| `safety_score` | INTEGER | 安全评分 | -| `created_at` | TEXT | 创建时间 | - -### 4.5 soldiers（士兵位置表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `soldier_id` | TEXT PK | 士兵编号 | -| `name` | TEXT | 姓名 | -| `lat` | REAL | 纬度 | -| `lng` | REAL | 经度 | -| `updated_at` | TEXT | 更新时间 | - -### 4.6 danger_zones（危险区域表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | INTEGER PK AI | 自增 ID | -| `lat` | REAL | 纬度 | -| `lng` | REAL | 经度 | -| `radius` | REAL | 半径（米） | -| `description` | TEXT | 描述 | -| `created_at` | TEXT | 创建时间 | - -### 4.7 sos_alerts（求救记录表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | INTEGER PK AI | 自增 ID | -| `soldier_id` | TEXT | 士兵编号 | -| `soldier_name` | TEXT | 姓名 | -| `lat` | REAL | 纬度 | -| `lng` | REAL | 经度 | -| `alert_time` | TEXT | 求救时间 | -| `handled` | INTEGER | 是否已处理（0/1） | - ---- - -## 五、错误码速查 - -| HTTP 状态码 | 含义 | 典型场景 | -|-------------|------|----------| -| 200 | 成功 | 正常响应 | -| 400 | 请求参数错误 | 缺少必填字段 | -| 401 | 未认证 | Token 无效或缺失 | -| 404 | 资源不存在 | 士兵编号不存在、需求不存在 | -| 409 | 冲突 | 账号已注册 | -| 500 | 服务器内部错误 | 代码异常 | - ---- - -## 六、联系 - -- 后端维护：赵昌 -- 服务器 IP：`121.41.216.243` -- 操作手册：`software/后端操作手册.md` - ---- - -*文档生成时间：2026-05-23*