# 智途投送系统 — 前后端对接文档

> 版本：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*
