wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-07/09_4869_核单Step3合并辅助结算-修改接口-管理后台.md

15 KiB
原始文件 Blame 文件历史

【修改接口·管理后台】核单 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 保存辅助人员结算状态

请求

PUT /v3/admin/order/2075415561948315650/settlement/step3
Authorization: Bearer <token>
Content-Type: application/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": "导游费用已转账"
    }
  ]
}

响应

{
  "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 边界：待结算可不传转账流水号

请求

PUT /v3/admin/order/2075415561948315650/settlement/step3
Authorization: Bearer <token>
Content-Type: application/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
    }
  ]
}

响应

{
  "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

请求

PUT /v3/admin/order/2075415561948315650/settlement/step3
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    {
      "staffRole": "GUIDE",
      "staffId": "2075000000000000001",
      "detail": {
        "persons": []
      },
      "settleStatus": "COMPLETED",
      "settledDate": "2026-07-10",
      "transferRef": ""
    }
  ]
}

响应

{
  "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 链接

13.2 联系人

  • 后端负责人: @腰苏图