# 智途投送系统 — 适配程度评估报告

> 评估范围：单兵终端APP + 软件电脑端后端  
> 评估时间：2026-05-23  
> 评估维度：功能完整性、接口一致性、安全性、健壮性、与整体架构适配度

---

## 一、总体评分

| 维度 | 评分 | 说明 |
|------|------|------|
| **功能完整性** | ⭐⭐⭐⭐☆ (4/5) | 覆盖了登录、位置上报、需求上报、任务查询、SOS、无人机监控等核心功能 |
| **接口一致性** | ⭐⭐⭐⭐☆ (4/5) | API 路径和字段名基本一致，少量字段缺失/不匹配 |
| **安全性** | ⭐⭐⭐☆☆ (3/5) | Token 认证正确，但存在明文存储、CORS 全开放、SQL 注入风险 |
| **健壮性** | ⭐⭐⭐☆☆ (3/5) | 存在运行时崩溃风险、输入验证漏洞、后台资源泄漏 |
| **架构适配度** | ⭐⭐⭐⭐☆ (4/5) | 后端作为数据中枢定位清晰，但与无人机模块深度集成不足 |

**综合评分：3.6 / 5** — 核心功能可用，但存在多处安全与健壮性问题，建议修复后再正式交付。

---

## 二、单兵终端APP 问题清单

### 🔴 严重问题（必须修复）

| # | 问题 | 位置 | 影响 | 修复建议 |
|---|------|------|------|----------|
| 1 | **HTML 语法错误** — `</nav>1` 多余字符 | `index.html:471` | DOM 结构破坏，底部导航异常 | 删除多余的 `1` |
| 2 | **调用不存在函数** — `toggleTheme`、`showChangePasswordModal`、`selectDropPointFromMap` | `index.html:237,426,436` | 点击直接抛出 `TypeError` | 补齐函数或从 HTML 移除调用 |
| 3 | **数量验证逻辑漏洞** — `"abc" < 1` 为 `false` | `js/app.js:287` | 非数字输入绕过验证，发送 `NaN` 到后端 | `const num = parseInt(qty, 10); if (isNaN(num) || num < 1)` |
| 4 | **高德地图 API Key 硬编码泄露** — `c014127be1ea5a1efead8419c94fbaba` | `js/location.js:22,66` | Key 被盗用风险，产生额外费用 | 移至配置文件，使用环境变量 |
| 5 | **DOM 操作空值保护缺失** — `loadDroneStatus` 多处 | `js/app.js:547-557` | 元素不存在时抛出 `TypeError` | 统一添加 `if (el) el.textContent = ...` |
| 6 | **敏感凭证明文存储** — `auth_token` 存 `localStorage` | `js/app.js:196`, `js/api.js:8` | XSS 攻击可直接窃取 Token | 改为 `sessionStorage` 或实现 Token 自动刷新 |
| 7 | **路由栈无限增长** — `pageStack` 只有 push 无清理 | `js/app.js:75-123` | 内存泄漏，长时间使用后卡顿 | 限制栈深度，登录成功用 replace 而非 push |
| 8 | **后台轮询未暂停** — 未监听 `visibilitychange` | `js/app.js:715`, `js/location.js:509` | 耗电、流量浪费、后台请求被系统限制 | 页面隐藏时 `clearInterval`，切回时恢复 |
| 9 | **请求超时过短** — 统一 5 秒 | `js/api.js:17` | 弱网环境下频繁超时 | 分接口设置超时（关键接口 10s，非关键 5s） |

### 🟡 一般问题（建议修复）

| # | 问题 | 位置 | 影响 |
|---|------|------|------|
| 10 | **重复嵌套目录** — `js/js/`、`www/js/js/` | 全项目 | 构建脚本配置错误，APK 体积增大 |
| 11 | **登录后未清空密码输入框** | `js/app.js:181-213` | 密码在内存中持续存在 |
| 12 | **Mock 数据字段缺失** — `getMockDropPoints` 无 `lat`/`lng` | `js/api.js:177-183` | 地图定位到 `(0, 0)` |
| 13 | **`setInterval` async 未防并发** | `js/location.js:514` | 网络阻塞时请求堆积 |
| 14 | **位置上报失败静默吞掉** | `js/location.js:520-528` | 用户不知位置是否同步成功 |
| 15 | **网络/电量为静态假数据** | `index.html:99-100` | UI 显示永远的占位符 `--` |
| 16 | **偏移距离使用随机数** | `js/app.js:636-637` | `Math.random() * 100 + 'm'` 误导用户 |
| 17 | **`rememberMe` 复选框为摆设** | `index.html` | UI 存在但代码完全未实现 |

### 🟢 建议（优化项）

| # | 建议 | 说明 |
|---|------|------|
| 18 | 迁移至 ES Modules | 当前全局 IIFE 方式，命名空间污染风险 |
| 19 | 增加 JSDoc 类型注解 | 提升代码可维护性 |
| 20 | 统一错误码体系 | 区分网络超时/500/认证失效/业务错误 |
| 21 | 地图实例缓存 | 避免每次进入页面销毁重建地图 |

