admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/tasks/review-north-mini-report.md
12451 12395ee9e2 init: PMS充电柜管理系统源代码
2026-07-02 05:38:01 +08:00

14 KiB
Raw Blame History

全面代码审查报告

总体评价

质量评分：7 / 10

项目整体架构清晰，分层合理（接口层/业务层/数据层），代码注释充分，命名语义化。后端 Rust 代码质量较高，错误处理覆盖全面；前端 React 组件拆分得当，H5 移动端体验完整。但存在若干安全、性能和代码规范问题需要修复。

统计

  • 后端文件数：30（Rust）
  • 前端文件数：35（TypeScript/React）
  • 总代码行数：约 11,700（后端 6,400 + 前端 5,300）
  • 问题总数：28（严重 7 / 警告 12 / 建议 9）

严重问题（必须修复）

问题1：心跳超时与协议上报间隔不匹配

  • 位置：software/server/src/tcp/server.rs:16
  • 描述：HEARTBEAT_TIMEOUT 设为 5000ms（5秒），但协议规定设备空闲时 1 分钟上报一次。设备在空闲状态下会在两次上报之间被断开连接。
  • 风险：设备频繁断连，无法保持在线状态，影响充电指令下发和状态监控。
  • 建议：将 HEARTBEAT_TIMEOUT 改为 Duration::from_secs(90)（90秒，留 1.5 倍余量），或根据设备上报频率动态调整。

问题2：安全码 auth_str 通过 API 明文返回前端

  • 位置：software/server/src/routes/cabinets.rs:254
  • 描述：regenerate_auth 接口将 auth_str 直接返回给前端。安全码是设备签名密钥，不应暴露给 Web 端。
  • 风险：安全码泄露后，攻击者可伪造设备签名登录。
  • 建议：接口只返回 { "success": true }，不返回 auth_str 值。如需查看，应通过独立的安全审计接口并记录操作日志。

问题3：登录接口无暴力破解防护

  • 位置：software/server/src/routes/auth.rs:24 和 software/server/src/routes/h5.rs:105
  • 描述：登录接口没有频率限制，攻击者可无限次尝试密码。
  • 风险：弱密码账户可被暴力破解。
  • 建议：添加基于 IP 或手机号的登录频率限制（如 5次/分钟），失败过多时临时锁定账户或要求验证码。

问题4：device:door:unlock 权限码未初始化

  • 位置：software/server/src/db/migrate.rs:225-258 和 software/server/src/routes/h5.rs:879
  • 描述：H5 开门接口使用 device:door:unlock 权限码，但 seed_permissions 中未插入该权限码。因此没有任何角色拥有此权限，开门功能永远返回 403。
  • 风险：开门功能完全不可用。
  • 建议：在 seed_permissions 中添加 ("device:door:unlock", "开门") 并分配给相应角色。

问题5：部分接口缺少权限校验

  • 位置：software/server/src/routes/roles.rs:37 和 software/server/src/routes/roles.rs:232
  • 描述：list_roles 和 list_permissions 接口使用 _user 忽略当前用户，未调用 check_permission。任何已登录用户都可查看角色和权限配置。
  • 风险：权限信息泄露，攻击者可了解系统权限结构。
  • 建议：添加 auth::check_permission(&user, "role:view")?; 校验。

问题6：下载文件路径无安全校验

  • 位置：software/server/src/routes/downloads.rs:205-213
  • 描述：download_file 从数据库读取 file_path 后直接读取文件，未验证路径是否在 ./exports 目录内。如果数据库中的路径被篡改（如 ../../etc/passwd），可读取服务器任意文件。
  • 风险：路径穿越攻击，可泄露服务器敏感文件。
  • 建议：验证 file_path 必须以 ./exports/ 开头，使用 std::path::Path::canonicalize 后检查前缀。

问题7：导出目录使用相对路径

  • 位置：software/server/src/routes/charge_records.rs:380 和 software/server/src/routes/energy_stats.rs:536
  • 描述：导出文件保存到 ./exports 相对路径。如果进程工作目录非预期，文件可能写入敏感位置。
  • 风险：文件写入位置不可控。
  • 建议：使用配置项指定导出根目录的绝对路径，或在 Config 中添加 export_dir 字段。

警告（建议修复）

警告1：h5.rs 文件过长（990行）

  • 位置：software/server/src/routes/h5.rs
  • 描述：单文件 990 行，远超 300 行限制。包含登录、仪表盘、设备查询、充电控制等多个功能模块。
  • 建议：拆分为 h5/auth.rs、h5/dashboard.rs、h5/cabinets.rs、h5/control.rs 等子模块。

警告2：users.rs list_users 函数分支过多，SQL 重复严重

  • 位置：software/server/src/routes/users.rs:108-268
  • 描述：list_users 函数约 160 行，因 keyword 和 org_filter 的组合产生 6 个分支，大量 SQL 重复。
  • 建议：使用动态 SQL 构建（类似 charge_records.rs 的 build_where_clause 模式），减少分支和重复代码。

