docs: 交付错误响应整数标识契约 (#7706)

2026-09-17 10:12:22 +08:00
@@ -0,0 +1,220 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7706"
+title: "错误响应中的整数标识不再出现千分位分隔"
+consumer: "multiple"
+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: "仅纠正 Result.message 中整数实参的渲染；code、HTTP 状态、响应结构和字段均不变，前端无需改代码。"
+updated_at: "2026-09-17"
+base: "dev-v3"
+---
+
+# common：错误响应中的整数标识原样输出
+
+> **服务**: 全部依赖 hl-common-core 的后端服务
+> **PR**: #7748（dev-v3）、#7749（dev）
+> **Issue**: #7706
+> **日期**: 2026-09-17
+> **影响范围**: 管理端、C 端及内部调用收到的业务错误 Result.message 文本
+
+---
+
+## ⚠️ 关键变化
+
+无类型消息占位符收到整数 ID 时，不再按 locale 加千分位分隔符。完整 19 位 ID 现在保持原始十进制串，便于复制检索；code、HTTP 200 约定、Result 包络及字段结构均未改变。
+
+---
+
+## 一、背景
+
+错误响应原来会把 2099459272533323777 显示为 2,099,459,272,533,323,777。运营复制带逗号的 ID 后无法检索。缺陷位于公共消息格式化层，因此修复覆盖所有依赖 hl-common-core 的错误响应；下方列出测试服真实验证接口。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 旅行社公司详情 | GET | `/v3/admin/travel-agency/{id}` | 错误消息行为纠正 | 不存在的大整数 ID 在 594001 消息中原样输出 |
+
+---
+
+## 三、接口详情
+
+### 1. 旅行社公司详情 `GET /v3/admin/travel-agency/{id}`
+
+**VO**: `Result<AgencyRespVO>`
+
+#### 使用场景
+
+管理端读取旅行社公司详情。传入不存在的公司 ID 时，接口仍按既有约定返回 HTTP 200 和业务码 594001；仅 message 中的整数渲染从带分组逗号改为原始十进制串。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | 正整数 | 旅行社公司 ID |
+
+#### 出参 `Result<AgencyRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | Integer | 业务码；不存在时为 594001 |
+| message | String | 业务消息；整数 ID 原样输出 |
+| data | AgencyRespVO / null | 成功时为详情，不存在时为 null |
+| traceId | String / null | 链路标识，语义不变 |
+| success | Boolean | 是否成功，语义不变 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/travel-agency/2099459272533323777
+Authorization: Bearer ***
+
+无请求体
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 594001,
+  "message": "旅行社公司不存在(id=2099459272533323777)",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口不存在独立空列表或降级包络；旅行社不存在时使用上面的 594001 错误响应，保持 HTTP 200。
+
+#### 错误响应
+
+```json
+{
+  "code": 594001,
+  "message": "旅行社公司不存在(id=2099459272533323777)",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 鉴权、权限、HTTP 状态、错误码和数据结构均未修改。
+- Byte、Short、Integer、Long、BigInteger、原子整型及长整型累加器进入无类型占位符时原样输出。
+- BigDecimal、Double、Float 继续保留 JDK locale 行为；日期、时间和 choice 模板不变。
+- 显式 number 元素收到非 Number（含 null）时按 String.valueOf 降级并记录 WARN，避免格式异常覆盖真实业务错误。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | 调用方行为 |
+|------|------------|
+| ✅ 判断业务结果 | 使用 code、success 和结构化 data |
+| ✅ 展示错误 | 将 message 作为展示文本，不依赖千分位形式 |
+| ❌ 反解析标识 | 不从 message 提取或计算 ID；需要标识时使用请求参数或结构化字段 |
+
+### 调用方注意事项
+
+前端无需改动，也不得依赖旧的带逗号文本。既有 String.valueOf 绕行和显式 number 模板保持兼容。
+
+---
+
+## 六、边界行为
+
+- 未登录仍由网关按既有规则拦截。
+- 旅行社存在时成功响应内容不变。
+- 旅行社不存在时仍为 HTTP 200、业务码 594001、data=null、success=false。
+- 金额和浮点数格式不在本次修复范围内。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 响应结构 | code/message/data/traceId/success | 不变 |
+| message 类型 | String | String，不变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 无类型占位符 + 19 位 Long | 2,099,459,272,533,323,777 | 2099459272533323777 |
+| BigDecimal/Double/Float | JDK locale 格式 | 不变 |
+| 显式 number + Number | 模板声明格式 | 不变 |
+| 显式 number + 非 Number（含 null） | 可能抛格式异常或静默保留占位符 | String.valueOf 降级并记录 WARN |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否；响应结构不变，message 文本得到纠正。
+- **前端是否必须同步上线**: 否。
+- **前端 workaround 清理点**: 无；存量 String.valueOf 绕行保留。
+
+## 七、不影响范围
+
+- **仅影响**: 业务错误消息里由无类型占位符渲染的整数实参，以及显式 number 收到非 Number 时的安全降级。
+- **零影响**:
+  - Controller 路径、HTTP 方法、请求字段、响应字段及必填性
+  - Feign 签名、DTO/VO/BO、错误码和 Result 包络
+  - 金额、小数、日期、时间及 choice 模板的既有 JDK 语义
+  - 数据库结构与存量数据
+
+---
+
+## 八、测试环境已验证
+
+- PR #7748 合并提交：250365ba83c189189b3ede09d9e61891000a1280。
+- gateway、user、resource、product-v2、order-v3、mp、fleet 均滚动到包含该提交的 335a853c52c4ec357518e080caa27cd8414e39ed，双实例健康。
+- 网关 3/3 实测：HTTP 200、code 594001、完整 19 位 ID 无逗号。
+- 双线聚焦契约矩阵全部通过；所有活动 consumer reactor 均已执行。非绿全量用例均在精确目标基线复现，与 #7706 无关。
+
+    GET /v3/admin/travel-agency/2099459272533323777
+    → HTTP 200
+    → code=594001
+    → message=旅行社公司不存在(id=2099459272533323777) ✓
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #7748 | #7706 | dev-v3 公共格式化器修复并已部署 | ✅ 有效 |
+| #7749 | #7706 | dev 一期同步修复，待合并 | ✅ 有效 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7706](https://git.1814.love:8443/wx/HL/issues/7706)
+- dev-v3 PR: [wx/HL#7748](https://git.1814.love:8443/wx/HL/pulls/7748)
+- dev PR: [wx/HL#7749](https://git.1814.love:8443/wx/HL/pulls/7749)
+- CODE_RULES PR: [wx/hl-workflow#27](https://git.1814.love:8443/wx/hl-workflow/pulls/27)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7706](https://git.1814.love:8443/wx/HL/issues/7706)
+- **PR**: [#7748](https://git.1814.love:8443/wx/HL/pulls/7748)
+- **Merge commit**: [250365ba83c189189b3ede09d9e61891000a1280](https://git.1814.love:8443/wx/HL/commit/250365ba83c189189b3ede09d9e61891000a1280)
+
+### 联系人
+
+- **后端负责人**: @wx