---

## 三、电脑端后端问题清单

### 🔴 严重问题

| # | 问题 | 位置 | 影响 | 修复建议 |
|---|------|------|------|----------|
| 1 | **SQL 注入风险** — `update_task` 使用 f-string 拼接 SQL | `app.py:462` | 攻击者可通过 `status` 字段注入恶意 SQL | 使用参数化查询：`f"UPDATE tasks SET {','.join(updates)} WHERE soldier_id=?"` 中 `updates` 列表需白名单校验 |
| 2 | **CORS 完全开放** — `CORS(app)` 未限制来源 | `app.py:21` | 任何网站都可跨域调用后端 API | `CORS(app, origins=["http://121.41.216.243", "http://localhost"])` |
| 3 | **Token 无过期机制** — 永久有效 | `app.py:551` | Token 泄露后攻击者可长期冒充用户 | 添加 `expires_at` 字段，定期清理过期 Token |
| 4 | **无连接池** — 每次请求新建 SQLite 连接 | `app.py:24-27` | 高并发时性能下降，连接开销大 | 使用连接池或单例连接（注意线程安全） |
| 5 | **无人机状态内存不一致** — `_drone_status` 是全局变量 | `app.py:139-148` | 多 worker 时不同进程看到不同状态 | 改为从 ROS/WebSocket 实时获取，或存数据库 |
| 6 | **Flask 默认 500 页面暴露信息** — 返回 HTML | 全局 | 泄露技术栈信息（Python/Flask 版本） | 注册自定义错误处理器：`@app.errorhandler(500)` |

### 🟡 一般问题

| # | 问题 | 位置 | 影响 |
|---|------|------|------|
| 7 | **密码最小长度无验证** | `app.py:515` | 可注册空密码或 1 位密码 |
| 8 | **注册时 unit/role 未校验** | `app.py:512-513` | 可传入超长字符串或特殊字符 |
| 9 | **`get_accounts` 返回所有字段** | `app.py:569-576` | 虽然密码是哈希的，但仍应只返回必要字段 |
| 10 | **无限流/防刷机制** | 全局 | 注册/登录接口可被暴力破解 |
| 11 | **数据库异常未捕获** — `sqlite3.IntegrityError` | `app.py` | 主键冲突时返回 500 而非友好的错误信息 |
| 12 | **危险区域与 SOS 联动缺少事务** | `app.py:488-499` | SOS 插入成功但危险区域插入失败时数据不一致 |

### 🟢 建议

| # | 建议 | 说明 |
|---|------|------|
| 13 | 添加 API 日志中间件 | 记录请求来源、耗时、错误，便于排错 |
| 14 | 使用 ` marshmallow ` 或 ` pydantic ` 做请求参数校验 | 替代手动 `data.get()`，减少类型转换错误 |
| 15 | 添加健康检查端点 | `/api/health` 返回数据库连接状态、服务运行时间 |

---

## 四、前后端接口一致性检查

### ✅ 一致的接口

| 功能 | 前端调用 | 后端路由 | 字段匹配 |
|------|----------|----------|----------|
| 登录 | `POST /api/auth/login` | `POST /api/auth/login` | `soldier_id`, `password` ✓ |
| 注册 | `POST /api/auth/register` | `POST /api/auth/register` | `soldier_id`, `password`, `name`, `unit`, `role` ✓ |
| 位置上报 | `POST /api/soldier/location` | `POST /api/soldier/location` | `id`, `name`, `lat`, `lng` ✓ |
| 需求上报 | `POST /api/demand` | `POST /api/demand` | `type`, `quantity`, `unit`, `urgency`, `drop_point` ✓ |
| 需求列表 | `GET /api/demands` | `GET /api/demands` | `soldier_id` (query) ✓ |
| 任务查询 | `GET /api/task/current` | `GET /api/task/current` | `soldier_id` (query) ✓ |
| SOS 求救 | `POST /api/sos` | `POST /api/sos` | `soldier_id`, `soldier_name`, `lat`, `lng` ✓ |
| 投放点列表 | `GET /api/drop-points` | `GET /api/drop-points` | 无参数 ✓ |
| 账号列表 | `GET /api/auth/accounts` | `GET /api/auth/accounts` | 无参数 ✓ |
| 存活检测 | `GET /api/ping` | `GET /api/ping` | 无参数 ✓ |

### ⚠️ 存在差异的接口

| 功能 | 问题 | 说明 |
|------|------|------|
| **前端调用不存在函数** | HTML 绑定 `App.toggleTheme()`、`App.showChangePasswordModal()`、`App.selectDropPointFromMap()`，但 `app.js` 中不存在 | 需补齐或移除 HTML 绑定 |
| **任务更新** | 后端有 `POST /api/task/update`，前端无对应调用 | 前端应增加任务进度上报功能 |
| **危险区域** | 后端有 `GET/POST /api/danger-zones`，前端无对应界面 | 前端应增加危险区域展示 |
| **无人机状态** | 前端有 `loadDroneStatus()` 调用 `/api/drone/status`，但后端返回的是**内存演示数据**，非真实无人机状态 | 需明确数据来源（后端演示 vs ROS 实时） |
| **投放点添加** | 后端有 `POST /api/drop-point`，前端无对应功能 | 前端地图选点功能需对接此接口 |

