# 运行轨迹关联名称显示优化操作日志

操作时间：2026-08-15

操作类型：修改

影响模块：平台总后台、气体配送订单运行轨迹

## 操作前状态

- 运行轨迹列表将配送订单和工作人员直接显示为截断的系统唯一标识。
- 用户无法从列表直接判断对应订单号和配送人员姓名，与其他已使用关联名称展示的页面不一致。

## 具体操作

- 配送订单列改为展示业务订单号，列名统一为“配送订单”。
- 工作人员列改为展示人员姓名，列名统一为“配送人员”。
- 配送人员关联明确限定 `delivery` 岗位，但历史详情不附加启用、在岗或资质有效过滤，确保离岗人员的历史轨迹仍可回看。
- 详情接口的 `{ track, points }` 聚合响应新增主记录解包与轨迹点固定中文列契约。
- 固定 Mock 轨迹点补齐上报流水号、服务端接收时间、速度和方向；新增独立幂等修复命令，不修改真实轨迹。
- 轨迹点“行进方向”按原始采集值展示，避免与钱包“收支方向”的同名字段枚举冲突。
- 两列继续保留完整系统唯一标识的悬浮提示、复制入口和关联详情跳转能力。
- 增加展示契约检查，防止运行轨迹退回裸唯一标识展示。

## 行为变化

- 修改前：列表主文案为截断系统唯一标识，如 `000000000018`、`000000000005`。
- 修改后：列表主文案分别为订单号和人员姓名；技术标识仅作为辅助排障信息，不丢失、不脱敏。

## 代码变更

- `frontend/platform_admin/src/api/resources.ts`：补充运行轨迹关联字段的名称展示配置。
- `frontend/platform_admin/scripts/check-resource-display-contracts.mjs`：补充运行轨迹展示回归检查。
- `frontend/platform_admin/scripts/check-staff-relation-policy.mjs`：补充历史轨迹人员角色与不过滤当前状态的契约检查。
- `frontend/platform_admin/src/api/resource-display.ts`：支持运行轨迹主记录解包及轨迹点专属中文字段语义。
- `frontend/platform_admin/src/api/resource-detail-contract.ts`：声明运行轨迹基本信息顺序、关联资源和轨迹点固定列。
- `backend/api/internal/seed/mock.go`：修正演示轨迹点生成值并提供精确范围的数据修复函数。
- `backend/api/cmd/cli/main.go`：新增 `repair-mock-track-point` 独立修复命令。
- `backend/api/internal/seed/mock_test.go`：补充演示轨迹点字段完整性测试。

## 风险评估

- 接口字段及公共组件均未改变，仅复用现有关系名称加载能力。
- 关联名称加载失败时仍保留唯一标识复制入口，不影响排障。

## 验证结果

- `pnpm run resource-display-contracts:check` 通过。
- `pnpm run type:check` 通过。
- `pnpm run build` 通过。
- 变更文件执行 Biome 检查通过；全项目 Biome 检查仍有既存的组件命名和未使用变量问题，本次未扩大范围修改。
- Codex 内置浏览器刷新运行轨迹后，配送订单显示 `MOCK-GASORDER-001`，配送人员显示“王师傅”；原截断标识不再作为主文案，两个完整唯一标识仍可复制。
- 修复详情页工作人员关联缺少显式角色策略导致的加载失败，并重新验证详情页。
- 浏览器详情页验证通过：加载失败提示数量为 0；基本信息正确显示订单号、配送人员姓名、尝试次数和时间，关联记录按固定中文列显示轨迹点。
- 执行 `go run ./cmd/cli repair-mock-track-point`，精确修复 1 条固定 Mock 轨迹点。
- 最终浏览器验证：零时间数量为 0；接收时间为 `2026-07-01 08:50:02`，速度为 `12 km/h`，方向为“东北（45°）”，上报流水号为 `MOCK-TRACK-POINT-001`。
- 后端 `go test ./...`、前端类型检查、生产构建和展示契约检查均通过。