# 作业预检修复操作日志

操作时间：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`；人员资质通过，未启用能力保持非阻断状态。