From 5aad9d2ed3db8132ba3ece2cb110b391c63802c1 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 10 Jul 2026 16:18:35 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E6=A0=B8=E5=8D=95Step3?= =?UTF-8?q?=E5=90=88=E5=B9=B6=E8=BE=85=E5=8A=A9=E7=BB=93=E7=AE=97=E5=8F=98?= =?UTF-8?q?=E6=9B=B4=E9=80=9A=E7=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...核单Step3合并辅助结算-修改接口-管理后台.md | 427 ++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md b/changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md new file mode 100644 index 0000000..ff80edf --- /dev/null +++ b/changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md @@ -0,0 +1,427 @@ +# 【修改接口·管理后台】核单 Step3 合并辅助人员结算 (#4869) + +> **PR**: #4870 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-10 00:00 + +## 1. 接口背景 + +核单流程中的“辅助人员结算 / 小算拨款”不再使用独立 payout 接口维护，统一收敛到 Step3 人员费用保存接口。前端需要在 Step3 人员费用行里一起提交结算状态、结算日期和转账流水号，并停止调用旧的 payout 查询/保存接口。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | Step3 人员费用保存 | PUT | `/v3/admin/order/{orderId}/settlement/step3` | 修改接口 | `items[]` 入参和响应行新增 `settleStatus`、`settledDate`、`transferRef` | +| 2 | 小算拨款列表查询 | GET | `/v3/admin/order/{orderId}/settlement/payout` | 删除接口 | 不再提供独立 payout 查询 | +| 3 | 小算拨款状态保存 | PUT | `/v3/admin/order/{orderId}/settlement/payout` | 删除接口 | 不再提供独立 payout 保存 | + +## 3. 接口详情 + +### 3.1 PUT Step3 人员费用保存 + +- **使用场景**: 核单中保存人员费用，并同步保存辅助人员结算状态。 +- **认证**: 管理后台 JWT。 +- **幂等性**: 非幂等；每次按 `items` 全量替换 Step3 人员费用行。 +- **路径**: `PUT /v3/admin/order/{orderId}/settlement/step3` + +#### 路径参数 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| orderId | Long/String | 是 | 订单 ID，雪花 ID 建议前端按字符串传递 | + +#### 请求体 + +| 字段 | 类型 | 必填 | 说明 | 校验规则 | +|------|------|------|------|----------| +| items | Array | 是 | 人员费用明细数组，全量替换 | 不可为 null | + +#### StaffFeeItem 字段 + +| 字段 | 类型 | 必填 | 说明 | 校验规则 | +|------|------|------|------|----------| +| id | Long/String | 否 | 已存在行 ID；为空表示新增行 | 雪花 ID 建议字符串传递 | +| staffRole | String | 是 | 人员角色 | `LEADER` / `DRIVER` / `GUIDE` / `PHOTOGRAPHER` / `OTHER` | +| staffId | Long/String | 否 | 人员派单 ID | 雪花 ID 建议字符串传递 | +| detail | Object | 是 | 按角色派生的费用明细结构 | 不可为 null | +| reimburse | Decimal | 否 | 小额报销金额 | 不传按 0 处理；传值需大于等于 0 | +| settleStatus | String | 否 | 辅助人员结算状态；主报账人行会忽略该字段 | `PENDING` / `COMPLETED` | +| settledDate | String | 否 | 辅助人员结算日期 | `yyyy-MM-dd` | +| transferRef | String | 条件必填 | 辅助人员结算转账流水号 | `settleStatus=COMPLETED` 时必填；最长 128 字符 | +| remark | String | 否 | 备注 | 最长 500 字符 | + +#### 响应字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| addedIds | Array | 新增行 ID 列表 | +| updatedIds | Array | 更新行 ID 列表 | +| deletedIds | Array | 本次全量替换删除的历史行 ID 列表 | +| totalActualCost | String/Decimal | 人员费用实际成本合计 | +| items | Array | 保存后的人员费用明细 | + +#### StaffFeeRespItem 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String | 行 ID | +| staffRole | String | 人员角色 | +| staffId | String/null | 人员派单 ID | +| staffName | String/null | 人员姓名快照 | +| totalPlannedCost | String/Decimal | 计划成本 | +| totalActualCost | String/Decimal | 实际成本 | +| detail | Object | 按角色派生的费用明细结构 | +| reimburse | String/Decimal | 小额报销金额 | +| settleStatus | String/null | 辅助人员结算状态；主报账人行为空 | +| settledDate | String/null | 辅助人员结算日期 | +| transferRef | String/null | 辅助人员结算转账流水号 | +| isPrimaryReporter | Boolean | 是否主报账人 | +| remark | String/null | 备注 | + +### 3.2 已删除 GET payout + +- **删除接口**: `GET /v3/admin/order/{orderId}/settlement/payout` +- **替代方式**: 使用 Step3 人员费用响应 `items[]` 中的 `settleStatus`、`settledDate`、`transferRef` 字段展示辅助人员结算状态。 + +### 3.3 已删除 PUT payout + +- **删除接口**: `PUT /v3/admin/order/{orderId}/settlement/payout` +- **替代方式**: 调用 `PUT /v3/admin/order/{orderId}/settlement/step3`，在对应 `items[]` 行内提交 `settleStatus`、`settledDate`、`transferRef`。 + +## 4. 入参 + +本变更的有效入参集中在 `PUT /v3/admin/order/{orderId}/settlement/step3`。旧 payout 入参整体删除。 + +### 4.1 新增字段 + +| 字段 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| settleStatus | `items[]` | String | 否 | 辅助人员结算状态；主报账人行忽略 | +| settledDate | `items[]` | String | 否 | 结算日期，格式 `yyyy-MM-dd` | +| transferRef | `items[]` | String | 条件必填 | `settleStatus=COMPLETED` 时必填 | + +### 4.2 删除的旧入参 + +| 旧接口 | 字段 | 处理方式 | +|--------|------|----------| +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].staffId` | 改为 Step3 `items[].staffId` | +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].staffRole` | 改为 Step3 `items[].staffRole` | +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].staffName` | 不再作为保存入参 | +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].settleStatus` | 改为 Step3 `items[].settleStatus` | +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].settledDate` | 改为 Step3 `items[].settledDate` | +| `PUT /v3/admin/order/{orderId}/settlement/payout` | `items[].transferRef` | 改为 Step3 `items[].transferRef` | + +## 5. 出参 + +### 5.1 Step3 响应新增字段 + +| 字段 | 位置 | 类型 | 说明 | +|------|------|------|------| +| settleStatus | `data.items[]` | String/null | 辅助人员结算状态；主报账人行为空 | +| settledDate | `data.items[]` | String/null | 辅助人员结算日期 | +| transferRef | `data.items[]` | String/null | 辅助人员结算转账流水号 | + +### 5.2 删除的旧出参 + +| 旧接口 | 字段 | 处理方式 | +|--------|------|----------| +| `GET /v3/admin/order/{orderId}/settlement/payout` | `staffId` | 从 Step3 `data.items[].staffId` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `staffName` | 从 Step3 `data.items[].staffName` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `staffRole` | 从 Step3 `data.items[].staffRole` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `laborCost` | 不再独立返回；人员费用成本看 Step3 `totalActualCost` / 明细 `detail` | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `reimburse` | 从 Step3 `data.items[].reimburse` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `dueAmount` | 不再独立返回；如需展示由前端按 Step3 行数据计算 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `settleStatus` | 从 Step3 `data.items[].settleStatus` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `settledDate` | 从 Step3 `data.items[].settledDate` 读取 | +| `GET /v3/admin/order/{orderId}/settlement/payout` | `transferRef` | 从 Step3 `data.items[].transferRef` 读取 | + +## 6. 枚举 / 数据字典 + +### 6.1 settleStatus + +**所属字段**: `items[].settleStatus` / `data.items[].settleStatus` | **类型**: String | **必填**: 否，`COMPLETED` 时需配合 `transferRef` + +| 值 | 中文 | 说明 | +|----|------|------| +| `PENDING` | 待结算 | 辅助人员尚未完成转账 | +| `COMPLETED` | 已结算 | 辅助人员已完成转账，必须填写 `transferRef` | + +### 6.2 staffRole + +**所属字段**: `items[].staffRole` / `data.items[].staffRole` | **类型**: String | **必填**: 是 + +| 值 | 中文 | 说明 | +|----|------|------| +| `LEADER` | 地接 | 地接人员费用 | +| `DRIVER` | 司机 | 司机人员费用 | +| `GUIDE` | 导游 | 导游人员费用 | +| `PHOTOGRAPHER` | 摄影师 | 摄影师人员费用 | +| `OTHER` | 其他 | 其他人员费用 | + +## 7. 错误码 + +| code | 含义 | 触发场景 | +|------|------|----------| +| 400 | 参数校验失败 | `settleStatus` 不在 `PENDING/COMPLETED` 内，或字段类型不合法 | +| 584038 | 结算状态为 COMPLETED 时转账流水号不能为空 | Step3 行 `settleStatus=COMPLETED` 且 `transferRef` 为空 | +| 584039 | 结算状态非法，必须是 PENDING 或 COMPLETED | Step3 保存时传入非法结算状态 | + +## 8. 示例 + +### 8.1 典型成功：Step3 保存辅助人员结算状态 + +**请求** + +```http +PUT /v3/admin/order/2075415561948315650/settlement/step3 +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "id": "2076000000000000001", + "staffRole": "GUIDE", + "staffId": "2075000000000000001", + "detail": { + "persons": [ + { + "name": "张三", + "days": [ + { + "date": "2026-07-10", + "is_used": true + } + ], + "per_day": 300 + } + ] + }, + "reimburse": 50, + "settleStatus": "COMPLETED", + "settledDate": "2026-07-10", + "transferRef": "TR202607100001", + "remark": "导游费用已转账" + } + ] +} +``` + +**响应** + +```json +{ + "code": 200, + "data": { + "addedIds": [], + "updatedIds": ["2076000000000000001"], + "deletedIds": [], + "totalActualCost": "350.00", + "items": [ + { + "id": "2076000000000000001", + "staffRole": "GUIDE", + "staffId": "2075000000000000001", + "staffName": "张三", + "totalPlannedCost": "300.00", + "totalActualCost": "350.00", + "detail": { + "persons": [ + { + "name": "张三", + "days": [ + { + "date": "2026-07-10", + "is_used": true + } + ], + "per_day": 300 + } + ] + }, + "reimburse": "50.00", + "settleStatus": "COMPLETED", + "settledDate": "2026-07-10", + "transferRef": "TR202607100001", + "isPrimaryReporter": false, + "remark": "导游费用已转账" + } + ] + }, + "msg": "success" +} +``` + +### 8.2 边界：待结算可不传转账流水号 + +**请求** + +```http +PUT /v3/admin/order/2075415561948315650/settlement/step3 +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "staffRole": "DRIVER", + "staffId": "2075000000000000002", + "detail": { + "days": [ + { + "service_date": "2026-07-10", + "daily_fee": 500, + "is_used": true + } + ], + "extra_cost": 0 + }, + "reimburse": 0, + "settleStatus": "PENDING", + "settledDate": null, + "transferRef": null + } + ] +} +``` + +**响应** + +```json +{ + "code": 200, + "data": { + "addedIds": ["2076000000000000002"], + "updatedIds": [], + "deletedIds": [], + "totalActualCost": "500.00", + "items": [ + { + "id": "2076000000000000002", + "staffRole": "DRIVER", + "staffId": "2075000000000000002", + "staffName": "李四", + "totalPlannedCost": "500.00", + "totalActualCost": "500.00", + "detail": { + "days": [ + { + "service_date": "2026-07-10", + "daily_fee": 500, + "is_used": true + } + ], + "extra_cost": 0 + }, + "reimburse": "0.00", + "settleStatus": "PENDING", + "settledDate": null, + "transferRef": null, + "isPrimaryReporter": false, + "remark": null + } + ] + }, + "msg": "success" +} +``` + +### 8.3 异常：已结算但未传 transferRef + +**请求** + +```http +PUT /v3/admin/order/2075415561948315650/settlement/step3 +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "staffRole": "GUIDE", + "staffId": "2075000000000000001", + "detail": { + "persons": [] + }, + "settleStatus": "COMPLETED", + "settledDate": "2026-07-10", + "transferRef": "" + } + ] +} +``` + +**响应** + +```json +{ + "code": 584038, + "data": null, + "msg": "结算状态为 COMPLETED 时转账流水号不能为空" +} +``` + +## 9. 业务边界 + +- 仅影响管理后台核单流程。 +- `settleStatus` / `settledDate` / `transferRef` 只用于辅助人员结算；主报账人行的 `settleStatus` 在响应中为空，提交时可不传。 +- `settleStatus=COMPLETED` 时 `transferRef` 必填。 +- 旧 payout 两个接口删除后，前端不能再依赖独立“小算拨款”接口加载或保存。 +- Step3 保存仍是全量替换语义，前端保存时需要提交完整 `items` 列表，不能只提交单行结算状态。 + +## 10. 修改前后对比 + +### 10.1 字段级对比 + +| 字段 | 修改前 | 修改后 | +|------|--------|--------| +| Step3 `items[].settleStatus` | 无 | 新增，保存辅助人员结算状态 | +| Step3 `items[].settledDate` | 无 | 新增，保存辅助人员结算日期 | +| Step3 `items[].transferRef` | 无 | 新增，保存辅助人员结算转账流水号 | +| Step3 `data.items[].settleStatus` | 无 | 新增，返回辅助人员结算状态 | +| Step3 `data.items[].settledDate` | 无 | 新增，返回辅助人员结算日期 | +| Step3 `data.items[].transferRef` | 无 | 新增，返回辅助人员结算转账流水号 | + +### 10.2 行为级对比 + +| 行为 | 修改前 | 修改后 | +|------|--------|--------| +| 查询小算拨款 | 调 `GET /settlement/payout` | 从 Step3 响应 `data.items[]` 读取 | +| 保存小算拨款 | 调 `PUT /settlement/payout` | 调 `PUT /settlement/step3`，在人员费用行内提交 | +| 已结算流水号校验 | payout 接口校验 | Step3 接口校验 | + +## 11. 影响评估 / 回滚 + +### 11.1 影响评估 + +- **是否破坏向后兼容**: 是。旧 `GET/PUT /settlement/payout` 删除，继续调用会失败。 +- **前端是否必须同步上线**: 是。前端需要移除 payout 查询/保存调用，并把小算拨款字段并入 Step3 人员费用行。 + +### 11.2 回滚方案 + +- 如需回滚，需要恢复旧 `GET/PUT /settlement/payout` 契约，并让前端重新按旧接口查询/保存小算拨款。 + +## 12. 注意事项 + +- 前端需要清理 `getSettlementPayout` / `saveSettlementPayout` 相关调用。 +- 前端保存 Step3 时请求体必须是 `{ "items": [...] }`，不是裸数组。 +- 前端如果仍保留“小算拨款”独立步骤，也必须从 Step3 `items[]` 取数和回写，不能再请求 payout 接口。 +- `settleStatus=COMPLETED` 时必须带 `transferRef`，否则返回 `584038`。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#4869](https://git.1814.love:8443/wx/HL/issues/4869) +- **PR**: [#4870](https://git.1814.love:8443/wx/HL/pulls/4870) +- **Merge commit**: [6d99b982a](https://git.1814.love:8443/wx/HL/commit/6d99b982a7bf8f5bacc52afb3de07bf5ed533f0a) +- **前置通知**: [#4768 核单对账 payout 新增接口](https://git.1814.love:8443/wx/hl-api-changelog/src/branch/main/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md) + +### 13.2 联系人 + +- **后端负责人**: @腰苏图