docs(changelog-v2): 电子行程单 documentType 三取值改名（消除撞名）修改接口通知

GET /v3/admin/order/{id}/itinerary-document 的 documentType 三取值改名： ITINERARY_C→CUSTOMER / ITINERARY_PRINT→CUSTOMER_PRINT / SIGNING→CUSTOMER_QUOTE。业务零变动，出参结构不变，仅入参枚举值改名。关联 HL #4675 / PR #4705。
2026-07-01 17:00:02 +08:00 · 2026-07-01 17:00:02 +08:00 · f9634974c8
--- a/changelogs-v2/2026-07/06_4675_电子行程单documentType改名-修改接口-管理后台.md
+++ 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<OrderItineraryDocumentVO>`
+- 三类文档共用本接口，前端按 `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）