From 83cbc282aad434c8fdb70fe3588958041ddce3ea Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 7 Jul 2026 17:59:33 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A8=E9=80=81=204=20=E6=9D=A1=E6=A0=B8?= =?UTF-8?q?=E5=8D=95=E4=BE=A7=E6=94=B9=E9=80=A0=E6=8E=A5=E5=8F=A3=E5=8F=98?= =?UTF-8?q?=E6=9B=B4=20changelog=EF=BC=88PR1=20=E7=BA=BF=E4=B8=8B=E6=94=B6?= =?UTF-8?q?=E6=AC=BE=20/=20PR2=20=E5=AD=90=E8=A1=A8=E6=89=A9=E5=88=97=20/?= =?UTF-8?q?=20PR3=20recon+payout=20/=20PR5=20submit=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../07_4763_线下收款登记-新增接口-管理后台.md | 193 +++++++++++++++ .../07_4764_核单子表扩列-修改接口-管理后台.md | 228 ++++++++++++++++++ ...7_4768_核单对账payout-新增接口-管理后台.md | 213 ++++++++++++++++ ...7_4780_核单submit收口-修改接口-管理后台.md | 173 +++++++++++++ 4 files changed, 807 insertions(+) create mode 100644 changelogs-v2/2026-07/07_4763_线下收款登记-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-07/07_4764_核单子表扩列-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-07/07_4780_核单submit收口-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/07_4763_线下收款登记-新增接口-管理后台.md b/changelogs-v2/2026-07/07_4763_线下收款登记-新增接口-管理后台.md new file mode 100644 index 0000000..ba5c6c6 --- /dev/null +++ b/changelogs-v2/2026-07/07_4763_线下收款登记-新增接口-管理后台.md @@ -0,0 +1,193 @@ +# 线下收款登记（司机现场代收人 / 对公转账） +- **变更日期**: 2026-07-07 +- **端类型**: 管理后台 +- **变更类型**: 新增接口 +- **Issue**: https://git.1814.love:8443/wx/HL/issues/4763 +- **PR**: https://git.1814.love:8443/wx/HL/pulls/4766 + +--- +## 1. 接口背景 + +核单 epic PR1。核单流程中，定制师需要记录非微信支付渠道的线下收款（司机现场代收人现金、对公转账），并确保订单 `paid_amount` 实时更新。 +登记成功后事务层推进 `paid_amount` 累加并重算 `pay_status`(PARTIAL_PAID/FULLY_PAID)。 +已撤销的凭据行保留在列表供审计溯源。 + +--- +## 2. 变更清单 + +| 序号 | 方法 | 路径 | 说明 | +|------|------|------|------| +| 1 | POST | `/v3/admin/order/{orderId}/payment/manual-receipt` | 登记线下收款 | +| 2 | DELETE | `/v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}` | 撤销线下收款（转删，行保留） | +| 3 | GET | `/v3/admin/order/{orderId}/payment/manual-receipt` | 查询订单线下收款列表 | + +--- +## 3. 接口详情 + +| 项 | 说明 | +|-----|------| +| 认证 | JWT Bearer(管理端), Gateway 注入 X-Admin-Id/X-Admin-RealName | +| 幂等性 | POST 非幂等; DELETE 幂等守卫（已撤销返 520406） | +| 限流 | 网关全局限流 | +| 订单状态白名单 | 仅 CANCELLED 拒绝，其余状态（含已结算）均可登记 | + +--- +## 4. 接口入参 + +### 4.1 路径参数（三个接口通用） +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| orderId | Long | 是 | 订单 ID | + +DELETE 额外路径参数: receiptId (Long, 必, 凭据 ID 由 POST 响应获取) + +### 4.2 请求体(POST) +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| channel | String | 是 | 收款渠道: DRIVER_CASH/BANK_TRANSFER | +| payType | String | 是 | 款项类型: DEPOSIT/BALANCE/FULL | +| amount | BigDecimal | 是 | >0 | +| receivedAt | LocalDateTime | 否 | 可补录历史，不传默认当前 | +| transferRef | String | 条件必填 | `BANK_TRANSFER`时必填 | +| collectorStaffId | Long | 条件必填 | `DRIVER_CASH`时必填且属本订单人员 | +| voucherUrls | List | 否 | 凭证图片 URL | +| remark | String | 否 | 备注, max 500 | + +**DELETE 请求体**: voidReason (String, 否, 撤销原因) +--- +## 5. 出参字段 + +POST/DELETE 返回单条 `ManualReceiptVO`，GET 返回 `List`。 +> `paidAmountAfter`/`payStatusAfter` 仅在 POST/DELETE 响应有値，GET 列表为 null。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String(Long) | 凭据 ID(雪花序列化） | +| orderId | String(Long) | 订单 ID | +| channel | String | DRIVER_CASH/BANK_TRANSFER | +| channelLabel | String | 渠道显示标签 | +| payType | String | DEPOSIT/BALANCE/FULL | +| payTypeLabel | String | 款项显示标签 | +| amount | BigDecimal | 收款金额 | +| receivedAt | LocalDateTime | 收款时间 | +| collectorStaffId | String(Long) | 代收人 assignmentId, 仅 DRIVER_CASH 有値 | +| collectorStaffName | String | 代收人姓名, 仅 DRIVER_CASH 有値 | +| transferRef | String | 流水号, 仅 BANK_TRANSFER 有値 | +| voucherUrls | List | 凭证图片 URL | +| remark | String | 备注 | +| operatorName | String | 登记人姓名 | +| createTime | LocalDateTime | 登记时间 | +| voided | Boolean | 是否已撤销 | +| voidedByName/voidedAt/voidReason | - | 撤销时有値 | +| paidAmountAfter | BigDecimal | 操作后订单累计已付金额, GET 为 null | +| payStatusAfter | String | 操作后订单支付状态, GET 为 null | + +--- +## 6. 枚举/数据字典 + +**channel:** DRIVER_CASH(司机现场代收人) / BANK_TRANSFER(对公转账) + +**payType:** DEPOSIT(订金) / BALANCE(尾款) / FULL(全款) + +**payStatusAfter:** UNPAID(未付款) / PARTIAL_PAID(已付订金) / FULLY_PAID(已付全款) +--- +## 7. 错误码 + +| 错误码 | 含义 | 触发场景 | +|--------|------|---------| +| 520401 | 收款渠道非法 | channel not DRIVER_CASH/BANK_TRANSFER | +| 520402 | 对公转账必填转账流水号 | channel=BANK_TRANSFER & transferRef 为空 | +| 520403 | 必须指定代收人 | channel=DRIVER_CASH & collectorStaffId 为空 | +| 520404 | 代收人不属本订单人员 | collectorStaffId 不在order_staff_assignment中 | +| 520405 | 凭据不存在 | receiptId 非法 | +| 520406 | 已撤销，无法重复 | 对已撤销行再 DELETE | +| 520407 | 订单已取消，不允许登记 | 订单状态为 CANCELLED | +| 520408 | 收款金额必须>0 | amount<=0 | + +--- +## 8. 示例 + +### 8.1 典型成功 -- 登记司机现场代收人尾款 + +请求: +```http +POST /v3/admin/order/1234567890123456/payment/manual-receipt +Content-Type: application/json +X-Admin-RealName: 扎西师傅 + +{ + "channel": "DRIVER_CASH", + "payType": "BALANCE", + "amount": 8800.00, + "collectorStaffId": "9800001001", + "remark": "客户现场支付尾款" +} +``` + +响应: +```json +{ + "code": 200, + "data": { + "id": "1900000001000001", + "channelLabel": "司机现场代收人", + "payTypeLabel": "尾款", + "amount": 8800.00, + "collectorStaffName": "扎西师傅", + "voided": false, + "paidAmountAfter": 24800.00, + "payStatusAfter": "FULLY_PAID" + } +} +``` + +### 8.2 边界 -- 对公转账，补录历史时间 +```json +{ + "channel": "BANK_TRANSFER", + "payType": "DEPOSIT", + "amount": 5000.00, + "receivedAt": "2026-06-20T10:00:00", + "transferRef": "GZL20260620001" +} +``` +返回: paidAmountAfter 为当前累计已付金额。 + +### 8.3 业务失败 -- DRIVER_CASH 未指定代收人 +```json +{ + "channel": "DRIVER_CASH", + "amount": 3000.00 +} +``` +```json +{ + "code": 520403, + "msg": "司机现场必须指定代收人" +} +``` + +--- +## 9. 业务边界 + +**适用:** 客户现金付款 / 对公转账补录 +**不适用:** 微信支付/支付宝 / 订单已取消 +**特殊边界:** +- 同一订单可登记多条，每条独立计入`paid_amount` +- 撤销后`paid_amount`同事务回退，行记录保留 +- paidAmountAfter/payStatusAfter 仅在 POST/DELETE 响应, GET 列表为 null + +--- +## 12. 注意事项 + +- id/orderId 均为 Long 雪花，序列化为字符串，前端禁 Number +- collectorStaffId 属于本订单人员配置(order_staff_assignment)中选取 +- 登记后在核单对账页查看`paid_amount`，需重请 GET /v3/admin/order/{orderId}/settlement/recon + +--- +## 13. 关联/联系人 + +- Issue: https://git.1814.love:8443/wx/HL/issues/4763 +- PR: https://git.1814.love:8443/wx/HL/pulls/4766 +- Commit: https://git.1814.love:8443/wx/HL/commit/076bd285a5cc87665fdf431f9fe0a704dcdd7a33 +- 后端负责人: 腰苏图 \ No newline at end of file diff --git a/changelogs-v2/2026-07/07_4764_核单子表扩列-修改接口-管理后台.md b/changelogs-v2/2026-07/07_4764_核单子表扩列-修改接口-管理后台.md new file mode 100644 index 0000000..d6b55e7 --- /dev/null +++ b/changelogs-v2/2026-07/07_4764_核单子表扩列-修改接口-管理后台.md @@ -0,0 +1,228 @@ +# 核单子表扩列 +- **变更日期**: 2026-07-07 +- **端类型**: 管理后台 +- **变更类型**: 修改接口 +- **Issue**: https://git.1814.love:8443/wx/HL/issues/4764 +- **PR**: https://git.1814.love:8443/wx/HL/pulls/4767 + +--- +## 1. 接口背景 + +核单 epic PR2。核单三个子表（车席、馨票、人员费用）分别扩充字段，具体： +- 车席 Step 1: `HotelItemVO` 新增 `voucherUrls`（住宿凭证图片） +- 馨票 Step 2: `TicketItemVO` 新增 `paymentMethod` / `voucherUrls`；`scenicAssignmentId` 由可空改必填（❗ 破坏兆容） +- 人员费用 Step 3: `StaffFeeItemVO` 新增 `reimburse`；`SettlementStaffFeesSaveRespVO` 新增 `isPrimaryReporter` / `reimburse` + +--- +## 2. 变更清单 + +| 序号 | 方法 | 路径 | 说明 | +|------|------|------|------| +| 1 | GET | `/v3/admin/order/{orderId}/settlement/step1` | Step 1 查询，`HotelItemVO` +`voucherUrls` | +| 2 | PUT | `/v3/admin/order/{orderId}/settlement/step1` | Step 1 保存，入参`HotelItemVO` +`voucherUrls` | +| 3 | GET | `/v3/admin/order/{orderId}/settlement/step2` | Step 2 查询，`TicketItemVO` +`paymentMethod`/`voucherUrls`; `scenicAssignmentId` 由可空改必填 | +| 4 | PUT | `/v3/admin/order/{orderId}/settlement/step2` | Step 2 保存，同上 | +| 5 | GET | `/v3/admin/order/{orderId}/settlement/step3` | Step 3 查询，响应 +`isPrimaryReporter`/`reimburse` | +| 6 | PUT | `/v3/admin/order/{orderId}/settlement/step3` | Step 3 保存，入参 +`reimburse` | +--- +## 3. 接口详情 + +| 项 | 说明 | +|-----|------| +| 认证 | JWT Bearer(管理端) | +| 幂等性 | PUT 非幂等（每次全量覆写子表） | +| 核单状态 | 仅允许在 settlement_status=IN_PROGRESS 时调用 | + +--- +## 4. 接口入参 + +### 4.1 路径参数（六个接口通用） +| orderId | Long | 是 | 订单 ID | + +### 4.2 Step 1 PUT 请求体（`List`） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| id | Long | 否 | 空表新建行 | +| hotelAssignmentId | Long | 否 | 酒店配置 ID | +| stayDate | LocalDate | 是 | 入住日期 | +| roomType | String | 否 | 房间类型 | +| roomCount | Integer | 是 | 房间数量 | +| plannedCost | BigDecimal | 否 | 计划成本 | +| actualCost | BigDecimal | 否 | 实际成本 | +| paymentMethod | String | 否 | SIGNED/COMPANY_PAID/CASH_PAID | +| settleType | String | 否 | 派生行类型：cash/sign/company | +| remark | String | 否 | 备注 | +| **voucherUrls** | List | 否 | **✨ 新增）: 住宿凭证图片 URL | + +### 4.3 Step 2 PUT 请求体（`List`） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| sourceType | String | 是 | SCENIC_ASSIGNMENT/ACTIVITY_ASSIGNMENT | +| **scenicAssignmentId** | Long | **是** | **❗ 破坏兆容：旧可空，新必填** | +| dayDate | LocalDate | 是 | 游玩日期 | +| ticketCount | Integer | 是 | 馨票人数 | +| ticketUnitPrice | BigDecimal | 否 | 单价 | +| actualCost | BigDecimal | 否 | 实际成本 | +| **paymentMethod** | String | 否 | **✨ 新增**: SIGNED/COMPANY_PAID/CASH_PAID | +| **voucherUrls** | List | 否 | **✨ 新增**: 馨票凭证图片 URL | +| remark | String | 否 | 备注 | + +### 4.4 Step 3 PUT 请求体（`List`） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| id | Long | 否 | 实体主键 | +| staffRole | String | 是 | LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER | +| staffId | Long | 否 | 人员 ID | +| detail | Object | 否 | 按角色不同, 见 §6 | +| **reimburse** | BigDecimal | 否 | **✨ 新增**: 小算补助金额，⊰ 0 | +| remark | String | 否 | 备注 | +--- +## 5. 出参字段 + +### Step 1 GET 响应（`List`） +> 新增 **`voucherUrls`** (List) + +### Step 2 GET 响应（`List`） +> 新增 **`paymentMethod`** (String) / **`voucherUrls`** (List) + +### Step 3 GET 响应（`SettlementStaffFeesSaveRespVO`） + +`StaffFeeRespItemVO` 内嵌子字段: +| 字段 | 类型 | 说明 | +|------|------|------| +| **isPrimaryReporter** | Boolean | **✨ 新增**: 是否主报账人，由 AssignmentService 实时派生 | +| **reimburse** | BigDecimal | **✨ 新增**: 小算补助金额，入参回显 | + +--- +## 6. 枚举/数据字典 + +**paymentMethod / settleType** +| 値 | 含义 | +|------|------| +| SIGNED | 签单结算（酒店收取相应金额） | +| COMPANY_PAID | 公司已付（公库打款） | +| CASH_PAID | 现付（司机墙付） | + +**staffRole** +| 値 | 含义 | +|------|------| +| LEADER | 地接 | +| DRIVER | 司机 | +| GUIDE | 导游 | +| PHOTOGRAPHER | 摄影师 | +| OTHER | 其他 | + +**detail 结构（按角色）** +- DRIVER: `{is_used, daily_fee, extra_cost, days[{date,is_used}]}` +- GUIDE/PHOTOGRAPHER: `{persons[{staffId,days[{date,is_used}]}], per_day}` +- LEADER: `{days, per_day}` +- OTHER: `[{name, amount}]` + +--- +## 7. 错误码 + +| 错误码 | 含义 | 触发场景 | +|--------|------|---------| +| 584028 | ❗ 破坏兆容 -- 馨票行必须关联资源配置 | Step 2 PUT 中 scenicAssignmentId 为空（曾可空，现必填） | +| 584001-584009 | Step 1 酒店校验错 | - | +| 584010-584018 | Step 2 馨票校验错 | - | +| 584020-584027 | Step 3 人员费用校验错 | - | + +--- +## 8. 示例 + +### 8.1 典型成功 -- Step 2 PUT （`scenicAssignmentId`必填） + +```http +PUT /v3/admin/order/1234567890123456/settlement/step2 +Content-Type: application/json + +[{ + "sourceType": "SCENIC_ASSIGNMENT", + "scenicAssignmentId": 98001, + "dayDate": "2026-07-10", + "ticketCount": 4, + "actualCost": 1200.00, + "paymentMethod": "CASH_PAID", + "voucherUrls": ["https://oss.example.com/ticket.jpg"] +}] +``` + +响应: 200 OK + +### 8.2 边界 -- Step 3 GET （`isPrimaryReporter` = true） +```json +{ + "code": 200, + "data": { + "items": [{ + "staffRole": "DRIVER", + "isPrimaryReporter": true, + "reimburse": 500.00 + }] + } +} +``` + +### 8.3 业务失败 -- scenicAssignmentId 为空触发 584028 +```json +[{ + "sourceType": "SCENIC_ASSIGNMENT", + "scenicAssignmentId": null, + "dayDate": "2026-07-10" +}] +``` +```json +{ + "code": 584028, + "msg": "馨票行必须关联资源配置（现必填，曾可空）" +} +``` +--- +## 9. 业务边界 + +适用: 核单流程中内 (settlement_status=IN_PROGRESS) +不适用: 已提交或已结算 +特殊边界: +- Step 1 `voucherUrls`: 不传默空列表，传空删除已传的凭证 +- Step 2 scenicAssignmentId: 必填，不再允许自由录入 (破坏兆容！) +- Step 3 isPrimaryReporter: 实时派生，前端只读 + +--- +## 10. 修改前后对比 + +### Step 2 `TicketItemVO` 字段变化 +| 字段 | 修改前 | 修改后 | +|------|------|------| +| scenicAssignmentId | 可空 | 必填 （❗破坏兆容） | +| paymentMethod | 无 | 新增 String | +| voucherUrls | 无 | 新增 List | + +### Step 3 `StaffFeeRespItemVO` 字段变化 +| 字段 | 修改前 | 修改后 | +|------|------|------| +| isPrimaryReporter | 无 | 新增 Boolean | +| reimburse | 无 | 新增 BigDecimal | + +--- +## 11. 影响评估/回滚 + +破坏兆容: scenicAssignmentId 旧可空, 新必填。前端补充 scenicAssignmentId字段后提交。 +回滚: 无需回滚，此为小版本内造数据制约。 + +--- +## 12. 注意事项 + +- scenicAssignmentId 必填是 **破坏兆容变更** +- isPrimaryReporter 实时计算，前端只读 + +--- +## 13. 关联/联系人 + +- Issue: https://git.1814.love:8443/wx/HL/issues/4764 +- PR: https://git.1814.love:8443/wx/HL/pulls/4767 +- Commit: https://git.1814.love:8443/wx/HL/commit/3fdb51f5aac7ee6bee58f8e9ab125d82859eaffd +- 后端负责人: 腰苏图 \ No newline at end of file diff --git a/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md b/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md new file mode 100644 index 0000000..c21c5ba --- /dev/null +++ b/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md @@ -0,0 +1,213 @@ +# 核单对账(recon)+小算抨款(payout) 新增接口 +- **变更日期**: 2026-07-07 +- **端类型**: 管理后台 +- **变更类型**: 新增接口 +- **Issue**: https://git.1814.love:8443/wx/HL/issues/4768 +- **PR**: https://git.1814.love:8443/wx/HL/pulls/4770 + +--- +## 1. 接口背景 + +核单 epic PR3。在核单单子表喅录完毕后，定制师需要进行两项补充： +1. **recon** (对账): 录入市属司机代收尾款信息、转账信息、预支冲抵确认、签字单回收 +2. **payout** (小算抨款): 查看干系人员应收金额，并确认转账状态 + +recon 派生字段说明: +- 入参字段（数据库存储）: customerCashToDriver / customerCashCollectedFlag / otherCollect / transferStatus / transferDate / transferRef / advanceSettledFlag / signedVoucher +- 派生字段（实时派生）: driverCollected / publicPrepaid / primaryDue / advanceOutstanding / reconNet +- 公式: reconNet = driverCollected - publicPrepaid - primaryDue - advanceOutstanding + +--- +## 2. 变更清单 + +| 序号 | 方法 | 路径 | 说明 | +|------|------|------|------| +| 1 | GET | `/v3/admin/order/{orderId}/settlement/recon` | 核单对账查询 | +| 2 | PUT | `/v3/admin/order/{orderId}/settlement/recon` | 核单对账保存 | +| 3 | GET | `/v3/admin/order/{orderId}/settlement/payout` | 小算抨款列表查询 | +| 4 | PUT | `/v3/admin/order/{orderId}/settlement/payout` | 小算抨款状态更新 | + +--- +## 3. 接口详情 + +| 项 | 说明 | +|-----|------| +| 认证 | JWT Bearer(管理端) | +| 幂等性 | PUT recon: upsert(同一 orderId 却覆）。 PUT payout: 幂等守卫（匹配需授权人员） | +| HEDAN状态 | settlement_status=IN_PROGRESS 时可调用 | +--- +## 4. 接口入参 + +### 4.1 路径参数（四个接口通用） +| orderId | Long | 是 | 订单 ID | + +### 4.2 PUT recon 请求体（`SettlementReconSaveReqVO`） + +全部字段可空, null=保持现有値 (upsert 语义): + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| customerCashToDriver | BigDecimal | 否 | 司机代收尾款 (null=累加 DRIVER_CASH) | +| customerCashCollectedFlag | Boolean | 否 | 尾款是否已收 | +| otherCollect | List | 否 | 其他代收项 | +| transferStatus | String | 否 | PENDING/COMPLETED | +| transferDate | LocalDate | 否 | 转账日期 | +| transferRef | String | 条件 | transferStatus=COMPLETED 时必填 | +| advanceSettledFlag | Boolean | 否 | 预支确认冲扣 | +| signedVoucher | SignedVoucherVO | 否 | 签字单回收，详见 4.2.1 | + +#### 4.2.1 OtherCollectItemVO +| name | String | 项目名称 | +| amount | BigDecimal | 金额 | +| collectedFlag | Boolean | 是否已收 | + +#### 4.2.2 SignedVoucherVO +| files | List | 签字单文件列表 | +| note | String | 备注 | +FileItem: { name(文件名), url(OSS 地址) } + +### 4.3 PUT payout 请求体（`SettlementPayoutSaveReqVO`） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| items | List | 是 | 抨款列表 | + +Item 字段: +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| staffId | Long | 否 | 人员 ID | +| staffRole | String | 是 | LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER | +| staffName | String | 是 | 展示性 | +| settleStatus | String | 是 | PENDING/COMPLETED | +| settledDate | LocalDate | 否 | 收款日期 | +| transferRef | String | 否 | 转账流水号 | +--- +## 5. 出参字段 + +### GET recon 响应（`SettlementReconRespVO`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| customerCashToDriver | BigDecimal | 司机代收尾款 | +| customerCashCollectedFlag | Boolean | 尾款是否已收 | +| otherCollect | List | 其他代收 | +| transferStatus | String | 转账状态 PENDING/COMPLETED | +| transferDate | LocalDate | 转账日期 | +| transferRef | String | 转账流水号 | +| advanceSettledFlag | Boolean | 预支冲扣确认 | +| signedVoucher | SignedVoucherVO | 签字单回收 | +| primaryName | String | 主报账人姓名，实时派生 | +| primaryRole | String | 主报账人角色，实时派生 | +| driverCollected | BigDecimal | 司机实际代收 = customerCashToDriver + Σ DRIVER_CASH | +| publicPrepaid | BigDecimal | 公库预付 | +| primaryDue | BigDecimal | 主报账人应付 | +| advanceOutstanding | BigDecimal | 预支未充 | +| reconNet | BigDecimal | **对账夹算** = driverCollected - publicPrepaid - primaryDue - advanceOutstanding | + +### GET payout 响应（`List`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| staffId | Long | 人员 ID | +| staffName | String | 姓名 | +| staffRole | String | 角色： LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER | +| laborCost | BigDecimal | 工资/劳务费 | +| reimburse | BigDecimal | 小算补助金额 | +| dueAmount | BigDecimal | **应付** = laborCost + reimburse | +| settleStatus | String | PENDING/COMPLETED | +| settledDate | LocalDate | 实际收款日期 | +| transferRef | String | 转账流水号 | + +--- +## 6. 枚举/数据字典 + +**transferStatus** +| 値 | 含义 | +|------|------| +| PENDING | 待转 | +| COMPLETED | 已转账 | + +**settleStatus (payout)** +| 値 | 含义 | +|------|------| +| PENDING | 待抨款 | +| COMPLETED | 已抨款 | + +--- +## 7. 错误码 + +| 错误码 | 含义 | +|--------|------| +| 584xxx | settlement_status 未为 IN_PROGRESS | +--- +## 8. 示例 + +### 8.1 典型成功 -- GET recon +```json +{ + "code": 200, + "data": { + "customerCashToDriver": 2000.00, + "transferStatus": "PENDING", + "primaryName": "张三", + "driverCollected": 3500.00, + "publicPrepaid": 1200.00, + "primaryDue": 800.00, + "advanceOutstanding": 0.00, + "reconNet": 1500.00 + } +} +``` + +### 8.2 边界 -- PUT recon, transferStatus=COMPLETED+transferRef +```http +PUT /v3/admin/order/1234567890123456/settlement/recon + +{ + "transferStatus": "COMPLETED", + "transferDate": "2026-07-10", + "transferRef": "202607100001" +} +``` +```json +{ + "code": 200, + "data": null +} +``` + +### 8.3 业务失败 -- transferRef 为空触发错误 +```json +{ + "transferStatus": "COMPLETED" +} +``` +```json +{ + "code": 584xxx, + "msg": "transferRef 必填（ transferStatus=COMPLETED）" +} +``` + +--- +## 9. 业务边界 + +适用: settlement_status=IN_PROGRESS +不适用: 已提交或已结算 +特殊边界: +- reconNet 为负属正常现象 +- payout staffId 可空（外请按实填 null) + +--- +## 12. 注意事项 + +- reconNet 公式: driverCollected - publicPrepaid - primaryDue - advanceOutstanding +- PUT recon: null 字段保持现有値，仅传变动字段 + +--- +## 13. 关联/联系人 + +- Issue: https://git.1814.love:8443/wx/HL/issues/4768 +- PR: https://git.1814.love:8443/wx/HL/pulls/4770 +- Commit: https://git.1814.love:8443/wx/HL/commit/cbff5a4d2f0706732c360c0ec99609c4687e2749 +- 后端负责人: 腰苏图 \ No newline at end of file diff --git a/changelogs-v2/2026-07/07_4780_核单submit收口-修改接口-管理后台.md b/changelogs-v2/2026-07/07_4780_核单submit收口-修改接口-管理后台.md new file mode 100644 index 0000000..2631031 --- /dev/null +++ b/changelogs-v2/2026-07/07_4780_核单submit收口-修改接口-管理后台.md @@ -0,0 +1,173 @@ +# 核单 Step 6 submit 收口务 (修改接口) +- **变更日期**: 2026-07-07 +- **端类型**: 管理后台 +- **变更类型**: 修改接口 +- **Issue**: https://git.1814.love:8443/wx/HL/issues/4780 +- **PR**: https://git.1814.love:8443/wx/HL/pulls/4783 + +--- +## 1. 接口背景 + +核单 epic PR5。 Step 6 submit (POST `/v3/admin/order/{orderId}/settlement/step6/submit`) 有两项修改： + +1. **出参新增 `warnings` 字段（软预警列表）**: 软预警不阻塑提交，提交定制师补传凭证 +2. **`orderStatusAfter` 値变更**: 将 "已结算" 改为 "待财务复核" + +**submit 阈条件新增** (任一不满即返错误）: +- 584081: recon 对账数据不完整 (财务人员要地接确认尾款）) +- 584082: 尾款未收全 (customerCashCollectedFlag=false 时) +- 584083: 转账未完成 (transferStatus != COMPLETED 时) +- 584084: 预支未冲扣 (advanceSettledFlag=false 时) +- 584085: payout 未全部 COMPLETED （有人员尚未抨款）) + +--- +## 2. 变更清单 + +| 变更项 | 内容 | +|------|------| +| orderStatusAfter | "已结算" -> "待财务复核" （❗ 破坏兆容） | +| 新增 `warnings` | List, 软预警列表，不阻塑，可空 | +| submit 阈条件 | 584081/084082/584083/584084/584085 新增 | +--- +## 3. 接口详情 + +| 项 | 说明 | +|-----|------| +| 方法 | POST | +| 路径 | /v3/admin/order/{orderId}/settlement/step6/submit | +| 认证 | JWT Bearer(管理端) | +| 幂等性 | 非幂等（重复提交不幂) | +| 核单状态 | settlement_status=IN_PROGRESS | + +--- +## 4. 接口入参 + +### 4.1 路径参数 +| orderId | Long | 是 | 订单 ID | + +### 4.2 请求体 +无 (空请求体) + +--- +## 5. 出参字段（`SettlementSubmitRespVO`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| summaryId | Long | settlement_summary 主键 | +| orderId | Long | 订单 ID | +| settledAt | LocalDateTime | 核单完成时间 | +| totalAmount | BigDecimal | 订单总金额快照 | +| paidAmount | BigDecimal | 已付金额快照 | +| balanceAmount | BigDecimal | 尾款金额 | +| roomCost | BigDecimal | 住宿实际成本 | +| ticketCost | BigDecimal | 门票实际成本 | +| staffCost | BigDecimal | 人员费用实际成本 | +| subsidyCost | BigDecimal | 补助实际成本 | +| insurancePremium | BigDecimal | 保险实际保费 | +| totalActualCost | BigDecimal | 总实际成本=四子表+保险 | +| driverTransferAmount | BigDecimal | 给司机转账金额 | +| profitAmount | BigDecimal | 公司毛利 | +| profitRate | BigDecimal | 毛利率（小数） | +| **orderStatusAfter** | String | **❗ 广报 "待财务复核" (修改前: "已结算")** | +| mqTriggered | Boolean | OrderSettledEvent 是否触发成功 | +| **warnings** | List | **✨ 新增**: 软预警, 不阻塑, null=无预警 | + +--- +## 6. 枚举/数据字典 + +无枚举字段。 orderStatusAfter 是文本展示. + +--- +## 7. 错误码 + +| 错误码 | 含义 | 触发场景 | +|--------|------|---------| +| 584081 | recon 对账数据不完整 | 未完全填写 recon 数据 | +| 584082 | 尾款未收 | customerCashCollectedFlag=false | +| 584083 | 转账未完成 | transferStatus != COMPLETED | +| 584084 | 预支未冲扣 | advanceSettledFlag=false | +| 584085 | payout 未封 COMPLETED | 有人员尚未抨款 | +--- +## 8. 示例 + +### 8.1 典型成功 -- 提交后带 warnings +```json +{ + "code": 200, + "data": { + "summaryId": 9600000000001, + "orderId": 1234567890123456, + "orderStatusAfter": "待财务复核", + "totalAmount": 24800.00, + "paidAmount": 24800.00, + "balanceAmount": 0.00, + "totalActualCost": 23120.00, + "profitAmount": 1680.00, + "profitRate": 0.0677, + "mqTriggered": true, + "warnings": ["住宿 D2 现付缺凭证"] + } +} +``` + +### 8.2 边界 -- warnings 为空，全部验完整 +```json +{ + "code": 200, + "data": { + "orderStatusAfter": "待财务复核", + "mqTriggered": true, + "warnings": null + } +} +``` + +### 8.3 业务失败 -- recon 未完全填写触发 584081 +```json +{ + "code": 584081, + "msg": "对账数据不完整，请先完善 recon 信息" +} +``` + +--- +## 9. 业务边界 + +适用: settlement_status=IN_PROGRESS +不适用: 已提交或已结算 +特殊边界: +- warnings 列表不为空时，定制师详阅并处理（如补传凭证） + +--- +## 10. 修改前后对比 + +| 字段 / 行为 | 修改前 | 修改后 | +|------|------|------| +| orderStatusAfter | "已结算" | "待财务复核" | +| warnings | 无 | List （可空，软预警列表） | +| submit 阈条件 | 仅 SETTLEMENT_STATUS_NOT_IN_PROGRESS | +584081~584085 | + +--- +## 11. 影响评估/回滚 + +**破坏兆容:** orderStatusAfter 变为 "待财务复核" -- 前端如果硬编 "已结算" 却仅需更新判断逻辑。 + +**前端同步上线:** +- 提交后状态按 "待财务复核" 展示，不再 "已结算" +- warnings 非空时展示提示，建议定制师补传凯缺凭证 + +**回滚方案:** 无需回滚，状态变更属正常业务流程变更。 + +--- +## 12. 注意事酹 + +- orderStatusAfter 修改是 **破坏兆容变更**，前端需更新判断逻辑 +- warnings 列表需备意 null (展示套带信息或展示 toast) + +--- +## 13. 关联/联系人 + +- Issue: https://git.1814.love:8443/wx/HL/issues/4780 +- PR: https://git.1814.love:8443/wx/HL/pulls/4783 +- Commit: https://git.1814.love:8443/wx/HL/commit/f4877036d4d8f8ac2d56573a16f81a30e1dc2b43 +- 后端负责人: 腰苏图 \ No newline at end of file