docs(changelog): 核单 finalize warnings 结构化带行id + summary 新增 settled 标识（#5876 / PR #5881）管理后台

2026-08-12 09:12:35 +08:00 · 2026-08-12 09:12:35 +08:00 · d1e98fa028
--- a/changelogs-v2/2026-08/12_5876_核单finalize-summary出参整改-修改接口-管理后台.md
+++ b/changelogs-v2/2026-08/12_5876_核单finalize-summary出参整改-修改接口-管理后台.md
@ -0,0 +1,470 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5876"
+title: "核单 finalize warnings 结构化带行id + summary 新增 settled 标识（warnings 出参破坏性变更）"
+consumer: "admin"
+change_type: "修改接口"
+author: "yst"
+backend_status: "deployed"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端 PR #5881 已 merge 到 dev-v3 并部署测试服。finalize 出参 warnings 由字符串数组改为对象数组（破坏性，按字符串渲染的前端必须改读 message 字段）；summary 出参新增 settled 字段，判是否已核单改读 settled，不要再判 id==null。"
+updated_at: "2026-08-12"
+base: "dev-v3"
+---
+
+# 【⚠️ 修改接口·管理后台】核单 finalize warnings 结构化 + summary 新增 settled 标识（#5876）
+
+## 1. 接口背景
+
+核单结算域的两个管理后台接口：
+
+1. **完成核单 finalize**：核单页点「完成核单」时提交，原子冻结核单事实并生成核单汇总。出参带 `warnings` 软预警（现付缺凭证等，不阻塞提交），前端用于提示定制师补传凭证。
+2. **核单汇总快照 summary**：核单页 / 财务报表页读取整单金额、成本、毛利汇总。
+
+本次整改两个出参可读性问题：
+
+1. **warnings 无法定位行**（旧结构）：warnings 是 `List<String>`，文案形如「住宿 D2 现付缺凭证」。同一天有多条住宿/门票明细时，前端拿到的多条文案完全相同，无法区分是哪一行缺凭证，也无法跳转/锚定到具体明细行。
+2. **summary 空壳无法可靠判空**（旧行为）：订单未核单时接口返回一个空壳对象，此前前端用 `id == null` 判「尚未核单」，但 `advanceSummary` 字段恒有默认空对象（不是 null），单靠字段判空容易误判。
+
+## 2. 变更清单
+
+| # | 变更 | 类型 |
+|---|------|------|
+| 1 | finalize 出参 `warnings` 由 `List<String>` 改为 `List<WarningItemVO>`（每条带 settlementId / category / dayNumber / message） | ⚠️ 破坏性 |
+| 2 | summary 出参新增 `settled` 字段（Boolean）：已核单 = true，未核单空壳 = false | ✨ 新增字段 |
+
+无入参变化、无删除字段、无 DDL。
+
+## 3. 接口详情
+
+### 3.1 完成核单
+
+| 项 | 值 |
+|---|---|
+| 方法 + 路径 | POST /v3/admin/order/{orderId}/settlement/finalize |
+| 接口名 | 完成核单 |
+| 使用场景 | 管理后台核单页，明细核对完成后提交，原子冻结核单事实并生成核单汇总快照 |
+| 认证 | 管理后台 JWT（/v3/admin/* 走网关鉴权） |
+| 角色限制 | 房务角色（HOUSE）不可访问，调了会被 403 拦截 |
+| 幂等性 | 非幂等写操作；重复提交会被「缺少核单终态快照 / 快照已变化」类错误码拦截，前端不要自动重试 |
+| 限流 | 走网关默认限流，无接口级特殊限流 |
+
+### 3.2 查核单汇总快照
+
+| 项 | 值 |
+|---|---|
+| 方法 + 路径 | GET /v3/admin/order/{orderId}/settlement/summary |
+| 接口名 | 查核单汇总快照 |
+| 使用场景 | 管理后台核单页 / 财务报表页读取整单金额、成本、毛利汇总 |
+| 认证 | 管理后台 JWT |
+| 角色限制 | 无接口级角色限制（网关鉴权通过即可） |
+| 幂等性 | 只读查询，幂等 |
+| 限流 | 走网关默认限流 |
+
+## 4. 接口入参
+
+### 4.1 路径参数
+
+| 接口 | 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| finalize | orderId | Long | 是 | 订单 ID，必须大于 0（否则 400「订单 ID 必须大于 0」） |
+| summary | orderId | Long | 是 | 订单 ID |
+
+### 4.2 请求体 / Query
+
+两个接口均无请求体、无 Query 参数。
+
+## 5. 出参字段
+
+### 5.1 finalize 出参（Result<SettlementSubmitRespVO>，本次仅 warnings 变化）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| summaryId | Long(String) | 新写入的 settlement_summary 主键，序列化为字符串 |
+| finalSnapshotId | Long(String) | 核单终态快照 ID，序列化为字符串 |
+| finalSnapshotVersionNo | Integer | 核单终态快照版本号 |
+| finalSnapshotStatus | String | 核单终态快照状态，固定 FINALIZED |
+| orderId | Long(String) | 订单 ID，序列化为字符串 |
+| settledAt | String | 核单完成时间，格式 yyyy-MM-ddTHH:mm:ss |
+| totalAmount | String | 订单总金额快照（BigDecimal 序列化为字符串，下同） |
+| paidAmount | String | 已付金额快照 |
+| balanceAmount | String | 尾款金额快照 |
+| roomCost | String | 住宿实际成本 |
+| ticketCost | String | 门票实际成本 |
+| staffCost | String | 人员费用实际成本 |
+| subsidyCost | String | 补助实际成本 |
+| mealCost | String | 餐食实际成本 |
+| vehicleCost | String | 车辆基础服务总车费 |
+| otherExpenseCost | String | 其他支出实际成本 |
+| insurancePremium | String | 保险实际保费（未出单/已撤单 = 0） |
+| totalActualCost | String | 总实际成本 |
+| driverTransferAmount | String | 给司机/主报账人转回金额（有付款类型的分类仅计 CASH_PAID，不含保险） |
+| profitAmount | String | 公司毛利 = totalAmount - totalActualCost |
+| profitRate | Number | 毛利率（小数，totalAmount=0 时填 0） |
+| orderStatusAfter | String | 结算后订单状态，如「待财务复核」 |
+| mqTriggered | Boolean | 当前版本固定 false；完成核单不发布结算 MQ |
+| warnings | Array<WarningItemVO> | **本次变更**：软预警对象数组（原来为字符串数组）；无预警时为空数组 [] |
+
+**WarningItemVO 字段表**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| settlementId | Long(String) | 触发预警的核单明细行 id（settlement_hotel / settlement_ticket 主键），序列化为字符串；前端据此锚定/跳转具体明细行 |
+| category | String | 核单分类枚举名，当前仅 HOTEL（住宿）/ TICKET（门票/游玩项目）两类会触发预警 |
+| dayNumber | Integer | 行程第几天 |
+| message | String | 预警文案，与旧字符串元素一致，如「住宿 D2 现付缺凭证」 |
+
+### 5.2 summary 出参（Result<SettlementSummaryRespVO>，本次新增 settled）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| settled | Boolean | **本次新增**：是否已核单。summary 快照存在 = true；未核单空壳 = false |
+| id | Long | settlement_summary 主键；未核单时为 null |
+| orderId | Long | 订单 ID；空壳时也有值 |
+| totalAmount | String | 订单总金额快照（BigDecimal 序列化为字符串，下同） |
+| paidAmount | String | 已付金额快照 |
+| balanceAmount | String | 尾款金额快照 |
+| roomCost | String | 住宿实际成本 |
+| ticketCost | String | 门票实际成本 |
+| staffCost | String | 人员费用实际成本 |
+| subsidyCost | String | 补助实际成本 |
+| mealCost | String | 餐食实际成本 |
+| vehicleCost | String | 车辆基础服务总车费（按 Fleet 派车组合计） |
+| otherExpenseCost | String | 其他支出实际成本 |
+| insurancePremium | String | 保险实际保费 |
+| refundTotal | String | 返还合计（只读展示，不进利润公式） |
+| totalActualCost | String | 总实际成本 |
+| driverTransferAmount | String | 给司机/主报账人转回金额（仅计 CASH_PAID） |
+| profitAmount | String | 公司毛利 |
+| profitRate | Number | 毛利率（小数） |
+| settledBy | Long | 核单人 id；未核单时为 null |
+| settledByName | String | 核单人姓名快照 |
+| settledAt | String | 核单完成时间，格式 yyyy-MM-ddTHH:mm:ss |
+| remark | String | 核单备注 |
+| finalSnapshotId | Long(String) | 当前核单终态快照 ID；未完成核单或已重新打开时为 null |
+| finalSnapshotVersionNo | Integer | 当前核单终态快照版本号；无当前快照时为 null |
+| finalSnapshotStatus | String | 有当前快照时固定 FINALIZED，否则为 null |
+| finalizedAt | String | 当前核单终态快照完成时间；无当前快照时为 null |
+| finalizedByName | String | 当前核单终态快照操作人姓名；无当前快照时为 null |
+| advanceSummary | Object | 已审批通过的订单预支汇总；**恒下发对象，不是 null**（空壳时也有值） |
+
+**advanceSummary 子对象字段表**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| approvedAmount | String | 已审批通过预支合计金额，默认 "0" |
+| records | Array | 已审批通过预支记录列表，默认空数组 []；元素结构同预支接口出参 |
+
+> 未核单空壳时：`settled=false`，仅 `orderId` 与 `advanceSummary`（默认空对象）有值，**其余字段全部为 null**。
+
+## 6. 枚举 / 数据字典
+
+| 字段 | 来源 | 取值 |
+|------|------|------|
+| warnings[].category | SettlementCategory 枚举 | 全量：HOTEL（住宿）/ TICKET（门票/游玩项目）/ MEAL（餐食）/ VEHICLE（车辆）/ GUIDE（导游）/ PHOTOGRAPHER（摄影）/ OTHER_INCOME（其他收入）/ OTHER_EXPENSE（其他支出）；**当前预警只会出现 HOTEL / TICKET** |
+| finalSnapshotStatus | 快照状态枚举 | FINALIZED（已定稿） |
+| orderStatusAfter | 订单状态中文文案 | 如「待财务复核」 |
+
+本次无枚举值增删；category 只是从隐含在文案里变成显式字段。
+
+## 7. 错误码
+
+### 7.1 finalize
+
+| code | message | 触发场景 |
+|------|---------|----------|
+| 581007 | 订单不存在 | orderId 查不到订单 |
+| 584081 | 对账数据不一致：已付金额与支付流水和线下收款合计不符，禁止带病结算 | paid_amount 与实际入账总额不符（存量脏数据或并发漂移） |
+| 584085 | 存在辅助人员结算未完成，请全部结算后提交 | 任一非主报账司机费用行未结算完成或缺转账凭证号 |
+| 584321 | 当前订单缺少核单终态快照，请重新完成核单 | 缺终态快照（含重复提交场景） |
+| 400 | 订单 ID 必须大于 0 | orderId 路径参数校验失败 |
+| 403 | 无权限访问 | 房务角色（HOUSE）JWT 调用 |
+
+> finalize 还有人员费用 / 其他收入未就绪等前置门禁错误码（584xxx 段），非本次变更，按响应 message 直接提示即可。
+
+### 7.2 summary
+
+只读接口，无业务错误码；orderId 查不到快照时返回 200 + 空壳对象（settled=false），**不会报「订单不存在」**。
+
+## 8. 示例
+
+### 8.1 典型成功
+
+**finalize**（核单完成，D2 住宿与 D2 门票各一条现付缺凭证，同日两行靠 settlementId 区分）：
+
+    POST /v3/admin/order/2087088947225038849/settlement/finalize
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "summaryId": "9600000000001",
+    "finalSnapshotId": "9600000000002",
+    "finalSnapshotVersionNo": 1,
+    "finalSnapshotStatus": "FINALIZED",
+    "orderId": "2087088947225038849",
+    "settledAt": "2026-08-12T10:30:25",
+    "totalAmount": "24800.00",
+    "paidAmount": "24800.00",
+    "balanceAmount": "0.00",
+    "roomCost": "4280.00",
+    "ticketCost": "3680.00",
+    "staffCost": "14260.00",
+    "subsidyCost": "720.00",
+    "mealCost": "860.00",
+    "vehicleCost": "5200.00",
+    "otherExpenseCost": "1260.00",
+    "insurancePremium": "180.00",
+    "totalActualCost": "23120.00",
+    "driverTransferAmount": "22940.00",
+    "profitAmount": "1680.00",
+    "profitRate": 0.0677,
+    "orderStatusAfter": "待财务复核",
+    "mqTriggered": false,
+    "warnings": [
+      {
+        "settlementId": "9600000000003",
+        "category": "HOTEL",
+        "dayNumber": 2,
+        "message": "住宿 D2 现付缺凭证"
+      },
+      {
+        "settlementId": "9600000000011",
+        "category": "TICKET",
+        "dayNumber": 2,
+        "message": "门票 D2 现付缺凭证"
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+**summary**（已核单订单）：
+
+    GET /v3/admin/order/2087088947225038849/settlement/summary
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "settled": true,
+    "id": "9600000000001",
+    "orderId": "2087088947225038849",
+    "totalAmount": "24800.00",
+    "paidAmount": "24800.00",
+    "balanceAmount": "0.00",
+    "roomCost": "4280.00",
+    "ticketCost": "3680.00",
+    "staffCost": "14260.00",
+    "subsidyCost": "720.00",
+    "mealCost": "860.00",
+    "vehicleCost": "5200.00",
+    "otherExpenseCost": "1260.00",
+    "insurancePremium": "180.00",
+    "refundTotal": "2260.00",
+    "totalActualCost": "23120.00",
+    "driverTransferAmount": "22940.00",
+    "profitAmount": "1680.00",
+    "profitRate": 0.0677,
+    "settledBy": "30001",
+    "settledByName": "李定制师",
+    "settledAt": "2026-08-12T10:30:25",
+    "remark": "核单完成 出行 7 天 0 投诉",
+    "finalSnapshotId": "9600000000002",
+    "finalSnapshotVersionNo": 1,
+    "finalSnapshotStatus": "FINALIZED",
+    "finalizedAt": "2026-08-12T10:30:25",
+    "finalizedByName": "财务终审员",
+    "advanceSummary": {
+      "approvedAmount": "2000.00",
+      "records": []
+    }
+  },
+  "success": true
+}
+```
+
+### 8.2 边界情况
+
+**边界 1：finalize 无任何软预警**——warnings 为空数组，不是 null：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "summaryId": "9600000000001",
+    "warnings": []
+  },
+  "success": true
+}
+```
+
+**边界 2：summary 查未核单订单**——返回空壳对象（HTTP 200，不报错），仅 orderId / advanceSummary 有值，其余全 null，settled=false：
+
+    GET /v3/admin/order/2087088947225038850/settlement/summary
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "settled": false,
+    "id": null,
+    "orderId": "2087088947225038850",
+    "totalAmount": null,
+    "paidAmount": null,
+    "balanceAmount": null,
+    "roomCost": null,
+    "ticketCost": null,
+    "staffCost": null,
+    "subsidyCost": null,
+    "mealCost": null,
+    "vehicleCost": null,
+    "otherExpenseCost": null,
+    "insurancePremium": null,
+    "refundTotal": null,
+    "totalActualCost": null,
+    "driverTransferAmount": null,
+    "profitAmount": null,
+    "profitRate": null,
+    "settledBy": null,
+    "settledByName": null,
+    "settledAt": null,
+    "remark": null,
+    "finalSnapshotId": null,
+    "finalSnapshotVersionNo": null,
+    "finalSnapshotStatus": null,
+    "finalizedAt": null,
+    "finalizedByName": null,
+    "advanceSummary": {
+      "approvedAmount": "0",
+      "records": []
+    }
+  },
+  "success": true
+}
+```
+
+**边界 3：同一天同分类多条缺凭证**——旧结构下两条文案完全相同无法区分；新结构每条带独立 settlementId，可逐条定位/跳转：
+
+```json
+"warnings": [
+  { "settlementId": "9600000000003", "category": "HOTEL", "dayNumber": 2, "message": "住宿 D2 现付缺凭证" },
+  { "settlementId": "9600000000005", "category": "HOTEL", "dayNumber": 2, "message": "住宿 D2 现付缺凭证" }
+]
+```
+
+### 8.3 业务失败
+
+**finalize 辅助人员结算未完成**：
+
+    POST /v3/admin/order/2087088947225038849/settlement/finalize
+
+```json
+{
+  "code": 584085,
+  "message": "存在辅助人员结算未完成，请全部结算后提交",
+  "success": false
+}
+```
+
+**finalize 订单不存在**：
+
+    POST /v3/admin/order/999999999/settlement/finalize
+
+```json
+{
+  "code": 581007,
+  "message": "订单不存在",
+  "success": false
+}
+```
+
+**finalize 房务角色访问被拦**（House 角色 JWT 调用）：
+
+```json
+{
+  "code": 403,
+  "message": "无权限访问",
+  "success": false
+}
+```
+
+## 9. 业务边界
+
+**适用**：
+
+- finalize：订单核单明细已逐步保存完成、核对无误后点「完成核单」提交
+- summary：核单页 / 财务报表页随时读取汇总；未核单订单也可调（返回空壳），前端据此展示「尚未核单」占位
+
+**不适用**：
+
+- finalize：明细未保存完整 / 辅助人员结算未完成 / 对账不一致的订单（被 584xxx 门禁拦截，见 §7）
+- summary：想看明细行级数据时不要用它，走各分类明细接口；本接口只有汇总快照
+
+**特殊边界**：
+
+- warnings 是**软预警**，不阻塞 finalize 提交；有预警也照常返回 200 完成核单
+- 预警仅覆盖 CASH_PAID（现付）且 voucher_urls 为空的住宿 / 门票明细行；签单、公司直付等其他支付方式不产生预警
+- summary 空壳的 advanceSummary 恒为默认对象（approvedAmount="0"、records=[]），**不是 null**，不能拿它当判空依据
+
+## 10. 修改前后对比
+
+### 10.1 字段级对比
+
+| 接口 | 字段 | 修改前 | 修改后 |
+|------|------|--------|--------|
+| finalize | warnings | `List<String>`，元素如 `"住宿 D2 现付缺凭证"` | `List<WarningItemVO>`，元素为对象 `{ settlementId, category, dayNumber, message }` |
+| summary | settled | 无此字段 | 新增 Boolean：已核单 = true，未核单空壳 = false |
+
+### 10.2 行为级对比
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 同日多条同类缺凭证 | 多条相同文案，无法区分哪一行 | 每条带独立 settlementId，可定位/跳转具体明细行 |
+| 前端渲染预警 | 直接渲染字符串 | 必须读 `warnings[].message`；可用 `settlementId` + `category` 做行锚定 |
+| 前端判「是否已核单」 | 判 `data.id == null`（不可靠，advanceSummary 恒非 null 易误导） | 判 `data.settled === false` |
+| 调旧结构（如把 warnings[i] 当字符串拼接） | 正常显示文案 | **显示 [object Object] 或报错**（字段结构已变） |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **破坏兼容性**：⚠️ 部分破坏。finalize 的 warnings 结构变化是破坏性的：原按字符串数组渲染 warnings 的前端代码会显示异常。summary 仅新增字段，向后兼容。
+- **前端必须同步上线**：是（针对 finalize warnings 渲染处）。前端需要：
+  1. warnings 渲染从「直接渲染字符串」改为读 `item.message`
+  2. （可选）用 `item.settlementId` + `item.category` 实现点击预警跳转/高亮对应明细行
+  3. 判「是否已核单」改读 `settled` 字段，删除 `id == null` 判空逻辑
+- **后端兼容**：无 DDL、无数据迁移；未消费 warnings 的前端功能不受影响。
+
+### 11.2 回滚方案
+
+- 后端回滚 = revert PR #5881 的 merge commit（125bb9c96e），重启 hl-order-service-v3，warnings 恢复字符串数组、settled 字段消失。
+- 前端回滚 = 切回旧版前端包。注意新旧前后端要配套：新前端 + 旧后端时 warnings[].message 取不到值、settled 恒 undefined。
+- 零 DDL，回滚无残留风险。
+
+## 12. 注意事项
+
+1. **warnings 元素里的 settlementId 序列化为 JSON 字符串**（Long 防 JS 精度丢失），前端按 string 处理，不要 Number() 转换。
+2. warnings 无预警时返回空数组 []，不是 null，渲染前正常遍历即可。
+3. category 当前只会出现 HOTEL / TICKET；SettlementCategory 枚举还有其他值（MEAL / VEHICLE / GUIDE 等），前端如做映射表建议按全量枚举写，缺值兜底显示原 code。
+4. summary 判空**只认 settled**：`settled === false` 即「尚未核单」，此时除 orderId / advanceSummary 外全部字段为 null，展示必须兜底，不要直接渲染金额。
+5. advanceSummary 恒为对象（未核单也是 `{ approvedAmount: "0", records: [] }`），不要拿它判「是否已核单」。
+6. finalize 是写操作且有前置门禁（对账一致、人员结算完成等），失败按错误码 message 提示，**不要静默重试**；重复提交会被快照类错误码拦截。
+7. finalize / summary 两个接口的金额类字段（totalAmount / paidAmount / 各 cost / profitAmount 等）均序列化为字符串，前端展示直接用，计算需自行转数值。
+
+## 13. 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/5876
+- PR：https://git.1814.love:8443/wx/HL/pulls/5881
+- Commit：https://git.1814.love:8443/wx/HL/commit/125bb9c96e
+- 服务：hl-order-service-v3（端口 8086）
+- 后端负责人：yst（腰苏图）