wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(changelog): 单团核算表扩充逐项明细出参（#5781 / PR #5786）
一些检查失败了
changelog-filename-gate / validate (push) Failing after 2s
详情

浏览代码 
incomeLines[i] 新增 details 收入逐项、costCategories[i] 新增 lines 成本逐项（按 category 窄化）；
配套新增 insurance_biz_type / settlement_refund_source 两个字典。纯出参增量，向后兼容。
这个提交包含在：
yaosutu 2026-08-10 22:42:28 +08:00
父节点 7921162dfa
当前提交 71a0544914
共有 1 个文件被更改，包括 680 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

680
changelogs-v2/2026-08/10_5781_单团核算表扩充逐项明细-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,680 @@
---
schema: "hl-changelog/v2"
ticket: "5781"
title: "单团核算表扩充逐项明细出参（incomeLines.details / costCategories.lines）"
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: ""
updated_at: "2026-08-10"
base: "dev-v3"
---
# 【✨ 修改接口·管理后台】单团核算表扩充逐项明细出参（#5781）
> **PR**: #5786 | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-10
## 1. 接口背景
单团核算表（GET /v3/admin/order/{orderId}/settlement/reports/group）此前只返回「4 行收入合计 + 8 行成本合计」，财务/运营在核对某一行合计时看不到它是由哪些逐项明细加总出来的，只能跳回各分类明细页签逐条对账。
本次变更为**纯出参增量**：在每条收入行下挂 details（收入逐项明细）、在每个成本分类下挂 lines（成本逐项明细，分类专属结构），让前端在核算表内直接展开逐项，无需再跳页签拼装。
**不变的部分**：顶部汇总字段（baseOrderAmount / totalCost / grossProfit 等全部金额字段）、incomeLines 仍固定 4 行、costCategories 仍固定 8 行、各行 amount 合计口径，全部与变更前一致。
## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 查询单团核算表 | GET | /v3/admin/order/{orderId}/settlement/reports/group | 修改（出参纯增量） | incomeLines[i] 新增 details 数组；costCategories[i] 新增 lines 数组（元素结构随 category 不同而不同，按 category 窄化） |
配套数据字典（前端可调 GET /admin/dict/data/{dictType} 动态渲染中文名）：
| 字典 type | 用途 | 本次状态 |
|-----------|------|----------|
| settlement_category | 成本分类中文名 | 已存在（不变） |
| settlement_payment_method | 付款方式中文名 | 已存在（不变） |
| settlement_report_line_type | 收入行类型中文名 | 已存在（不变） |
| insurance_biz_type | 保险业务类型中文名 | **本次新增** |
| settlement_refund_source | 人工返还来源中文名 | **本次新增** |
## 3. 接口详情
### 3.1 查询单团核算表
- **使用场景**：核单工作台「单团核算」页签，财务/运营查看单团收入成本毛利全貌及逐项明细
- **认证**：管理后台 JWT；房务角色（ROOM_MANAGER / HOUSE_KEEPER_LEAD）无权调用（返 581045）
- **幂等性**：是（GET 只读）
- **限流**：无
## 4. 接口入参
### 4.1 路径参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long | ✅ | 订单 ID，必须 > 0，否则返参数校验错误 |
### 4.2 请求体字段
无请求体。
## 5. 出参（响应）
响应类型：`Result<SettlementGroupReportRespVO>`（`code=200` 表示成功，`data` 为下表结构）。
### 5.1 顶层字段（SettlementGroupReportRespVO）
> ⚠️ 本表全部字段与变更前一致，**本次无增删改**，列出仅为自包含。
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | String | 报表 ID（Long 序列化为字符串，无落库记录时可能缺省） |
| `orderId` | String | 订单 ID（Long 序列化为字符串） |
| `reportStatus` | String | 报表状态：`GENERATED`=已生成（实时组装）/ `CONFIRMED`=已确认（终态快照回放） |
| `baseOrderAmount` | Number | 订单应收金额，两位小数 |
| `otherIncomeAmount` | Number | 其他收入合计 |
| `discountAmount` | Number | 优惠合计（负数） |
| `adjustedReceivableAmount` | Number | 调整后应收 |
| `paidAmount` | Number | 已收金额 |
| `actualRefundedAmount` | Number | 实际退款合计（负数） |
| `netRevenueAmount` | Number | 净收入 |
| `netReceivedAmount` | Number | 实收净额 |
| `outstandingAmount` | Number | 未收尾款 |
| `hotelCost` / `ticketCost` / `mealCost` / `vehicleCost` / `guideCost` / `photographerCost` / `otherExpenseCost` / `insurancePremium` | Number | 8 个成本分类合计（住宿/门票/餐食/车辆/导游/摄影/其他支出/保险） |
| `totalCost` | Number | 成本总计 |
| `paidCost` | Number | 已付成本合计 |
| `unpaidCost` | Number | 未付成本合计 |
| `grossProfit` | Number | 毛利 |
| `grossProfitRate` | Number | 毛利率 |
| `travelerCount` | Number | 出行人数 |
| `perCapitaRevenue` / `perCapitaCost` / `perCapitaProfit` | Number | 人均收入 / 人均成本 / 人均毛利 |
| `incomeLines` | Array | 收入行，**固定 4 行**，结构见 5.2 |
| `costCategories` | Array | 成本分类行，**固定 8 行**，结构见 5.3 |
| `generatedBy` / `generatedByName` / `generatedAt` | String / String / String | 生成人 ID / 姓名 / 生成时间 |
| `confirmedBy` / `confirmedByName` / `confirmedAt` | String / String / String | 确认人 ID / 姓名 / 确认时间（未确认时缺省） |
### 5.2 收入行（SettlementGroupIncomeLineVO）
| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | String | 行类型：`BASE_ORDER`=订单应收 / `OTHER_INCOME`=其他收入 / `DISCOUNT`=优惠 / `ACTUAL_REFUND`=实际退款 |
| `typeName` | String | 行类型中文名（字典 `settlement_report_line_type` 回填） |
| `amount` | Number | 行合计金额，两位小数；`DISCOUNT` / `ACTUAL_REFUND` 为负数 |
| `details` | Array | ✨ **本次新增**：收入逐项明细（`SettlementGroupIncomeDetailVO`），无逐项时为空数组 `[]` |
### 5.3 收入逐项明细（SettlementGroupIncomeDetailVO）✨ 本次新增
| 字段 | 类型 | 说明 |
|------|------|------|
| `itemName` | String | 项目名（订单应收 / 增费项目名 / 优惠名称 / 退款来源中文名） |
| `content` | String | 内容说明（如规格、退款原因） |
| `source` | String | 人工返还来源 code，**仅** `ACTUAL_REFUND` 下的人工返还行透出：`DRIVER_ONSITE` / `COMPANY_COMPENSATION` |
| `sourceName` | String | 人工返还来源中文名（字典 `settlement_refund_source`） |
| `unitPrice` | Number | 单价，两位小数；无单价概念时缺省 |
| `headCount` | Number | 人数；无人数概念时缺省 |
| `quantity` | Number | 数量；无数量概念时缺省 |
| `amount` | Number | 金额，两位小数；`DISCOUNT` / `ACTUAL_REFUND` 明细为负数 |
| `paymentMethod` | String | 付款方式：`CASH_PAID` / `COMPANY_PAID` / `SIGNED`；无付款方式时缺省 |
| `paymentMethodName` | String | 付款方式中文名（字典 `settlement_payment_method`） |
| `sourceType` | String | 来源类型（9 值，见 §6.6）；无来源时缺省 |
| `sourceTypeName` | String | 来源中文名 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
**各 type 下 details 的内容口径**：
| type | details 内容 |
|------|-------------|
| `BASE_ORDER` | 订单应收一行汇总（订单侧无逐项时单行） |
| `OTHER_INCOME` | 其他收入逐项 |
| `DISCOUNT` | 优惠逐项（金额取负） |
| `ACTUAL_REFUND` | 实际退款逐项：线上退款 + 人工返还（`source` = DRIVER_ONSITE / COMPANY_COMPENSATION），金额取负 |
### 5.4 成本分类行（SettlementGroupCostCategoryVO）
| 字段 | 类型 | 说明 |
|------|------|------|
| `category` | String | 费用类别：`HOTEL` / `TICKET` / `MEAL` / `VEHICLE` / `GUIDE` / `PHOTOGRAPHER` / `OTHER_EXPENSE` / `INSURANCE` |
| `categoryName` | String | 费用类别中文名（字典 `settlement_category`） |
| `amount` | Number | 分类合计金额，两位小数 |
| `lines` | Array | ✨ **本次新增**：成本逐项明细，**元素结构随 `category` 不同而不同**（分类专属行 VO），无逐项时为空数组 `[]`；前端按 `category` 判别窄化到 5.5～5.11 的对应结构 |
### 5.5 成本逐项行 · HOTEL 住宿（SettlementGroupHotelLineVO）✨
| 字段 | 类型 | 说明 |
|------|------|------|
| `stayDate` | String | 入住日期，`yyyy-MM-dd` |
| `hotelName` | String | 酒店名称 |
| `roomTypeName` | String | 房型名称 |
| `roomCount` | Number | 房间数 |
| `unitPrice` | Number | 单价，两位小数 |
| `plannedCost` | Number | 计划成本，两位小数 |
| `amount` | Number | 核算金额（实际成本），两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.6 成本逐项行 · TICKET 门票（SettlementGroupTicketLineVO）✨
| 字段 | 类型 | 说明 |
|------|------|------|
| `dayDate` | String | 游玩日期，`yyyy-MM-dd` |
| `scenicName` | String | 景区/项目名称 |
| `specName` | String | 规格名称（如 成人票） |
| `ticketCount` | Number | 票数 |
| `ticketUnitPrice` | Number | 门票单价，两位小数 |
| `sellPrice` | Number | 销售价，两位小数 |
| `plannedCost` | Number | 计划成本，两位小数 |
| `amount` | Number | 核算金额（实际成本），两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.7 成本逐项行 · MEAL 餐食（SettlementGroupMealLineVO）✨
| 字段 | 类型 | 说明 |
|------|------|------|
| `mealDate` | String | 用餐日期，`yyyy-MM-dd` |
| `mealName` | String | 餐食名称 |
| `mealType` | String | 餐食类型：`BREAKFAST` / `LUNCH` / `DINNER` / `SELF` |
| `mealTypeName` | String | 餐食类型中文名（字典 `meal_type`） |
| `quantity` | Number | 份数 |
| `unitPrice` | Number | 单价，两位小数 |
| `amount` | Number | 核算金额（实际金额），两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名；餐食明细无来源时缺省 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.8 成本逐项行 · VEHICLE 用车（SettlementGroupVehicleLineVO）✨
> 车务逐日行（VEHICLE_FEE 族）与车辆费用行（EXPENSE 族：油费/过路费等）的**稀疏并集**：每行仅本族字段非空，另一族字段整体缺省。无单价/数量概念，`dailyPrice` 即核算单价列。
| 字段 | 类型 | 说明 |
|------|------|------|
| `serviceDate` | String | [VEHICLE_FEE] 服务日期，`yyyy-MM-dd` |
| `startDate` | String | [VEHICLE_FEE] 服务开始日期，`yyyy-MM-dd` |
| `endDate` | String | [VEHICLE_FEE] 服务结束日期，`yyyy-MM-dd` |
| `vehiclePlate` | String | [VEHICLE_FEE] 车牌号 |
| `vehicleModelName` | String | [VEHICLE_FEE] 车型名称 |
| `driverName` | String | [VEHICLE_FEE] 司机姓名 |
| `dailyPrice` | Number | [VEHICLE_FEE] 日单价（即核算单价列），两位小数 |
| `paymentTypeName` | String | [VEHICLE_FEE] 车务付款类型名称 |
| `amount` | Number | 核算金额，两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名 |
| `expenseType` | String | [EXPENSE] 车辆费用类型：`FUEL` / `TOLL` / `PARKING` / `RENTAL` / `MAINTENANCE` |
| `expenseTypeName` | String | [EXPENSE] 车辆费用类型中文名（字典 `expense_type`） |
| `projectName` | String | [EXPENSE] 项目名称 |
| `expenseDate` | String | [EXPENSE] 费用发生日期，`yyyy-MM-dd` |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.9 成本逐项行 · GUIDE 导游 / PHOTOGRAPHER 摄影（SettlementGroupStaffLineVO，两分类共用）✨
| 字段 | 类型 | 说明 |
|------|------|------|
| `serviceDate` | String | 服务日期，`yyyy-MM-dd`；无服务日时缺省 |
| `name` | String | 人员姓名 |
| `serviceType` | String | 服务类型：`GUIDE` / `PHOTOGRAPHER` |
| `serviceTypeName` | String | 服务类型中文名（字典 `staff_role`） |
| `amount` | Number | 核算金额，两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名；无来源时缺省 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.10 成本逐项行 · OTHER_EXPENSE 其他支出（SettlementGroupOtherExpenseLineVO）✨
> 其他费用行（EXPENSE 族）与补贴行（SUBSIDY 族）的**稀疏并集**：每行仅本族字段非空。无单价/数量概念。
| 字段 | 类型 | 说明 |
|------|------|------|
| `expenseDate` | String | 费用发生日期，`yyyy-MM-dd` |
| `projectName` | String | 项目名称 |
| `expenseType` | String | [EXPENSE] 其他费用类型：固定 `OTHER` |
| `expenseTypeName` | String | [EXPENSE] 其他费用类型中文名（字典 `expense_type`） |
| `subsidyType` | String | [SUBSIDY] 补贴类型：`PHONE` / `OVERTIME` |
| `subsidyTypeName` | String | [SUBSIDY] 补贴类型中文名（字典 `subsidy_type`） |
| `amount` | Number | 核算金额（实际金额），两位小数 |
| `paymentMethod` / `paymentMethodName` | String | 付款方式 code / 中文名 |
| `sourceType` / `sourceTypeName` | String | 来源类型 code / 中文名；无来源时缺省 |
| `remark` | String | 备注 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组 |
### 5.11 成本逐项行 · INSURANCE 保险（SettlementGroupInsuranceLineVO）✨
| 字段 | 类型 | 说明 |
|------|------|------|
| `productName` | String | 保险产品名称 |
| `bizType` | String | 业务类型：`ORDER` / `DRIVER` |
| `bizTypeName` | String | 业务类型中文名（字典 `insurance_biz_type`，本次新增） |
| `totalPremium` | Number | 保费（即核算金额列），两位小数 |
| `extPolicyNo` | String | 外部保单号 |
| `voucherUrls` | Array&lt;String&gt; | 凭证 URL 数组（电子保单 PDF） |
> 保险行无 `plannedCost` / `sourceType` 字段，不输出。
## 6. 枚举 / 数据字典
### 6.1 `incomeLines[].type`（字典 `settlement_report_line_type`）
| 值 | 中文 | 说明 |
|----|------|------|
| `BASE_ORDER` | 订单应收 | 订单应收行 |
| `OTHER_INCOME` | 其他收入 | 其他收入行 |
| `DISCOUNT` | 优惠 | 优惠行（金额为负） |
| `ACTUAL_REFUND` | 实际退款 | 实际退款行（金额为负） |
### 6.2 `costCategories[].category`（字典 `settlement_category`）
| 值 | 中文 | 对应 lines 行结构 |
|----|------|-------------------|
| `HOTEL` | 住宿 | §5.5 |
| `TICKET` | 门票/游玩项目 | §5.6 |
| `MEAL` | 餐食 | §5.7 |
| `VEHICLE` | 车辆 | §5.8 |
| `GUIDE` | 导游 | §5.9 |
| `PHOTOGRAPHER` | 摄影 | §5.9（与 GUIDE 共用） |
| `OTHER_EXPENSE` | 其他支出 | §5.10 |
| `INSURANCE` | 保险 | §5.11 |
### 6.3 `paymentMethod`（字典 `settlement_payment_method`）
出现于：收入逐项明细、HOTEL / TICKET / MEAL / VEHICLE / 人员 / 其他支出各成本逐项行。
| 值 | 中文 |
|----|------|
| `CASH_PAID` | 现金已付 |
| `COMPANY_PAID` | 公司支付 |
| `SIGNED` | 签单 |
### 6.4 `details[].source`（字典 `settlement_refund_source`，✨ 本次新增字典）
仅 `ACTUAL_REFUND` 下人工返还行透出。
| 值 | 中文 |
|----|------|
| `DRIVER_ONSITE` | 司机现场返还 |
| `COMPANY_COMPENSATION` | 公司赔付 |
### 6.5 `lines[].bizType`（字典 `insurance_biz_type`，✨ 本次新增字典）
仅 INSURANCE 保险行。
| 值 | 中文 |
|----|------|
| `ORDER` | 订单险 |
| `DRIVER` | 司机险 |
### 6.6 `sourceType`（后端枚举 SettlementDetailSourceType）
出现于：收入逐项明细、HOTEL / TICKET / MEAL / VEHICLE / 人员 / 其他支出各成本逐项行。
| 值 | 中文 |
|----|------|
| `MANUAL` | 手工 |
| `HOUSE_ASSIGNMENT` | 配房结果 |
| `SCENIC_ASSIGNMENT` | 景区 |
| `ACTIVITY_ASSIGNMENT` | 游玩项目 |
| `MEAL_ASSIGNMENT` | 餐饮安排 |
| `FLEET` | 车务 |
| `STAFF_ASSIGNMENT` | 人员安排 |
| `ORDER_SURCHARGE` | 订单增费 |
| `SYSTEM` | 系统 |
### 6.7 `lines[].mealType`（字典 `meal_type`）
仅 MEAL 餐食行。
| 值 | 中文 |
|----|------|
| `BREAKFAST` | 早餐 |
| `LUNCH` | 午餐 |
| `DINNER` | 晚餐 |
| `SELF` | 自理 |
### 6.8 `lines[].serviceType`（字典 `staff_role`）
仅 GUIDE / PHOTOGRAPHER 人员行。本接口只会出现 `GUIDE` / `PHOTOGRAPHER` 两个值（字典另有 助理导游/领队/司机/其他，不在本接口出现）。
| 值 | 中文 |
|----|------|
| `GUIDE` | 导游 |
| `PHOTOGRAPHER` | 摄影师 |
### 6.9 `lines[].expenseType`（字典 `expense_type`）
VEHICLE 行（EXPENSE 族）：`FUEL`=油费 / `TOLL`=过路费 / `PARKING`=停车费 / `RENTAL`=租车费 / `MAINTENANCE`=维修保养。
OTHER_EXPENSE 行（EXPENSE 族）：固定 `OTHER`=其他。
### 6.10 `lines[].subsidyType`（字典 `subsidy_type`）
仅 OTHER_EXPENSE 行（SUBSIDY 族）。
| 值 | 中文 |
|----|------|
| `PHONE` | 话补 |
| `OVERTIME` | 加班补贴 |
### 6.11 `reportStatus`
| 值 | 中文 | 说明 |
|----|------|------|
| `GENERATED` | 已生成 | 未核单订单，实时组装 |
| `CONFIRMED` | 已确认 | 已核单（SETTLED）订单，终态快照回放 |
## 7. 错误码
| code | 含义 | 触发场景 |
|------|------|----------|
| 400 | 参数校验失败 | `orderId` 缺失或 < 1 |
| 581007 | 订单不存在 | `orderId` 对应订单不存在或已删除 |
| 581045 | 房务角色无权查看订单详情，房务仅可配房 | 房务管理员 / 房务组长角色调用 |
## 8. 示例（3 组：典型 / 边界 / 异常）
### 8.1 典型成功（已核单订单，逐项明细完整填充）
**请求**：
GET /v3/admin/order/1956112233445566778/settlement/reports/group
Authorization: Bearer <admin JWT>
（无请求体）
**响应**（节选，仅展示本次新增结构所在的 incomeLines / costCategories，顶层汇总字段与变更前一致故省略）：
```json
{
"code": 200,
"data": {
"id": "1957000000000000001",
"orderId": "1956112233445566778",
"reportStatus": "CONFIRMED",
"incomeLines": [
{
"type": "BASE_ORDER",
"typeName": "订单应收",
"amount": 12800.00,
"details": [
{
"itemName": "订单应收",
"content": "小红书(孙雷) 王彧琪",
"unitPrice": 1280.00,
"headCount": 10,
"amount": 12800.00
}
]
},
{
"type": "OTHER_INCOME",
"typeName": "其他收入",
"amount": 200.00,
"details": [
{
"itemName": "现场加收骑马费",
"unitPrice": 100.00,
"quantity": 2,
"amount": 200.00,
"paymentMethod": "CASH_PAID",
"paymentMethodName": "现金已付",
"sourceType": "ORDER_SURCHARGE",
"sourceTypeName": "订单增费",
"remark": "现场加收"
}
]
},
{
"type": "DISCOUNT",
"typeName": "优惠",
"amount": -500.00,
"details": [
{
"itemName": "早鸟优惠",
"amount": -500.00
}
]
},
{
"type": "ACTUAL_REFUND",
"typeName": "实际退款",
"amount": -300.00,
"details": [
{
"itemName": "司机现场返还",
"content": "少住一晚退房差",
"source": "DRIVER_ONSITE",
"sourceName": "司机现场返还",
"amount": -300.00,
"paymentMethod": "CASH_PAID",
"paymentMethodName": "现金已付",
"remark": "现场返还现金"
}
]
}
],
"costCategories": [
{
"category": "HOTEL",
"categoryName": "住宿",
"amount": 3600.00,
"lines": [
{
"stayDate": "2026-07-30",
"hotelName": "草原明珠大酒店",
"roomTypeName": "标间",
"roomCount": 3,
"unitPrice": 400.00,
"plannedCost": 1200.00,
"amount": 1200.00,
"paymentMethod": "CASH_PAID",
"paymentMethodName": "现金已付",
"sourceType": "HOUSE_ASSIGNMENT",
"sourceTypeName": "配房结果",
"remark": "含早",
"voucherUrls": ["https://oss/v1.jpg"]
}
]
},
{
"category": "VEHICLE",
"categoryName": "车辆",
"amount": 1760.00,
"lines": [
{
"serviceDate": "2026-07-30",
"startDate": "2026-07-30",
"endDate": "2026-07-31",
"vehiclePlate": "蒙A-5376",
"vehicleModelName": "坦克500",
"driverName": "司机甲",
"dailyPrice": 880.00,
"amount": 880.00,
"paymentMethod": "CASH_PAID",
"paymentMethodName": "现金已付",
"sourceType": "FLEET",
"sourceTypeName": "车务"
},
{
"expenseType": "FUEL",
"expenseTypeName": "油费",
"projectName": "全程油费",
"expenseDate": "2026-07-31",
"amount": 880.00,
"paymentMethod": "COMPANY_PAID",
"paymentMethodName": "公司支付",
"sourceType": "FLEET",
"sourceTypeName": "车务"
}
]
},
{
"category": "GUIDE",
"categoryName": "导游",
"amount": 1600.00,
"lines": [
{
"serviceDate": "2026-07-30",
"name": "导游乙",
"serviceType": "GUIDE",
"serviceTypeName": "导游",
"amount": 1600.00,
"paymentMethod": "SIGNED",
"paymentMethodName": "签单",
"sourceType": "STAFF_ASSIGNMENT",
"sourceTypeName": "人员安排"
}
]
},
{
"category": "INSURANCE",
"categoryName": "保险",
"amount": 150.00,
"lines": [
{
"productName": "保游畅享境内游保险",
"bizType": "ORDER",
"bizTypeName": "订单险",
"totalPremium": 150.00,
"extPolicyNo": "PY20260730001",
"voucherUrls": ["https://oss/policy1.pdf"]
}
]
}
]
},
"msg": ""
}
```
### 8.2 边界情况（无任何逐项明细 / 金额为 0）
**场景说明**：订单无任何其他收入、优惠、退款，且各成本分类未录入任何逐项 —— `details` / `lines` 返回**空数组** `[]`（不是 null），对应分类 `amount` 可为 `0.00`。所有 null 的可选字段（unitPrice / headCount / paymentMethod / remark / voucherUrls 等）**整体缺省不出现在 JSON 中**。
**请求**：
GET /v3/admin/order/1956112233445566889/settlement/reports/group
Authorization: Bearer <admin JWT>
（无请求体）
**响应**（节选）：
```json
{
"code": 200,
"data": {
"orderId": "1956112233445566889",
"reportStatus": "GENERATED",
"incomeLines": [
{ "type": "BASE_ORDER", "typeName": "订单应收", "amount": 12800.00, "details": [
{ "itemName": "订单应收", "unitPrice": 1280.00, "headCount": 10, "amount": 12800.00 }
] },
{ "type": "OTHER_INCOME", "typeName": "其他收入", "amount": 0.00, "details": [] },
{ "type": "DISCOUNT", "typeName": "优惠", "amount": 0.00, "details": [] },
{ "type": "ACTUAL_REFUND", "typeName": "实际退款", "amount": 0.00, "details": [] }
],
"costCategories": [
{ "category": "HOTEL", "categoryName": "住宿", "amount": 0.00, "lines": [] },
{ "category": "TICKET", "categoryName": "门票/游玩项目", "amount": 0.00, "lines": [] },
{ "category": "MEAL", "categoryName": "餐食", "amount": 0.00, "lines": [] },
{ "category": "VEHICLE", "categoryName": "车辆", "amount": 0.00, "lines": [] },
{ "category": "GUIDE", "categoryName": "导游", "amount": 0.00, "lines": [] },
{ "category": "PHOTOGRAPHER", "categoryName": "摄影", "amount": 0.00, "lines": [] },
{ "category": "OTHER_EXPENSE", "categoryName": "其他支出", "amount": 0.00, "lines": [] },
{ "category": "INSURANCE", "categoryName": "保险", "amount": 0.00, "lines": [] }
]
},
"msg": ""
}
```
### 8.3 业务失败（订单不存在 / 房务角色越权）
**场景说明 A**：`orderId` 不存在 → 581007。
**请求**：
GET /v3/admin/order/999999999/settlement/reports/group
Authorization: Bearer <admin JWT>
（无请求体）
**响应**：
```json
{ "code": 581007, "msg": "订单不存在", "data": null }
```
**场景说明 B**：房务管理员角色调用 → 581045。
```json
{ "code": 581045, "msg": "房务角色无权查看订单详情，房务仅可配房", "data": null }
```
## 9. 业务边界
- ✅ **适用场景**：订单存在即可调；未核单订单（`reportStatus=GENERATED`）走实时组装，已核单订单（`reportStatus=CONFIRMED`）走终态快照回放，**两条路径出参结构完全一致**，前端无需区分
- ❌ **不适用场景**：房务角色（ROOM_MANAGER / HOUSE_KEEPER_LEAD）调用 → 581045
- ⚠️ **特殊边界**：
- 逐项明细**不出已付/未付逐行列**，逐行只有单价/数量/核算金额（`paidCost` / `unpaidCost` 仍是顶层分类维度的合计口径，不在逐项层）
- VEHICLE / OTHER_EXPENSE 两分类的行是同数组内两族结构稀疏并集（见 §5.8 / §5.10），前端渲染列时按「本族字段是否出现」判别
- `DISCOUNT` / `ACTUAL_REFUND` 行及其明细金额均为**负数**，前端不要自行取绝对值
## 10. 修改前后对比
### 10.1 字段级对比
| 字段 | 改前 | 改后 |
|------|------|------|
| `incomeLines[].details` | 无此字段 | ✨ 新增 `Array<SettlementGroupIncomeDetailVO>`，无逐项时为 `[]` |
| `costCategories[].lines` | 无此字段 | ✨ 新增 `Array`（分类专属行结构，按 `category` 窄化），无逐项时为 `[]` |
| 顶层汇总字段 / 4 行收入合计 / 8 行成本合计 | 现状 | **不变** |
### 10.2 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 核算表核对逐项明细 | 只能看到行合计，需跳各分类明细页签逐条对账 | 行内直接展开 `details` / `lines` 逐项 |
| 数据字典 | 无 `insurance_biz_type` / `settlement_refund_source` | ✨ 新增两个字典（保险业务类型 / 人工返还来源） |
## 11. 影响评估 / 回滚
### 11.1 影响评估
- **是否破坏向后兼容**：否。纯出参增量，原有字段名 / 类型 / 结构 / 合计口径零变化；老前端不读 `details` / `lines` 不受影响
- **前端是否必须同步上线**：否。前端按自身排期接入逐项展开即可
### 11.2 回滚方案
- **回滚方式**：revert PR #5786
- **回滚后清理**：无（无 DDL、无缓存、无脏数据；两个字典 `insurance_biz_type` / `settlement_refund_source` 保留无害）
## 12. 注意事项
- **null 字段整体缺省**：所有行 VO 标注了 null 不序列化，可选字段（unitPrice / headCount / quantity / paymentMethod / sourceType / remark / voucherUrls 等）为 null 时**该 key 不出现在 JSON 中**，前端按可选字段处理，不要断言 key 必存在
- `details` / `lines` 无逐项时是**空数组 `[]`** 而不是字段缺省，可直接 `.length` 判空
- **行结构窄化**：`costCategories[].lines` 元素是多态结构，前端必须先按 `category` 判别再取分类专属字段（GUIDE / PHOTOGRAPHER 共用人员行结构）
- **金额符号**：`DISCOUNT` / `ACTUAL_REFUND` 的行金额与明细金额均为负数；成本各行为正数
- **中文名渲染**：`*Name` 字段后端已回填中文名（字典缺值时回退硬编码），可直接展示；如需动态字典渲染，调 `GET /admin/dict/data/{dictType}`，dictType 见 §6 各子节
- 无历史 workaround 需要清理（本能力此前不存在）
## 13. 关联 / 联系人
### 13.1 链接
- **Issue**: [#5781](https://git.1814.love:8443/wx/HL/issues/5781)
- **PR**: [#5786](https://git.1814.love:8443/wx/HL/pulls/5786)
- **Merge commit**: [fdc429bf](https://git.1814.love:8443/wx/HL/commit/fdc429bf8546ce2cbb8c69f4166b153cccb4839c)
### 13.2 联系人
- **后端负责人**: @yaosutu