From 3f3f5e755890cad8f8264b3867152795ec9dfcc6 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 30 Sep 2026 11:04:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=9B=A2=E6=9C=9F=E6=A0=B8?= =?UTF-8?q?=E5=8D=95=E5=88=86=E7=B1=BB=E7=A7=91=E7=9B=AE=E6=98=8E=E7=BB=86?= =?UTF-8?q?=20tab=E2=80=94=E2=80=948=20=E4=B8=AA=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E8=AF=BB=E7=AB=AF=E7=82=B9=EF=BC=88#8632=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 团期核单新增 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。 --- ..._团期核单分类科目明细-新增接口-管理后台.md | 231 ++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 changelogs-v2/2026-09/30_8632_团期核单分类科目明细-新增接口-管理后台.md diff --git a/changelogs-v2/2026-09/30_8632_团期核单分类科目明细-新增接口-管理后台.md b/changelogs-v2/2026-09/30_8632_团期核单分类科目明细-新增接口-管理后台.md new file mode 100644 index 00000000..0f11219e --- /dev/null +++ b/changelogs-v2/2026-09/30_8632_团期核单分类科目明细-新增接口-管理后台.md @@ -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`。 + +### 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` | 该科目的核单科目行，**整团维度**，默认空数组（不返回 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 +- 负责人：腰苏图