729 行
29 KiB
Markdown
729 行
29 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6117"
|
||
title: "导游/摄影核单去 EXCLUDED + 全量替换，确认状态统一 settlementConfirmStatus"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yst"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "ec7f2a9a"
|
||
target_release: ""
|
||
verified_at: "2026-08-21"
|
||
status_note: "PR #6119 已合并 dev-v3（merge commit 27ac77b500），测试服已验证。破坏性变化：导游/摄影核单废弃「按天候选 + EXCLUDED」机制改全量替换语义；保存入参删 candidateKey/completionState/sourceResolution/excludedCandidateKeys，传旧字段一律 400（584128）；查询出参删 candidateKey/completionState/candidateResolution/sourceActive/pendingCandidateCount；确认状态统一 settlementConfirmStatus（UNCONFIRMED/CONFIRMED 二值）；blockReasonCode 删 SOURCE_INACTIVE/CANDIDATES_UNRESOLVED 两值。无 DDL。"
|
||
updated_at: "2026-08-21"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 【修改接口·管理后台】导游/摄影核单确认状态统一——去 EXCLUDED 改全量替换（#6117）
|
||
|
||
> **PR**: #6119 | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-21
|
||
|
||
## 1. 接口背景
|
||
|
||
订单核单页「导游」「摄影」两个费用 tab 此前使用「按天候选 + EXCLUDED」机制：后端按订单行程天数预生成候选行，前端要在「纳入（INCLUDED）/ 排除（EXCLUDED）/ 未处理（UNRESOLVED）」三种候选处理结果之间来回切换，还要单独维护一份 `excludedCandidateKeys` 排除清单。这套机制字段多、状态绕，和酒店/门票 tab 的「全量保存 + 确认状态」模型完全不一致，前端两套交互逻辑要分别维护。
|
||
|
||
本次变更把导游/摄影 tab 拉齐到酒店/门票同款模型：
|
||
|
||
- 废弃候选机制，保存接口改**全量替换**语义——传当前应存在的全部行，没传的未确认行即删除；
|
||
- 确认状态统一为每行一个 `settlementConfirmStatus`（`UNCONFIRMED` / `CONFIRMED` 二值），保存时可直接把行置为已确认；
|
||
- 已确认行受保护：不能被全量替换顺手删掉，编辑业务字段会自动退回未确认、需重新确认。
|
||
|
||
涉及导游（guide-fees）与摄影（photographer-fees）两组共 6 个接口，两组结构完全同构，仅字段名有差异（导游用 `name`/`serviceType`，摄影用 `photographerName`/`feeType`）。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 查询导游单层费用明细 | GET | `/v3/admin/order/{orderId}/settlement/guide-fees` | 修改接口 | 出参删 candidateKey/completionState/candidateResolution/sourceActive/pendingCandidateCount |
|
||
| 2 | 全量保存导游单层费用明细 | PUT | `/v3/admin/order/{orderId}/settlement/guide-fees` | 修改接口 | 入参删 candidateKey/completionState/sourceResolution/excludedCandidateKeys，新增 settlementConfirmStatus；改全量替换语义 |
|
||
| 3 | 确认导游单层费用明细 | POST | `/v3/admin/order/{orderId}/settlement/guide-fees/confirm` | 修改接口 | 签名不变（itemIds），确认语义对齐新模型 |
|
||
| 4 | 查询摄影单层费用明细 | GET | `/v3/admin/order/{orderId}/settlement/photographer-fees` | 修改接口 | 同 #1 |
|
||
| 5 | 全量保存摄影单层费用明细 | PUT | `/v3/admin/order/{orderId}/settlement/photographer-fees` | 修改接口 | 同 #2 |
|
||
| 6 | 确认摄影单层费用明细 | POST | `/v3/admin/order/{orderId}/settlement/photographer-fees/confirm` | 修改接口 | 同 #3 |
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 查询导游单层费用明细（GET guide-fees）
|
||
|
||
- **使用场景**：打开核单页「导游」tab 时加载费用明细列表与分类汇总
|
||
- **认证**：管理后台 JWT（房务角色只读拦截，返回 403）
|
||
- **幂等性**：是（只读）
|
||
- **限流**：无
|
||
|
||
**入参**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| orderId | Long（路径参数） | ✅ | 订单 ID，必须大于 0 |
|
||
|
||
**出参**（`Result<SettlementGuideFeesRespVO>`）
|
||
|
||
响应级字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category | String | 核算分类，恒为 `GUIDE` |
|
||
| totalAmount | String | 纳入核算的费用合计，金额字符串，如 `500.00` |
|
||
| cashPaidAmount | String | 现付费用合计，金额字符串 |
|
||
| unconfirmedCount | Integer | 未确认明细数（全行口径，见 §10.2） |
|
||
| settlementReady | Boolean | 是否满足本分类提交核单条件 |
|
||
| blockReasonCode | String | 阻断原因码；无阻断时为 null，取值见 §6.4 |
|
||
| items | Array | 费用明细数组；无数据返回空数组 |
|
||
| editable | Boolean | 当前订单是否允许编辑本分类 |
|
||
| readOnlyReasonCode | String | 只读原因码；可编辑时为 null |
|
||
|
||
items[] 行字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String | 费用明细 ID（Long 序列化为字符串）；未落库的预填草稿行为 null |
|
||
| staffAssignmentId | String | 人员分配 ID；手工新增行为 null |
|
||
| serviceDate | String | 服务日期 `YYYY-MM-DD`；预填草稿行为 null |
|
||
| name | String | 导游姓名 |
|
||
| serviceType | String | 服务类型，取值见 §6.1 |
|
||
| serviceTypeName | String | 服务类型中文名；serviceType 为 null 时为 null |
|
||
| paymentMethod | String | 付款方式，取值见 §6.3 |
|
||
| paymentMethodName | String | 付款方式中文名；paymentMethod 为 null 时为 null |
|
||
| amount | String | 金额字符串；预填草稿行为 null |
|
||
| settlementConfirmStatus | String | 核单确认状态，取值见 §6.5 |
|
||
| settlementConfirmStatusName | String | 核单确认状态中文名 |
|
||
| remark | String | 备注；无备注为 null |
|
||
| sourceType | String | 来源类型：`STAFF_ASSIGNMENT` 人员安排 / `MANUAL` 手工 / `SYSTEM` 系统 |
|
||
| sourceTypeName | String | 来源类型中文名 |
|
||
| voucherUrls | Array<String> | 凭证 URL；无凭证返回空数组 |
|
||
|
||
**错误码**：见 §7 全组共用错误码表。
|
||
|
||
**业务边界**：首次查询（订单尚无该角色核单行）时，返回按订单人员分配预填的草稿行（不落库，行特征：`id` 为 null、`settlementConfirmStatus=UNCONFIRMED`）；这些预填行会被计入 `unconfirmedCount`，影响 `settlementReady` 展示口径。
|
||
|
||
**示例（典型成功）**
|
||
|
||
请求：
|
||
```
|
||
GET /v3/admin/order/12345/settlement/guide-fees
|
||
Authorization: Bearer {admin-token}
|
||
（无请求体）
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"category": "GUIDE",
|
||
"totalAmount": "800.00",
|
||
"cashPaidAmount": "300.00",
|
||
"unconfirmedCount": 1,
|
||
"settlementReady": false,
|
||
"blockReasonCode": "ITEMS_UNCONFIRMED",
|
||
"editable": true,
|
||
"readOnlyReasonCode": null,
|
||
"items": [
|
||
{
|
||
"id": "9001",
|
||
"staffAssignmentId": "11",
|
||
"serviceDate": "2026-08-03",
|
||
"name": "导游甲",
|
||
"serviceType": "FULL_COURSE_GUIDE",
|
||
"serviceTypeName": "全陪导游",
|
||
"paymentMethod": "COMPANY_PAID",
|
||
"paymentMethodName": "公司支付",
|
||
"amount": "500.00",
|
||
"settlementConfirmStatus": "CONFIRMED",
|
||
"settlementConfirmStatusName": "已确认",
|
||
"remark": null,
|
||
"sourceType": "STAFF_ASSIGNMENT",
|
||
"sourceTypeName": "人员安排",
|
||
"voucherUrls": []
|
||
},
|
||
{
|
||
"id": "9002",
|
||
"staffAssignmentId": null,
|
||
"serviceDate": "2026-08-04",
|
||
"name": "导游乙",
|
||
"serviceType": "LOCAL_GUIDE",
|
||
"serviceTypeName": "地接导游",
|
||
"paymentMethod": "CASH_PAID",
|
||
"paymentMethodName": "现付",
|
||
"amount": "300.00",
|
||
"settlementConfirmStatus": "UNCONFIRMED",
|
||
"settlementConfirmStatusName": "未确认",
|
||
"remark": "现场临时请的地陪",
|
||
"sourceType": "MANUAL",
|
||
"sourceTypeName": "手工",
|
||
"voucherUrls": ["https://oss.example.com/voucher/a.jpg"]
|
||
}
|
||
]
|
||
},
|
||
"msg": "",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
**示例（边界：首次查询返回预填草稿行）**
|
||
|
||
场景说明：订单分配了 1 名导游但从未保存过核单行，GET 返回不落库的预填草稿（`id`/`serviceDate`/`amount` 为 null）。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"category": "GUIDE",
|
||
"totalAmount": "0.00",
|
||
"cashPaidAmount": "0.00",
|
||
"unconfirmedCount": 1,
|
||
"settlementReady": false,
|
||
"blockReasonCode": "ITEMS_UNCONFIRMED",
|
||
"editable": true,
|
||
"readOnlyReasonCode": null,
|
||
"items": [
|
||
{
|
||
"id": null,
|
||
"staffAssignmentId": "11",
|
||
"serviceDate": null,
|
||
"name": "导游甲",
|
||
"serviceType": null,
|
||
"serviceTypeName": null,
|
||
"paymentMethod": null,
|
||
"paymentMethodName": null,
|
||
"amount": null,
|
||
"settlementConfirmStatus": "UNCONFIRMED",
|
||
"settlementConfirmStatusName": "未确认",
|
||
"remark": null,
|
||
"sourceType": "STAFF_ASSIGNMENT",
|
||
"sourceTypeName": "人员安排",
|
||
"voucherUrls": []
|
||
}
|
||
]
|
||
},
|
||
"msg": "",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 3.2 全量保存导游单层费用明细（PUT guide-fees）
|
||
|
||
- **使用场景**：在「导游」tab 编辑完费用明细后整体保存（新增 / 修改 / 删除行都通过本接口一次性提交）
|
||
- **认证**：管理后台 JWT
|
||
- **幂等性**：是（全量替换语义，同一 body 重放结果一致）
|
||
- **限流**：无
|
||
|
||
**入参**
|
||
|
||
路径参数：`orderId`（Long，必填，订单 ID）。
|
||
|
||
请求体字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||
|------|------|------|------|----------|
|
||
| items | Array<ItemVO> | ✅ | 导游费用明细**全量集合**（当前应存在的全部行） | 最多 200 条，超出报 584121 |
|
||
|
||
ItemVO 字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||
|------|------|------|------|----------|
|
||
| id | String | ❌ | 费用明细 ID；已存在行必传，新增行不传 | 必须传字符串形式 |
|
||
| staffAssignmentId | String | ❌ | 人员分配 ID；关联人员分配的行传 | 非空时必须属本单且角色为导游，否则报 584115 |
|
||
| serviceDate | String | ❌ | 服务日期 `YYYY-MM-DD` | 必须在订单行程范围内，否则报 584112；订单出发/返程日期缺失时报 584123 |
|
||
| name | String | ❌ | 导游姓名 | 最长 64 字符 |
|
||
| serviceType | String | ❌ | 服务类型 | 取值见 §6.1，非法值报 584113 |
|
||
| paymentMethod | String | ❌ | 付款方式 | 取值见 §6.3 |
|
||
| amount | String | ❌ | 金额字符串 | 0 至 99999999.99 且最多两位小数，否则报 584114 |
|
||
| remark | String | ❌ | 备注；无备注传 null | 最长 500 字符 |
|
||
| voucherUrls | Array<String> | ❌ | 凭证 URL | 最多 9 个，单条最长 1024；重复值去重并保持首次出现顺序 |
|
||
| settlementConfirmStatus | String | ❌ | 核单确认状态；**缺省/null 按 UNCONFIRMED 处理**，保存时可直接置 CONFIRMED | 仅允许 `UNCONFIRMED` / `CONFIRMED`，其他值报 584128 |
|
||
|
||
**严格模式**：请求体（顶层或行内）出现任何未定义字段一律 400。改前旧字段 `candidateKey` / `completionState` / `sourceResolution` / `excludedCandidateKeys` 现已删除，**传了同样 400**（错误码 584128，msg 形如 `导游或摄影费用请求字段不合法：导游费用明细不支持字段: candidateKey`）。
|
||
|
||
**出参**：同 3.1 的响应结构（保存成功后返回最新全量）。
|
||
|
||
**错误码**：见 §7。
|
||
|
||
**业务边界**（全量替换语义）：
|
||
|
||
- 本次请求传入的 `items` 即保存后的全部行；**库里存在但未传入的未确认行会被删除**；
|
||
- **已 CONFIRMED 行不可删除**——若库里某行已确认但本次未传，报 584120「已确认的有效费用不能直接删除，请先进入编辑状态」，整单保存失败；
|
||
- 已 CONFIRMED 行若本次修改了业务字段（姓名/金额/日期/类型/付款方式等），保存后自动重置回 `UNCONFIRMED`，需重新确认；
|
||
- 新增行可在保存时直接置 `CONFIRMED`（与酒店/门票 tab 行为一致）。
|
||
|
||
**示例（典型成功：两行全量保存，一行直接置已确认）**
|
||
|
||
请求：
|
||
```json
|
||
PUT /v3/admin/order/12345/settlement/guide-fees
|
||
Authorization: Bearer {admin-token}
|
||
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "9001",
|
||
"staffAssignmentId": "11",
|
||
"serviceDate": "2026-08-03",
|
||
"name": "导游甲",
|
||
"serviceType": "FULL_COURSE_GUIDE",
|
||
"paymentMethod": "COMPANY_PAID",
|
||
"amount": "500.00",
|
||
"remark": null,
|
||
"voucherUrls": [],
|
||
"settlementConfirmStatus": "CONFIRMED"
|
||
},
|
||
{
|
||
"serviceDate": "2026-08-04",
|
||
"name": "导游乙",
|
||
"serviceType": "LOCAL_GUIDE",
|
||
"paymentMethod": "CASH_PAID",
|
||
"amount": "300.00",
|
||
"remark": "现场临时请的地陪",
|
||
"voucherUrls": ["https://oss.example.com/voucher/a.jpg"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应：`code=200`，`data` 为保存后的最新全量（结构同 3.1 响应示例）。
|
||
|
||
**示例（业务失败：误传已删除的旧字段）**
|
||
|
||
场景说明：前端未清理旧逻辑，行内仍带 `candidateKey`。
|
||
|
||
请求：
|
||
```json
|
||
PUT /v3/admin/order/12345/settlement/guide-fees
|
||
|
||
{
|
||
"items": [
|
||
{
|
||
"candidateKey": "2026-08-03#11",
|
||
"name": "导游甲",
|
||
"amount": "500.00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 584128,
|
||
"data": null,
|
||
"msg": "导游或摄影费用请求字段不合法：导游费用明细不支持字段: candidateKey",
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
**示例（业务失败：已确认行被全量替换遗漏）**
|
||
|
||
场景说明：库中行 9001 已 CONFIRMED，本次 items 只传了行 9002，相当于要删掉 9001。
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 584120,
|
||
"data": null,
|
||
"msg": "已确认的有效费用不能直接删除，请先进入编辑状态",
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
### 3.3 确认导游单层费用明细（POST guide-fees/confirm）
|
||
|
||
- **使用场景**：勾选若干未确认行后点「确认」，将这批行批量置为已确认
|
||
- **认证**：管理后台 JWT
|
||
- **幂等性**：是（对已确认行重复确认无副作用）
|
||
- **限流**：无
|
||
|
||
**入参**
|
||
|
||
路径参数：`orderId`（Long，必填）。
|
||
|
||
请求体字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||
|------|------|------|------|----------|
|
||
| itemIds | Array<String> | ✅ | 待确认的费用明细 ID 列表，JSON 中每项为字符串 | 1 至 200 条；ID 不存在或不属于本订单及导游角色报 584111 |
|
||
|
||
同样走严格模式，多传字段报 584128（msg 形如 `导游费用确认请求不支持字段: xxx`）。
|
||
|
||
**出参**：同 3.1 的响应结构（确认后的最新全量）。
|
||
|
||
**示例（典型成功）**
|
||
|
||
请求：
|
||
```json
|
||
POST /v3/admin/order/12345/settlement/guide-fees/confirm
|
||
Authorization: Bearer {admin-token}
|
||
|
||
{
|
||
"itemIds": ["9002"]
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"category": "GUIDE",
|
||
"totalAmount": "800.00",
|
||
"cashPaidAmount": "300.00",
|
||
"unconfirmedCount": 0,
|
||
"settlementReady": true,
|
||
"blockReasonCode": null,
|
||
"editable": true,
|
||
"readOnlyReasonCode": null,
|
||
"items": [
|
||
{
|
||
"id": "9002",
|
||
"staffAssignmentId": null,
|
||
"serviceDate": "2026-08-04",
|
||
"name": "导游乙",
|
||
"serviceType": "LOCAL_GUIDE",
|
||
"serviceTypeName": "地接导游",
|
||
"paymentMethod": "CASH_PAID",
|
||
"paymentMethodName": "现付",
|
||
"amount": "300.00",
|
||
"settlementConfirmStatus": "CONFIRMED",
|
||
"settlementConfirmStatusName": "已确认",
|
||
"remark": "现场临时请的地陪",
|
||
"sourceType": "MANUAL",
|
||
"sourceTypeName": "手工",
|
||
"voucherUrls": ["https://oss.example.com/voucher/a.jpg"]
|
||
}
|
||
]
|
||
},
|
||
"msg": "",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 3.4 查询摄影单层费用明细（GET photographer-fees）
|
||
|
||
- **使用场景**：打开核单页「摄影」tab 时加载费用明细列表与分类汇总
|
||
- **认证 / 幂等 / 限流**：同 3.1
|
||
|
||
**入参**：同 3.1（`orderId` 路径参数）。
|
||
|
||
**出参**（`Result<SettlementPhotographerFeesRespVO>`）：响应级字段与 3.1 完全一致（`category` 恒为 `PHOTOGRAPHER`），items[] 行字段仅以下差异，其余字段同 3.1：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| photographerName | String | 摄影姓名（对应导游组的 `name`） |
|
||
| feeType | String | 摄影费用类型，取值见 §6.2 |
|
||
| feeTypeName | String | 摄影费用类型中文名；feeType 为 null 时为 null |
|
||
|
||
（行内不再有 `name` / `serviceType` / `serviceTypeName`。）
|
||
|
||
**示例（典型成功）**
|
||
|
||
请求：
|
||
```
|
||
GET /v3/admin/order/12345/settlement/photographer-fees
|
||
Authorization: Bearer {admin-token}
|
||
（无请求体）
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"category": "PHOTOGRAPHER",
|
||
"totalAmount": "300.00",
|
||
"cashPaidAmount": "0.00",
|
||
"unconfirmedCount": 0,
|
||
"settlementReady": true,
|
||
"blockReasonCode": null,
|
||
"editable": true,
|
||
"readOnlyReasonCode": null,
|
||
"items": [
|
||
{
|
||
"id": "9101",
|
||
"staffAssignmentId": "12",
|
||
"serviceDate": "2026-08-03",
|
||
"photographerName": "摄影甲",
|
||
"feeType": "FOLLOW_SHOOT",
|
||
"feeTypeName": "跟拍",
|
||
"paymentMethod": "SIGNED",
|
||
"paymentMethodName": "签单",
|
||
"amount": "300.00",
|
||
"settlementConfirmStatus": "CONFIRMED",
|
||
"settlementConfirmStatusName": "已确认",
|
||
"remark": null,
|
||
"sourceType": "STAFF_ASSIGNMENT",
|
||
"sourceTypeName": "人员安排",
|
||
"voucherUrls": []
|
||
}
|
||
]
|
||
},
|
||
"msg": "",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
首次查询同样返回按人员分配预填的草稿行（不落库，`UNCONFIRMED`），行为同 3.1 边界示例。
|
||
|
||
### 3.5 全量保存摄影单层费用明细（PUT photographer-fees）
|
||
|
||
- **使用场景 / 认证 / 幂等 / 限流**：同 3.2
|
||
|
||
**入参**：结构同 3.2，ItemVO 字段仅以下差异，其余（含 `settlementConfirmStatus`、严格模式、全量替换语义、584120 保护、已确认行编辑自动退回未确认）完全一致：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||
|------|------|------|------|----------|
|
||
| photographerName | String | ❌ | 摄影姓名 | 最长 64 字符 |
|
||
| feeType | String | ❌ | 摄影费用类型 | 取值见 §6.2，非法值报 584113 |
|
||
|
||
（不再有 `name` / `serviceType`；`staffAssignmentId` 非空时角色须为摄影，否则报 584115。）
|
||
|
||
**示例（典型成功）**
|
||
|
||
请求：
|
||
```json
|
||
PUT /v3/admin/order/12345/settlement/photographer-fees
|
||
Authorization: Bearer {admin-token}
|
||
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "9101",
|
||
"staffAssignmentId": "12",
|
||
"serviceDate": "2026-08-03",
|
||
"photographerName": "摄影甲",
|
||
"feeType": "FOLLOW_SHOOT",
|
||
"paymentMethod": "SIGNED",
|
||
"amount": "300.00",
|
||
"settlementConfirmStatus": "CONFIRMED"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应：`code=200`，`data` 为保存后的最新全量（结构同 3.4 响应示例）。
|
||
|
||
**示例（业务失败：金额非法）**
|
||
|
||
请求：
|
||
```json
|
||
PUT /v3/admin/order/12345/settlement/photographer-fees
|
||
|
||
{
|
||
"items": [
|
||
{
|
||
"photographerName": "摄影甲",
|
||
"feeType": "FOLLOW_SHOOT",
|
||
"amount": "-50.00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 584114,
|
||
"data": null,
|
||
"msg": "金额必须为 0 至 99999999.99 且最多两位小数",
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
### 3.6 确认摄影单层费用明细（POST photographer-fees/confirm）
|
||
|
||
- **使用场景 / 认证 / 幂等 / 限流**：同 3.3
|
||
|
||
**入参**：同 3.3（`itemIds` 字符串数组，1-200 条；ID 不存在或不属于本订单及摄影角色报 584111；多传字段报 584128，msg 形如 `摄影费用确认请求不支持字段: xxx`）。
|
||
|
||
**出参**：同 3.4 的响应结构。
|
||
|
||
**示例（典型成功）**
|
||
|
||
请求：
|
||
```json
|
||
POST /v3/admin/order/12345/settlement/photographer-fees/confirm
|
||
Authorization: Bearer {admin-token}
|
||
|
||
{
|
||
"itemIds": ["9101"]
|
||
}
|
||
```
|
||
|
||
响应：`code=200`，`data` 中该行 `settlementConfirmStatus` 变为 `CONFIRMED`、`unconfirmedCount` 相应减少（结构同 3.4 响应示例）。
|
||
|
||
## 4. 接口入参
|
||
|
||
已按接口分散在 §3.1 ~ §3.6 各自小节内（本组为多接口 changelog，入参不单独集中成节）。
|
||
|
||
## 5. 出参（响应）
|
||
|
||
已按接口分散在 §3.1 ~ §3.6 各自小节内。
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
### 6.1 serviceType（导游服务类型）
|
||
|
||
**所属字段**：导游组 ItemVO 的 `serviceType` | **类型**：`String` | **必填**：❌
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `FULL_COURSE_GUIDE` | 全陪导游 | — |
|
||
| `LOCAL_GUIDE` | 地接导游 | — |
|
||
| `COMMENTARY_SERVICE` | 讲解服务 | — |
|
||
| `TEMPORARY_SUPPLEMENT` | 临时补录 | — |
|
||
|
||
### 6.2 feeType（摄影费用类型）
|
||
|
||
**所属字段**：摄影组 ItemVO 的 `feeType` | **类型**：`String` | **必填**：❌
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `FOLLOW_SHOOT` | 跟拍 | — |
|
||
| `PORTRAIT` | 写真 | — |
|
||
| `AERIAL_SHOOT` | 航拍 | — |
|
||
| `EDITING_DELIVERY` | 剪辑出片 | — |
|
||
| `CAMERA_DRONE` | 相机/无人机 | — |
|
||
| `OTHER` | 其他 | — |
|
||
|
||
### 6.3 paymentMethod（付款方式）
|
||
|
||
**所属字段**：两组 ItemVO 的 `paymentMethod` | **类型**：`String` | **必填**：❌
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `COMPANY_PAID` | 公司支付 | — |
|
||
| `CASH_PAID` | 现付 | 计入 `cashPaidAmount` |
|
||
| `SIGNED` | 签单 | — |
|
||
|
||
### 6.4 blockReasonCode（阻断原因码）
|
||
|
||
**所属字段**：响应级 `blockReasonCode` | **类型**：`String` | **必填**：❌（无阻断时为 null）
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `ORDER_DATE_INCOMPLETE` | 订单日期不完整 | 订单出发或返程日期缺失，无法校验服务日期 |
|
||
| `ITEMS_UNCONFIRMED` | 存在未确认明细 | 存在 `UNCONFIRMED` 行（含预填草稿行），不满足提交核单条件 |
|
||
|
||
> ⚠️ 本次变更**删除**两个旧值：`SOURCE_INACTIVE`、`CANDIDATES_UNRESOLVED`，后端不再返回。
|
||
|
||
### 6.5 settlementConfirmStatus（核单确认状态）
|
||
|
||
**所属字段**：两组 ItemVO 的 `settlementConfirmStatus`（入参 + 出参） | **类型**：`String` | **必填**：❌（入参缺省按 UNCONFIRMED）
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `UNCONFIRMED` | 未确认 | 可被全量替换删除 |
|
||
| `CONFIRMED` | 已确认 | 不可删除；编辑业务字段自动退回 UNCONFIRMED |
|
||
|
||
## 7. 错误码
|
||
|
||
| code | 含义 | 触发场景 |
|
||
|------|------|----------|
|
||
| 584111 | 费用明细不存在或不属于当前订单及角色 | confirm 的 itemIds 含不存在/他单/角色不符的行 |
|
||
| 584112 | 服务日期不在订单行程范围内 | 保存时 serviceDate 超出订单出发~返程日期 |
|
||
| 584113 | 服务类型或摄影费用类型不合法 | serviceType / feeType 传了枚举外值 |
|
||
| 584114 | 金额必须为 0 至 99999999.99 且最多两位小数 | amount 为负数、超限或小数位超过 2 位 |
|
||
| 584115 | 人员分配不存在、角色不匹配或来源已失效 | staffAssignmentId 非空但不属本单，或角色不匹配（导游组传了摄影人员等） |
|
||
| 584120 | 已确认的有效费用不能直接删除，请先进入编辑状态 | 全量保存时遗漏了库里已 CONFIRMED 的行 |
|
||
| 584121 | 单个导游或摄影分类最多 200 条明细 | items 超过 200 条 |
|
||
| 584123 | 订单出发或返程日期缺失，无法校验服务日期 | 保存时订单日期不完整且传了 serviceDate |
|
||
| 584125 | 导游或摄影费用请求字段不合法 | 请求体缺失或整体解析失败（无具体字段原因时） |
|
||
| 584128 | 导游或摄影费用请求字段不合法：{0} | 请求体（顶层或行内）出现未定义字段（含已删除的旧字段 candidateKey / completionState / sourceResolution / excludedCandidateKeys）；msg 带具体字段名 |
|
||
|
||
## 8. 示例（典型 / 边界 / 异常）
|
||
|
||
已按接口分散在 §3.1 ~ §3.6 各自小节内，每组示例均含请求 + 响应：
|
||
|
||
- 典型成功：§3.1 / §3.2 / §3.3 / §3.4 / §3.5 / §3.6
|
||
- 边界（首次查询预填草稿行，id/serviceDate/amount 为 null）：§3.1 第二组示例
|
||
- 业务失败（584128 旧字段误传 / 584120 已确认行误删 / 584114 金额非法）：§3.2 / §3.5
|
||
|
||
## 9. 业务边界
|
||
|
||
- ✅ **适用场景**：订单核单进行中（editable=true）时可调保存/确认接口；查询接口在核单各阶段均可调（只读阶段 editable=false + readOnlyReasonCode 指明原因）
|
||
- ❌ **不适用场景**：订单已提交核单终态后，保存/确认接口被拒（editable=false 时调用按只读规则拦截）；房务角色（house）调本组接口返回 403
|
||
- ⚠️ **特殊边界 1（预填草稿行）**：首次 GET 返回的草稿行不落库（id 为 null），但计入 `unconfirmedCount` 影响 `settlementReady` 展示；而「完成核单」的提交门禁只查已落库行，两个口径有意分离（展示口径 ≠ 提交口径）
|
||
- ⚠️ **特殊边界 2（已确认行保护）**：已 CONFIRMED 行想删除，必须先修改该行业务字段使其退回 UNCONFIRMED（或走反确认流程），再在下一轮全量保存中不传该行
|
||
- ⚠️ **特殊边界 3（金额 0）**：amount 允许 `0.00`，不被非负校验拦截
|
||
|
||
## 10. 修改前后对比
|
||
|
||
### 10.1 字段级对比
|
||
|
||
保存入参（PUT，ItemVO 行内）：
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| candidateKey | 有，候选行标识 | **删除**，传了报 400（584128） |
|
||
| completionState | 有（NEEDS_INPUT/COMPLETE/EXCLUDED） | **删除**，传了报 400（584128） |
|
||
| sourceResolution | 有，来源处理结果 | **删除**，传了报 400（584128） |
|
||
| settlementConfirmStatus | 无 | **新增**，非必填，UNCONFIRMED/CONFIRMED，缺省按 UNCONFIRMED |
|
||
|
||
保存入参（PUT，请求体顶层）：
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| excludedCandidateKeys | 有，排除候选 key 清单 | **删除**，传了报 400（584128） |
|
||
|
||
查询出参（GET，ItemVO 行内）：
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| candidateKey | 有 | **删除**，不再下发 |
|
||
| completionState | 有 | **删除**，不再下发 |
|
||
| candidateResolution | 有（INCLUDED/EXCLUDED/UNRESOLVED） | **删除**，不再下发 |
|
||
| sourceActive | 有 | **删除**，不再下发 |
|
||
| settlementConfirmStatus / settlementConfirmStatusName | 有（仅展示） | 保留，语义不变 |
|
||
|
||
查询出参（GET，响应级）：
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| pendingCandidateCount | 有，未处理候选数 | **删除**，不再下发 |
|
||
| blockReasonCode 值域 | 含 `SOURCE_INACTIVE`、`CANDIDATES_UNRESOLVED` | **删除这两个值**，只保留 `ORDER_DATE_INCOMPLETE`、`ITEMS_UNCONFIRMED` |
|
||
|
||
### 10.2 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 保存语义 | 候选机制：行按 candidateKey 对齐候选，配合 excludedCandidateKeys 声明排除 | **全量替换**：items 即保存后的全部行，未传的未确认行删除 |
|
||
| 确认入口 | 只能通过 confirm 接口把 INCLUDED 行置已确认 | confirm 接口保留；**保存时也可直接置 CONFIRMED**（settlementConfirmStatus 入参） |
|
||
| 已确认行删除 | 通过 excludedCandidateKeys 排除 | 不可删：全量保存遗漏已确认行报 584120 |
|
||
| 已确认行编辑 | 编辑后走候选重算 | 编辑业务字段**自动退回 UNCONFIRMED**，需重新确认 |
|
||
| unconfirmedCount 口径 | 未确认的 INCLUDED 明细数 | 未确认明细数（全行口径，含预填草稿行） |
|
||
| 未处理候选 | 前端要处理 UNRESOLVED 候选（pendingCandidateCount > 0 阻断提交） | 机制删除，无此概念 |
|
||
| 旧字段容错 | 未知字段按 Jackson 默认处理 | **严格模式**：任何未定义字段（含全部旧字段）一律 400 |
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
### 11.1 影响评估
|
||
|
||
- **是否破坏向后兼容**：**是**。保存接口传旧字段（candidateKey / completionState / sourceResolution / excludedCandidateKeys）从「生效」变为「一律 400」；查询出参删 5 个字段；blockReasonCode 删 2 个枚举值。
|
||
- **前端是否必须同步上线**：**是**。导游/摄影 tab 的保存请求必须清掉旧字段，否则保存全部 400；出参侧引用 candidateKey / completionState / candidateResolution / sourceActive / pendingCandidateCount 的渲染与逻辑必须同步删除。
|
||
|
||
### 11.2 回滚方案
|
||
|
||
- **回滚方式**：后端 revert PR #6119 即可恢复旧候选机制契约；无 DDL、无数据迁移，回滚不涉及数据清理
|
||
- **前端配合**：前端若已按新契约上线，后端回滚时需同步回退前端版本（新旧契约互不兼容）
|
||
|
||
## 12. 注意事项
|
||
|
||
- **前端 workaround 清理点**：此前为候选机制写的 workaround 可全部删除——按 candidateKey 对齐行的本地映射、excludedCandidateKeys 的收集逻辑、对 candidateResolution=UNRESOLVED 行的特殊渲染、等待 pendingCandidateCount 归零的轮询/重试逻辑
|
||
- **行内确认状态直接用 settlementConfirmStatus**：新模型下「行是否已确认」只看 `settlementConfirmStatus`，不要再拼接 completionState + candidateResolution 推断
|
||
- **保存即全量**：局部更新场景也必须先 GET 拿全量、改完整体 PUT，缺行等于删行（未确认行）
|
||
- **ID 一律字符串**：入参 id / staffAssignmentId / itemIds 均传字符串形式；出参 id / staffAssignmentId 也是字符串，不要按 Number 解析
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
### 13.1 链接
|
||
|
||
- **Issue**: [#6117](https://git.1814.love:8443/wx/HL/issues/6117)
|
||
- **PR**: [#6119](https://git.1814.love:8443/wx/HL/pulls/6119)
|
||
- **Merge commit**: [27ac77b500](https://git.1814.love:8443/wx/HL/commit/27ac77b500ff53496432a0e6e869dc96669e8f24)
|
||
|
||
### 13.2 联系人
|
||
|
||
- **后端负责人**: @yst（腰苏图）
|