platforms/docs/开发日志_作业预检修复_20260905.md

作业预检修复操作日志

操作时间：2026-09-05 操作类型：修改 影响模块：工作人员 App 作业预检、后端工作人员预检接口、模拟数据

操作前状态

• 示例配送员 2–10 缺少人员资质，导致在岗账号无法进入工作台。
• 预检接口仅返回资质阻断状态，无法区分缺失、过期和停用。
• 未启用检查项使用警告样式，容易被误认为阻断项。
• 定位权限错误直接展示 Dart 的 Bad state: 前缀。

具体操作

• 为示例配送员 2–10 增加幂等的有效配送资质种子数据。
• 预检接口增加资质原因码、资质类型和到期时间，同时保持原字段兼容。
• 页面仅统计 blocked 状态，未配置能力显示为“暂不检查”。
• 人员资质阻断时显示中文原因和联系管理员的处理指引。
• 下班打卡保持可用；定位权限失败时提供重新授权入口和设置指引。

代码变更

• backend/api/internal/seed/mock.go：补齐模拟工作人员资质。
• backend/api/internal/logic/client/staff/auth.go：增加资质状态判定和原因码。
• backend/api/internal/logic/client/staff/auth_test.go：覆盖资质判定边界。
• apps/service_app/lib/domain/models/service_models.dart：增加真实阻断项计数。
• apps/service_app/lib/ui/features/preflight/preflight_page.dart：优化状态、提示和定位错误展示。
• apps/service_app/lib/data/services/location_service.dart：补充中文授权路径。
• apps/service_app/test/ui/preflight_page_test.dart：覆盖预检页面关键行为。

行为变化

• 修改前：示例配送员普遍因缺失资质被阻断；修改后：重启并执行模拟数据初始化后自动补齐。
• 修改前：“暂未启用”与失败状态视觉接近；修改后：中性显示且不计入阻断数量。
• 修改前：资质统一显示“未通过”；修改后：按缺失、过期、停用给出明确中文说明。

风险评估

• 接口仅新增响应字段，不删除或修改既有字段，兼容现有调用方。
• 种子记录使用未占用的场景内编号并采用 FirstOrCreate，不会覆盖已有资质。
• 进入工作台的服务端准入规则未放宽；下班打卡仍要求真实定位。

验证结果

• go test ./internal/logic/client/staff ./internal/seed：通过。
• flutter analyze：通过，无静态分析问题。
• flutter test test/ui/preflight_page_test.dart：2 项测试全部通过。
• Release Web 构建成功，http://127.0.0.1:5181/ 返回 HTTP 200。
• 新后端已监听 12426，健康检查返回 HTTP 200。
• 示例配送员9实测预检返回 can_work=true；人员资质通过，未启用能力保持非阻断状态。