警告3：N+1 查询 — 柜子详情

  • 位置：software/server/src/routes/cabinets.rs:292-308
  • 描述：get_cabinet_detail 先查仓板列表，再逐个查仓体。若柜有 N 块仓板，产生 N+1 次查询。
  • 建议：使用一条 SQL 联表查询所有仓板和仓体，在 Rust 中按 board_id 分组。

警告4：N+1 查询 — H5 项目摘要

  • 位置：software/server/src/routes/h5.rs:436-486
  • 描述：fetch_project_summaries 对每个项目执行 4 次独立查询（柜子数、充电中、空闲、故障），项目数为 N 时产生 4N+1 次查询。
  • 建议：合并为一条 SQL，使用 LEFT JOIN + SUM(CASE WHEN...) 聚合。

警告5：N+1 查询 — 角色列表

  • 位置：software/server/src/routes/roles.rs:42-71
  • 描述：list_roles 对每个角色单独查询权限码，角色数为 N 时产生 N+1 次查询。
  • 建议：一条 SQL 联表查询所有角色及其权限码，在 Rust 中按 role_id 分组。

警告6：前端多处使用 as unknown as 类型断言

  • 位置：software/web/src/pages/devices/index.tsx:81,103、OrganizationTree.tsx:169,171
  • 描述：多处使用 as unknown as 进行类型转换，等同于 as any，绕过 TypeScript 类型检查。
  • 建议：修正 API 返回类型定义，使类型匹配，消除 as unknown as。

警告7：H5 认证恢复不验证 token 有效性

  • 位置：software/web/src/h5/auth.ts:48-55
  • 描述：H5 restore 仅从 localStorage 读取 token 和用户信息，不调用服务端验证 token 是否过期/有效。若 token 已过期，用户看到已登录状态但请求会失败。
  • 建议：restore 时调用 /api/h5/auth/me 或类似接口验证 token，失败则清除本地状态。对比后台管理端的 restore 实现（stores/auth.ts:72-91），后者正确调用了 /auth/me。

警告8：前端权限分组缺少组织和项目模块

  • 位置：software/web/src/pages/settings/roles.tsx:37-46
  • 描述：PERM_GROUPS 缺少 org 和 project 分组，导致组织和项目管理权限在权限树中显示为原始前缀名。
  • 建议：添加 org: '组织管理' 和 project: '项目管理' 到 PERM_GROUPS。

警告9：Dashboard 页面为空

  • 位置：software/web/src/pages/Dashboard.tsx
  • 描述：后台管理 Dashboard 仅显示欢迎文字，无任何数据看板。H5 端有完整的 dashboard API，但后台端未使用。
  • 建议：复用 H5 dashboard API 或创建独立的后台 dashboard 接口，展示设备总览、充电统计等。

警告10：org_condition 使用字符串拼接 SQL

  • 位置：software/server/src/middleware/auth.rs:255-288
  • 描述：org_condition 和 org_condition_for_logs 通过 format! 拼接 SQL 子句，虽然参数使用 ? 占位符，但表名/列名直接插入字符串。模式脆弱，容易引入 SQL 语法错误。
  • 建议：考虑使用 query builder 库（如 sea-query），或至少将子查询模板定义为常量。

警告11：compartments 表缺少 updated_at 索引

  • 位置：software/server/src/db/migrate.rs:47-55 和 software/server/src/routes/h5.rs:379-391
  • 描述：fetch_fault_alerts 使用 ORDER BY comp.updated_at DESC，但 compartments 表没有 updated_at 索引。
  • 建议：添加 idx_compartments_updated 索引，或在 create_indexes 中添加。

警告12：充电记录导出缺少组织数据隔离

  • 位置：software/server/src/routes/charge_records.rs:309-397
  • 描述：generate_charge_records_excel 异步导出时未追加组织过滤条件，企业管理员可导出全部组织的充电记录。
  • 风险：数据越权，企业管理员可导出非本组织数据。
  • 建议：在导出查询中追加 org_condition 过滤。

建议

建议1：统一 API 响应格式

  • 位置：全局
  • 描述：部分接口返回 { "code": 0, "data": ..., "message": "ok" } 格式，部分直接返回数据对象（如 organizations 列表接口返回 json!(rows)）。前端需要兼容两种格式。
  • 建议：统一所有接口使用 { code, data, message } 包装。

建议2：常量抽离 — 魔法数字

  • 位置：多处
  • 描述：状态码（0/1/2/3）、角色值（0/1/2）等魔法数字散落在前后端代码中。
  • 建议：后端使用 Rust 枚举（enum CompartmentStatus { Idle = 0, Charging = 1, ... }），前端使用常量对象（COMPARTMENT_STATUS）。

