增量质检报告 · huanyan/server · v0.1.44

• 对比区间：e3bd32a（base，上一版本）→ 4eb1d79（head，v0.1.44）
• 分支：v0.1.44
• 变更性质：功能收尾批（员工端最后 3 条 app 端点 + 后台员工详情 + 单据支付意向），含文档与测试
• 质检数据来源：codescan_issues_diff（真实对比 修复 10 / 新增 18）、codescan_git_diff、源码复核

---

一、变更概览

本版本是「员工端接口缺口清零」收尾批，代码变更面较小（6 个源/测试文件 + 1 个文档）：

功能结论：变更以「新增只读/动作端点 + DTO 字段」为主，方向正确、权限与脱敏口径一致（预约域 appointment.register、员工域 staff.manage、手机号脱敏、openid 不外泄）。未发现阻断性功能缺陷。

---

二、交付功能核对

1. GET /app/appointments（list_inner）

   • 参数校验完整：scope 枚举、from/to 必填、from<=to、MAX_RANGE_DAYS=62 上限（防全表扫描）；缺参/倒置 → 1001。
   • 门店隔离：app_store(ctx)? 恒会话门店（不接收 store_id），StoreId.eq(store_id) 过滤，无跨店越权面。
   • scope=mine：StaffId==me OR OriginalStaffId==me（覆盖改派历史，口径正确）。
   • 手机号 mask_mobile 恒脱敏、客户/项目/护理师姓名批量回填（N+1 已规避为 is_in 批量查）。
   • 路由挂 AppFuncGuard(appointment.register)，OpenAPI 已登记。

2. GET /staffs/{id}（service_show）

   • find_alive + ensure_staff_in_scope（与写操作同作用域口径）；路由 FuncGuard(STAFF_MANAGE)。
   • StaffDto 不含 wx_openid，仅 wx_bound 布尔 + wx_bound_at 时点，符合「明文只经 /wx-binding 脱敏出口」设计。

---

三、修复问题（对比 base 有、head 无 —— 共 10 条）

⚠️ 重要判读：本次 issues_diff 呈报的「修复 10 条」绝大多数不是真实修复，而是行号漂移（line-shift）重锚——同一问题因上方新增代码/函数插入导致行号变化，被工具当成「旧位置修复 + 新位置新增」。逐条核实如下：

结论：真实意义上无一条「缺陷被修复」；staffs.rs 三个大函数（create/update/leave）与测试 helper 的历史问题依旧存在，仅位置变化。报告不应将本节计为「减债」。

---

四、新增问题（对比 head 有、base 无 —— 共 18 条）

按「真实新增 vs 行号漂移」分类：

4.1 真实新增（生产代码，值得关注）

真正的「本轮新代码引入」复杂度问题仅集中在 list_inner。staffs.rs 三条是旧函数被重新锚定，不应算作本版新增技术债。

4.2 测试文件新增（tests/app_employee.rs）

说明：测试文件中的 SQL 拼接与 unwrap 属测试夹具惯用写法，known_false_positives 为空未做抑制，故被计入。建议后续在测试模块统一 #![allow(clippy::unwrap_used)] 或在质检规则中排除 tests/**，避免长期噪声。

---

五、重点问题详解：list_inner 复杂度与耦合

list_inner（src/modules/app/appointments.rs:306，131 行、圈复杂度 12、扇出 73）是本次唯一实质新增的生产复杂度热点。其职责链：

1. scope 校验 + from/to 解析 + 区间上限（约 12 行）
2. 条件构造（Condition::all + scope=mine 的 any 分支）
3. 三张表批量回填：customer / project / staff（三段 is_in map，各带空判分支，约 60 行）
4. 行装配（reassigned_to 改派判定、start_minutes/duration_minutes/time_range 计算、mask_mobile）

评价：功能正确、无越权/脱敏缺陷，但可维护性偏弱。扇出 73 主要来自 sea_orm 链式调用与 chrono 格式化，属框架调用噪声，非真正业务耦合，故「高耦合」告警可适度降级看待。

建议（非阻断）：

• 抽出 fn build_list_cond(...)、fn load_names(...)（三表回填合并为一个 helper）、fn to_item(r, maps) -> AppAppointmentItemDto，可将单函数压到 ~40 行、复杂度降到阈值内；
• 三表回填结构重复（if empty { default } else { query...collect }）可提取泛型 helper 复用。

---

六、风险与建议

功能正确性：未发现内存安全、越权、脱敏泄漏、事务一致性等实质缺陷。新增端点权限守卫、门店隔离、手机号脱敏、openid 不外泄均到位，测试覆盖了正/反向与参数校验。

---

七、结论

• 功能交付：员工端接口缺口批收尾（预约列表 + 员工详情 + 支付意向）实现正确、边界清晰，可放行。
• 质量增量：真实新增技术债仅 list_inner 一处复杂度/耦合热点（Medium，可维护性），其余 17 条新增告警中约 15 条为行号漂移重锚或测试代码误报。
• 「修复」实为行号漂移，不构成真实改善，建议复盘时纠正口径。
• 优先改进：拆分 list_inner；在 tests/** 抑制 unwrap/SQL 拼接噪声。