yaosutu
父节点
a3ee62d00d
当前提交
bb0cdc6e80
@ -0,0 +1,875 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "5324"
|
||||
title: "删除旧核单兼容接口"
|
||||
consumer: "admin"
|
||||
change_type: "删除接口"
|
||||
backend_status: "deployed"
|
||||
backend_ref: "PR #5328 · merge 709105c1a1d26ae1c867fcc998286781f499faf2"
|
||||
deployment_status: "deployed"
|
||||
deployment_ref: "deploy-panel task ad042377"
|
||||
gateway_status: "verified"
|
||||
verification_status: "verified"
|
||||
verification_ref: "D:/work/project-doc/PRPs/reports/5328-deploy-qa-report.md · D:/work/project-doc/test/5328/evidence.json"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: "2026-07-28T18:09:00+08:00"
|
||||
status_note: "部署 task ad042377 成功；8086/8186 正常；网关 20/20 HTTP 200、0 网络错误、0 个 5xx、RST 0；3 个删除路由均返回业务 404，4 个保留路由进入业务门禁且零写入。管理后台待迁移到双报表确认后调用 finalize 的五步流程。"
|
||||
updated_at: "2026-07-28"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-28T18:04:49+08:00"
|
||||
---
|
||||
|
||||
# 【删除接口·管理后台】删除旧核单兼容接口 (#5324)
|
||||
|
||||
> **PR**: #5328 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-28 18:04
|
||||
|
||||
## 1. 接口背景
|
||||
|
||||
核单完成入口统一为“双报表确认后完成核单”：管理后台先读取并确认主报账人报账表，再读取并确认单团核算表，最后携带两份报告的当前来源指纹调用 `finalize`。旧分类确认兼容接口和旧 Step6 提交入口不再提供。
|
||||
|
||||
## 2. 变更清单
|
||||
|
||||
### 2.1 删除的接口
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 |
|
||||
|---|------|------|------|----------|----------|
|
||||
| 1 | 查询核单分类确认状态 | GET | `/v3/admin/order/{orderId}/settlement/category-checks` | 删除 | 删除调用及分类确认状态门禁 |
|
||||
| 2 | 确认单个核单分类 | POST | `/v3/admin/order/{orderId}/settlement/category-checks/{category}/confirm` | 删除 | 删除调用及“本分类已确认”交互 |
|
||||
| 3 | 旧 Step6 提交核单 | POST | `/v3/admin/order/{orderId}/settlement/step6/submit` | 删除 | 改为下表五步流程 |
|
||||
|
||||
### 2.2 唯一替代流程
|
||||
|
||||
| 顺序 | 接口 | 方法 | 路径 | 用途 |
|
||||
|------|------|------|------|------|
|
||||
| 1 | 查询主报账人报账表 | GET | `/v3/admin/order/{orderId}/settlement/reports/reimbursement` | 获取实时数据和主报账表 `sourceFingerprint` |
|
||||
| 2 | 确认主报账人报账表 | POST | `/v3/admin/order/{orderId}/settlement/reports/reimbursement/confirm` | 确认转账、预支结清标志和签字凭证 |
|
||||
| 3 | 查询单团核算表 | GET | `/v3/admin/order/{orderId}/settlement/reports/group` | 获取实时数据和单团核算表 `sourceFingerprint` |
|
||||
| 4 | 确认单团核算表 | POST | `/v3/admin/order/{orderId}/settlement/reports/group/confirm` | 确认当前单团核算结果 |
|
||||
| 5 | 完成核单 | POST | `/v3/admin/order/{orderId}/settlement/finalize` | 携带两份已确认报告的当前指纹完成核单 |
|
||||
|
||||
## 3. 接口详情
|
||||
|
||||
以下五个接口都需要管理后台登录态，房务角色不可访问；`orderId` 为必填路径参数，类型为 `Long/String`，值必须大于 0。
|
||||
|
||||
### 3.1 查询主报账人报账表
|
||||
|
||||
- **方法 + 路径**：`GET /v3/admin/order/{orderId}/settlement/reports/reimbursement`
|
||||
- **使用场景**：进入报账报表页面、确认前刷新、来源数据变化后重新获取。
|
||||
- **幂等性**：幂等，只读。
|
||||
- **请求体**：无。
|
||||
- **成功响应**：`Result<SettlementReimbursementReportRespVO>`，完整字段见 §5.2。
|
||||
- **关键规则**：前端必须保存本次响应的 `data.sourceFingerprint`；确认请求不得使用缓存的旧指纹。
|
||||
|
||||
**请求示例**
|
||||
|
||||
```http
|
||||
GET /v3/admin/order/1914050000000001/settlement/reports/reimbursement
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": null,
|
||||
"orderId": "1914050000000001",
|
||||
"reportStatus": "GENERATED",
|
||||
"sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"primaryReporterId": "3001",
|
||||
"primaryReporterName": "王司机",
|
||||
"primaryReporterRole": "DRIVER",
|
||||
"reportVersion": 1,
|
||||
"driverCollectedTailAmount": 2000.00,
|
||||
"approvedAdvanceAmount": 500.00,
|
||||
"reportablePaidCostAmount": 1000.00,
|
||||
"reporterNetAmount": 1500.00,
|
||||
"primaryReporterCollectedAmount": 2000.00,
|
||||
"publicPrepaidAmount": 1000.00,
|
||||
"primaryReporterDueAmount": 1000.00,
|
||||
"advanceOutstandingAmount": 500.00,
|
||||
"reconNetAmount": 1500.00,
|
||||
"transferDirection": "REPORTER_TO_COMPANY",
|
||||
"transferAmount": 1500.00,
|
||||
"incomeLines": [
|
||||
{
|
||||
"type": "DRIVER_CASH_RECEIPT",
|
||||
"receiptId": "9100000000001",
|
||||
"amount": 2000.00,
|
||||
"channel": "DRIVER_CASH",
|
||||
"payType": "CASH",
|
||||
"collectorStaffId": "3001",
|
||||
"collectorName": "王司机",
|
||||
"collectorRole": "DRIVER",
|
||||
"receivedAt": "2026-07-27T18:30:00",
|
||||
"remark": "司机代收尾款"
|
||||
}
|
||||
],
|
||||
"expenseLines": [
|
||||
{
|
||||
"category": "HOTEL",
|
||||
"kind": "HOTEL",
|
||||
"hotelAssignmentId": "9200000000001",
|
||||
"hotelName": "示例酒店",
|
||||
"stayDate": "2026-07-20",
|
||||
"amount": 1000.00,
|
||||
"paymentMethod": "CASH_PAID",
|
||||
"remark": null
|
||||
}
|
||||
],
|
||||
"advanceLines": [
|
||||
{
|
||||
"type": "APPROVED_ADVANCE",
|
||||
"advanceId": "9300000000001",
|
||||
"payeeStaffId": "3001",
|
||||
"payeeName": "王司机",
|
||||
"payeeRole": "DRIVER",
|
||||
"advanceType": "PUBLIC",
|
||||
"amount": 500.00,
|
||||
"purpose": "途中费用",
|
||||
"voucherUrl": "https://oss.example.com/advance.jpg",
|
||||
"status": "APPROVED",
|
||||
"submittedAt": "2026-07-18T10:00:00",
|
||||
"approvedAt": "2026-07-18T11:00:00",
|
||||
"approvedBy": "10001"
|
||||
}
|
||||
],
|
||||
"vehicleLines": [],
|
||||
"transferStatus": null,
|
||||
"transferDate": null,
|
||||
"transferRef": null,
|
||||
"advanceSettledFlag": false,
|
||||
"signedVoucher": null,
|
||||
"generatedBy": null,
|
||||
"generatedByName": null,
|
||||
"generatedAt": null,
|
||||
"confirmedBy": null,
|
||||
"confirmedByName": null,
|
||||
"confirmedAt": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 确认主报账人报账表
|
||||
|
||||
- **方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/reports/reimbursement/confirm`
|
||||
- **使用场景**：已核对主报账表，且转账、预支标记和签字凭证已经填写完毕。
|
||||
- **幂等性**：同一当前指纹和完全相同的确认内容可重复提交；确认后改传其它内容返回 `584317`。
|
||||
- **请求体**：见 §4.2。
|
||||
- **成功响应**：与 §3.1 相同，`reportStatus=CONFIRMED`，并返回确认信息。
|
||||
|
||||
**请求示例**
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/reports/reimbursement/confirm
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"expectedSourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"transferStatus": "COMPLETED",
|
||||
"transferDate": "2026-07-28",
|
||||
"transferRef": "BANK-20260728-001",
|
||||
"advanceSettledFlag": true,
|
||||
"signedVoucher": {
|
||||
"files": [
|
||||
{
|
||||
"name": "司机签字单.pdf",
|
||||
"url": "https://oss.example.com/signed-voucher.pdf"
|
||||
}
|
||||
],
|
||||
"note": "签字凭证已回收"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": "9400000000001",
|
||||
"orderId": "1914050000000001",
|
||||
"reportStatus": "CONFIRMED",
|
||||
"sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"primaryReporterId": "3001",
|
||||
"primaryReporterName": "王司机",
|
||||
"primaryReporterRole": "DRIVER",
|
||||
"reportVersion": 1,
|
||||
"driverCollectedTailAmount": 2000.00,
|
||||
"approvedAdvanceAmount": 500.00,
|
||||
"reportablePaidCostAmount": 1000.00,
|
||||
"reporterNetAmount": 1500.00,
|
||||
"primaryReporterCollectedAmount": 2000.00,
|
||||
"publicPrepaidAmount": 1000.00,
|
||||
"primaryReporterDueAmount": 1000.00,
|
||||
"advanceOutstandingAmount": 500.00,
|
||||
"reconNetAmount": 1500.00,
|
||||
"transferDirection": "REPORTER_TO_COMPANY",
|
||||
"transferAmount": 1500.00,
|
||||
"incomeLines": [],
|
||||
"expenseLines": [],
|
||||
"advanceLines": [],
|
||||
"vehicleLines": [],
|
||||
"transferStatus": "COMPLETED",
|
||||
"transferDate": "2026-07-28",
|
||||
"transferRef": "BANK-20260728-001",
|
||||
"advanceSettledFlag": true,
|
||||
"signedVoucher": {
|
||||
"files": [
|
||||
{
|
||||
"name": "司机签字单.pdf",
|
||||
"url": "https://oss.example.com/signed-voucher.pdf"
|
||||
}
|
||||
],
|
||||
"note": "签字凭证已回收"
|
||||
},
|
||||
"generatedBy": null,
|
||||
"generatedByName": null,
|
||||
"generatedAt": null,
|
||||
"confirmedBy": "10001",
|
||||
"confirmedByName": "财务管理员",
|
||||
"confirmedAt": "2026-07-28T18:10:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 查询单团核算表
|
||||
|
||||
- **方法 + 路径**：`GET /v3/admin/order/{orderId}/settlement/reports/group`
|
||||
- **使用场景**：主报账表确认后查看单团收入、成本、毛利和人均指标。
|
||||
- **幂等性**：幂等，只读。
|
||||
- **请求体**：无。
|
||||
- **成功响应**：`Result<SettlementGroupReportRespVO>`，完整字段见 §5.3。
|
||||
- **关键规则**：前端必须保存本次响应的 `data.sourceFingerprint`；确认请求不得使用缓存的旧指纹。
|
||||
|
||||
**请求示例**
|
||||
|
||||
```http
|
||||
GET /v3/admin/order/1914050000000001/settlement/reports/group
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": null,
|
||||
"orderId": "1914050000000001",
|
||||
"reportStatus": "GENERATED",
|
||||
"sourceFingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
|
||||
"baseOrderAmount": 24800.00,
|
||||
"otherIncomeAmount": 500.00,
|
||||
"discountAmount": 300.00,
|
||||
"adjustedReceivableAmount": 25000.00,
|
||||
"paidAmount": 25000.00,
|
||||
"actualRefundedAmount": 0.00,
|
||||
"netRevenueAmount": 25000.00,
|
||||
"netReceivedAmount": 25000.00,
|
||||
"outstandingAmount": 0.00,
|
||||
"hotelCost": 4280.00,
|
||||
"ticketCost": 3680.00,
|
||||
"mealCost": 860.00,
|
||||
"vehicleCost": 1260.00,
|
||||
"guideCost": 800.00,
|
||||
"photographerCost": 600.00,
|
||||
"otherExpenseCost": 300.00,
|
||||
"insurancePremium": 180.00,
|
||||
"totalCost": 11960.00,
|
||||
"paidCost": 11960.00,
|
||||
"unpaidCost": 0.00,
|
||||
"grossProfit": 13040.00,
|
||||
"grossProfitRate": 0.5216,
|
||||
"travelerCount": 5,
|
||||
"perCapitaRevenue": 5000.00,
|
||||
"perCapitaCost": 2392.00,
|
||||
"perCapitaProfit": 2608.00,
|
||||
"incomeLines": [
|
||||
{"type": "BASE_ORDER", "amount": 24800.00},
|
||||
{"type": "OTHER_INCOME", "amount": 500.00},
|
||||
{"type": "DISCOUNT", "amount": -300.00},
|
||||
{"type": "ACTUAL_REFUND", "amount": 0.00}
|
||||
],
|
||||
"costCategories": [
|
||||
{"category": "HOTEL", "amount": 4280.00},
|
||||
{"category": "TICKET", "amount": 3680.00},
|
||||
{"category": "MEAL", "amount": 860.00},
|
||||
{"category": "VEHICLE", "amount": 1260.00},
|
||||
{"category": "GUIDE", "amount": 800.00},
|
||||
{"category": "PHOTOGRAPHER", "amount": 600.00},
|
||||
{"category": "OTHER_EXPENSE", "amount": 300.00},
|
||||
{"category": "INSURANCE", "amount": 180.00}
|
||||
],
|
||||
"generatedBy": null,
|
||||
"generatedByName": null,
|
||||
"generatedAt": null,
|
||||
"confirmedBy": null,
|
||||
"confirmedByName": null,
|
||||
"confirmedAt": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 确认单团核算表
|
||||
|
||||
- **方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/reports/group/confirm`
|
||||
- **使用场景**：主报账表已经确认，且已核对当前单团收入、成本和利润。
|
||||
- **幂等性**：相同当前指纹重复确认返回已确认结果。
|
||||
- **请求体**：见 §4.3。
|
||||
- **成功响应**：与 §3.3 相同，`reportStatus=CONFIRMED`，并返回确认人和确认时间。
|
||||
|
||||
**请求示例**
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/reports/group/confirm
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"expectedSourceFingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": "9500000000001",
|
||||
"orderId": "1914050000000001",
|
||||
"reportStatus": "CONFIRMED",
|
||||
"sourceFingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
|
||||
"baseOrderAmount": 24800.00,
|
||||
"otherIncomeAmount": 500.00,
|
||||
"discountAmount": 300.00,
|
||||
"adjustedReceivableAmount": 25000.00,
|
||||
"paidAmount": 25000.00,
|
||||
"actualRefundedAmount": 0.00,
|
||||
"netRevenueAmount": 25000.00,
|
||||
"netReceivedAmount": 25000.00,
|
||||
"outstandingAmount": 0.00,
|
||||
"hotelCost": 4280.00,
|
||||
"ticketCost": 3680.00,
|
||||
"mealCost": 860.00,
|
||||
"vehicleCost": 1260.00,
|
||||
"guideCost": 800.00,
|
||||
"photographerCost": 600.00,
|
||||
"otherExpenseCost": 300.00,
|
||||
"insurancePremium": 180.00,
|
||||
"totalCost": 11960.00,
|
||||
"paidCost": 11960.00,
|
||||
"unpaidCost": 0.00,
|
||||
"grossProfit": 13040.00,
|
||||
"grossProfitRate": 0.5216,
|
||||
"travelerCount": 5,
|
||||
"perCapitaRevenue": 5000.00,
|
||||
"perCapitaCost": 2392.00,
|
||||
"perCapitaProfit": 2608.00,
|
||||
"incomeLines": [
|
||||
{"type": "BASE_ORDER", "amount": 24800.00},
|
||||
{"type": "OTHER_INCOME", "amount": 500.00},
|
||||
{"type": "DISCOUNT", "amount": -300.00},
|
||||
{"type": "ACTUAL_REFUND", "amount": 0.00}
|
||||
],
|
||||
"costCategories": [
|
||||
{"category": "HOTEL", "amount": 4280.00},
|
||||
{"category": "TICKET", "amount": 3680.00},
|
||||
{"category": "MEAL", "amount": 860.00},
|
||||
{"category": "VEHICLE", "amount": 1260.00},
|
||||
{"category": "GUIDE", "amount": 800.00},
|
||||
{"category": "PHOTOGRAPHER", "amount": 600.00},
|
||||
{"category": "OTHER_EXPENSE", "amount": 300.00},
|
||||
{"category": "INSURANCE", "amount": 180.00}
|
||||
],
|
||||
"generatedBy": null,
|
||||
"generatedByName": null,
|
||||
"generatedAt": null,
|
||||
"confirmedBy": "10001",
|
||||
"confirmedByName": "财务管理员",
|
||||
"confirmedAt": "2026-07-28T18:12:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 完成核单
|
||||
|
||||
- **方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/finalize`
|
||||
- **使用场景**：两份报告均已确认且来源仍为当前版本时，点击“完成核单”。
|
||||
- **幂等性**：已完成且存在当前终态结果时，重复提交返回当前终态结果。
|
||||
- **请求体**：见 §4.4；请求体在业务上必填。
|
||||
- **成功响应**：`Result<SettlementSubmitRespVO>`，完整字段见 §5.4。
|
||||
|
||||
**请求示例**
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/finalize
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"remark": "双报表已核对完成",
|
||||
"reimbursementExpectedSourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"groupExpectedSourceFingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"summaryId": "9600000000001",
|
||||
"finalSnapshotId": "9600000000002",
|
||||
"finalSnapshotVersionNo": 1,
|
||||
"finalSnapshotStatus": "FINALIZED",
|
||||
"orderId": "1914050000000001",
|
||||
"settledAt": "2026-07-28T18:15:00",
|
||||
"totalAmount": 25000.00,
|
||||
"paidAmount": 25000.00,
|
||||
"balanceAmount": 0.00,
|
||||
"roomCost": 4280.00,
|
||||
"ticketCost": 3680.00,
|
||||
"staffCost": 1400.00,
|
||||
"subsidyCost": 0.00,
|
||||
"mealCost": 860.00,
|
||||
"vehicleCost": 1260.00,
|
||||
"otherExpenseCost": 300.00,
|
||||
"insurancePremium": 180.00,
|
||||
"totalActualCost": 11960.00,
|
||||
"driverTransferAmount": 1000.00,
|
||||
"profitAmount": 13040.00,
|
||||
"profitRate": 0.5216,
|
||||
"orderStatusAfter": "待财务复核",
|
||||
"mqTriggered": true,
|
||||
"warnings": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 接口入参
|
||||
|
||||
### 4.1 五个替代接口共用路径参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 校验 |
|
||||
|------|------|------|------|------|
|
||||
| `orderId` | Long/String | 是 | 订单 ID | 必须大于 0 |
|
||||
|
||||
两个 GET 接口没有 Query 参数和请求体。
|
||||
|
||||
### 4.2 主报账表确认请求体
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|------|------|------|------|----------|
|
||||
| `expectedSourceFingerprint` | String | 是 | §3.1 最新响应的 `data.sourceFingerprint` | 64 位小写十六进制 |
|
||||
| `transferStatus` | String | 是 | 转账处理状态 | 固定传 `COMPLETED` |
|
||||
| `transferDate` | String/date | 条件必填 | 转账日期 | `reporterNetAmount != 0` 时必填；格式 `YYYY-MM-DD` |
|
||||
| `transferRef` | String | 条件必填 | 转账流水号或可追溯凭证号 | `reporterNetAmount != 0` 时不得为空白 |
|
||||
| `advanceSettledFlag` | Boolean | 是 | 预支款项是否已处理完毕 | 不得为 `null` |
|
||||
| `signedVoucher` | Object | 是 | 签字凭证 | 不得为 `null` |
|
||||
| `signedVoucher.files` | Array | 是 | 签字凭证文件列表 | 至少 1 项 |
|
||||
| `signedVoucher.files[].name` | String | 否 | 文件名 | 可为空 |
|
||||
| `signedVoucher.files[].url` | String | 是 | 文件地址 | 不得为空白 |
|
||||
| `signedVoucher.note` | String | 否 | 凭证备注 | 可为空 |
|
||||
|
||||
当 `reporterNetAmount = 0` 时，`transferDate` 和 `transferRef` 可不传；`transferStatus` 仍必须是 `COMPLETED`，签字凭证仍必须至少包含一个有效文件。
|
||||
|
||||
### 4.3 单团核算表确认请求体
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|------|------|------|------|----------|
|
||||
| `expectedSourceFingerprint` | String | 是 | §3.3 最新响应的 `data.sourceFingerprint` | 64 位小写十六进制 |
|
||||
|
||||
### 4.4 完成核单请求体
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|------|------|------|------|----------|
|
||||
| `remark` | String | 否 | 本次完成核单的整体备注 | 最长 500 字 |
|
||||
| `reimbursementExpectedSourceFingerprint` | String | 是 | 已确认主报账表的当前 `sourceFingerprint` | 64 位小写十六进制 |
|
||||
| `groupExpectedSourceFingerprint` | String | 是 | 已确认单团核算表的当前 `sourceFingerprint` | 64 位小写十六进制 |
|
||||
|
||||
### 4.5 指纹传递关系
|
||||
|
||||
| 来源 | 确认接口字段 | 完成核单字段 |
|
||||
|------|--------------|--------------|
|
||||
| `GET .../reports/reimbursement` 的 `data.sourceFingerprint` | `POST .../reports/reimbursement/confirm` 的 `expectedSourceFingerprint` | `POST .../finalize` 的 `reimbursementExpectedSourceFingerprint` |
|
||||
| `GET .../reports/group` 的 `data.sourceFingerprint` | `POST .../reports/group/confirm` 的 `expectedSourceFingerprint` | `POST .../finalize` 的 `groupExpectedSourceFingerprint` |
|
||||
|
||||
## 5. 出参
|
||||
|
||||
### 5.1 统一响应外层
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | Integer | `200` 表示成功；其它值见 §7 |
|
||||
| `msg` | String | 结果说明 |
|
||||
| `data` | Object/null | 成功时为业务数据，失败时通常为 `null` |
|
||||
|
||||
所有 Long ID 以 JSON 字符串消费，避免前端数字精度损失；金额字段为十进制数。
|
||||
|
||||
### 5.2 主报账人报账表响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | String/null | 报账表记录 ID；仅实时预览、尚未确认时可为 `null` |
|
||||
| `orderId` | String | 订单 ID |
|
||||
| `reportStatus` | String | `GENERATED` / `CONFIRMED` / `STALE`，见 §6.1 |
|
||||
| `sourceFingerprint` | String | 当前来源指纹，64 位小写十六进制 |
|
||||
| `primaryReporterId` | String/null | 主报账人 ID |
|
||||
| `primaryReporterName` | String/null | 主报账人姓名 |
|
||||
| `primaryReporterRole` | String/null | 主报账人角色 |
|
||||
| `reportVersion` | Integer/null | 报账表版本 |
|
||||
| `driverCollectedTailAmount` | Decimal | 司机代收尾款 |
|
||||
| `approvedAdvanceAmount` | Decimal | 已审批预支合计 |
|
||||
| `reportablePaidCostAmount` | Decimal | 主报账人已支付、可报账成本合计 |
|
||||
| `reporterNetAmount` | Decimal | 报账净额：司机代收尾款 + 已审批预支 - 可报账已支付成本 |
|
||||
| `primaryReporterCollectedAmount` | Decimal | 主报账人代收金额 |
|
||||
| `publicPrepaidAmount` | Decimal | 公共预支金额 |
|
||||
| `primaryReporterDueAmount` | Decimal | 主报账人应报账金额 |
|
||||
| `advanceOutstandingAmount` | Decimal | 待处理预支金额 |
|
||||
| `reconNetAmount` | Decimal | 报账净额兼容字段 |
|
||||
| `transferDirection` | String | 转账方向，见 §6.2 |
|
||||
| `transferAmount` | Decimal | 需转账金额，取 `reporterNetAmount` 绝对值 |
|
||||
| `incomeLines` | Array<Object> | 司机代收尾款明细 |
|
||||
| `expenseLines` | Array<Object> | 主报账人现金支付成本明细 |
|
||||
| `advanceLines` | Array<Object> | 已审批预支明细 |
|
||||
| `vehicleLines` | Array<Object> | 车辆逐日明细；允许空数组 |
|
||||
| `transferStatus` | String/null | 未确认时可为空；确认后为 `COMPLETED` |
|
||||
| `transferDate` | String/date/null | 转账日期 |
|
||||
| `transferRef` | String/null | 转账流水号或凭证号 |
|
||||
| `advanceSettledFlag` | Boolean | 预支是否已处理完毕 |
|
||||
| `signedVoucher` | Object/null | 签字凭证，结构同 §4.2 |
|
||||
| `generatedBy` | String/null | 历史生成操作人 ID |
|
||||
| `generatedByName` | String/null | 历史生成操作人姓名 |
|
||||
| `generatedAt` | String/date-time/null | 历史生成时间 |
|
||||
| `confirmedBy` | String/null | 确认人 ID |
|
||||
| `confirmedByName` | String/null | 确认人姓名 |
|
||||
| `confirmedAt` | String/date-time/null | 确认时间 |
|
||||
|
||||
`incomeLines[]` 的固定字段为 `type`、`receiptId`、`amount`、`channel`、`payType`、`collectorStaffId`、`collectorName`、`collectorRole`、`receivedAt`、`remark`。
|
||||
|
||||
`advanceLines[]` 的固定字段为 `type`、`advanceId`、`payeeStaffId`、`payeeName`、`payeeRole`、`advanceType`、`amount`、`purpose`、`voucherUrl`、`status`、`submittedAt`、`approvedAt`、`approvedBy`。
|
||||
|
||||
`expenseLines[]` 至少包含 `category`、`kind`、`amount`、`paymentMethod`；按分类还会包含对应的名称、日期、数量、单价、人员或车辆标识、凭证和备注字段。前端列表应按字段是否存在展示，不依赖固定列宽。
|
||||
|
||||
### 5.3 单团核算表响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | String/null | 单团核算表记录 ID；仅实时预览、尚未确认时可为 `null` |
|
||||
| `orderId` | String | 订单 ID |
|
||||
| `reportStatus` | String | `GENERATED` / `CONFIRMED` / `STALE` |
|
||||
| `sourceFingerprint` | String | 当前来源指纹，64 位小写十六进制 |
|
||||
| `baseOrderAmount` | Decimal | 订单基础金额 |
|
||||
| `otherIncomeAmount` | Decimal | 其他收入 |
|
||||
| `discountAmount` | Decimal | 优惠金额 |
|
||||
| `adjustedReceivableAmount` | Decimal | 调整后应收 |
|
||||
| `paidAmount` | Decimal | 已收金额 |
|
||||
| `actualRefundedAmount` | Decimal | 实际退款 |
|
||||
| `netRevenueAmount` | Decimal | 净收入 |
|
||||
| `netReceivedAmount` | Decimal | 净已收 |
|
||||
| `outstandingAmount` | Decimal | 待收金额 |
|
||||
| `hotelCost` | Decimal | 住宿成本 |
|
||||
| `ticketCost` | Decimal | 门票/游玩项目成本 |
|
||||
| `mealCost` | Decimal | 餐食成本 |
|
||||
| `vehicleCost` | Decimal | 车辆成本 |
|
||||
| `guideCost` | Decimal | 导游成本 |
|
||||
| `photographerCost` | Decimal | 摄影成本 |
|
||||
| `otherExpenseCost` | Decimal | 其他支出成本 |
|
||||
| `insurancePremium` | Decimal | 保险保费 |
|
||||
| `totalCost` | Decimal | 总成本 |
|
||||
| `paidCost` | Decimal | 已支付成本 |
|
||||
| `unpaidCost` | Decimal | 未支付成本 |
|
||||
| `grossProfit` | Decimal | 毛利 |
|
||||
| `grossProfitRate` | Decimal | 毛利率；收入为 0 时为 0 |
|
||||
| `travelerCount` | Integer | 出行人数 |
|
||||
| `perCapitaRevenue` | Decimal | 人均收入 |
|
||||
| `perCapitaCost` | Decimal | 人均成本 |
|
||||
| `perCapitaProfit` | Decimal | 人均利润 |
|
||||
| `incomeLines` | Array<Object> | 收入构成；元素字段为 `type`、`amount` |
|
||||
| `costCategories` | Array<Object> | 成本构成；元素字段为 `category`、`amount` |
|
||||
| `generatedBy` | String/null | 历史生成操作人 ID |
|
||||
| `generatedByName` | String/null | 历史生成操作人姓名 |
|
||||
| `generatedAt` | String/date-time/null | 历史生成时间 |
|
||||
| `confirmedBy` | String/null | 确认人 ID |
|
||||
| `confirmedByName` | String/null | 确认人姓名 |
|
||||
| `confirmedAt` | String/date-time/null | 确认时间 |
|
||||
|
||||
### 5.4 完成核单响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `summaryId` | String | 核单汇总 ID |
|
||||
| `finalSnapshotId` | String | 核单终态版本 ID |
|
||||
| `finalSnapshotVersionNo` | Integer | 核单终态版本号 |
|
||||
| `finalSnapshotStatus` | String | 核单终态状态，成功时为 `FINALIZED` |
|
||||
| `orderId` | String | 订单 ID |
|
||||
| `settledAt` | String/date-time | 核单完成时间 |
|
||||
| `totalAmount` | Decimal | 订单总金额 |
|
||||
| `paidAmount` | Decimal | 已收金额 |
|
||||
| `balanceAmount` | Decimal | 待收金额；完成核单时必须为 0 |
|
||||
| `roomCost` | Decimal | 住宿实际成本 |
|
||||
| `ticketCost` | Decimal | 门票实际成本 |
|
||||
| `staffCost` | Decimal | 人员实际成本 |
|
||||
| `subsidyCost` | Decimal | 补助实际成本 |
|
||||
| `mealCost` | Decimal | 餐食实际成本 |
|
||||
| `vehicleCost` | Decimal | 车辆实际成本 |
|
||||
| `otherExpenseCost` | Decimal | 其他支出实际成本 |
|
||||
| `insurancePremium` | Decimal | 保险保费 |
|
||||
| `totalActualCost` | Decimal | 总实际成本 |
|
||||
| `driverTransferAmount` | Decimal | 需与司机/主报账人结算的金额 |
|
||||
| `profitAmount` | Decimal | 公司毛利 |
|
||||
| `profitRate` | Decimal | 公司毛利率 |
|
||||
| `orderStatusAfter` | String | 完成核单后的订单状态 |
|
||||
| `mqTriggered` | Boolean | 核单完成事件是否已触发 |
|
||||
| `warnings` | Array<String> | 软提示列表；不阻塞成功结果 |
|
||||
|
||||
## 6. 枚举 / 数据字典
|
||||
|
||||
### 6.1 `reportStatus`
|
||||
|
||||
**所属字段**：两份报告的 `reportStatus` | **类型**：String
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `GENERATED` | 待确认 | 当前实时数据可供核对，尚未确认 |
|
||||
| `CONFIRMED` | 已确认 | 当前来源数据已经确认 |
|
||||
| `STALE` | 已失效 | 来源数据已变化，旧确认不能用于完成核单 |
|
||||
|
||||
### 6.2 `transferDirection`
|
||||
|
||||
**所属字段**：主报账表 `transferDirection` | **类型**：String
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `REPORTER_TO_COMPANY` | 报账人转给公司 | `reporterNetAmount > 0` |
|
||||
| `COMPANY_TO_REPORTER` | 公司转给报账人 | `reporterNetAmount < 0` |
|
||||
| `BALANCED` | 无需转账 | `reporterNetAmount = 0` |
|
||||
|
||||
### 6.3 `transferStatus`
|
||||
|
||||
**所属字段**：主报账表确认请求和响应 `transferStatus` | **类型**：String
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `COMPLETED` | 已完成 | 确认主报账表时唯一允许值 |
|
||||
|
||||
### 6.4 单团收入行 `type`
|
||||
|
||||
| 值 | 中文 | 金额符号 |
|
||||
|----|------|----------|
|
||||
| `BASE_ORDER` | 订单基础收入 | 正数 |
|
||||
| `OTHER_INCOME` | 其他收入 | 正数 |
|
||||
| `DISCOUNT` | 优惠 | 负数 |
|
||||
| `ACTUAL_REFUND` | 实际退款 | 负数或 0 |
|
||||
|
||||
### 6.5 单团成本行 `category`
|
||||
|
||||
| 值 | 中文 |
|
||||
|----|------|
|
||||
| `HOTEL` | 住宿 |
|
||||
| `TICKET` | 门票/游玩项目 |
|
||||
| `MEAL` | 餐食 |
|
||||
| `VEHICLE` | 车辆 |
|
||||
| `GUIDE` | 导游 |
|
||||
| `PHOTOGRAPHER` | 摄影 |
|
||||
| `OTHER_EXPENSE` | 其他支出 |
|
||||
| `INSURANCE` | 保险 |
|
||||
|
||||
## 7. 错误码
|
||||
|
||||
| code | 含义 | 触发场景 |
|
||||
|------|------|----------|
|
||||
| `400` | 参数校验失败 | `orderId <= 0`、请求体缺字段、指纹格式错误等 |
|
||||
| `403` | 无访问或写入权限 | 房务角色访问，或操作人没有核单写权限 |
|
||||
| `404` | 接口不存在 | 调用本次删除的 3 个旧接口 |
|
||||
| `584082` | 存在待收尾款，请收齐后再提交核单 | `finalize` 时单团核算表 `outstandingAmount != 0` |
|
||||
| `584312` | 主报账表尚未确认或数据已变化 | 单团核算表确认前，主报账表未确认或已失效 |
|
||||
| `584314` | 单团核算表尚未确认或数据已变化 | `finalize` 时单团核算表未确认、已失效或指纹不匹配 |
|
||||
| `584315` | 核单来源数据已变化，请刷新后重新确认 | 确认报告时提交的 `expectedSourceFingerprint` 不是当前值 |
|
||||
| `584316` | 核单报告发生并发变化，请刷新后重试 | 多人同时确认同一报告发生冲突 |
|
||||
| `584317` | 当前报告状态不允许执行该操作 | 确认内容不合法，或报告当前状态不允许重复变更 |
|
||||
| `584325` | 完成核单必须提交主报账和单团核算的当前指纹 | `finalize` 缺少任一指纹或指纹不是 64 位小写十六进制 |
|
||||
|
||||
## 8. 示例（典型 / 边界 / 异常）
|
||||
|
||||
### 8.1 典型成功：五步完成核单
|
||||
|
||||
1. 调用 `GET .../reports/reimbursement`，保存响应 `sourceFingerprint=aaaa...`。
|
||||
2. 调用 `POST .../reports/reimbursement/confirm`，`expectedSourceFingerprint` 传 `aaaa...`，响应状态为 `CONFIRMED`。
|
||||
3. 调用 `GET .../reports/group`，保存响应 `sourceFingerprint=bbbb...`。
|
||||
4. 调用 `POST .../reports/group/confirm`，`expectedSourceFingerprint` 传 `bbbb...`，响应状态为 `CONFIRMED`。
|
||||
5. 调用 `POST .../finalize`，两个指纹分别传 `aaaa...` 和 `bbbb...`，响应 `finalSnapshotStatus=FINALIZED`。
|
||||
|
||||
各步完整请求和响应见 §3.1～§3.5。
|
||||
|
||||
### 8.2 边界：报账净额为 0
|
||||
|
||||
当最新主报账表返回 `reporterNetAmount=0`、`transferDirection=BALANCED` 时：
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/reports/reimbursement/confirm
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"expectedSourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"transferStatus": "COMPLETED",
|
||||
"advanceSettledFlag": true,
|
||||
"signedVoucher": {
|
||||
"files": [
|
||||
{
|
||||
"name": "司机签字单.pdf",
|
||||
"url": "https://oss.example.com/signed-voucher.pdf"
|
||||
}
|
||||
],
|
||||
"note": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"orderId": "1914050000000001",
|
||||
"reportStatus": "CONFIRMED",
|
||||
"sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"reporterNetAmount": 0.00,
|
||||
"transferDirection": "BALANCED",
|
||||
"transferAmount": 0.00,
|
||||
"transferStatus": "COMPLETED",
|
||||
"transferDate": null,
|
||||
"transferRef": null,
|
||||
"advanceSettledFlag": true,
|
||||
"signedVoucher": {
|
||||
"files": [
|
||||
{
|
||||
"name": "司机签字单.pdf",
|
||||
"url": "https://oss.example.com/signed-voucher.pdf"
|
||||
}
|
||||
],
|
||||
"note": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 异常：来源数据变化
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/reports/group/confirm
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"expectedSourceFingerprint": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 584315,
|
||||
"msg": "核单来源数据已变化，请刷新后重新确认",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
收到该错误后重新执行对应 GET，使用新的 `data.sourceFingerprint` 重新确认；不得继续用旧指纹调用 `finalize`。
|
||||
|
||||
### 8.4 异常：仍有待收尾款
|
||||
|
||||
```http
|
||||
POST /v3/admin/order/1914050000000001/settlement/finalize
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"reimbursementExpectedSourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"groupExpectedSourceFingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 584082,
|
||||
"msg": "存在待收尾款，请收齐后再提交核单",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 业务边界
|
||||
|
||||
- 必须按“查询主报账表 → 确认主报账表 → 查询单团核算表 → 确认单团核算表 → 完成核单”的顺序执行。
|
||||
- 两份报告的指纹互不通用；禁止把主报账表指纹传到单团核算字段，或反向混用。
|
||||
- 每次确认前都应重新 GET；当 `reportStatus=STALE` 或收到 `584315` 时，必须刷新数据并使用新指纹。
|
||||
- 单团核算表确认依赖当前有效的主报账表确认，否则返回 `584312`。
|
||||
- `finalize` 同时校验两份报告已确认、指纹仍为当前值，以及 `outstandingAmount=0`。
|
||||
- 主报账表 `reporterNetAmount != 0` 时，确认请求必须提供 `transferDate` 和非空 `transferRef`。
|
||||
- 主报账表确认始终要求至少一个含有效 `url` 的签字凭证文件。
|
||||
|
||||
## 10. 修改前后对比
|
||||
|
||||
### 10.1 接口级对比
|
||||
|
||||
| 功能 | 修改前 | 修改后 |
|
||||
|------|--------|--------|
|
||||
| 分类状态 | 调用 `GET .../category-checks` | 不再查询分类确认状态 |
|
||||
| 分类确认 | 调用 `POST .../category-checks/{category}/confirm` | 保存各核单明细即可，不再单独确认分类 |
|
||||
| 报账与单团核算 | 可能绕过双报表直接提交旧 Step6 | 必须分别 GET、confirm 两份报告 |
|
||||
| 完成核单 | `POST .../step6/submit` | `POST .../finalize`，请求体必须携带两个当前指纹 |
|
||||
|
||||
### 10.2 请求体对比
|
||||
|
||||
| 入口 | 修改前 | 修改后 |
|
||||
|------|--------|--------|
|
||||
| 旧 `step6/submit` | 旧提交请求 | 接口删除 |
|
||||
| 新 `finalize` | 不适用 | `remark` 可选；`reimbursementExpectedSourceFingerprint`、`groupExpectedSourceFingerprint` 必填 |
|
||||
|
||||
## 11. 影响评估 / 回滚
|
||||
|
||||
### 11.1 影响评估
|
||||
|
||||
- **是否破坏向后兼容**：是。3 个旧接口已删除。
|
||||
- **前端是否必须同步上线**：是。仍调用任一旧接口的管理后台将收到 404；旧 Step6 提交必须迁移为五步流程。
|
||||
|
||||
### 11.2 回滚原则
|
||||
|
||||
- 后端回退时，前端仍可保留五步新流程。
|
||||
- 前端不得因为短期回退重新新增分类确认入口或恢复旧 Step6 调用；如需临时兼容，应单独确认接口契约后再处理。
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
- 删除 `category-checks` 查询、分类确认 API 封装、分类确认按钮和相关状态门禁。
|
||||
- 删除 `step6/submit` API 封装及所有调用点。
|
||||
- “完成核单”按钮改为调用 `finalize`，并在调用前确保两份报告都为 `CONFIRMED`。
|
||||
- 页面状态中分别保存两份 `sourceFingerprint`，不要只保存一个通用指纹。
|
||||
- 主报账表确认成功后再开放单团核算确认；单团核算确认成功后再开放“完成核单”。
|
||||
- 收到 `584312`、`584314`、`584315`、`584316` 时刷新对应报告，不得自动使用旧数据重试。
|
||||
|
||||
## 13. 关联 / 联系人
|
||||
|
||||
### 13.1 链接
|
||||
|
||||
- **Issue**: [#5324](https://git.1814.love:8443/wx/HL/issues/5324)
|
||||
- **PR**: [#5328](https://git.1814.love:8443/wx/HL/pulls/5328)
|
||||
- **Merge commit**: [709105c1a1](https://git.1814.love:8443/wx/HL/commit/709105c1a1d26ae1c867fcc998286781f499faf2)
|
||||
|
||||
### 13.2 联系人
|
||||
|
||||
- **后端负责人**: @yst
|
||||
- **前端负责人**: 待认领
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户