补充核单Step3合并辅助结算变更通知

2026-07-10 16:18:35 +08:00 · 2026-07-10 16:18:35 +08:00 · 5aad9d2ed3
--- a/changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md
+++ 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<StaffFeeItem> | 是 | 人员费用明细数组，全量替换 | 不可为 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<String> | 新增行 ID 列表 |
+| updatedIds | Array<String> | 更新行 ID 列表 |
+| deletedIds | Array<String> | 本次全量替换删除的历史行 ID 列表 |
+| totalActualCost | String/Decimal | 人员费用实际成本合计 |
+| items | Array<StaffFeeRespItem> | 保存后的人员费用明细 |
+
+#### 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 <token>
+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 <token>
+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 <token>
+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 联系人
+
+- **后端负责人**: @腰苏图