125 行
5.8 KiB
Markdown
125 行
5.8 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5463"
|
||
title: "派单司机/员工手机号密文解密失败降级容错"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "Pi"
|
||
frontend_ref: "hl-admin@4c8bdb97c89fa399e5fbb13240ea082f64fefc59"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-08-04"
|
||
status_note: "订单详情/行程接口对手机号密文解密失败（keyVersion 缺失/密文损坏）不再 500，降级返回空手机号；后端 warn 日志含 keyVersion 与密文指纹，不含明文。"
|
||
updated_at: "2026-08-04"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 【修改接口·管理后台】派单司机/员工手机号密文解密失败降级容错 (#5463)
|
||
|
||
> **PR**: #5464 | **服务**: order-v3 | **更新时间**: 2026-08-04
|
||
|
||
## 1. 接口背景
|
||
|
||
订单详情/行程接口对含派单司机/员工手机号密文的记录，在密钥版本缺失或密文损坏时返回 500（`assignment phone key version is unavailable`），用户端订单详情页直接报错不可用。本次改为解密失败降级：仅手机号字段返回空，订单其余字段正常展示。
|
||
|
||
## 变更接口清单
|
||
|
||
| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|--------|------|------|----------|------|
|
||
| 1 | 订单行程（v2 详情页） | GET | `/v3/admin/order/{id}/itinerary` | 修改 | 手机号解密失败不再 500，降级为空展示 |
|
||
| 2 | 订单详情（9 Tab 聚合） | GET | `/v3/admin/order/{id}` | 修改 | 车辆/人员手机号解密失败不再 500，降级为空展示 |
|
||
|
||
## 2. 行为变化
|
||
|
||
| 场景 | 原来 | 现在 |
|
||
|------|------|------|
|
||
| 派单/员工手机号密文 keyVersion 缺失（如配置未下发） | 整接口 500 | 200，手机号字段为 `null`/空，其余字段正常 |
|
||
| 密文损坏 / Base64 非法 / AAD 不匹配 | 整接口 500 | 200，手机号字段为 `null`/空，其余字段正常 |
|
||
| 手机号无密文（明文快照或空） | 正常展示 | 不变 |
|
||
| 密钥配置齐全且密文正常 | 正常解密展示 | 不变 |
|
||
|
||
**涉及字段**（响应中车辆/人员相关节点）：
|
||
|
||
| 字段 | 类型 | 变化 |
|
||
|------|------|------|
|
||
| 车辆行 `driverPhone`（订单行程/详情车辆列表） | string | 解密失败时为 `null`（原来导致整接口 500） |
|
||
| 签收凭证 `driverPhone` / `guidePhone` / `leaderPhone` | string | 解密失败时为 `null`（原来导致整接口 500） |
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 订单行程
|
||
|
||
- **方法/路径**：`GET /v3/admin/order/{id}/itinerary`
|
||
- **认证**：管理后台登录态（定制师/车务均可）
|
||
- **无请求体**；`id` 为订单雪花 ID。
|
||
- **典型成功示例**（手机号解密失败时，其余字段完整返回）：
|
||
|
||
```
|
||
GET /v3/admin/order/2084280253366124546/itinerary
|
||
Authorization: Bearer <token>
|
||
（无请求体）
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"orderId": "2084280253366124546",
|
||
"orderNo": "HL20260803220000001",
|
||
"vehicles": [
|
||
{
|
||
"assignmentId": "2084280300000000001",
|
||
"driverName": "张师傅",
|
||
"driverPhone": null,
|
||
"licensePlate": "蒙A-12345",
|
||
"serviceStartDate": "2026-08-03",
|
||
"serviceEndDate": "2026-08-05"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 订单详情
|
||
|
||
- **方法/路径**：`GET /v3/admin/order/{id}`
|
||
- **行为**：与 3.1 一致；聚合内所有来源自 `driver_phone_ciphertext` / `staff_phone_ciphertext` 的手机号字段在解密失败时均为 `null`，不再触发整接口 500。
|
||
|
||
## 4. 错误码
|
||
|
||
无新增错误码。解密失败不再返回 500，改为 200 + 字段 `null`；后端以 warn 日志记录（`assignment phone decrypt degraded: ... keyVersion=... envelopeFingerprint=...`），日志不含明文与密钥。
|
||
|
||
## 5. 前端需要做什么
|
||
|
||
- 无需代码改动即可恢复可用（页面从 500 变为正常打开）。
|
||
- 请确认车辆/人员手机号为空（`null`）时页面展示兜底（如显示 `-` 或留空），避免出现 `undefined` 文案。
|
||
- 前端遇到 `driverPhone` 为空时，不要向用户提示“数据异常”，按“暂无/未填写”处理即可。
|
||
|
||
## 6. 后端测试、部署与网关验证
|
||
|
||
- 单元测试：`AssignmentPhoneCryptoTest` 10 个（正常解密 / keyVersion 缺失 / 损坏密文 / Base64 非法 / AAD 不匹配 / AAD 身份缺失 / 加密 fail-fast / previous-keys 轮换）全部通过。
|
||
- 模块验证：`mvn -pl hl-order-service-v3 -am verify` 7414 测试 0 失败。
|
||
- 部署：TEST 环境 hl-order-service-v3 已部署。
|
||
- 网关验证：原 500 订单（`2084280253366124546` / `2084280407016062978`）`GET /v3/admin/order/{id}/itinerary` 恢复 200，手机号字段降级为空，其余字段正常。
|
||
|
||
## 验证证据
|
||
|
||
- 单元测试：`AssignmentPhoneCryptoTest` 10 个用例（正常 v1/v2 往返、keyVersion 缺失降级 null、损坏密文降级 null、Base64 非法降级 null、AAD 不匹配降级 null、AAD 身份缺失降级 null、加密 fail-fast、previous-keys 轮换）全通过。
|
||
- 模块验证：`mvn -pl hl-order-service-v3 -am verify` 7414 测试 0 失败。
|
||
- 部署：TEST 环境 hl-order-service-v3 rolling 部署完成（dev-v3 @ fcde24ec，双实例 UP）。
|
||
- 网关验证（wx=CUSTOMIZER）：原 500 订单 `2084280253366124546` / `2084280407016062978` / `2084278362947158017` 的 `GET /v3/admin/order/{id}/itinerary` 全部恢复 200；含 v1 密文的订单 `2084266179660013569` 车辆行 `driverPhoneMasked` 正常掩码回显（测试服已补配 v1 密钥，存量 414 条密文可解密；无密钥时走降级路径返回空，由单元测试覆盖）。
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#5463](https://git.1814.love:8443/wx/HL/issues/5463)
|
||
- **PR**: [#5464](https://git.1814.love:8443/wx/HL/pulls/5464)
|
||
- **Merge commit**: [fcde24ec63](https://git.1814.love:8443/wx/HL/commit/fcde24ec63)
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|