wx/hl-api-changelog

派生 0

文件

T

Mimingguang 653936db83

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): #8632/#8641 回写 implemented(hl-admin d5a372be)

2026-09-30 17:59:13 +08:00

10 KiB

原始文件 永久链接 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, base, updated_at, status_note

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	base	updated_at	status_note
hl-changelog/v2	8632	团期核单新增 8 个分类科目明细只读端点（住宿/景区门票/车辆/导游/摄影/餐食/其他支出/其他收入）	admin	yst(GIT)	新增接口	deployed	verified	implemented	hl-admin(claude-opus-4-8)	d5a372be4a2079adf9c1ca91a68b992f92918507	v2.1	2026-09-30	dev-v3	2026-09-30	团期核单弹窗补 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（与核心订单核单同一套渲染思路，路径逐字对齐核心订单命名）。;前端已交付:step2 只读 8 tab 区(GroupCategoryItems 一 tab 一接口懒加载+缓存,空态判 auditStatus=NOT_STARTED),33 例定向全绿

团期核单分类科目明细 tab —— 新增接口（管理后台）

Issue: wx/HL#8632 PR: wx/HL#8634 Commit: 02572e5daa 负责人：腰苏图

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

{
  "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

{
  "code": 200,
  "message": "成功",
  "data": {
    "auditStatus": "NOT_STARTED",
    "batchStatus": "RESOURCE_PREPARING",
    "category": "MEAL",
    "categoryText": "用餐",
    "items": []
  },
  "success": true
}

8.3 异常（团期不存在）

{
  "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. 注意事项

8 个端点结构完全一致，前端可封装一个通用的「分类 tab 请求 + 渲染」组件，按路径段切换。
渲染空态请看 auditStatus（NOT_STARTED 时显示「团期未返团，返团后可核单」类提示），而不是看 items 是否为空（已返团某科目无数据时 items 也为空，但 auditStatus 是 DRAFT）。
金额字段（unitPrice/totalAmount/budgetAmount）是字符串（BigDecimal 序列化），展示直接用，参与计算需自行转数值。
本批是「分类科目明细」读口；核单录入（写）与逐户用量下钻走既有 /audit 与下钻端点，不在本批范围。

13. 关联 / 联系人

Issue: wx/HL#8632
PR: wx/HL#8634
Commit: 02572e5daa
负责人：腰苏图

10 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape