p82feo7wg
/
software
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Delete 'software/前后端对接文档.md'

Browse Source
master
pkx2w7qjn 2 weeks ago
parent f6c3b4107a
commit 1ce73e6b94
1 changed files with 0 additions and 727 deletions
Show Stats Download Patch File Download Diff File

727
software/前后端对接文档.md
Unescape View File

@ -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: <token>
```
或在 URL 参数中携带（调试用）：
```http
GET /api/task/current?soldier_id=xxx&token=<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: <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: <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: <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: <token>
```
**响应**：
```json
{ "demand": { ... } }
```
---
### 3.4 任务调度
#### ① 派发任务（需认证）
```http
POST /api/task/dispatch
Content-Type: application/json
X-Auth-Token: <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: <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: <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: <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: <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: <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*
Write Preview
Loading…
Cancel
Save