docs(changelog): #5739 核单报表快照指纹彻底下线（PR #5764）

- GET /v3/admin/order/{orderId}/settlement/reports/group 出参删除 sourceFingerprint，reportStatus 枚举删除 STALE - GET /v3/admin/order/{orderId}/settlement/reports/reimbursement 同步变更 - 承接 #5704 写入路径指纹下线，本次为报表读取路径收尾批次
2026-08-09 23:04:28 +08:00 · 2026-08-09 23:04:28 +08:00 · a24f7cc724
--- a/changelogs-v2/2026-08/09_5739_核单指纹下线-修改接口-管理后台.md
+++ b/changelogs-v2/2026-08/09_5739_核单指纹下线-修改接口-管理后台.md
@ -0,0 +1,362 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5739"
+title: "核单报表快照指纹彻底下线：报表出参删除 sourceFingerprint，reportStatus 不再返回 STALE"
+consumer: "admin"
+change_type: "修改接口"
+author: "yaosutu(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #5764 已合并 dev-v3；reports/group 与 reports/reimbursement 出参删除 sourceFingerprint 字段，reportStatus 枚举删除 STALE 值（原 reopen 后指纹不一致实时派生）。属出参删字段 + 枚举删值的硬破坏契约，前端需停读字段并清理 STALE 特判后与后端同批发布。"
+updated_at: "2026-08-09"
+base: "dev-v3"
+---
+
+# 【⚠️ 修改接口·管理后台】核单报表快照指纹彻底下线，出参删 sourceFingerprint、reportStatus 不再返回 STALE（#5739）
+
+> **PR**: [#5764](https://git.1814.love:8443/wx/HL/pulls/5764) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-09
+
+## 1. 接口背景
+
+本次是核单域指纹机制下线的**收尾批次**，承接 [#5704](https://git.1814.love:8443/wx/HL/issues/5704)（PR #5709，写入路径 6 端点指纹入参/出参下线）。
+
+#5704 之后，核单报表（单团核算表 / 主报账人报账表）的读取路径仍残留一套「快照指纹」逻辑：报表落库时记录来源数据 sha256 指纹，前端每次 GET 报表时后端实时重算当前来源指纹，两者不一致就把 reportStatus 实时改报为 STALE（提示「数据已变化，需刷新」），并在出参中携带 sourceFingerprint。
+
+指纹机制整体废弃后，该派生逻辑同步删除：
+
+- 两个报表查询接口出参**删除 sourceFingerprint 字段**；
+- reportStatus 枚举**删除 STALE 值**，只保留落库状态 GENERATED / CONFIRMED，接口不再做实时指纹比对。
+
+> ⚠️ 本次为**出参删字段 + 枚举删值的硬破坏契约**：前端若还在读取 sourceFingerprint、或对 reportStatus === 'STALE' 写过特判（刷新提示 / 重新生成按钮等），必须清理后再与后端同批发布。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 |
+|---|---|---|---|---|---|
+| 1 | 查询单团核算表 | GET | /v3/admin/order/{orderId}/settlement/reports/group | 删除出参 sourceFingerprint；reportStatus 枚举删除 STALE | 停读字段 / 清理 STALE 特判 |
+| 2 | 查询主报账人报账表 | GET | /v3/admin/order/{orderId}/settlement/reports/reimbursement | 删除出参 sourceFingerprint；reportStatus 枚举删除 STALE | 停读字段 / 清理 STALE 特判 |
+
+## 3. 接口详情
+
+- **使用场景**：核单页面展示单团核算表（全团收入/成本/毛利核算）与主报账人报账表（主报账人收付对账与转账结论）。
+- **认证**：需要管理后台登录态（Bearer Token）；房务角色（HOUSE）被 OrderViewGuard.assertNotHouseRole 拦截。
+- **幂等性**：只读查询，天然幂等。
+- **限流**：未声明接口专属限流。
+- **方法/路径**：见 §2 变更清单。
+
+## 4. 接口入参
+
+### 4.1 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| orderId | Long | 是 | 订单 ID，路径参数，必须大于 0 |
+
+### 4.2 请求体字段
+
+无（GET 请求，无请求体，无 Query 参数）。**入参零变化**。
+
+## 5. 出参字段
+
+### 5.1 GET /v3/admin/order/{orderId}/settlement/reports/group（单团核算表）
+
+统一响应 Result 包装，data 字段如下（按响应 JSON 字段序）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String(Long) | 报表记录 ID；报表未落库时可为 null |
+| orderId | String(Long) | 订单 ID |
+| reportStatus | String | 报表状态，枚举见 §6；**不再返回 STALE** |
+| ~~sourceFingerprint~~ | - | **已删除**，前端不再收到此字段 |
+| baseOrderAmount | String(BigDecimal) | 订单应收（基础订单金额） |
+| otherIncomeAmount | String(BigDecimal) | 其他收入合计 |
+| discountAmount | String(BigDecimal) | 优惠合计（负数） |
+| adjustedReceivableAmount | String(BigDecimal) | 调整后应收 |
+| paidAmount | String(BigDecimal) | 已收金额 |
+| actualRefundedAmount | String(BigDecimal) | 实际退款金额 |
+| netRevenueAmount | String(BigDecimal) | 净收入 |
+| netReceivedAmount | String(BigDecimal) | 净收款 |
+| outstandingAmount | String(BigDecimal) | 待收尾款 |
+| hotelCost | String(BigDecimal) | 住宿成本 |
+| ticketCost | String(BigDecimal) | 门票成本 |
+| mealCost | String(BigDecimal) | 餐食成本 |
+| vehicleCost | String(BigDecimal) | 车辆成本 |
+| guideCost | String(BigDecimal) | 导游成本 |
+| photographerCost | String(BigDecimal) | 摄影成本 |
+| otherExpenseCost | String(BigDecimal) | 其他支出成本 |
+| insurancePremium | String(BigDecimal) | 保费 |
+| totalCost | String(BigDecimal) | 成本合计 |
+| paidCost | String(BigDecimal) | 已付成本 |
+| unpaidCost | String(BigDecimal) | 未付成本 |
+| grossProfit | String(BigDecimal) | 毛利 |
+| grossProfitRate | String(BigDecimal) | 毛利率 |
+| travelerCount | Integer | 出行人数 |
+| perCapitaRevenue | String(BigDecimal) | 人均收入 |
+| perCapitaCost | String(BigDecimal) | 人均成本 |
+| perCapitaProfit | String(BigDecimal) | 人均毛利 |
+| incomeLines | Array | 收入行，固定 4 行；每项含 type(BASE_ORDER/OTHER_INCOME/DISCOUNT/ACTUAL_REFUND) / typeName / amount |
+| costCategories | Array | 成本分类行，固定 8 行；每项含 category(HOTEL/TICKET/MEAL/VEHICLE/GUIDE/PHOTOGRAPHER/OTHER_EXPENSE/INSURANCE) / categoryName / amount |
+| generatedBy | String(Long) | 生成人 ID |
+| generatedByName | String | 生成人姓名 |
+| generatedAt | String | 生成时间，格式 yyyy-MM-dd HH:mm:ss |
+| confirmedBy | String(Long) | 确认人 ID；未确认为 null |
+| confirmedByName | String | 确认人姓名 |
+| confirmedAt | String | 确认时间 |
+
+### 5.2 GET /v3/admin/order/{orderId}/settlement/reports/reimbursement（主报账人报账表）
+
+统一响应 Result 包装，data 字段如下：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | String(Long) | 报表记录 ID；未落库时可为 null |
+| orderId | String(Long) | 订单 ID |
+| reportStatus | String | 报表状态，枚举见 §6；**不再返回 STALE** |
+| ~~sourceFingerprint~~ | - | **已删除**，前端不再收到此字段 |
+| primaryReporterId | String(Long) | 主报账人人员安排 ID |
+| primaryReporterName | String | 主报账人姓名 |
+| primaryReporterRole | String | 主报账人角色（如 DRIVER） |
+| reportVersion | Integer | 报表版本号 |
+| driverCollectedTailAmount | String(BigDecimal) | 司机代收尾款 |
+| approvedAdvanceAmount | String(BigDecimal) | 已审批预支金额 |
+| reportablePaidCostAmount | String(BigDecimal) | 可报账已付成本 |
+| reporterNetAmount | String(BigDecimal) | 报账人净额 |
+| primaryReporterCollectedAmount | String(BigDecimal) | 主报账人已收款 |
+| publicPrepaidAmount | String(BigDecimal) | 对公预付金额 |
+| primaryReporterDueAmount | String(BigDecimal) | 主报账人应结金额 |
+| advanceOutstandingAmount | String(BigDecimal) | 预支未销余额 |
+| reconNetAmount | String(BigDecimal) | 对账净额 |
+| transferDirection | String | 转账方向 |
+| transferAmount | String(BigDecimal) | 转账金额 |
+| incomeLines | Array | 收款行；每项含 type / typeName / receiptId / amount / channel / channelName / payType / payTypeName / collectorStaffId / collectorName / collectorRole / collectorRoleName / receivedAt / remark |
+| expenseLines | Array | 支出行；每项含 kind / category / categoryName / amount / paymentMethod / paymentMethodName / voucherUrls / remark + 类别扩展字段（住宿 hotelName/roomTypeName 等） |
+| advanceLines | Array | 预支行 |
+| vehicleLines | Array | 已确认车辆逐日费用明细；**无数据固定返回空数组** |
+| transferStatus | String | 转账状态 |
+| transferDate | String | 转账日期，格式 yyyy-MM-dd |
+| transferRef | String | 转账流水号 |
+| advanceSettledFlag | Boolean | 预支是否已处理 |
+| signedVoucher | Object | 签字凭证；含 files[{name,url}] + note |
+| generatedBy | String(Long) | 生成人 ID |
+| generatedByName | String | 生成人姓名 |
+| generatedAt | String | 生成时间 |
+| confirmedBy | String(Long) | 确认人 ID |
+| confirmedByName | String | 确认人姓名 |
+| confirmedAt | String | 确认时间 |
+
+> 上述两表除删除 sourceFingerprint 外，其余字段名称、类型、语义均无变化。前端不要再读取 sourceFingerprint，读取结果恒为 undefined。
+
+## 6. 枚举 / 数据字典
+
+### reportStatus（两接口共用）
+
+| 值 | 含义 | 本次变化 |
+|---|---|---|
+| GENERATED | 报表已生成（或实时计算态），未确认 | 不变 |
+| CONFIRMED | 报表已随完成核单确认 | 不变 |
+| ~~STALE~~ | 原语义：落库后来源数据发生变化（指纹不一致），实时派生 | **已删除，不再返回** |
+
+**STALE 原触发场景（现已消亡）**：报表落库（生成/确认）后，订单的收退款、费用明细、车辆费用等来源数据又被修改（含 reopen 反确认后改数），原来 GET 报表时后端会比对落库指纹与实时指纹，不一致则把 reportStatus 改报 STALE。现在该实时比对整体移除，reportStatus 就是落库原值。
+
+其余枚举/字典（incomeLines[].type、costCategories[].category、channel、payType、paymentMethod、transferDirection、transferStatus 等）取值与语义均无变化。
+
+## 7. 错误码
+
+本次**无新增、无删除错误码**。两接口既有的访问拦截（如房务角色 403、订单不存在）行为不变；finalize 前置的双报告已生成保护（584311 / 584313）不在本次范围、保持不变。
+
+## 8. 示例
+
+### 8.1 典型成功（单团核算表）
+
+```http
+GET /v3/admin/order/2084000000000002978/settlement/reports/group
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": "8801",
+    "orderId": "2084000000000002978",
+    "reportStatus": "GENERATED",
+    "baseOrderAmount": "12800.00",
+    "otherIncomeAmount": "500.00",
+    "discountAmount": "-300.00",
+    "adjustedReceivableAmount": "13000.00",
+    "paidAmount": "13000.00",
+    "actualRefundedAmount": "0.00",
+    "netRevenueAmount": "13000.00",
+    "netReceivedAmount": "13000.00",
+    "outstandingAmount": "0.00",
+    "hotelCost": "3600.00",
+    "ticketCost": "1200.00",
+    "mealCost": "800.00",
+    "vehicleCost": "2000.00",
+    "guideCost": "500.00",
+    "photographerCost": "0.00",
+    "otherExpenseCost": "100.00",
+    "insurancePremium": "200.00",
+    "totalCost": "8400.00",
+    "paidCost": "7000.00",
+    "unpaidCost": "1400.00",
+    "grossProfit": "4600.00",
+    "grossProfitRate": "0.3538",
+    "travelerCount": 4,
+    "perCapitaRevenue": "3250.00",
+    "perCapitaCost": "2100.00",
+    "perCapitaProfit": "1150.00",
+    "incomeLines": [
+      {"type": "BASE_ORDER", "typeName": "订单应收", "amount": "12800.00"},
+      {"type": "OTHER_INCOME", "typeName": "其他收入", "amount": "500.00"},
+      {"type": "DISCOUNT", "typeName": "优惠", "amount": "-300.00"},
+      {"type": "ACTUAL_REFUND", "typeName": "实际退款", "amount": "0.00"}
+    ],
+    "costCategories": [
+      {"category": "HOTEL", "categoryName": "住宿", "amount": "3600.00"},
+      {"category": "TICKET", "categoryName": "门票", "amount": "1200.00"}
+    ],
+    "generatedBy": "1001",
+    "generatedByName": "张三",
+    "generatedAt": "2026-08-09 10:20:30",
+    "confirmedBy": null,
+    "confirmedByName": null,
+    "confirmedAt": null
+  },
+  "success": true
+}
+```
+
+> 注意：响应中已无 sourceFingerprint 字段；reportStatus 只会是 GENERATED 或 CONFIRMED。
+
+### 8.2 边界（报账表无车辆明细 + 未落库实时态）
+
+报表未落库（订单尚未生成过报账表）时接口仍正常返回实时计算结果，id 可为 null、reportStatus 固定 GENERATED、vehicleLines 固定空数组：
+
+```http
+GET /v3/admin/order/2084000000000002978/settlement/reports/reimbursement
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": null,
+    "orderId": "2084000000000002978",
+    "reportStatus": "GENERATED",
+    "primaryReporterId": "7001",
+    "primaryReporterName": "司机甲",
+    "primaryReporterRole": "DRIVER",
+    "reportVersion": null,
+    "driverCollectedTailAmount": "0.00",
+    "approvedAdvanceAmount": "0.00",
+    "reportablePaidCostAmount": "0.00",
+    "reporterNetAmount": "0.00",
+    "primaryReporterCollectedAmount": "0.00",
+    "publicPrepaidAmount": "0.00",
+    "primaryReporterDueAmount": "0.00",
+    "advanceOutstandingAmount": "0.00",
+    "reconNetAmount": "0.00",
+    "transferDirection": null,
+    "transferAmount": "0.00",
+    "incomeLines": [],
+    "expenseLines": [],
+    "advanceLines": [],
+    "vehicleLines": [],
+    "transferStatus": null,
+    "transferDate": null,
+    "transferRef": null,
+    "advanceSettledFlag": null,
+    "signedVoucher": null,
+    "generatedBy": null,
+    "generatedByName": null,
+    "generatedAt": null,
+    "confirmedBy": null,
+    "confirmedByName": null,
+    "confirmedAt": null
+  },
+  "success": true
+}
+```
+
+### 8.3 业务失败（订单不存在）
+
+```http
+GET /v3/admin/order/999999999/settlement/reports/group
+Authorization: Bearer <token>
+```
+
+```json
+{"code": 584xxx, "message": "订单不存在", "data": null, "success": false}
+```
+
+> 该失败路径与本次变更无关，仅作最小复现样例；具体错误码以订单域统一「订单不存在」码为准。
+
+## 9. 业务边界
+
+- ✅ 报表落库后再改来源数据（收款、费用、车辆费用等），reportStatus 保持落库原值（GENERATED / CONFIRMED），不再实时翻成 STALE；前端展示的报表金额仍是实时计算的当前值。
+- ✅ reopen（反确认）后重新查报表，reportStatus 按落库记录返回，不再出现 STALE 中间态。
+- ❌ 不要再依赖 reportStatus === 'STALE' 做「数据已变化」提示；该信号已彻底不存在，且没有替代字段（指纹机制整体废弃，核单为单人负责场景，见 #5704 背景）。
+- ❌ 不要把历史缓存/本地存储里的 sourceFingerprint 回传到任何接口——报表两个 GET 接口本就无入参；写入侧接口的指纹入参已在 #5704 删除。
+
+## 10. 修改前后对比
+
+### 10.1 字段级对比
+
+| 接口 | 字段 | 原来 | 现在 |
+|---|---|---|---|
+| GET reports/group | sourceFingerprint | 出参，64 位十六进制 sha256 | **已删除** |
+| GET reports/reimbursement | sourceFingerprint | 出参，64 位十六进制 sha256 | **已删除** |
+| 两接口 | reportStatus | GENERATED / CONFIRMED / STALE（实时派生） | 仅 GENERATED / CONFIRMED（落库原值） |
+
+### 10.2 行为级对比
+
+| 场景 | 原来 | 现在 |
+|---|---|---|
+| 报表落库后来源数据被修改，再 GET 报表 | reportStatus 实时改报 STALE | 返回落库原值（GENERATED 或 CONFIRMED） |
+| reopen 反确认后 GET 报表 | 指纹不一致，reportStatus = STALE | 按落库状态返回，无 STALE |
+| 出参字段 | 含 sourceFingerprint | 不再含该字段 |
+| 报表金额数值 | 实时计算 | 实时计算（**不变**） |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**：**是，硬破坏**。出参删除 sourceFingerprint 字段 + 枚举删除 STALE 值。旧前端若读取 sourceFingerprint 得到 undefined、若对 STALE 写了特判分支则永远不会再命中（静默失效，不报错）。
+- **前端是否必须同步上线**：**必须同批**。前端需先停读 sourceFingerprint、清理 STALE 特判（刷新提示/禁用确认按钮/重新生成入口等），再与后端同批发布。
+- **上线顺序边界**：前后端同批发布；若必须分先后，**先上前端（停读字段 + 清理 STALE 分支），再上后端**。旧前端 + 新后端不会报 500，但 STALE 相关 UI 逻辑成死代码。
+- **数据库侧**：本批次后端同步 DROP 了 settlement 域 15 个指纹列（Flyway 迁移随服务部署执行），与前端无直接关系，但意味着**回滚后指纹无法恢复原值**（见 §11.2）。
+
+### 11.2 回滚方案
+
+- 代码回滚即恢复 sourceFingerprint 出参与 STALE 派生逻辑；但**数据库指纹列已 DROP**，回滚后重新计算的落库指纹为空，历史报表的 STALE 比对行为不可完全复原。
+- 因此**回滚必须前后端同批回滚**，且接受「历史报表不再派生 STALE」的行为落差。数据侧无业务数据修复成本（指纹非业务数据）。
+
+## 12. 注意事项
+
+- 本次只动两个报表查询接口的出参与 reportStatus 枚举；接口路径、入参、金额数值计算逻辑**均未变化**。
+- 与 #5704 的关系：#5704 下线**写入路径**（保存/确认/完成核单 6 个端点）的指纹入参与出参；本次 #5739 下线**报表读取路径**的指纹出参与 STALE 派生。两批共同完成指纹机制的整体下线，前端的指纹相关代码应已全部清除。
+- 原分类确认状态 VO（SettlementCategoryChecksRespVO）中的 sourceFingerprint 字段本次也顺手删除、confirmStatus 的 STALE 派生同步移除；但该 VO 对应的 category-checks 接口**早在 PR #5324 已下线**，当前无任何端点返回它，前端无感，无需处理。
+- finalize（完成核单）接口的 Swagger notes 中「提交双指纹」属文档残留，实际入参指纹字段已在 #5704 删除，以 #5704 changelog 为准。
+- 小程序端（/v3/mp/*）不涉及本次变更，无需任何改动。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#5739](https://git.1814.love:8443/wx/HL/issues/5739)
+- **PR**: [#5764](https://git.1814.love:8443/wx/HL/pulls/5764)
+- **Merge Commit**: [60e4409a](https://git.1814.love:8443/wx/HL/commit/60e4409a77ca81e203e456f063e3d8d91d8f48a1)
+- **前置批次**: Issue [#5704](https://git.1814.love:8443/wx/HL/issues/5704) / PR [#5709](https://git.1814.love:8443/wx/HL/pulls/5709)（写入路径指纹下线，changelog 见 2026-08/08_5704）
+
+### 13.2 联系人
+
+- **后端负责人**: @yaosutu (yst)