docs(changelog): 导游/摄影核单确认状态去签名重置-修改接口-管理后台 (#6168)

changelogs-v2/2026-08/22_6168_导游摄影核单确认状态去签名重置-修改接口-管理后台.md

@@ -0,0 +1,175 @@
+---
+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