# 项目审查问题清单

审查日期：2026-05-01

本文档用于记录当前项目中已发现的高风险问题，并作为后续逐项修复的跟踪清单。状态说明：

- `待处理`：尚未开始修复。
- `处理中`：已经开始改动或验证。
- `已修复`：代码已修复并通过基本验证。
- `暂缓`：因演示环境、硬件依赖或其他原因暂不处理。

## 1. 优先级概览

| 编号 | 优先级 | 状态 | 模块 | 问题 |
| --- | --- | --- | --- | --- |
| R-001 | P0 | 已修复 | 服务端 | 公网接口无鉴权且允许任意来源 |
| R-002 | P0 | 部分修复 | 全项目 | 明文密钥和凭据已进入项目文件 |
| R-003 | P1 | 已修复 | 服务端 | `face_id` 可造成路径穿越写读删文件 |
| R-004 | P1 | 已修复 | 服务端 | 大请求体会被静默截断 |
| R-005 | P1 | 已修复 | 服务端 / Qt | CSV/JSON 没有转义会破坏数据和响应 |
| R-006 | P1 | 已修复 | STM32 固件 | `sscanf` 未限制宽度，UART 输入可溢出栈缓冲 |
| R-007 | P2 | 已修复 | 服务端 | 多个 `std::stoi` 可被非法参数打崩服务线程 |
| R-008 | P2 | 已修复 | Qt 管理端 | 删除人脸 URL 未编码 |

## 2. 详细问题

### R-001 公网接口无鉴权且允许任意来源

- 优先级：P0
- 状态：已修复
- 位置：`server/server_encrypted.cpp:1666`
- 影响：服务端暴露清空记录、删除人脸、上传映射、上传照片等写操作，但没有鉴权；响应固定允许任意跨域来源。只要端口可访问，外部请求就可能改写或删除考勤数据。
- 建议处理：
  1. 给所有写接口增加 API Token 或签名校验。
  2. 按部署环境限制 CORS 来源，不再使用通配符。
  3. 公网部署时使用 HTTPS 和反向代理鉴权。
  4. 将管理类接口与设备上传接口区分权限。
- 本次处理：主服务端 `server/server_encrypted.cpp` 已增加 `X-Api-Token` 校验，健康检查和 OPTIONS 预检除外；CORS 来源改为 `ATTENDANCE_CORS_ORIGIN` 配置，默认仅本地来源。Qt、STM32、K210 请求均已补 `X-Api-Token`。

### R-002 明文密钥和凭据已进入项目文件

- 优先级：P0
- 状态：部分修复
- 位置：`k210/main.py:34`、`User/main.c:23`、`QT/qml/Main.qml:2725`、`server/attendance.log`
- 影响：项目文件中包含 WiFi 密码、公网服务地址、固定 AES Key/IV、查看账号密码、日志中的疑似 API Key 等敏感信息。泄露后即使代码修复，旧凭据仍可能被继续使用。
- 建议处理：
  1. 立即轮换已暴露的 WiFi 密码、API Key、演示账号密码和 AES Key/IV。
  2. 将服务地址、WiFi、Token 等改为外部配置文件或烧录参数。
  3. 日志输出中屏蔽敏感请求头。
  4. 清理已有日志文件中的敏感内容。
- 本次处理：主链路代码和文档中的 WiFi 密码、公网地址改为占位配置；日志中的疑似 API Key 已脱敏；Qt 默认服务地址改为本机地址。仍需在真实环境中轮换已暴露的 WiFi、API Key、演示账号和 AES Key/IV。

### R-003 `face_id` 可造成路径穿越写读删文件

- 优先级：P1
- 状态：已修复
- 位置：`server/server_encrypted.cpp:837`
- 影响：`face_id` 直接来自 URL 并拼接成 `faces/<face_id>.jpg`，用于写入、读取和删除。包含路径分隔符或 `..` 时，可能越过 `faces` 目录操作其他文件。
- 建议处理：
  1. 增加 `face_id` 白名单校验，只允许数字、字母、下划线、短横线等明确字符。
  2. 对最终路径做规范化检查，确认仍位于 `faces` 目录下。
  3. 所有照片读写删入口共用同一个安全路径构造函数。
- 本次处理：主服务端已增加 `isSafeId` 与 `buildFacePhotoPath`，照片读写删和重命名路径统一走安全 ID 校验。

### R-004 大请求体会被静默截断

- 优先级：P1
- 状态：已修复
- 位置：`server/server_encrypted.cpp:1228`
- 影响：读取 POST body 时，如果剩余数据超过约 40KB，循环不会继续读取，导致照片或配置内容被截断。K210 JPEG 上传很容易触发该问题。
- 建议处理：
  1. 按 `Content-Length` 循环读取完整 body。
  2. 设置明确最大请求大小，例如照片接口单独允许更大上限。
  3. 超限时返回 HTTP 413。
  4. 对读取不足的请求返回 400，不保存半截文件。
