173 行
5.2 KiB
Markdown
173 行
5.2 KiB
Markdown
# 核单 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<String>, 软预警列表，不阻塑，可空 |
|
||
| 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<String> | **✨ 新增**: 软预警, 不阻塑, 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<String> （可空，软预警列表） |
|
||
| 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
|
||
- 后端负责人: 腰苏图 |