wx/hl-api-changelog

派生 0

文件

T

yaosutu 3c0a8ce1a7

changelog-filename-gate / validate (push) Failing after 2s

详情

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

2026-08-22 15:28:41 +08:00

7.8 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6168	导游/摄影核单确认状态去签名重置——编辑不再自动退回待确认	admin	修改接口	yst	deployed	verified	verified				2026-08-22	PR #6169 已合并 dev-v3（merge commit 22a09e556cfa），测试服已行为级验证。仅行为语义变化、字段签名不变：导游/摄影核单删除「编辑已确认行自动重置确认状态」的业务签名机制，保存时确认状态完全由入参 settlementConfirmStatus 决定（传啥存啥），与酒店/门票等其它费用 tab 行为拉齐。入参/出参字段、枚举值均无变化，无 DDL。	2026-08-22	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（待确认）。

这带来两个问题：

入参被忽略——前端/用户明明传了「已确认」，仅因顺手改了备注，状态就被后端悄悄打回「待确认」，语义反直觉；
跨 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. 示例

典型：编辑已确认行的备注，状态保持已确认（新行为）

请求：

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）：

{
  "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 传非法值

{ "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

7.8 KiB 原始文件 Blame 文件历史 Unescape Escape