- 本次处理：主服务端按 `Content-Length` 读取完整请求体，普通 JSON 请求限制 64KB，照片请求限制 512KB，超限返回 413，读取不足返回 400。

### R-005 CSV/JSON 没有转义会破坏数据和响应

- 优先级：P1
- 状态：已修复
- 位置：`server/server_encrypted.cpp:459`、`QT/src/AppController.cpp:284`、`QT/src/AppController.cpp:317`
- 影响：签到记录直接用逗号拼 CSV，读取时也直接按逗号拆，再手写 JSON 字符串。姓名、状态、班级等字段包含逗号、引号、换行或反斜杠时，会导致 CSV 列错位、JSON 非法或 Qt 解析失败。
- 建议处理：
  1. 服务端增加 CSV 字段转义和解析函数。
  2. 服务端 JSON 响应统一经过 JSON 转义函数。
  3. Qt 导出 CSV 时对每个字段做标准 CSV 转义。
  4. 使用 SQLite 替代 CSV/多 JSON 文件，减少数据状态不一致。
- 本次处理：主服务端增加 CSV 解析/转义和 JSON 转义；Qt 导出 CSV 已对字段做标准转义；后端主存储已迁移到 `attendance.db`，旧 CSV/JSON 仅作为首次导入来源。

### R-006 `sscanf` 未限制宽度，UART 输入可溢出栈缓冲

- 优先级：P1
- 状态：已修复
- 位置：`Hardware/K210_USART.c:80`
- 影响：`%[^,]` 没有宽度限制，但目标缓冲只有 `id[20]` 和 `name[32]`。串口收到异常长字段时可能覆盖栈内存，造成固件异常。
- 建议处理：
  1. 将格式改为 `%19[^,]`、`%31[^,]`。
  2. 对接收缓冲做最大帧长、换行结束符和字段合法性校验。
  3. 异常帧直接丢弃并清空缓冲。
- 本次处理：`Hardware/K210_USART.c` 和示例文件中的 `sscanf` 已增加字段宽度限制。

### R-007 多个 `std::stoi` 可被非法参数打崩服务线程

- 优先级：P2
- 状态：已修复
- 位置：`server/server_encrypted.cpp:1310`
- 影响：`limit`、`offset`、时间段参数直接调用 `std::stoi`，没有异常捕获和范围校验。非法请求参数可能让请求处理线程异常终止。
- 建议处理：
  1. 增加安全整数解析函数。
  2. 参数非法时返回 400。
  3. 限制 `limit`、`offset` 和时间范围。
  4. 所有 URL 参数统一走校验函数。
- 本次处理：主服务端已增加安全整数和时间解析，`limit`、`offset`、时间段和记录时间解析不再直接裸用 `std::stoi`。

### R-008 删除人脸 URL 未编码

- 优先级：P2
- 状态：已修复
- 位置：`QT/src/ApiClient.cpp:453`
- 影响：Qt 端删除人脸时直接把 `studentId` 拼进路径。如果学号包含空格、`#`、`?`、`/` 或中文，URL 会被截断或路由错乱。
- 建议处理：
  1. 使用 `QUrl::toPercentEncoding` 编码路径段。
  2. 服务端接收后进行 URL 解码和 ID 校验。
  3. 为删除人脸接口补充异常 ID 的测试用例。
- 本次处理：Qt 删除人脸路径段已使用 `QUrl::toPercentEncoding` 编码。

## 3. 建议修复顺序

1. 处理 R-002：轮换凭据，清理敏感日志，避免继续泄露。
2. 处理 R-001：服务端写接口增加鉴权，限制跨域来源。
3. 处理 R-003、R-004：修复文件路径安全和请求体读取，防止文件被覆盖或照片损坏。
4. 处理 R-006：修复固件串口解析溢出风险。
5. 处理 R-005：统一 CSV/JSON 转义，避免数据格式破坏。
6. 处理 R-007、R-008：增强参数健壮性和 Qt URL 构造。

## 4. 验证记录

- `k210/main.py`、`k210/view_attendance.py` 已通过普通 Python 语法检查；MaixPy 运行时仍需上板验证。
- `server/server_encrypted.cpp` 因当前本机缺少 OpenSSL 头文件，未完成语法编译验证。
- 现有 Keil 构建日志显示固件旧构建为 `0 Error(s), 0 Warning(s)`，但尚未在本次审查中重新编译固件。
- 2026-05-01：已完成主链路安全修复；旧版备用服务端与测试脚本已清理，避免误部署非鉴权接口。