From f9634974c803973773753727eaabb75a726e726c Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 1 Jul 2026 17:00:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E7=94=B5=E5=AD=90?= =?UTF-8?q?=E8=A1=8C=E7=A8=8B=E5=8D=95=20documentType=20=E4=B8=89=E5=8F=96?= =?UTF-8?q?=E5=80=BC=E6=94=B9=E5=90=8D=EF=BC=88=E6=B6=88=E9=99=A4=E6=92=9E?= =?UTF-8?q?=E5=90=8D=EF=BC=89=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3=E9=80=9A?= =?UTF-8?q?=E7=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GET /v3/admin/order/{id}/itinerary-document 的 documentType 三取值改名： ITINERARY_C→CUSTOMER / ITINERARY_PRINT→CUSTOMER_PRINT / SIGNING→CUSTOMER_QUOTE。 业务零变动，出参结构不变，仅入参枚举值改名。关联 HL #4675 / PR #4705。 --- ...行程单documentType改名-修改接口-管理后台.md | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 changelogs-v2/2026-07/06_4675_电子行程单documentType改名-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/06_4675_电子行程单documentType改名-修改接口-管理后台.md b/changelogs-v2/2026-07/06_4675_电子行程单documentType改名-修改接口-管理后台.md new file mode 100644 index 0000000..49fda24 --- /dev/null +++ b/changelogs-v2/2026-07/06_4675_电子行程单documentType改名-修改接口-管理后台.md @@ -0,0 +1,173 @@ +# 电子行程单 documentType 三取值改名（消除与 sign-voucher / print-itinerary 撞名） + +**接口路径**：GET /v3/admin/order/{id}/itinerary-document +**服务**：hl-order-service-v3 +**PR**：[#4705](https://git.1814.love:8443/wx/HL/pulls/4705)｜ **Issue**：[#4675](https://git.1814.love:8443/wx/HL/issues/4675)｜ **前序**：[#4641](https://git.1814.love:8443/wx/HL/pulls/4641)（接口初建）/ #4638｜ **合并至**：dev-v3 +**变更类型**：修改接口（入参枚举值改名，破坏性变更） + +--- + +## 1. 接口背景 + +电子行程单接口 `GET /v3/admin/order/{id}/itinerary-document` 用一个 `documentType` 参数区分三种「对客视角」文档。原三个取值（`ITINERARY_C` / `ITINERARY_PRINT` / `SIGNING`）与系统另外两个**独立单据接口**撞名，受众实测不同却名字混淆： + +- `documentType=SIGNING`（对客核应收）撞独立接口 `sign-voucher`（对供应商核成本） +- `documentType=ITINERARY_PRINT`（客人打印版）撞独立接口 `print-itinerary`（司机出团 Driver Copy） + +本次将三取值统一改名为「对客视角」命名，消除歧义。**业务逻辑零变动，三个接口一个不砍，仅入参取值改名，无 DDL。** + +--- + +## 2. 变更清单 + +| 类型 | 位置 | 变更说明 | +|------|------|----------| +| 破坏性变更 | 入参 `documentType` | 三个取值改名（见第 6 节映射表） | +| 出参 `documentType` | 回显值同步改名（后端原样回填入参值） | +| 无变化 | 出参结构 | 所有字段、层级、语义完全不变 | + +**无 DDL，无新依赖，出参结构不变。** + +--- + +## 3. 接口详情 + +- 方法：GET ｜ 路径：`/v3/admin/order/{id}/itinerary-document` ｜ 鉴权：管理后台 JWT +- 响应：`Result` +- 三类文档共用本接口，前端按 `documentType` 渲染模板 + +--- + +## 4. 入参 + +| 位置 | 字段 | 类型 | 必填 | 说明 | +|------|------|------|:---:|------| +| Path | `id` | Long | 是 | 订单 ID | +| Query | `documentType` | String | 是 | 文档类型（对客视角）：`CUSTOMER` / `CUSTOMER_PRINT` / `CUSTOMER_QUOTE`（**取值已改名**，见第 6 节） | +| Query | `includeResourceDetail` | Boolean | 否 | 是否调 Feign 取资源详情，默认 `true`；`CUSTOMER` 可传 `false` | + +--- + +## 5. 出参 + +出参结构**完全不变**，仅 `documentType` 回显值随入参改名。关键字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `documentType` | String | 回显文档类型（值同入参新命名） | +| `header.totalAmount` | BigDecimal | 订单总金额（**仅 `CUSTOMER_QUOTE` 文档返回**，其余为 null） | +| `travelers[].idCard` | String | 身份证 6+4 脱敏（**`CUSTOMER` 文档为 null**，不含身份证） | +| `days` / `hotels` / `feeNotes` / `supplies` / `transports` / `summary` | —— | 结构与语义均不变 | + +--- + +## 6. 枚举 / 数据字典 + +`documentType` 取值改名映射（**旧值全部下线，调用旧值不会报参数错但语义不匹配，请前端全量替换**）： + +| 旧值（已废弃） | 新值 | 含义 | +|------|------|------| +| `ITINERARY_C` | `CUSTOMER` | 客人电子行程单 | +| `ITINERARY_PRINT` | `CUSTOMER_PRINT` | 客人行程打印版 | +| `SIGNING` | `CUSTOMER_QUOTE` | 对客核价单（含 totalAmount） | + +> 命名统一为「对客视角」，与供应商单据 `sign-voucher`、司机单据 `print-itinerary` 明确区分。 + +--- + +## 7. 错误码 + +无新增错误码。订单不存在仍返回 `581401 订单不存在`。 + +--- + +## 8. 示例 + +### 8.1 典型成功（对客核价单） + +请求： +``` +GET /v3/admin/order/60001/itinerary-document?documentType=CUSTOMER_QUOTE +``` +响应片段： +```json +{ + "code": 200, + "message": "成功", + "data": { + "documentType": "CUSTOMER_QUOTE", + "header": { "orderNo": "HL2026...", "totalAmount": "12800.00" }, + "travelers": [ { "name": "张*", "idCard": "110101******1234" } ] + } +} +``` + +### 8.2 边界（客人电子行程单，不含身份证） + +请求： +``` +GET /v3/admin/order/60001/itinerary-document?documentType=CUSTOMER&includeResourceDetail=false +``` +响应片段： +```json +{ + "code": 200, + "data": { + "documentType": "CUSTOMER", + "header": { "totalAmount": null }, + "travelers": [ { "name": "张*", "idCard": null } ] + } +} +``` + +### 8.3 异常（订单不存在） + +```json +{ "code": 581401, "message": "订单不存在", "data": null, "success": false } +``` + +--- + +## 9. 业务边界 + +- 三个取值均为「对客视角」文档，本接口与供应商 `sign-voucher`、司机 `print-itinerary` 是三个独立接口，勿混用。 +- `CUSTOMER_QUOTE` 才返回 `header.totalAmount`；`CUSTOMER` 文档 `travelers[].idCard` 恒为 null（对客不暴露身份证）。 +- 出参结构与改名前一致，前端仅需替换请求参数取值。 + +--- + +## 10. 修改前后对比 + +| 场景 | 修改前 documentType | 修改后 documentType | +|------|--------|--------| +| 客人电子行程单 | `ITINERARY_C` | `CUSTOMER` | +| 客人打印版 | `ITINERARY_PRINT` | `CUSTOMER_PRINT` | +| 对客核价单 | `SIGNING` | `CUSTOMER_QUOTE` | + +出参 JSON 结构、字段名、层级均无变化。 + +--- + +## 11. 影响评估 / 回滚 + +**破坏性变更（前端必须同步）**：调用本接口处的 `documentType` 请求参数须按第 6 节映射表全量替换为新值。 + +**迁移成本**：接口于 PR #4641 刚建、前端尚未接入，改即新基线，无历史数据/存量调用迁移。 + +**回滚**：接口层回退到 PR #4705 之前版本即恢复旧取值。零 DDL，无数据迁移。 + +--- + +## 12. 注意事项 + +- 旧取值传入不会触发参数校验错误（`documentType` 是自由 String），但会命中默认分支（未知值按 `CUSTOMER_QUOTE` 兜底处理），**语义不匹配**，务必替换为新值。 +- 已部署测试服并行为验证：新值 `CUSTOMER` / `CUSTOMER_QUOTE` 网关实调可达（HTTP 200，路由健康），实时 OpenAPI 文档已反映新命名、无旧值残留。 + +--- + +## 13. 关联 / 联系人 + +- Issue：[#4675](https://git.1814.love:8443/wx/HL/issues/4675) +- PR：[#4705](https://git.1814.love:8443/wx/HL/pulls/4705) +- 前序：[#4641](https://git.1814.love:8443/wx/HL/pulls/4641)（接口初建）/ #4638 +- 负责人：腰苏图（yst）