176 行
7.8 KiB
Markdown
176 行
7.8 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6168"
|
||
title: "导游/摄影核单确认状态去签名重置——编辑不再自动退回待确认"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yst"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: "2026-08-22"
|
||
status_note: "PR #6169 已合并 dev-v3（merge commit 22a09e556cfa），测试服已行为级验证。仅行为语义变化、字段签名不变：导游/摄影核单删除「编辑已确认行自动重置确认状态」的业务签名机制，保存时确认状态完全由入参 settlementConfirmStatus 决定（传啥存啥），与酒店/门票等其它费用 tab 行为拉齐。入参/出参字段、枚举值均无变化，无 DDL。"
|
||
updated_at: "2026-08-22"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 【修改接口·管理后台】导游/摄影核单确认状态去签名重置——编辑不再自动退回待确认（#6168）
|
||
|
||
> **PR**: #6169 | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-22
|
||
|
||
## 1. 接口背景
|
||
|
||
上一版（#6117 / PR #6119）把导游/摄影核单拉齐到「全量替换 + 统一 settlementConfirmStatus」时，给这两个 tab **额外**加了一道其它费用 tab 没有的「**业务签名重置**」机制：
|
||
|
||
> 后端把每行的 `staffId / 金额 / remark / voucherUrls / detail(日期/类型)` 等字段拼成一个"业务签名"，**只要保存时签名和库里有任何差异（哪怕只是改了备注 remark 或传了凭证），就无视入参里显式传的 `settlementConfirmStatus: "CONFIRMED"`，强制把该行确认状态重置回 `UNCONFIRMED`（待确认）**。
|
||
|
||
这带来两个问题：
|
||
|
||
1. **入参被忽略**——前端/用户明明传了「已确认」，仅因顺手改了备注，状态就被后端悄悄打回「待确认」，语义反直觉；
|
||
2. **跨 tab 行为不一致**——酒店/门票/餐饮/车辆/补贴/其它收支等 tab 保存时是「**传啥存啥**」（确认状态原样落库，无任何签名校验），唯独导游/摄影多一道隐式重置闸，前端对接逻辑要区别对待。
|
||
|
||
本次变更**删除该签名重置机制**，导游/摄影确认状态逻辑与其它 6 个费用 tab 完全拉齐。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 保存导游单层费用明细 | PUT | `/v3/admin/order/{orderId}/settlement/guide-fees` | 修改接口 | 行为变化：编辑已确认行不再自动重置确认状态 |
|
||
| 2 | 保存摄影单层费用明细 | PUT | `/v3/admin/order/{orderId}/settlement/photographer-fees` | 修改接口 | 同上 |
|
||
|
||
> ⚠️ **字段签名零变化**：入参 / 出参字段、`settlementConfirmStatus` 枚举值（`UNCONFIRMED`/`CONFIRMED`）、`unconfirmedCount` / `settlementReady` / `blockReasonCode` 等聚合字段**全部不变**。变的只有「编辑已确认行时确认状态是否被自动重置」这一个**行为语义**。
|
||
|
||
## 3. 接口详情
|
||
|
||
两个保存接口均为「全量替换」语义（与 #6117 一致，本次未改），传入当前应存在的全部行。
|
||
|
||
## 4. 入参
|
||
|
||
无变化。每行 `settlementConfirmStatus` 仍为非必填，枚举 `UNCONFIRMED` / `CONFIRMED`。
|
||
|
||
## 5. 出参
|
||
|
||
无变化。
|
||
|
||
## 6. 确认状态落库规则（本次唯一变化点）
|
||
|
||
### 修改前（旧：签名重置）
|
||
|
||
| 场景 | 落库确认状态 |
|
||
|---|---|
|
||
| 新增行，入参 null | `UNCONFIRMED`（默认） |
|
||
| 新增行，入参有值 | 入参值 |
|
||
| 编辑行，**业务签名有变化**（改了 remark/金额/日期/凭证等任一） | **强制 `UNCONFIRMED`，无视入参** ⚠️ |
|
||
| 编辑行，签名未变，入参 null | 保留现值 |
|
||
| 编辑行，签名未变，入参有值 | 入参值 |
|
||
|
||
### 修改后（新：传啥存啥，与酒店/门票一致）
|
||
|
||
| 场景 | 落库确认状态 |
|
||
|---|---|
|
||
| 新增行，入参 null | `UNCONFIRMED`（默认） |
|
||
| 新增行，入参有值 | 入参值 |
|
||
| 编辑行，入参 null | **保留现值**（不再重置） |
|
||
| 编辑行，入参有值 | **入参值**（不再重置） |
|
||
|
||
**核心差异**：删掉了「编辑已确认行 → 业务签名变化 → 强制重置 UNCONFIRMED」这条分支。现在编辑任何字段（含备注 remark、凭证 voucherUrls、金额、日期）都**不会**触碰确认状态，确认状态完全由入参决定。
|
||
|
||
## 7. 错误码
|
||
|
||
无新增 / 无删除。`settlementConfirmStatus` 非法值仍报 `SETTLEMENT_CONFIRM_STATUS_INVALID`。
|
||
|
||
## 8. 示例
|
||
|
||
### 典型：编辑已确认行的备注，状态保持已确认（新行为）
|
||
|
||
请求：
|
||
```http
|
||
PUT /v3/admin/order/{orderId}/settlement/guide-fees
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "2090634300167766018",
|
||
"serviceDate": "2026-08-29",
|
||
"name": "李雪梅",
|
||
"serviceType": "FULL_COURSE_GUIDE",
|
||
"paymentMethod": "CASH_PAID",
|
||
"amount": "100.00",
|
||
"remark": "已确认行-改了备注",
|
||
"voucherUrls": [],
|
||
"settlementConfirmStatus": "CONFIRMED"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应（关键：status 保持 CONFIRMED，**旧逻辑会被重置成 UNCONFIRMED**）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": "2090634300167766018",
|
||
"name": "李雪梅",
|
||
"remark": "已确认行-改了备注",
|
||
"settlementConfirmStatus": "CONFIRMED",
|
||
"settlementConfirmStatusName": "已确认",
|
||
"amount": "100.00"
|
||
}
|
||
],
|
||
"unconfirmedCount": 0,
|
||
"settlementReady": true,
|
||
"blockReasonCode": null
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 边界：编辑行不传 settlementConfirmStatus（null）→ 保留现值
|
||
|
||
若该行原状态为 `CONFIRMED`，本次保存入参不传 `settlementConfirmStatus`（或传 null），保存后仍为 `CONFIRMED`。
|
||
|
||
### 异常：settlementConfirmStatus 传非法值
|
||
|
||
```json
|
||
{ "code": 584xxx, "message": "确认状态非法", "success": false }
|
||
```
|
||
（传 `UNCONFIRMED` / `CONFIRMED` 之外的值时报 `SETTLEMENT_CONFIRM_STATUS_INVALID`）
|
||
|
||
## 9. 业务边界
|
||
|
||
- 「已 CONFIRMED 行不能被全量替换顺手删除」的守卫**保留不变**（删已确认行仍报 `STAFF_FEE_CONFIRMED_DELETE_FORBIDDEN`）；本次只删「编辑重置」，没删「禁删」。
|
||
- 若业务上确实需要「改金额后强制重确认」，由**前端在编辑关键字段后主动把该行 `settlementConfirmStatus` 传 `UNCONFIRMED`** 来实现，后端不再隐式代劳。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
| 维度 | 修改前 | 修改后 |
|
||
|---|---|---|
|
||
| 编辑已确认行（改备注/金额等） | 确认状态强制退回 UNCONFIRMED，入参 CONFIRMED 被忽略 | 确认状态按入参/现值，不自动退回 |
|
||
| 与其它费用 tab 一致性 | 导游/摄影独有一道签名重置闸 | 6+ 个 tab 行为完全统一 |
|
||
| 前端对接 | 需预知「编辑会被重置」的隐式行为 | 传啥存啥，无需特殊处理 |
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
- **影响面**：仅导游/摄影两个保存接口的确认状态落库语义；字段契约不变，前端无需改字段映射。
|
||
- **前端注意**：若此前针对「编辑已确认行会自动退回待确认」做过 UI 提示（如编辑后弹"需重新确认"），该提示触发条件已不存在，建议移除。
|
||
- **回滚**：`git revert 22a09e556cfa`（merge commit）即可恢复签名重置机制；无 DDL，纯代码。
|
||
|
||
## 12. 注意事项
|
||
|
||
- 本变更不改变任何字段名 / 类型 / 枚举值，OpenAPI（Knife4j）文档无需改动字段定义。
|
||
- 测试服已行为级验证：编辑已确认行（改 remark）+ 显式传 `CONFIRMED`，GET 复查保持 `CONFIRMED`、`unconfirmedCount=0`、`settlementReady=true`。
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
- Issue: https://git.1814.love:8443/wx/HL/issues/6168
|
||
- PR: https://git.1814.love:8443/wx/HL/pulls/6169
|
||
- merge commit: https://git.1814.love:8443/wx/HL/commit/22a09e556cfa
|
||
- 前序重构: Issue #6117 / PR #6119
|
||
- 负责人: yst
|