hl-api-changelog/changelogs-v2/2026-08/09_5746_全项目报错文案中文治理-修改接口-管理后台.md

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

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

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

后端完成：PR #5760 已合并 dev-v3 并部署 TEST，网关实证通过。

关联 / 联系人

链接

• Issue: #5746
• PR: #5760
• Merge 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 即可。