changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): 联系人章节补全 yst 完整格式——链接（Issue+PR+Merge commit）+ 联系人

2026-08-04 14:13:26 +08:00

5.8 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5463	派单司机/员工手机号密文解密失败降级容错	admin	修改接口	deployed	verified	verified	Pi	hl-admin@4c8bdb97c89fa399e5fbb13240ea082f64fefc59	v2.1	2026-08-04	订单详情/行程接口对手机号密文解密失败（keyVersion 缺失/密文损坏）不再 500，降级返回空手机号；后端 warn 日志含 keyVersion 与密文指纹，不含明文。	2026-08-04	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>
（无请求体）

{
  "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 条密文可解密；无密钥时走降级路径返回空，由单元测试覆盖）。

5.8 KiB 原始文件 Blame 文件历史 Unescape Escape