---
schema: "hl-changelog/v2"
ticket: "5746"
title: "全项目报错文案中文治理——兜底不泄漏英文原文，校验/错误码/e2e 文案全中文"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5760 已合并 dev-v3 并部署 TEST（order-v3/fleet/resource/user/order-v2/product-v2/mp 七服务）。接口字段/结构/错误码 code 均不变，仅 message 文案治理：500 兜底不再拼接[异常类名]:英文原文（统一中文+带 traceId）、校验/JSON 解析/类型不匹配等框架错误全中文、39 条英文错误码与 318 条夹杂技术词文案中文化、e2e 引擎文案中文化、防回潮守门测试上线。前端无需改动。"
updated_at: "2026-08-09"
base: "dev-v3"
generated: "2026-08-09T18:00:00+08:00"
---

# 全项目报错文案中文治理——兜底不泄漏英文原文，校验/错误码/e2e 文案全中文

> 后端完成：PR [#5760](https://git.1814.love:8443/wx/HL/pulls/5760) 已合并 dev-v3 并部署 TEST，网关实证通过。

## 关联 / 联系人

### 链接

- **Issue**: [#5746](https://git.1814.love:8443/wx/HL/issues/5746)
- **PR**: [#5760](https://git.1814.love:8443/wx/HL/pulls/5760)
- **Merge commit**: [fa7dc738f](https://git.1814.love:8443/wx/HL/commit/fa7dc738f)

### 联系人

- **后端负责人**: @wx

## 背景

前端弹窗直接展示英文技术异常原文（真实截图：`服务器内部错误[UnknownClassException]: Unable to find an implementation for interface io.jsonwebtoken.io.Serializer...`）。治理目标：到达前端响应的 message 必须全中文、无技术黑话、说人话（请检查/请重试/联系客服）、可定位（traceId）。

## 变更内容

1. **兜底 handler 改造（hl-common-log GlobalExceptionHandler，全项目生效）**：`handleGeneral` 不再拼接 `[异常类名]: 英文原文`，统一「系统繁忙，请稍后重试或联系客服」+ traceId（原文只进日志/监控）；`handleConstraint`/`handleValidation`/`handleBind` 非中文文案一律降级中文；`handleHttpMessageNotReadable` 不再回显 Jackson 英文原文；`handleTypeMismatch` 去掉 Java 类型名；`handleBusiness` 的 null 文案兜底。
2. **全局中文校验兜底**：新增 `ValidationMessages.properties`（hl-common-log，27 键覆盖 javax.validation 内置约束），287 处无 message 校验注解自动中文（决策：全局兜底方案替代逐一补 message，记录于工单）。
3. **错误码文案治理**：39 条无中文（含 E2E 581090-581099、合同 510302/510503/510504、结算 584014/584015、微信 240102 等）+ 318 条中文夹杂技术词（字段名→中文、枚举值→中文、字典 key/配置 key→中文；保留日期格式 yyyy-MM-dd、车型 SUV/MPV、文件格式 PDF/SVG 等用户可理解项）逐条过一遍；23 条纯 `{0}` 占位符约定调用方必须填中文（javadoc + 守门测试）。
4. **e2e 引擎文案中文化**：E2eRunService/E2eScopedLifecycleService/E2eScopedOrderCreateService/E2eVehicleAssignmentFinalizeService 等 70+ 处英文 → 中文，同步测试断言。
5. **防回潮守门**：新增 `ErrorCodeChineseAuditTest`（错误码 message 必须含中文；BusinessException 单实参字面量必须中文）+ `ValidationMessagesPresenceTest`。
6. **测试基础设施**：resource-service Testcontainers 1.19.8→1.21.4（Docker Desktop 29 API 兼容）。

## 行为变化

| 场景 | 变更前 | 变更后 |
|------|--------|--------|
| 任意未捕获异常（500 兜底） | `服务器内部错误[UnknownClassException]: Unable to...` | `系统繁忙，请稍后重试或联系客服` + traceId |
| 校验失败（无 message 注解） | `must not be null` / `list.arg0: must not be empty` | `该字段不能为空` 等中文 |
| JSON 解析失败 | 回显 `Unrecognized field "xxx"...` 英文片段 | `请求数据格式错误，请检查参数是否正确` |
| 参数类型不匹配 | `参数类型错误: xx='yy'（需要 Long 类型）` | `参数 xx 格式错误，请检查后重试` |
| 错误码文案（510302/E2E 等 39+318 条） | 英文/技术词/纯占位符 | 全中文 |
| e2e 引擎错误（581090-581099） | `E2E RUN_STATE_CONFLICT: version mismatch` | `测试执行状态冲突：版本不一致` |

**不变**：接口字段/结构、HTTP 状态语义（400/401/403/404/405/500）、错误码 code 全部保持，前端仅展示文案变化。

## 验证证据

- **网关实证（TEST，ROOM_MANAGER）**：非法 JSON → `请求数据格式错误，请检查参数是否正确`；缺参 → `服务日期不能为空`；类型不匹配 → `参数 orderId 格式错误，请检查后重试`（无 Java 类型名）；业务错误 → `该订单非房务可见`；网关 401 → `缺少有效的 Authorization 头` + traceId。
- **500 兜底**：GlobalExceptionHandlerTest 单测断言 handleGeneral 返回 `系统繁忙，请稍后重试或联系客服` 且不含异常类名/英文（真实截图 JJWT 场景在旧实例复现后，重启新代码登录恢复正常）。
- **测试**：守门测试 4/4；order-v3 7550 / fleet 3307 / user 3530 / resource 1755 / order-v2 3496 / product-v2 1510 / mp 986 全量 verify（文案相关全绿，基线失败集除外：fleet ReleaseEOccupancy 10、order-v3 IT 上下文 51 + 业务断言漂移 5 等，dev-v3 原样复现）。

## 前端交接

无接口契约变化（字段、结构、错误码 code 均不变，仅 message 文案），前端无需改动；弹窗直接展示 message 即可。
