From e1e4159a23a1631d4c13ed61a823f72db49ab3c5 Mon Sep 17 00:00:00 2001 From: pkx2w7qjn <392871505@qq.com> Date: Sun, 24 May 2026 00:44:16 +0800 Subject: [PATCH] =?UTF-8?q?Delete=20'=E9=80=82=E9=85=8D=E7=A8=8B=E5=BA=A6?= =?UTF-8?q?=E8=AF=84=E4=BC=B0=E6=8A=A5=E5=91=8A.md'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 适配程度评估报告.md | 229 ------------------------------------ 1 file changed, 229 deletions(-) delete mode 100644 适配程度评估报告.md diff --git a/适配程度评估报告.md b/适配程度评估报告.md deleted file mode 100644 index e1dda293..00000000 --- a/适配程度评估报告.md +++ /dev/null @@ -1,229 +0,0 @@ -# 智途投送系统 — 适配程度评估报告 - -> 评估范围：单兵终端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 语法错误** — `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` 语法错误** (`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*