# 核单 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
- 后端负责人: 腰苏图