wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

修正 changelog 文件名并新增核单门票来源通知
一些检查失败了
changelog-filename-gate / validate (push) Failing after 1s
详情

浏览代码
这个提交包含在：
yaosutu 2026-07-25 10:57:14 +08:00
父节点 86d9356d72
当前提交 736a17f084
共有 8 个文件被更改，包括 382 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

0
changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/22_5158_派车按行程日标记车费日期-修改接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/86_5160_一名司机多辆常驻车-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/22_5160_一名司机多辆常驻车-修改接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/88_5176_房务配房彻底移除成交价历史字段-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/23_5176_房务配房彻底移除成交价历史字段-修改接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/89_5178_用车手动加急与派车看板状态颜色-新增接口-前端待处理-管理后台.md → changelogs-v2/2026-07/23_5178_用车手动加急与派车看板状态颜色-新增接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/90_5193_用车需求增加独立接机送机选择-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/23_5193_用车需求增加独立接机送机选择-修改接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/91_5202_调整订单行程节点时间-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/24_5202_调整订单行程节点时间-修改接口-管理后台.md
查看文件

0
changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md → changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md
查看文件

382
changelogs-v2/2026-07/25_5238_核单门票来源类型统一-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,382 @@
# 【修改接口·管理后台】核单门票来源类型统一 (#5238)
> **PR**: #5242 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-25 10:03
## 1. 接口背景
核单 Step2 门票/游玩项目页签中，手工补充的门票行此前在查询出参中使用 `CUSTOM_ASSIGNMENT`。为避免前端按不同 Tab 或来源类型做额外分支，本次将查询出参的手工门票来源统一为 `MANUAL`，中文名统一为 `手工项目`；保存接口同步允许直接提交 `MANUAL`。
## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | Step 2 查询门票核单明细 | GET | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | 手工/自定义门票行的 `sourceType` 统一返回 `MANUAL`，`sourceTypeName` 返回 `手工项目` |
| 2 | Step 2 录门票核单明细 | PUT | `/v3/admin/order/{orderId}/settlement/step2` | 修改接口 | `items[].sourceType` 新增允许 `MANUAL`；旧 `CUSTOM_ASSIGNMENT` 入参继续兼容 |
## 3. 接口详情
### 3.1 Step 2 查询门票核单明细
- **方法**：GET
- **路径**：`/v3/admin/order/{orderId}/settlement/step2`
- **接口名**：`listTicket`
- **ApiOperation**：Step 2 查询门票核单明细
- **使用场景**：进入核单 Step2 门票/游玩项目页签，或保存成功后回读页面明细。
- **认证**：需要管理后台 JWT。
- **幂等性**：幂等，只读查询。
- **限流**：无单接口额外限流。
- **响应结构**：`data` 为 `TicketItemVO[]`。
### 3.2 Step 2 录门票核单明细
- **方法**：PUT
- **路径**：`/v3/admin/order/{orderId}/settlement/step2`
- **接口名**：`saveTicket`
- **ApiOperation**：Step 2 录门票核单明细
- **使用场景**：保存核单 Step2 门票/游玩项目明细，包含派生门票行和手工补充门票行。
- **认证**：需要管理后台 JWT。
- **幂等性**：全量替换保存；同一份 `items` 重复提交后，以最后一次提交结果为准。
- **限流**：无单接口额外限流。
- **请求体兼容**：推荐使用 `{ "items": [...] }`；历史数组 body `[...]` 仍兼容。
- **响应结构**：`data` 为 `SettlementTicketSaveRespVO`。
## 4. 接口入参
### 4.1 路径参数 / Query 参数
| 接口 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| GET / PUT | `orderId` | string | 是 | 订单 ID，长整型字符串 |
两个接口均无 Query 参数。
### 4.2 GET 请求体字段
GET 无请求体。
### 4.3 PUT 请求体字段
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| `items` | array | 是 | 门票/游玩项目明细行数组，全量替换保存 | 不允许为 `null` |
| `items[].id` | string | 否 | 已存在行 ID；新增行可不传 | 长整型字符串 |
| `items[].sourceType` | string | 是 | 来源类型；手工门票推荐传 `MANUAL` | `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` |
| `items[].sourceTypeName` | string | 否 | 来源类型中文名，仅展示字段；保存时可不传 | 最大 32 字符 |
| `items[].scenicAssignmentId` | string/null | 否 | 来源 assignment ID；手工项目传 `null` | 长整型字符串或 `null` |
| `items[].dayNumber` | integer/null | 否 | 行程第几天；保存后以回读值为准 | 从 1 开始 |
| `items[].dayDate` | string | 是 | 行程日期 | `yyyy-MM-dd` |
| `items[].scenicName` | string | 是 | 景区/游玩项目名称 | 1-200 字符 |
| `items[].specName` | string/null | 否 | 规格/票型名称 | 最大 128 字符 |
| `items[].ticketCount` | integer | 是 | 实际购票数量；套餐含门票但无额外成本时可填 0 | 整数 |
| `items[].ticketUnitPrice` | number/null | 否 | 参考成本单价，单位元 | 小数 |
| `items[].sellPrice` | number/null | 否 | 客户成交单价，单位元 | `>= 0` |
| `items[].totalAmount` | number/null | 否 | 客户成交小计，单位元 | `>= 0` |
| `items[].plannedCost` | number | 是 | 计划成本，单位元 | `>= 0` |
| `items[].actualCost` | number | 是 | 实际成本，单位元 | `>= 0` |
| `items[].paymentMethod` | string | 否 | 付款方式；不传时按公司付款处理 | `SIGNED` / `COMPANY_PAID` / `CASH_PAID` |
| `items[].paymentMethodName` | string | 否 | 付款方式中文名，仅展示字段；保存时可不传 | 最大 32 字符 |
| `items[].voucherUrls` | array | 否 | 凭证图片 URL 数组 | 字符串数组 |
| `items[].remark` | string/null | 否 | 备注 | 最大 500 字符 |
## 5. 出参字段
### 5.1 GET 响应字段：`TicketItemVO[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 业务状态码，成功为 `200` |
| `message` | string | 响应消息 |
| `success` | boolean | 是否成功 |
| `data` | array | 门票/游玩项目明细行数组 |
| `data[].id` | string/null | 核单明细行 ID；未持久化派生行可能为 `null` |
| `data[].sourceType` | string | 来源类型；手工/自定义门票行本次统一返回 `MANUAL` |
| `data[].sourceTypeName` | string/null | 来源类型中文名；`MANUAL` 返回 `手工项目` |
| `data[].scenicAssignmentId` | string/null | 来源 assignment ID；手工项目为 `null` |
| `data[].dayNumber` | integer/null | 行程第几天 |
| `data[].dayDate` | string | 行程日期，`yyyy-MM-dd` |
| `data[].scenicName` | string | 景区/游玩项目名称 |
| `data[].specName` | string/null | 规格/票型名称 |
| `data[].ticketCount` | integer | 实际购票数量 |
| `data[].ticketUnitPrice` | number/null | 参考成本单价，单位元 |
| `data[].sellPrice` | number/null | 客户成交单价，单位元 |
| `data[].totalAmount` | number/null | 客户成交小计，单位元 |
| `data[].plannedCost` | number | 计划成本，单位元 |
| `data[].actualCost` | number | 实际成本，单位元 |
| `data[].paymentMethod` | string/null | 付款方式 |
| `data[].paymentMethodName` | string/null | 付款方式中文名 |
| `data[].voucherUrls` | array | 凭证图片 URL 数组 |
| `data[].remark` | string/null | 备注 |
### 5.2 PUT 响应字段：`SettlementTicketSaveRespVO`
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 业务状态码，成功为 `200` |
| `message` | string | 响应消息 |
| `success` | boolean | 是否成功 |
| `data.addedIds` | string[] | 本次保存新增的核单明细行 ID 列表 |
| `data.updatedIds` | string[] | 本次保存更新的核单明细行 ID 列表；当前全量替换语义下通常为空数组 |
| `data.deletedIds` | string[] | 本次保存删除的核单明细行 ID 列表；当前返回通常为空数组 |
| `data.totalActualCost` | string | 保存后 Step2 实际成本合计，单位元 |
## 6. 枚举 / 数据字典
### 6.1 `sourceType`
**所属字段**：`items[].sourceType`、`data[].sourceType` | **类型**：String | **PUT 必填**：是 | **GET 必返**：是
| 值 | 中文 | 说明 |
|----|------|------|
| `SCENIC_ASSIGNMENT` | 景区 | 景区派生来源行；查询和保存语义不变 |
| `ACTIVITY_ASSIGNMENT` | 游玩项目 | 游玩项目派生来源行；查询和保存语义不变 |
| `MANUAL` | 手工项目 | 本次推荐值；查询手工/自定义门票行统一返回该值，保存接口也允许提交该值 |
| `CUSTOM_ASSIGNMENT` | 手工项目（旧入参兼容） | 仅用于兼容旧保存请求；查询响应不再返回该值 |
### 6.2 `sourceTypeName`
**所属字段**：`items[].sourceTypeName`、`data[].sourceTypeName` | **类型**：String | **必填**：否
| sourceType | sourceTypeName | 说明 |
|------------|----------------|------|
| `SCENIC_ASSIGNMENT` | `景区` | 景区派生来源行 |
| `ACTIVITY_ASSIGNMENT` | `游玩项目` | 游玩项目派生来源行 |
| `MANUAL` | `手工项目` | 手工/自定义门票行统一展示名 |
| `CUSTOM_ASSIGNMENT` | `手工项目` | 旧保存请求兼容；保存成功后回读为 `MANUAL` / `手工项目` |
| `null` / 未知值 | `null` | 查询行为不变，不新增兜底文案 |
### 6.3 `paymentMethod`
**所属字段**：`items[].paymentMethod`、`data[].paymentMethod` | **类型**：String | **必填**：否
| 值 | 中文 | 说明 |
|----|------|------|
| `SIGNED` | 签单 | 现场签单 |
| `COMPANY_PAID` | 公司付款 | 公司统一付款；未传 `paymentMethod` 时按该值处理 |
| `CASH_PAID` | 现付 | 现场现金/线下现付 |
## 7. 错误码
| HTTP 状态 / code | 含义 | 触发场景 |
|------------------|------|----------|
| `200` / `200` | 成功 | GET 查询成功或 PUT 保存成功 |
| `200` / `401` | 未授权 | 缺少有效的管理后台 `Authorization` 头 |
| `400` / `400` | 请求参数非法 | `sourceType` 不在 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` 内，或请求体结构不符合要求 |
| `200` / `584011` | 当前核单状态不允许录门票核单 | PUT 保存时订单不是可录门票核单的状态 |
### 7.1 错误结构
```json
{
"code": 400,
"message": "sourceType 必须是 SCENIC_ASSIGNMENT / ACTIVITY_ASSIGNMENT / MANUAL / CUSTOM_ASSIGNMENT 之一",
"data": null,
"success": false
}
```
## 8. 示例（3 组：典型 / 边界 / 异常）
### 8.1 典型成功：GET 返回手工项目为 MANUAL
**请求**：
```http
GET /v3/admin/order/2079576729147338754/settlement/step2
Authorization: Bearer {token}
```
GET 无请求体。
**响应**：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": [
{
"id": "2080186487600025601",
"sourceType": "MANUAL",
"sourceTypeName": "手工项目",
"scenicAssignmentId": null,
"dayNumber": 2,
"dayDate": "2026-07-22",
"scenicName": "临时补充门票",
"specName": "成人票",
"ticketCount": 2,
"ticketUnitPrice": 30.00,
"sellPrice": 50.00,
"totalAmount": 100.00,
"plannedCost": 60.00,
"actualCost": 60.00,
"paymentMethod": "COMPANY_PAID",
"paymentMethodName": "公司付款",
"voucherUrls": [],
"remark": "现场补充"
}
]
}
```
### 8.2 边界成功：查询结果原样 PUT
**场景说明**：前端可把 GET 回来的 `MANUAL` 行原样放入 `items` 后提交；保存成功后再次 GET 仍返回 `MANUAL` / `手工项目`。
**请求**：
```http
PUT /v3/admin/order/2079576729147338754/settlement/step2
Authorization: Bearer {token}
Content-Type: application/json
```
```json
{
"items": [
{
"id": "2080186487600025601",
"sourceType": "MANUAL",
"sourceTypeName": "手工项目",
"scenicAssignmentId": null,
"dayNumber": 2,
"dayDate": "2026-07-22",
"scenicName": "临时补充门票",
"specName": "成人票",
"ticketCount": 2,
"ticketUnitPrice": 30.00,
"sellPrice": 50.00,
"totalAmount": 100.00,
"plannedCost": 60.00,
"actualCost": 60.00,
"paymentMethod": "COMPANY_PAID",
"paymentMethodName": "公司付款",
"voucherUrls": [],
"remark": "现场补充"
}
]
}
```
**响应**：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"addedIds": ["2080186500000000001"],
"updatedIds": [],
"deletedIds": [],
"totalActualCost": "60.00"
}
}
```
### 8.3 业务失败：非法 sourceType
**场景说明**：`items[].sourceType` 传入未定义值时仍按参数非法处理。
**请求**：
```http
PUT /v3/admin/order/2079576729147338754/settlement/step2
Authorization: Bearer {token}
Content-Type: application/json
```
```json
{
"items": [
{
"sourceType": "TAB_MANUAL",
"scenicAssignmentId": null,
"dayDate": "2026-07-22",
"scenicName": "临时补充门票",
"specName": "成人票",
"ticketCount": 1,
"ticketUnitPrice": 0,
"sellPrice": 0,
"totalAmount": 0,
"plannedCost": 0,
"actualCost": 0,
"paymentMethod": "COMPANY_PAID",
"voucherUrls": [],
"remark": null
}
]
}
```
**响应**：
```json
{
"code": 400,
"message": "sourceType 必须是 SCENIC_ASSIGNMENT / ACTIVITY_ASSIGNMENT / MANUAL / CUSTOM_ASSIGNMENT 之一",
"data": null,
"success": false
}
```
## 9. 业务边界
- **适用场景**：核单 Step2 门票/游玩项目页签查询、保存门票明细时使用。
- **手工项目保存**：新增或编辑手工门票行时，`items[].sourceType` 推荐传 `MANUAL`，`scenicAssignmentId` 可传 `null`。
- **旧入参兼容**：旧页面继续传 `CUSTOM_ASSIGNMENT` 仍可保存；保存成功后再次查询会返回 `MANUAL`。
- **查询结果原样提交**：GET 返回的 `MANUAL` 行可原样进入 PUT 的 `items`。
- **未变化范围**：`SCENIC_ASSIGNMENT`、`ACTIVITY_ASSIGNMENT` 的查询和保存语义不变；`null` / 未知来源的查询兜底行为不变。
- **不适用场景**：人员费用、住宿、餐食、其他支出接口没有本次契约变化。
## 10. 修改前后对比
### 10.1 字段级对比
| 字段 | 修改前 | 修改后 |
|------|--------|--------|
| GET `data[].sourceType` | 手工/自定义门票行返回 `CUSTOM_ASSIGNMENT` | 手工/自定义门票行统一返回 `MANUAL` |
| GET `data[].sourceTypeName` | 手工/自定义门票行可能按旧来源展示 | 手工/自定义门票行统一返回 `手工项目` |
| PUT `items[].sourceType` | 允许 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `CUSTOM_ASSIGNMENT` | 允许 `SCENIC_ASSIGNMENT` / `ACTIVITY_ASSIGNMENT` / `MANUAL` / `CUSTOM_ASSIGNMENT` |
### 10.2 行为级对比
| 行为 | 修改前 | 修改后 |
|------|--------|--------|
| 查询手工门票行 | 前端需要识别 `CUSTOM_ASSIGNMENT` | 前端按 `MANUAL` 识别手工项目 |
| 保存手工门票行 | 前端需要把手工 Tab 转成 `CUSTOM_ASSIGNMENT` | 前端可直接提交 `MANUAL` |
| 查询结果原样保存 | GET 的旧来源值与页面手工 Tab 值可能不一致 | GET 结果可原样 PUT |
| 旧请求兼容 | 旧 `CUSTOM_ASSIGNMENT` 入参可保存 | 继续可保存，回读统一为 `MANUAL` |
## 11. 影响评估 / 回滚
### 11.1 影响评估
- **是否破坏向后兼容**：否。PUT 继续兼容旧 `CUSTOM_ASSIGNMENT` 入参；GET 只统一手工门票来源的展示值。
- **前端是否必须同步上线**：否。旧保存请求仍可用；但前端可清理 `MANUAL` 与 `CUSTOM_ASSIGNMENT` 互转逻辑。
- **影响已有数据**：不需要前端处理历史数据；页面以后端返回的 `MANUAL` 为准。
### 11.2 回滚方案
- 如接口回滚，前端需恢复兼容 GET 返回 `CUSTOM_ASSIGNMENT` 的判断。
- 回滚后不要把 GET 查询结果中的 `sourceType` 假定为一定可原样提交。
## 12. 注意事项
- 前端不要再按 Tab 名称把手工项目强制转换成 `CUSTOM_ASSIGNMENT`；新增手工行可以直接传 `MANUAL`。
- 前端如有 `sourceType === "CUSTOM_ASSIGNMENT"` 才展示手工项目的判断，需要同步兼容或改为判断 `MANUAL`。
- `CUSTOM_ASSIGNMENT` 仅作为旧保存请求兼容值保留，不应再作为新页面查询展示值。
- `sourceTypeName` 是展示字段，保存时可不传；保存后以再次查询结果为准。
- 非法 `sourceType` 仍会返回参数非法，不新增兜底保存。
## 13. 关联 / 联系人
### 13.1 链接
- **Issue**: [#5238](https://git.1814.love:8443/wx/HL/issues/5238)
- **PR**: [#5242](https://git.1814.love:8443/wx/HL/pulls/5242)
- **Merge commit**: [bfb28a258](https://git.1814.love:8443/wx/HL/commit/bfb28a258)
### 13.2 联系人
- **后端负责人**: @yst