---

## 五、与整体项目的集成评估

### 5.1 在整体架构中的定位

```
【单兵APP】◄──HTTP REST──►【后端】◄──数据服务──►【电脑端前端】
                                              │
                                              ▼ WebSocket
                                        【rosbridge】
                                              │
                                              ▼
                                    【多模态融合 / PX4】
```

后端在架构中的角色是 **"数据中枢 + 认证网关"**：
- ✅ 接收单兵APP的位置、需求、SOS 数据
- ✅ 为电脑端提供任务调度数据
- ❌ **不参与无人机控制链路**（无人机状态是演示数据）
- ❌ **不参与声源/热成像/闪光检测链路**

### 5.2 与无人机模块的集成

| 评估项 | 现状 | 评估 |
|--------|------|------|
| 无人机状态数据 | 后端 `_drone_status` 是内存演示数据 | ⚠️ **假数据**，真实状态应来自 ROS |
| 任务派发链路 | 后端生成任务 → 电脑端展示 → 操作员确认 → 无人机执行 | ✅ 链路完整，但后端到无人机的控制命令未打通 |
| 航线规划 | 后端未提供航线规划 API | ❌ 缺失，无人机组可能需要手动规划 |
| 实时遥测 | 电脑端前端通过 WebSocket 直连 rosbridge，不经过后端 | ⚠️ 后端被绕过，无法做数据持久化 |

**建议**：后端应增加无人机状态同步接口，从 ROS 话题订阅真实状态并存入数据库，供单兵APP和电脑端统一查询。

### 5.3 与声源分析模块的集成

| 评估项 | 现状 | 评估 |
|--------|------|------|
| 声源威胁数据 | 声源检测节点 → ROS Topic → 多模态融合 → 地面站 | ✅ 链路完整，但**不经过后端** |
| 后端感知 | 后端完全不知道声源检测状态 | ❌ 后端与声源模块零集成 |

**建议**：如需要单兵APP接收声源威胁告警，后端应订阅 `AcousticThreatArray` 话题，通过 WebSocket 或推送通知发送到APP。

### 5.4 与热成像/闪光检测模块的集成

| 评估项 | 现状 | 评估 |
|--------|------|------|
| 热成像数据 | 直接 C++ 调用，被多模态融合消费 | ✅ 内部链路完整 |
| 闪光检测数据 | ROS Topic → 多模态融合 | ✅ 内部链路完整 |
| 后端感知 | 后端完全不知道这些检测状态 | ❌ 零集成 |

---

## 六、优先级修复建议

### 🔥 第一优先级（课程演示前必须修复）

1. **修复 `index.html` 语法错误** (`</nav>1`)
2. **补齐或移除 HTML 中不存在的函数调用**
3. **修复数量验证逻辑漏洞**（前后端都要修）
4. **修复 SQL 注入风险**（`update_task`）
5. **移除硬编码的高德 Key**

### 🔶 第二优先级（提升稳定性）

6. **为 DOM 操作添加空值保护**
7. **限制 CORS 来源**
8. **为 Token 添加过期机制**
9. **后台轮询暂停**（`visibilitychange`）
10. **添加密码最小长度验证**

### 🟢 第三优先级（优化体验）

11. **清理 `js/js/` 重复目录**
12. **前端增加任务更新调用**（对接 `POST /api/task/update`）
13. **前端增加危险区域展示**
14. **添加 API 日志中间件**
15. **自定义 500 错误页面**

---

## 七、总结

### 优势
1. **功能覆盖完整**：登录、位置上报、需求上报、任务调度、SOS、无人机监控等核心场景均已实现
2. **架构分层清晰**：APP → 后端 → 数据库 → 前端，职责明确
3. **Token 认证正确**：数据库存储，支持多 worker 共享
4. **SQLite 持久化**：数据不丢失，支持课程演示

### 劣势
1. **健壮性不足**：多处运行时崩溃风险、输入验证漏洞
2. **安全性薄弱**：CORS 全开放、SQL 注入、敏感信息明文存储
3. **与机载模块集成浅**：后端不参与无人机控制链路，声源/热成像数据不经过后端
4. **代码质量参差**：HTML 与 JS 契约不一致、Mock 数据与真实数据不匹配

### 适配度结论

**单兵终端APP + 电脑端后端** 作为 **"地面层数据服务"** 与整体项目是**适配的**，能够支撑课程演示所需的核心场景（士兵上报需求 → 指挥部调度 → 任务跟踪）。

但在以下方面存在明显短板，需要在正式演示前修复：
- 前端的健壮性（运行时崩溃、验证漏洞）
- 后端的安全性（SQL 注入、CORS、Token 过期）
- 前后端契约一致性（不存在的函数调用、缺失的接口对接）

---

*报告生成时间：2026-05-23*
