修复工作人员作业预检状态与提示

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

@@ -0,0 +1,51 @@
+# 作业预检修复操作日志
+
+操作时间：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`；人员资质通过，未启用能力保持非阻断状态。