# 电子行程单 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）