建议3：前端 DownloadCenter 组件复用

  • 位置：software/web/src/pages/charge-records/DownloadCenter.tsx
  • 描述：DownloadCenter 被充电记录和能耗管理共用，但路径为 charge-records/ 下。
  • 建议：移到 components/DownloadCenter.tsx，体现其通用组件定位。

建议4：JWT 密钥在 middleware/auth.rs 和 config.rs 中重复定义

  • 位置：software/server/src/config.rs:4 和 software/server/src/middleware/auth.rs:33
  • 描述：JWT_SECRET_DEFAULT 在两个文件中重复定义。
  • 建议：统一从 Config 结构体读取，避免不一致。

建议5：set_role_permissions 非原子操作

  • 位置：software/server/src/routes/roles.rs:202-228
  • 描述：先 DELETE 再逐条 INSERT，非事务操作。如果中途失败，角色权限处于不一致状态。
  • 建议：使用事务包裹，或批量 INSERT。

建议6：set_user_roles 同样非原子

  • 位置：software/server/src/routes/users_perm.rs:144-168
  • 描述：同上，先 DELETE 再逐条 INSERT。
  • 建议：使用事务。

建议7：前端 eslint-disable-next-line 注释

  • 位置：software/web/src/h5/pages/devices.tsx:62、device-detail.tsx:36、compartment-detail.tsx:42
  • 描述：多处使用 eslint-disable-next-line react-hooks/exhaustive-deps 跳过 hooks 依赖检查。
  • 建议：修正依赖数组，或使用 useCallback/useRef 解决。

建议8：充电曲线使用硬编码假数据

  • 位置：software/web/src/h5/pages/compartment-detail.tsx:174
  • 描述：充电曲线图表使用硬编码数据 [30, 45, 55, ...]，非真实数据。
  • 建议：标注为 TODO 或移除该图表，待后端提供充电曲线 API 后再实现。

建议9：generate_abstract_id 算法可预测

  • 位置：software/server/src/routes/organizations.rs:130-135
  • 描述：抽象 ID 由 IMEI 的 SHA256 前 4 字节生成，仅 8 位十六进制（约 43 亿种组合）。虽然碰撞概率低，但可被预测。
  • 建议：如抽象 ID 不需可预测性，可加入随机盐或使用更长哈希。

优点

  1. 架构分层清晰：后端严格按 路由/中间件/协议/数据库 分层，前端按 API/Store/Page/Component 分层，职责明确。
  2. 统一错误处理：后端 AppError 统一错误类型，自动映射 HTTP 状态码，错误信息对用户友好，内部错误详情仅记录日志。
  3. 密码安全：使用 argon2 哈希（业界推荐），非 MD5/SHA。
  4. 参数化查询：所有数据库查询使用 ? 占位符，有效防止 SQL 注入。
  5. RBAC 权限模型完整：角色-权限-范围三层设计，前端 Permission 组件支持隐藏/禁用两种模式。
  6. 组织数据隔离：核心查询接口均实现组织级数据隔离，防止跨组织数据泄露。
  7. TCP 协议处理健壮：LF 分隔粘包、JSON 解析容错、签名验证、时间戳窗口校验、auth_str 频率限制。
  8. 异步导出流程完整：任务创建 -> 后台生成 Excel -> 进度更新 -> 下载 -> 过期清理，全链路覆盖。
  9. H5 移动端完整：扫码入口、设备概览、充电控制、BMS 数据展示、确认弹窗，用户体验良好。
  10. 代码注释充分：所有模块和公共函数都有中文文档注释，便于维护。
  11. 数据库迁移自动化：启动时自动建表、建索引、初始化权限码和角色，部署简便。
  12. 前端组件拆分合理：设备管理页拆分为 OrganizationTree、CabinetGrid、AddCabinetModal 等独立组件。

总结

优先修复建议（按紧急程度排序）

  1. P0 — 立即修复：

    • 心跳超时改为 90 秒（问题1），否则设备无法保持在线
    • 添加 device:door:unlock 权限码（问题4），否则开门功能不可用
    • 下载文件路径安全校验（问题6），防止路径穿越攻击

  2. P1 — 本迭代修复：

    • 登录接口添加频率限制（问题3）
    • auth_str 不返回前端（问题2）
    • 补充缺失的权限校验（问题5）
    • 充电记录导出添加组织隔离（警告12）
    • 导出目录使用绝对路径（问题7）

  3. P2 — 下迭代优化：

    • 拆分 h5.rs（警告1）
    • 修复 N+1 查询（警告3/4/5）
    • H5 认证恢复验证 token（警告7）
    • 消除 as unknown as 类型断言（警告6）
    • 补充 compartments.updated_at 索引（警告11）

整体代码质量良好，核心业务逻辑正确，安全基础扎实。上述问题修复后可达到生产就绪水平。