docs(changelog): 团期核单分类科目明细 tab——8 个新增读端点（#8632）

团期核单新增 8 个分类明细只读端点（/v3/admin/order/group-batch/{id}/settlement/{hotels,activities,vehicles,guide-fees,photographer-fees,meals,other-expenses,other-incomes}），数据来自团维度 order_batch_audit_item 按 category 过滤，命名对齐核心订单核单 tab。管理后台目录 changelogs-v2/，关联 PR #8634。
2026-09-30 11:04:46 +08:00
@@ -0,0 +1,231 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8632"
+title: "团期核单新增 8 个分类科目明细只读端点（住宿/景区门票/车辆/导游/摄影/餐食/其他支出/其他收入）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-09-30"
+base: "dev-v3"
+updated_at: "2026-09-30"
+status_note: "团期核单弹窗补 8 个分类明细 tab 的只读端点，命名语义化（核心订单 step1/2/3 改 hotels/activities/vehicles，其余沿用核心订单既有语义名），数据来自团维度 order_batch_audit_item 按 category 过滤。行复用核单录入面板的 ItemVO（整团维度，无 orderId/orderNo/customerName 归属字段），外层带 auditStatus 供前端渲 NOT_STARTED 空态。后端已部署测试服并行为级验证：gid 不存在返 589500，真实未返团团期返 NOT_STARTED + 空 items（五字段齐全、categoryText 中文正确）。前端可按 §5 字段表接入各分类 tab（与核心订单核单同一套渲染思路，路径逐字对齐核心订单命名）。"
+---
+
+# 团期核单分类科目明细 tab —— 新增接口（管理后台）
+
+> Issue: https://git.1814.love/wx/HL/issues/8632
+> PR: https://git.1814.love/wx/HL/pulls/8634
+> Commit: https://git.1814.love/wx/HL/commit/02572e5daa62432c6cf31393d62eadaafd993066
+> 负责人：腰苏图
+
+---
+
+## 1. 接口背景
+
+团期核单弹窗（一团一核单）此前只有「核单录入」`GET /v3/admin/order/group-batch/{groupBatchId}/audit`（返回全科目平铺 items）和「聚合复核」两个 tab。前端要按「酒店住宿 / 景区门票 / 车辆 / 导游 / 摄影 / 餐食 / 其他支出 / 其他收入」分 tab 展示，需自己按 category 过滤，且与核心订单核单「一 tab 一接口」的对接模式不一致。
+
+本次新增 **8 个分类明细只读端点**，让团期核单弹窗可以像核心订单核单一样，一个 tab 调一个专用接口。数据全部来自团维度核单科目表（`order_batch_audit_item`），与「核单录入」面板同源。
+
+关联：#8510 / PR #8546（团期核单详情对齐常规订单核单 PR-1：财务总览 + 客户合并 + 人数口径）。
+
+---
+
+## 2. 变更清单
+
+| 类型 | 接口 | 说明 |
+|---|---|---|
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/hotels` | 住宿（HOUSE） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/activities` | 景区门票（ACTIVITY） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/vehicles` | 车辆（VEHICLE） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/guide-fees` | 导游（GUIDE） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/photographer-fees` | 摄影（PHOTO） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/meals` | 餐食（MEAL） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/other-expenses` | 其他支出（OTHER_EXPENSE） |
+| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/other-incomes` | 其他收入（OTHER_INCOME） |
+
+8 个端点结构完全一致，只是固定过滤一个 category。无入参字段、无枚举变更、无删除。
+
+---
+
+## 3. 接口详情
+
+- **方法/路径**：`GET /v3/admin/order/group-batch/{groupBatchId}/settlement/{分类路径段}`
+- **鉴权**：管理后台，复用团期核单查看权限 `group-batch:audit:view`（GROUP_BATCH_MANAGER / FINANCE / ADMIN）
+- **路径段与 category 对应**：hotels→HOUSE、activities→ACTIVITY、vehicles→VEHICLE、guide-fees→GUIDE、photographer-fees→PHOTO、meals→MEAL、other-expenses→OTHER_EXPENSE、other-incomes→OTHER_INCOME
+- **说明**：返回该团期核单下指定科目的全量科目行（不分页，单类通常几行到二三十行）。命名对齐核心订单核单 tab（核心订单 step1→hotels、step2→activities、step3/vehicles→vehicles，其余语义名沿用）。
+
+---
+
+## 4. 入参
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| `groupBatchId` | path | Long | 是 | 运营团期 ID |
+
+无 query / body 参数。
+
+---
+
+## 5. 出参
+
+统一返回 `Result<GroupBatchAuditItemsRespVO>`。
+
+### 5.1 GroupBatchAuditItemsRespVO（外层）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `auditStatus` | String | 核单状态：`NOT_STARTED`（未开始/未返团）/ `DRAFT`（录入中）/ `ALLOCATED`（已核算）/ `CHECKED`（已验团）。前端据此渲空态 |
+| `batchStatus` | String | 团期状态（GroupBatchStatus，如 RECRUITING/RESOURCE_PREPARING/TRIP_FINISHED/REVIEWING/SETTLED 等） |
+| `category` | String | 本端点固定的科目大类（见 §3 对应表） |
+| `categoryText` | String | 科目大类中文（住宿/景区娱乐/车辆/导游/摄影/用餐/其他支出/其他收入） |
+| `items` | `List<ItemVO>` | 该科目的核单科目行，**整团维度**，默认空数组（不返回 null） |
+
+### 5.2 ItemVO（科目行，复用核单录入面板结构）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `itemId` | String | 科目行 ID（Long 序列化为字符串，防 JS 精度丢失） |
+| `category` | String | 科目大类（与本端点固定值一致） |
+| `itemName` | String | 科目名，如「D2 图嘎营地 蒙古包」「导游·双领队」 |
+| `dayNo` | Integer | 第几天/第几晚，无日归属为 null |
+| `unitPrice` | String | 单价（单价型科目，如房每晚房价；金额字符串），总额型为 null |
+| `totalAmount` | String | 总额（总额型科目，如车/导游/其他收支；金额字符串），单价型为 null |
+| `allocRule` | String | 分摊口径：`PER_ROOM_NIGHT`（按各户用房数）/ `PER_HEAD_CHECKED`（勾选参加后按人数）/ `PER_VEHICLE_GROUP`（按乘车分组内户数均分）/ `PER_ORDER_AVG`（按户平均） |
+| `allocGroup` | String | 分摊分组（车科目 BUS / SUV），无分组为 null |
+| `budgetAmount` | String | 带出源金额（仅供对比，不参与计算；金额字符串） |
+| `changeReason` | String | 改价原因（科目行本身不存此列，读接口恒为 null） |
+| `seq` | Integer | 排序 |
+
+> 说明：`unitPrice` 与 `totalAmount` 互斥——单价型科目（住宿/景娱/餐）有 `unitPrice` 无 `totalAmount`，总额型科目（车辆/导游/摄影/其他收支）反之。`items` 为**整团科目行**，不含逐户归属字段（无 orderId/orderNo/customerName），也不含逐户用量明细。
+
+---
+
+## 6. 枚举 / 数据字典
+
+- **auditStatus**：`NOT_STARTED` / `DRAFT` / `ALLOCATED` / `CHECKED`
+- **category**：`HOUSE` / `VEHICLE` / `ACTIVITY` / `MEAL` / `GUIDE` / `PHOTO` / `OTHER_EXPENSE` / `OTHER_INCOME`
+- **allocRule**：`PER_ROOM_NIGHT` / `PER_HEAD_CHECKED` / `PER_VEHICLE_GROUP` / `PER_ORDER_AVG`
+
+无新增枚举值（全部复用核单录入既有枚举）。
+
+---
+
+## 7. 错误码
+
+| 错误码 | 说明 |
+|---|---|
+| `589500` | 团期不存在（groupBatchId 非法） |
+| 403 | 无 `group-batch:audit:view` 权限 |
+
+---
+
+## 8. 示例
+
+### 8.1 典型（已返团团期，住宿 tab）
+
+`GET /v3/admin/order/group-batch/2105074382613413890/settlement/hotels`
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "auditStatus": "DRAFT",
+    "batchStatus": "REVIEWING",
+    "category": "HOUSE",
+    "categoryText": "住宿",
+    "items": [
+      {
+        "itemId": "1934567890123456790",
+        "category": "HOUSE",
+        "itemName": "D2 图嘎营地 蒙古包",
+        "dayNo": 2,
+        "unitPrice": "380.00",
+        "totalAmount": null,
+        "allocRule": "PER_ROOM_NIGHT",
+        "allocGroup": null,
+        "budgetAmount": "5320.00",
+        "changeReason": null,
+        "seq": 1
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+### 8.2 边界（未返团团期，空态）
+
+`GET /v3/admin/order/group-batch/{未返团团期}/settlement/meals`
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "auditStatus": "NOT_STARTED",
+    "batchStatus": "RESOURCE_PREPARING",
+    "category": "MEAL",
+    "categoryText": "用餐",
+    "items": []
+  },
+  "success": true
+}
+```
+
+### 8.3 异常（团期不存在）
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "data": null,
+  "success": false
+}
+```
+
+---
+
+## 9. 业务边界
+
+- **整团维度**：`items` 是整团核单科目行（来自「核单录入」面板同一份数据），**不含逐户归属**（无 orderId/orderNo/customerName），也不含逐户用量明细。前端按 tab 直接渲染即可，无需按户分组。
+- **生命周期**：住宿/门票等科目行**在团期返团后、首次打开核单面板时才生成**。未返团的团期调任一分类端点返回 `auditStatus=NOT_STARTED` + 空 `items`（见 8.2）；已返团首读会自动建 DRAFT（读接口带写副作用，权限判权在先）。
+- **数据来源**：与「核单录入」`GET .../audit` 的 `items[]` 完全同源，本批端点只是按 category 拆成独立 tab 读口，不改变数据本身。
+
+---
+
+## 10. 修改前后对比（修改类）
+
+非修改类（纯新增接口），不适用。
+
+---
+
+## 11. 影响评估 / 回滚（修改类）
+
+- **兼容性**：纯新增接口，不影响任何既有接口。
+- **性能**：单端点一次查询 + 内存按 category 过滤，不分页、无 N+1；不触碰核单试算。
+- **回滚**：回退 merge commit `02572e5daa` 即可下线 8 个端点；无 DDL、无数据迁移成本。
+
+---
+
+## 12. 注意事项
+
+1. 8 个端点结构完全一致，前端可封装一个通用的「分类 tab 请求 + 渲染」组件，按路径段切换。
+2. 渲染空态请看 `auditStatus`（`NOT_STARTED` 时显示「团期未返团，返团后可核单」类提示），而不是看 `items` 是否为空（已返团某科目无数据时 items 也为空，但 auditStatus 是 DRAFT）。
+3. 金额字段（unitPrice/totalAmount/budgetAmount）是**字符串**（BigDecimal 序列化），展示直接用，参与计算需自行转数值。
+4. 本批是「分类科目明细」读口；核单录入（写）与逐户用量下钻走既有 `/audit` 与下钻端点，不在本批范围。
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue: https://git.1814.love/wx/HL/issues/8632
+- PR: https://git.1814.love/wx/HL/pulls/8634
+- Commit: https://git.1814.love/wx/HL/commit/02572e5daa62432c6cf31393d62eadaafd993066
+- 负责人：腰苏图