wx/hl-api-changelog

派生 0

文件

T

Mimingguang和Claude Opus 4.8 eb2dc899f2

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

详情

chore(changelog): #8516 回写 implemented(hl-admin d8de94a8)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-10-01 09:36:34 +08:00

53 KiB

原始文件 Blame 文件历史

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

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8516	团期状态「出行完毕」TRIP_FINISHED 改名「待核单」PENDING_REVIEW（破坏性，前端须同批发布）；团期详情 / 分页新增整团核单、结算状态四个字段；进度条核单 / 结算节点新增分支；三处入参旧值兼容	admin	jw(GIT)	修改接口	deployed	verified	implemented	hl-admin(claude-opus-4-8)	d8de94a894680f3b3e62985f03fce235ccb0f3f8	v2.1	2026-10-01	① 团期主状态取值 TRIP_FINISHED「出行完毕」改为 PENDING_REVIEW「待核单」，存量数据与时间线历史行已随迁移改写，所有返回团期主状态的接口只输出新值；出行子状态 tripSubStatus 同步由 TRIP_FINISHED「已返团」改为 PENDING_REVIEW「待核单」。② A2 团期详情、A1 团期分页新增 reviewStatus / reviewStatusName / settlementStatus / settlementStatusName。③ 详情进度条 REVIEW、SETTLE 节点各新增一条分支，文案如「核单·已核单」「结算·结算中」，字段为 NONE 时「待开始」；当前节点仍按主状态分桶。④ 团期分页 batchStatus、房务配房列表（含 scope=mine）batchStatus、房务团期看板 batchStatus 传旧值 TRIP_FINISHED 时按 PENDING_REVIEW 处理；opsStage=TRIP_FINISHED 旧桶名保留。⑤ 团期时间线新增「核单状态变更」「结算状态变更」两类事件。⑥ 发起核单、首笔共享成本、/settle、/settle/reopen 四个既有写入口请求与响应不变，/settle 不再逐户推 ORDER 报账单。hl-ui 必须同批改：按 TRIP_FINISHED 判断的 7 处与显示映射 3 处，不改则「发起核单」按钮消失、财务面板「完成核单」点不了。TEST 已于 2026-09-30 部署（dev-v3 dd0452916，合并提交 54e64c50f）并实测；jw 09-30 定 TEST 先行，正式环境前后端同批发布，故 frontend_status 记 pending。财务回写用的两个内部接口见同日 30_8516 新增接口那份。2026-10-01 hl-admin 交付：判断 7 处改 [TRIP_FINISHED, PENDING_REVIEW] 并集兼容（batchLifecycle/orderDetailActions/requirementFreeze/canStartReview/canWaive/FinanceTab ADVANCE_STAGES/finalizeNodeOk），显示映射 3 处加新键保留旧键（FLOW_STATUS_TEXT/boardLabels/GroupBatchTable），BatchHero 页头新增「核单·X」「结算·X」标签（NONE 不显示，直显后端 *Name，与进度条分支文案一致），api JSDoc 3 文件钉新口径；定向 4 spec 66 例全绿，ref d8de94a8。	2026-09-30	dev-v3

团期：「出行完毕」改名「待核单」，新增整团核单 / 结算状态字段（管理后台）

服务: hl-order-service-v3（端口 8086 / 8186） PR: #8650（merge commit 54e64c50f） Issue: #8516 日期: 2026-09-30 影响范围: 团期详情 / 分页 / 进度条 / 时间线的核单、结算展示；团期状态筛选入参；所有按团期状态值做判断的前端代码

⚠️ 关键变化

破坏性变更，前端必须与后端同批发布。

变了什么	以前	现在
团期主状态 `batchStatus` 的一个取值	`TRIP_FINISHED`「出行完毕」	`PENDING_REVIEW`「待核单」。存量团期、时间线历史行已统一改写，任何接口的返回值里都不再出现 `TRIP_FINISHED`
出行子状态 `tripSubStatus` 的一个取值	`TRIP_FINISHED`「已返团」	`PENDING_REVIEW`「待核单」；进度条出行节点 label 同步变为「待核单」
团期详情、分页	没有整团核单 / 结算状态	新增 `reviewStatus` / `reviewStatusName` / `settlementStatus` / `settlementStatusName`
详情进度条核单、结算节点	`subFlows=null`	各带一条分支，如「核单·已核单」「结算·结算中」
`/settle` 整团结算	逐户做财务复核并推 ORDER 报账单（#8341）	只把子订单状态置为已结算，不推报账单；请求 / 响应不变

前端代码里凡是写死 'TRIP_FINISHED' 当状态值判断的地方，不改就会静默失效——最明显的是团期详情「发起核单」按钮会消失、财务面板「完成核单」点不了（清单见六.7）。

一、背景

jw 09-29 定口径：团期上加核单、结算两个独立状态（写法参照配房、配车），出行结束后团期自动进入「待核单」，此后核单中、已核单、待结算、结算中、已结算都由财务从外部更新，团期主状态由这两个状态推导，子订单跟着同步。

「出行完毕」描述的是出行结束这件事，事件之后团期所处的状态是「待核单」，所以主状态改名；时间线里的事件「出行完毕」BATCH_TRIP_FINISH 不改名。财务回写这两个状态用的内部接口见同日 30_8516_团期核单与结算状态财务内部回写接口-新增接口-管理后台.md（前端无需对接）。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	A2 团期详情	GET	`/v3/admin/order/group-batch/:groupBatchId`	修改接口	新增 4 个字段；`batchStatus` / `tripSubStatus` 取值改名；进度条核单、结算节点新增分支
2	A1 团期分页	GET	`/v3/admin/order/group-batch`	修改接口	新增 4 个字段；取值改名；入参 `batchStatus` 旧值兼容；`opsStage=TRIP_FINISHED` 桶名保留
3	房务配房列表（团期）	GET	`/v3/admin/order/house-allocation/group-batches`	修改接口	入参 `batchStatus` 旧值兼容（含 `scope=mine`，改前返回 400）；`batchStatus` / `batchStatusLabel` 取值改名
4	房务团期看板列表	GET	`/v3/admin/house/group-batches`	修改接口	入参 `batchStatus` 旧值兼容（改前退回默认筛选）；`batchStatus` / `batchStatusText` 取值改名
5	团期状态流水（时间线）	GET	`/v3/admin/order/group-batch/:groupBatchId/status-logs`	修改接口	新增「核单状态变更」「结算状态变更」两类事件；`fromStatus` / `toStatus` 取值改名（含历史行）

三、接口详情

1. A2 团期详情 `GET /v3/admin/order/group-batch/:groupBatchId`

VO: GroupBatchDetailRespVO（进度条节点 GroupBatchProgressNodeVO，分支 GroupBatchProgressSubFlowVO）

使用场景

团期详情页页头状态、进度条、核单 / 结算信息。本次新增整团核单 / 结算状态四个字段，进度条核单、结算节点新增分支，主状态与出行子状态的「出行完毕 / 已返团」改为「待核单」。其余出参不变。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	团期 ID	不存在返回 589500；未变

出参 `Result<GroupBatchDetailRespVO>`

只列本次新增或取值有变化的字段。

字段	类型	说明
reviewStatus	String	新增。整团核单状态：`NONE` 未核单（还没出行完毕）/ `PENDING` 待核单 / `IN_PROGRESS` 核单中 / `COMPLETED` 已核单。与子订单核单状态同名同值。恒非 null
reviewStatusName	String	新增。未核单 / 待核单 / 核单中 / 已核单
settlementStatus	String	新增。整团结算状态：`NONE` 未结算（核单还没完成）/ `PENDING` 待结算 / `IN_PROGRESS` 结算中 / `COMPLETED` 已结算。恒非 null。与财务 tab 逐户付款结清的 `settleStatus` 无关
settlementStatusName	String	新增。未结算 / 待结算 / 结算中 / 已结算
batchStatus	String	取值 `TRIP_FINISHED` 改为 `PENDING_REVIEW`，其余八个取值不变
batchStatusName	String	「出行完毕」改为「待核单」
tripSubStatus	String	仅 `stage=TRIP` 时有值：`PENDING_DEPARTURE` 待出发 / `TRAVELLING` 出行中 / `PENDING_REVIEW` 待核单（原 `TRIP_FINISHED` 已返团）
tripSubStatusName	String	「已返团」改为「待核单」
progressStepper[].label	String	出行节点为当前节点且团期待核单时，由「已返团」改为「待核单」
progressStepper[].subFlows	List<GroupBatchProgressSubFlowVO>	REVIEW、SETTLE 两个节点由 `null` 改为各 1 条分支；CONFIGURE 仍是 5 条；RECRUIT / CONFIRM / TRIP 仍为 `null`
progressStepper[].subFlows[].code	String	核单节点 `REVIEW`，结算节点 `SETTLE`
progressStepper[].subFlows[].name	String	核单 / 结算
progressStepper[].subFlows[].status	String	直接取 `reviewStatus` / `settlementStatus` 的值：`PENDING` / `IN_PROGRESS` / `COMPLETED`；字段为 `NONE` 时为 `WAITING`
progressStepper[].subFlows[].statusName	String	核单节点：待核单 / 核单中 / 已核单；结算节点：待结算 / 结算中 / 已结算；字段为 `NONE` 时「待开始」
progressStepper[].subFlows[].displayText	String	`name·statusName`，如「核单·已核单」「结算·结算中」「结算·待开始」

请求示例

GET /v3/admin/order/group-batch/2105223438312652802 HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

无请求体。

响应示例

T26-5936（核单已完成、结算中）：注意核单节点 label 仍是「核单中」（按主状态分桶），分支是「核单·已核单」（TEST 2026-09-30 实测，只列与本次相关的字段）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2105223438312652802",
    "batchNo": "T26-5936",
    "batchName": "呼伦贝尔草原3日游·9月26日团",
    "batchStatus": "REVIEWING",
    "batchStatusName": "核单中",
    "reviewStatus": "COMPLETED",
    "reviewStatusName": "已核单",
    "settlementStatus": "IN_PROGRESS",
    "settlementStatusName": "结算中",
    "stage": "REVIEW",
    "stageName": "核单",
    "tripSubStatus": null,
    "tripSubStatusName": null,
    "progressStepper": [
      {"step": 1, "code": "RECRUIT", "name": "招募", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 2, "code": "CONFIGURE", "name": "配置", "status": "DONE", "label": null, "isCurrent": false, "subFlows": [
        {"code": "HOTEL", "name": "配房", "status": "UNMET", "statusName": "未配齐", "displayText": "配房·未配齐"},
        {"code": "VEHICLE", "name": "配车", "status": "UNMET", "statusName": "未配齐", "displayText": "配车·未配齐"},
        {"code": "GUIDE", "name": "配导游", "status": "WAIVED", "statusName": "无需", "displayText": "配导游·无需"},
        {"code": "PHOTOGRAPHER", "name": "配摄影", "status": "WAIVED", "statusName": "无需", "displayText": "配摄影·无需"},
        {"code": "MATERIAL", "name": "配物资", "status": "UNMET", "statusName": "未确认", "displayText": "配物资·未确认"}
      ] },
      {"step": 3, "code": "CONFIRM", "name": "确认", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 4, "code": "TRIP", "name": "出行", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 5, "code": "REVIEW", "name": "核单", "status": "PROCESSING", "label": "核单中", "isCurrent": true, "subFlows": [
        {"code": "REVIEW", "name": "核单", "status": "COMPLETED", "statusName": "已核单", "displayText": "核单·已核单"}
      ] },
      {"step": 6, "code": "SETTLE", "name": "结算", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "SETTLE", "name": "结算", "status": "IN_PROGRESS", "statusName": "结算中", "displayText": "结算·结算中"}
      ] }
    ]
  },
  "traceId": null,
  "success": true
}

T26-2325（待核单）：主状态、出行子状态、出行节点 label 都是「待核单」，核单分支「核单·待核单」：

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2105223439872933889",
    "batchNo": "T26-2325",
    "batchName": "呼伦贝尔草原3日游·9月25日团",
    "batchStatus": "PENDING_REVIEW",
    "batchStatusName": "待核单",
    "reviewStatus": "PENDING",
    "reviewStatusName": "待核单",
    "settlementStatus": "NONE",
    "settlementStatusName": "未结算",
    "stage": "TRIP",
    "stageName": "出行",
    "tripSubStatus": "PENDING_REVIEW",
    "tripSubStatusName": "待核单",
    "progressStepper": [
      {"step": 1, "code": "RECRUIT", "name": "招募", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 2, "code": "CONFIGURE", "name": "配置", "status": "DONE", "label": null, "isCurrent": false, "subFlows": [
        {"code": "HOTEL", "name": "配房", "status": "UNMET", "statusName": "未配齐", "displayText": "配房·未配齐"},
        {"code": "VEHICLE", "name": "配车", "status": "WAIVED", "statusName": "整团免车", "displayText": "配车·整团免车"},
        {"code": "GUIDE", "name": "配导游", "status": "WAIVED", "statusName": "无需", "displayText": "配导游·无需"},
        {"code": "PHOTOGRAPHER", "name": "配摄影", "status": "WAIVED", "statusName": "无需", "displayText": "配摄影·无需"},
        {"code": "MATERIAL", "name": "配物资", "status": "UNMET", "statusName": "未确认", "displayText": "配物资·未确认"}
      ] },
      {"step": 3, "code": "CONFIRM", "name": "确认", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 4, "code": "TRIP", "name": "出行", "status": "PROCESSING", "label": "待核单", "isCurrent": true, "subFlows": null },
      {"step": 5, "code": "REVIEW", "name": "核单", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "REVIEW", "name": "核单", "status": "PENDING", "statusName": "待核单", "displayText": "核单·待核单"}
      ] },
      {"step": 6, "code": "SETTLE", "name": "结算", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "SETTLE", "name": "结算", "status": "WAITING", "statusName": "待开始", "displayText": "结算·待开始"}
      ] }
    ]
  },
  "traceId": null,
  "success": true
}

空数据 / 降级响应

出行完毕之前（招募中 ~ 出行中）：reviewStatus / settlementStatus 恒为 NONE（不会是 null），核单、结算分支都是「待开始」。
已流团、batchStatus 为 null 或不在九态内：progressStepper 仍为空列表 []（与 #8478 相同，未改）；四个新字段照常输出（已流团团期为 NONE）。
库里是枚举外的脏值时：reviewStatus / settlementStatus 原样输出、中文名回原值；进度条分支按 NONE 处理（WAITING「待开始」），不报错。

T26-5936 招募中时（17:18 实测，只列相关字段）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2105223438312652802",
    "batchStatus": "RECRUITING",
    "batchStatusName": "招募中",
    "reviewStatus": "NONE",
    "reviewStatusName": "未核单",
    "settlementStatus": "NONE",
    "settlementStatusName": "未结算",
    "progressStepper": [
      {"step": 1, "code": "RECRUIT", "name": "招募", "status": "PROCESSING", "label": "招募中", "isCurrent": true, "subFlows": null },
      {"step": 2, "code": "CONFIGURE", "name": "配置", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "HOTEL", "name": "配房", "status": "WAITING", "statusName": "待开始", "displayText": "配房·待开始"},
        {"code": "VEHICLE", "name": "配车", "status": "WAITING", "statusName": "待开始", "displayText": "配车·待开始"},
        {"code": "GUIDE", "name": "配导游", "status": "WAITING", "statusName": "待开始", "displayText": "配导游·待开始"},
        {"code": "PHOTOGRAPHER", "name": "配摄影", "status": "WAITING", "statusName": "待开始", "displayText": "配摄影·待开始"},
        {"code": "MATERIAL", "name": "配物资", "status": "WAITING", "statusName": "待开始", "displayText": "配物资·待开始"}
      ] },
      {"step": 3, "code": "CONFIRM", "name": "确认", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 4, "code": "TRIP", "name": "出行", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": null },
      {"step": 5, "code": "REVIEW", "name": "核单", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "REVIEW", "name": "核单", "status": "WAITING", "statusName": "待开始", "displayText": "核单·待开始"}
      ] },
      {"step": 6, "code": "SETTLE", "name": "结算", "status": "WAITING", "label": null, "isCurrent": false, "subFlows": [
        {"code": "SETTLE", "name": "结算", "status": "WAITING", "statusName": "待开始", "displayText": "结算·待开始"}
      ] }
    ]
  },
  "traceId": null,
  "success": true
}

错误响应

{
  "code": 589500,
  "message": "团期不存在",
  "data": null,
  "traceId": null,
  "success": false
}

错误码	触发条件
589500	团期不存在（未变）
589507	缺 `group-batch:view` 权限码（未变）

业务边界

当前节点（isCurrent / 节点 status / label）仍按主状态分桶，不看这两个新字段；两个新字段只决定核单、结算分支的文案。
因此「核单已完成、结算未完成」时：核单节点 label 仍是「核单中」，分支是「核单·已核单」；结算节点仍是 WAITING，分支显示「结算·待结算 / 结算中」。前端要表达「核单已完成」，请展示分支 displayText，不要只看节点 label。
进度条只供展示；业务判断仍读 batchStatus。
TEST 实测到的分支组合：

团期所处	出行节点 label	核单节点 label	核单分支	结算分支
招募中 / 出行中	—（出行中时为「出行中」）	—	核单·待开始	结算·待开始
待核单	待核单	—	核单·待核单	结算·待开始
核单中	—	核单中	核单·核单中	结算·待开始
已核单 + 待结算	—	核单中	核单·已核单	结算·待结算
已核单 + 结算中	—	核单中	核单·已核单	结算·结算中
已结算	—	—（结算节点 DONE + 当前，label「已结算」）	核单·已核单	结算·已结算

2. A1 团期分页 `GET /v3/admin/order/group-batch`

VO: GroupBatchPageItemRespVO（入参 GroupBatchListReqVO）

使用场景

团期列表页。本次每行新增整团核单 / 结算状态四个字段；batchStatus 筛选传旧值 TRIP_FINISHED 时按 PENDING_REVIEW 查询（改前静默返回空）；看板桶筛选 opsStage=TRIP_FINISHED 照常可用。

入参

只列本次有变化的入参，其余（productId、keyword、deadlineFrom / To、departFrom / To、month、scope、sortBy、sortOrder 等）不变。

字段	位置	类型	必填	约束	说明
batchStatus	Query	String	否	九态之一	新值传 `PENDING_REVIEW`；旧值 `TRIP_FINISHED` 按 `PENDING_REVIEW` 处理（兼容用，新代码请传新值）。其他取值规则不变
opsStage	Query	String	否	七桶或旧八桶别名	`TRIP` 桶展开为待出发 + 出行中 + 待核单；旧桶名 `TRIP_FINISHED` 保留，展开为 `PENDING_REVIEW`（它是桶名，不是状态值）
pageNo	Query	Integer	否	默认 1	未变
pageSize	Query	Integer	否	默认 20	未变

出参 `Result<PageResult<GroupBatchPageItemRespVO>>`

字段	类型	说明
records[].reviewStatus	String	新增，同 A2：`NONE` / `PENDING` / `IN_PROGRESS` / `COMPLETED`
records[].reviewStatusName	String	新增，未核单 / 待核单 / 核单中 / 已核单
records[].settlementStatus	String	新增，同 A2：`NONE` / `PENDING` / `IN_PROGRESS` / `COMPLETED`
records[].settlementStatusName	String	新增，未结算 / 待结算 / 结算中 / 已结算
records[].batchStatus	String	取值 `TRIP_FINISHED` 改为 `PENDING_REVIEW`
records[].batchStatusName	String	「出行完毕」改为「待核单」
records[].tripSubStatus	String	`TRIP_FINISHED` 改为 `PENDING_REVIEW`
records[].tripSubStatusName	String	「已返团」改为「待核单」
total / page / pageSize	Long / Integer / Integer	未变

请求示例

GET /v3/admin/order/group-batch?batchStatus=TRIP_FINISHED&pageNo=1&pageSize=50 HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

无请求体。

响应示例

传旧值 TRIP_FINISHED，返回的是两个待核单团期，与传 PENDING_REVIEW 结果一致（TEST 实测，只列与本次相关的字段）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "groupBatchId": "2105223438312652802",
        "batchNo": "T26-5936",
        "batchName": "呼伦贝尔草原3日游·9月26日团",
        "batchStatus": "PENDING_REVIEW",
        "batchStatusName": "待核单",
        "reviewStatus": "PENDING",
        "reviewStatusName": "待核单",
        "settlementStatus": "NONE",
        "settlementStatusName": "未结算",
        "stage": "TRIP",
        "stageName": "出行",
        "tripSubStatus": "PENDING_REVIEW",
        "tripSubStatusName": "待核单",
        "opsStage": "TRIP",
        "opsStageName": "出行",
        "departDate": "2026-09-26",
        "endDate": "2026-09-28"
      },
      {
        "groupBatchId": "2105223439872933889",
        "batchNo": "T26-2325",
        "batchName": "呼伦贝尔草原3日游·9月25日团",
        "batchStatus": "PENDING_REVIEW",
        "batchStatusName": "待核单",
        "reviewStatus": "PENDING",
        "reviewStatusName": "待核单",
        "settlementStatus": "NONE",
        "settlementStatusName": "未结算",
        "stage": "TRIP",
        "stageName": "出行",
        "tripSubStatus": "PENDING_REVIEW",
        "tripSubStatusName": "待核单",
        "opsStage": "TRIP",
        "opsStageName": "出行",
        "departDate": "2026-09-25",
        "endDate": "2026-09-27"
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 50
  },
  "traceId": null,
  "success": true
}

空数据 / 降级响应

无匹配时 records=[]、total=0（未变，下例为结构示意）。已流团团期照常返回，四个新字段为 NONE / 未核单 / NONE / 未结算（TEST 上 T27-2584 实测）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}

错误响应

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "data": null,
  "traceId": null,
  "success": false
}

错误码	触发条件
589507	缺 `group-batch:list` 权限码（未变）

业务边界

入参只兼容旧值，返回值一律输出新值。
opsStage 旧八桶别名（FORMED / PENDING_TRIP / TRAVELLING / TRIP_FINISHED / AUDITING / CHECKED）照常接受；TRIP_FINISHED 桶现在就是「待核单」团期。
本次没有做按 reviewStatus / settlementStatus 筛选（jw 09-29 定不做），列表只输出这两个字段。
团期统计条 GET /v3/admin/order/group-batch/summary 的旧桶统计键 TRIP_FINISHED 同样保留，计数对象是待核单团期。

3. 房务配房列表（团期） `GET /v3/admin/order/house-allocation/group-batches`

VO: HouseAllocationGroupPageRespVO（入参 HouseAllocationGroupPageReqVO，列表项 HouseAllocationGroupRespVO）

使用场景

房务配房列表（一行一团），同时承接原房务「我的团」（scope=mine，原「我的团」接口已随 #8491 下线）。本次 batchStatus 筛选传旧值 TRIP_FINISHED 时按 PENDING_REVIEW 查询（改前直接返回 400）。

入参

只列本次有变化的入参，其余不变。

字段	位置	类型	必填	约束	说明
scope	Query	String	否	`all` / `mine`，默认 `all`	未变；两种范围都享受旧值兼容
batchStatus	Query	String	否	九态之一或空串	合法值中 `TRIP_FINISHED` 换成 `PENDING_REVIEW`；传旧值 `TRIP_FINISHED` 先按 `PENDING_REVIEW` 处理再校验，不再 400；其他非法值仍 400

出参 `Result<HouseAllocationGroupPageRespVO>`

字段	类型	说明
list[].batchStatus	String	取值 `TRIP_FINISHED` 改为 `PENDING_REVIEW`
list[].batchStatusLabel	String	「出行完毕」改为「待核单」
total / stats	Long / Object	未变

请求示例

GET /v3/admin/order/house-allocation/group-batches?scope=mine&batchStatus=TRIP_FINISHED HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

无请求体。

响应示例

传旧值返回房务-赵丽娟整团认领的待核单团期（TEST 实测，只列与本次相关的字段）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "groupBatchId": "2105223439872933889",
        "batchNo": "T26-2325",
        "batchName": "呼伦贝尔草原3日游·9月25日团",
        "batchStatus": "PENDING_REVIEW",
        "batchStatusLabel": "待核单",
        "departDate": "2026-09-25",
        "endDate": "2026-09-27",
        "houseClaimerName": "房务-赵丽娟",
        "isMine": true
      }
    ],
    "total": 1,
    "stats": { "pendingClaim": 0, "claimed": 1, "all": 1 }
  },
  "traceId": null,
  "success": true
}

空数据 / 降级响应

无匹配时 list=[]、total=0；stats 按同一筛选条件计数（未变，下例为结构示意）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [],
    "total": 0,
    "stats": { "pendingClaim": 0, "claimed": 0, "all": 0 }
  },
  "traceId": null,
  "success": true
}

错误响应

非法状态值仍被拒（TEST 实测）：

{
  "code": 400,
  "message": "batchStatus 不是合法的团期阶段",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

只兼容 TRIP_FINISHED 这一个旧值；返回值一律输出新值。
scope=mine 与 scope=all 的兼容行为一致（均已实测）。

4. 房务团期看板列表 `GET /v3/admin/house/group-batches`

VO: HouseGroupBatchBoardSimpleRespVO（入参 HouseGroupBatchBoardPageReqVO）

使用场景

房务团期看板（只显示已认领的团）。本次 batchStatus 多选筛选里的旧值 TRIP_FINISHED 按 PENDING_REVIEW 处理（改前被当成非法值丢弃，整页退回默认筛选）。

入参

只列本次有变化的入参，其余不变。

字段	位置	类型	必填	约束	说明
scope	Query	String	否	`MINE` / `ALL`，默认 `MINE`	未变
batchStatus	Query	String	否	逗号分隔多选，最长 200	旧值 `TRIP_FINISHED` 按 `PENDING_REVIEW` 处理；`CANCELLED` 与非法值仍忽略；不传时默认四态（资源准备中 / 物料准备中 / 待出发 / 出行中，不含待核单，未变）
pageSize	Query	Long	否	1~50，默认 20	未变

出参 `Result<PageResult<HouseGroupBatchBoardSimpleRespVO>>`

字段	类型	说明
records[].batchStatus	String	取值 `TRIP_FINISHED` 改为 `PENDING_REVIEW`
records[].batchStatusText	String	「出行完毕」改为「待核单」
total / page / pageSize	Long	未变

请求示例

GET /v3/admin/house/group-batches?batchStatus=TRIP_FINISHED HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

无请求体。

响应示例

传旧值返回待核单团期，没有退回默认筛选（TEST 实测，只列与本次相关的字段）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "groupBatchId": "2105223439872933889",
        "batchNo": "T26-2325",
        "batchName": "呼伦贝尔草原3日游·9月25日团",
        "batchStatus": "PENDING_REVIEW",
        "batchStatusText": "待核单",
        "departDate": "2026-09-25",
        "endDate": "2026-09-27",
        "claimerName": "房务-赵丽娟",
        "boardStatus": "NOT_STARTED"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}

空数据 / 降级响应

不传 batchStatus 走默认四态，待核单团期不在其中；同一账号此时为空（TEST 实测）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}

错误响应

{
  "code": 400,
  "message": "pageSize 最大 50",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

只兼容 TRIP_FINISHED 这一个旧值；返回值一律输出新值。
scope=ALL 同样兼容（已实测）。

5. 团期状态流水（时间线） `GET /v3/admin/order/group-batch/:groupBatchId/status-logs`

VO: GroupBatchStatusLogItemVO

使用场景

团期详情页时间线。本次新增两类事件：财务或管理后台入口改动整团核单 / 结算状态时各记一条；主状态值 TRIP_FINISHED 改名后，历史行的 fromStatus / toStatus 也已统一改写。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	团期 ID	未变；按时间升序返回全部流水，不分页

出参 `Result<List<GroupBatchStatusLogItemVO>>`

字段	类型	说明
eventType	String	新增两个取值：`BATCH_REVIEW_STATUS_CHANGE`「核单状态变更」、`BATCH_SETTLE_STATUS_CHANGE`「结算状态变更」。事件 `BATCH_TRIP_FINISH`「出行完毕」不改名
eventTypeName	String	核单状态变更 / 结算状态变更
changeType	String	新事件一般为 `DATA`；核单从核单中退回待核单（主状态核单中 → 待核单）那一条为 `STATUS`
fromStatus / toStatus	String	取值 `TRIP_FINISHED` 改为 `PENDING_REVIEW`（含历史行）
fromStatusName / toStatusName	String	「出行完毕」改为「待核单」
content	String	如「核单状态：核单中 → 已核单」「结算状态：已结算 → 结算中」；核单从已核单退回时追加「；结算状态随之置回：结算中 → 未结算」
reason	String	调用方传入的原因；管理后台入口为验团意见或 null
operatorType / operatorId / operatorName	String / Long / String	财务内部接口写入的行：`SYSTEM`、`null`、财务传入的姓名（如「财务-王丽华」）；管理后台入口写入的行为登录管理员
extra	Object	新事件带 `field` / `from` / `to` / `fromName` / `toName` / `source`，有操作人时带 `operatorName`；核单退回时带 `settlementFrom` / `settlementTo`；有子订单同步时带 `subOrderSyncedCount` / `subOrderSkippedOrderIds`；结算离开已结算、核团被退回时带 `auditReverted: true`

请求示例

GET /v3/admin/order/group-batch/2105223438312652802/status-logs HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

无请求体。

响应示例

T26-5936 时间线中的四条（TEST 实测，节选）：

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "logId": "2105228170246713346",
      "groupBatchId": "2105223438312652802",
      "changeType": "STATUS",
      "eventType": "BATCH_TRIP_FINISH",
      "eventTypeName": "出行完毕",
      "fromStatus": "TRAVELLING",
      "fromStatusName": "出行中",
      "toStatus": "PENDING_REVIEW",
      "toStatusName": "待核单",
      "content": "系统自动出行完毕",
      "reason": null,
      "operatorType": "SYSTEM",
      "operatorId": null,
      "operatorName": "系统",
      "extra": null,
      "changedAt": "2026-09-30 17:28:04"
    },
    {
      "logId": "2105231057186156546",
      "groupBatchId": "2105223438312652802",
      "changeType": "STATUS",
      "eventType": "BATCH_REVIEW_STATUS_CHANGE",
      "eventTypeName": "核单状态变更",
      "fromStatus": "REVIEWING",
      "fromStatusName": "核单中",
      "toStatus": "PENDING_REVIEW",
      "toStatusName": "待核单",
      "content": "核单状态：核单中 → 待核单",
      "reason": "大巴费用票据未到，退回待核单",
      "operatorType": "SYSTEM",
      "operatorId": null,
      "operatorName": "财务-王丽华",
      "extra": {
        "field": "reviewStatus",
        "from": "IN_PROGRESS",
        "to": "PENDING",
        "fromName": "核单中",
        "toName": "待核单",
        "operatorName": "财务-王丽华",
        "source": "GroupBatchReviewSettleService",
        "subOrderSyncedCount": 2,
        "subOrderSkippedOrderIds": []
      },
      "changedAt": "2026-09-30 17:39:32"
    },
    {
      "logId": "2105239217246531585",
      "groupBatchId": "2105223438312652802",
      "changeType": "DATA",
      "eventType": "BATCH_SETTLE_STATUS_CHANGE",
      "eventTypeName": "结算状态变更",
      "fromStatus": "SETTLED",
      "fromStatusName": "已结算",
      "toStatus": "SETTLED",
      "toStatusName": "已结算",
      "content": "结算状态：未结算 → 已结算",
      "reason": "报账款已付清，整团结算完成",
      "operatorType": "SYSTEM",
      "operatorId": null,
      "operatorName": "财务-王丽华",
      "extra": {
        "field": "settlementStatus",
        "from": "NONE",
        "to": "COMPLETED",
        "fromName": "未结算",
        "toName": "已结算",
        "operatorName": "财务-王丽华",
        "source": "GroupBatchReviewSettleService",
        "subOrderSyncedCount": 1,
        "subOrderSkippedOrderIds": ["2105223438178435074"]
      },
      "changedAt": "2026-09-30 18:11:58"
    },
    {
      "logId": "2105241608285024259",
      "groupBatchId": "2105223438312652802",
      "changeType": "DATA",
      "eventType": "BATCH_SETTLE_STATUS_CHANGE",
      "eventTypeName": "结算状态变更",
      "fromStatus": "REVIEWING",
      "fromStatusName": "核单中",
      "toStatus": "REVIEWING",
      "toStatusName": "核单中",
      "content": "结算状态：已结算 → 结算中",
      "reason": "出纳付款失败需重付，结算改回结算中",
      "operatorType": "SYSTEM",
      "operatorId": null,
      "operatorName": "财务-王丽华",
      "extra": {
        "field": "settlementStatus",
        "from": "COMPLETED",
        "to": "IN_PROGRESS",
        "fromName": "已结算",
        "toName": "结算中",
        "operatorName": "财务-王丽华",
        "source": "GroupBatchReviewSettleService",
        "auditReverted": true,
        "subOrderSyncedCount": 2,
        "subOrderSkippedOrderIds": []
      },
      "changedAt": "2026-09-30 18:21:28"
    }
  ],
  "traceId": null,
  "success": true
}

空数据 / 降级响应

团期没有流水时返回空数组（未变）：

{
  "code": 200,
  "message": "成功",
  "data": [],
  "traceId": null,
  "success": true
}

错误响应

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "data": null,
  "traceId": null,
  "success": false
}

错误码	触发条件
589507	缺 `group-batch:view` 权限码（未变）

业务边界

主状态随核单 / 结算变化时，除新事件这一行外，另有一条既有事件的主状态流转行：进入核单中记 BATCH_TRIP_END「发起核单」，进出已结算记 BATCH_SETTLE「结算」；只有「核单中 → 待核单」没有既有事件可用，由新事件那一行直接以 STATUS 记录。
因此进入核单中时，新事件那一行是 DATA 行，fromStatus / toStatus 都是变化后的主状态（如 REVIEWING → REVIEWING），前端不要据此判断主状态有没有变。
同值重复回写不记流水。

四、契约约束与正确调用方式

本节只写后端接受 / 拒绝的规则，以及字段该怎么读。

✅ 正确 / ❌ 错误用法对照

场景	用法
✅ 判断团期是否待核单（如「发起核单」按钮）	`batchStatus === 'PENDING_REVIEW'`（与 `reviewStatus === 'PENDING'` 等价）
❌ 仍按旧值判断	`batchStatus === 'TRIP_FINISHED'` → 永远为 false，按钮消失
✅ 按待核单筛选列表	`?batchStatus=PENDING_REVIEW`
⚠️ 旧书签 / 旧代码传 `?batchStatus=TRIP_FINISHED`	三处入参按 `PENDING_REVIEW` 处理，能查出数据；新代码请改传新值
✅ 看板页签按旧桶筛选	`?opsStage=TRIP_FINISHED`（桶名保留）或七桶 `?opsStage=TRIP`
✅ 展示「核单已完成」	读 `reviewStatus === 'COMPLETED'` 或进度条核单分支 `displayText`
❌ 用核单节点 label 判断核单是否完成	核单已完成、结算未完成时 label 仍是「核单中」
❌ 用 `settlementStatus` 当逐户付款结清	那是财务 tab `items[].settleStatus`，与整团结算状态无关

切换状态时的必要动作

管理后台没有直接改 reviewStatus / settlementStatus 的入口。整团核单 / 结算状态由财务通过内部接口回写；管理后台既有的「发起核单」「首笔共享成本」「整团结算 /settle」「反结算 /settle/reopen」会按固定规则改这两个状态（见六）。
前端操作后如需刷新状态，重新拉 A2 详情即可，不要在前端自行推导主状态。

五、数据库行为

本文五个接口都是只读接口，不写数据。
存量数据已由迁移一次性改写（TEST 迁移 20260929.8516 已执行）：
- 主状态「出行完毕」统一改为「待核单」，团期时间线历史行、团级核单快照里的流程状态一并改名；
- 两个新状态按主状态回填：待核单 → 核单=待核单；核单中 → 核单=核单中；已结算 → 核单=已核单、结算=已结算；其余团期两者都是 NONE。回填可重跑，重跑不产生变化。
管理后台写入口的数据变化见六「既有写入口」。

六、边界行为

未登录 → 401（网关拦截，未变）；缺权限码 → 589507（未变）。
团期不存在 → 589500（未变）。
入参传旧值 TRIP_FINISHED：A1 分页、房务配房列表、房务团期看板按 PENDING_REVIEW 处理；其他任何接口的返回值都不会再出现 TRIP_FINISHED。
新字段 reviewStatus / settlementStatus 恒非 null；出行完毕前为 NONE。

既有写入口：请求 / 响应契约不变，行为变化

以下四个管理后台入口的路径、入参、出参结构、成功返回值都没有变，变的是它们对团期核单 / 结算状态与子订单的写入。子订单同步与团期改动同一事务，任何一步都不推报账单。

入口	请求 / 响应	行为变化	TEST 实测
发起核单 `POST /v3/admin/order/group-batch/:groupBatchId/review/start`	不变：无请求体，返回 `groupBatchId` / `batchStatus` / `batchStatusDesc` / `alreadyStarted`	核单改为核单中，团期推导为核单中，核单为待核单的在团户同事务进核单中（替代 #8341 的「整团带入核单中」）；核单已是核单中或已核单时返回 `alreadyStarted=true`、零写入，不会把已核单退回；错误码 589564 文案由「须为「出行完毕」」改为「须为「待核单」」，589565 / 589566 不变	首次 `alreadyStarted=false`；重复调用、已核单时调用均 `alreadyStarted=true`
首笔共享成本 `POST /v3/admin/order/group-batch/:groupBatchId/settlement/cost`	不变：返回成本明细 ID	核单为待核单时改为核单中并同步子订单；第二笔起不再改状态；状态不符仍 589501	待核单 → 核单中，两户同步进核单中
整团结算 `POST /v3/admin/order/group-batch/:groupBatchId/settle`	不变：请求体 `checkNote` 可空，`data=null`	核单置已核单（已是则跳过）、结算置已结算 → 团期已结算；待结算的在团户只改状态为已结算，不再逐户推 ORDER 报账单（停掉 #8341 的逐户财务复核推单）；有在团户逐户核单未提交时仍整团 589568 并列出订单号、零写入；589555 / 589567 / 589573 不变	从已核单、从核单中两种起点都成功，核团 → 已结算（CHECKED），报账单行数不变；未提交户 589568
反结算 `POST /v3/admin/order/group-batch/:groupBatchId/settle/reopen`	不变：无请求体，`data=null`	结算改为待结算 → 团期核单中；核团从已结算退回已核算；已结算的在团户退回待结算，已推的报账单不撤；非已结算仍 589501	结算 → 待结算，两户退回待结算，之后重新核算、再结算均可用

四个入口在极端并发下可能多出一个兜底码 589703「团期核单或结算状态已被他人修改，请刷新后重试」（内部已先加团期行锁，正常操作不会出现），前端透传 message 即可。
团级核单定稿 POST /v3/admin/order/group-batch/:groupBatchId/settlement/finalize 的 584138 文案「需出行完毕或核单中」改为「需待核单或核单中」，码与触发条件不变。

六.5、枚举 / 数据字典

batchStatus（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）

所属字段: GroupBatchDetailRespVO.batchStatus、GroupBatchPageItemRespVO.batchStatus 等所有团期主状态字段 | 类型: String

值	中文	说明
`RECRUITING`	招募中	未变
`RESOURCE_PREPARING`	资源准备中	未变
`MATERIAL_PREPARING`	物料准备中	未变
`PENDING_DEPARTURE`	待出发	未变
`TRAVELLING`	出行中	未变
`PENDING_REVIEW`	待核单	原 `TRIP_FINISHED`「出行完毕」。返团日已过、尚未开始核单；等价于 `reviewStatus=PENDING`
`REVIEWING`	核单中	未变；`reviewStatus` 为核单中，或已核单但结算未到已结算
`SETTLED`	已结算	未变；`reviewStatus` 与 `settlementStatus` 都已完成
`CANCELLED`	已取消	未变（已流团）

tripSubStatus（`GroupBatchStageBuckets.TripSubStatus`）

所属字段: GroupBatchDetailRespVO.tripSubStatus、GroupBatchPageItemRespVO.tripSubStatus | 类型: String

值	中文	说明
`PENDING_DEPARTURE`	待出发	未变
`TRAVELLING`	出行中	未变
`PENDING_REVIEW`	待核单	原 `TRIP_FINISHED`「已返团」

reviewStatus（`com.hulalv.order.settlement.enums.ReviewStatus`，与子订单核单状态同一枚举）

所属字段: GroupBatchDetailRespVO.reviewStatus、GroupBatchPageItemRespVO.reviewStatus | 类型: String

值	中文	说明
`NONE`	未核单	还没出行完毕
`PENDING`	待核单	出行完毕后自动进入
`IN_PROGRESS`	核单中	财务开始核单，或管理后台发起核单 / 首笔共享成本
`COMPLETED`	已核单	财务完成核单，或管理后台整团结算

settlementStatus（`com.hulalv.order.groupbatch.enums.GroupBatchSettlementStatus`）

所属字段: GroupBatchDetailRespVO.settlementStatus、GroupBatchPageItemRespVO.settlementStatus | 类型: String

值	中文	说明
`NONE`	未结算	核单完成之前恒为此值
`PENDING`	待结算	核单已完成、尚未开始结算。同一个值在子订单上叫「待财务复核」
`IN_PROGRESS`	结算中	团期独有，子订单没有这一态；含义由财务定义
`COMPLETED`	已结算	团期主状态随之为已结算

进度条核单 / 结算分支 status（`GroupBatchProgressSubFlowVO.status`）

所属字段: progressStepper[].subFlows[].status（仅 code 为 REVIEW / SETTLE 的分支） | 类型: String

值	中文（statusName）	说明
`WAITING`	待开始	对应字段为 `NONE`（或脏值）
`PENDING`	待核单 / 待结算	对应字段为 `PENDING`
`IN_PROGRESS`	核单中 / 结算中	对应字段为 `IN_PROGRESS`
`COMPLETED`	已核单 / 已结算	对应字段为 `COMPLETED`

时间线新增 eventType（`com.hulalv.order.groupbatch.enums.GroupBatchLogEventType`）

所属字段: GroupBatchStatusLogItemVO.eventType | 类型: String

值	中文	说明
`BATCH_REVIEW_STATUS_CHANGE`	核单状态变更	整团核单状态每次真的变化记一条
`BATCH_SETTLE_STATUS_CHANGE`	结算状态变更	整团结算状态每次真的变化记一条

六.6、修改前后对比

字段级对比

字段	改前	改后
`batchStatus`（所有返回团期主状态的接口）	可能为 `TRIP_FINISHED`「出行完毕」	该值改为 `PENDING_REVIEW`「待核单」，`TRIP_FINISHED` 不再出现
`tripSubStatus` / `tripSubStatusName`	`TRIP_FINISHED` / 已返团	`PENDING_REVIEW` / 待核单
`progressStepper` 出行节点 label（待核单团期）	已返团	待核单
A2 / A1 `reviewStatus` / `reviewStatusName`	无	新增
A2 / A1 `settlementStatus` / `settlementStatusName`	无	新增
A2 `progressStepper` REVIEW / SETTLE 节点 `subFlows`	`null`	各 1 条分支
时间线 `eventType`	无核单 / 结算状态事件	新增 `BATCH_REVIEW_STATUS_CHANGE` / `BATCH_SETTLE_STATUS_CHANGE`
时间线历史行 `fromStatus` / `toStatus`	可能为 `TRIP_FINISHED`	已改写为 `PENDING_REVIEW`

行为级对比

行为	改前	改后
A1 分页 `?batchStatus=TRIP_FINISHED`	静默返回空	返回待核单团期
房务配房列表 `?batchStatus=TRIP_FINISHED`（含 `scope=mine`）	400「batchStatus 不是合法的团期阶段」	返回待核单团期
房务团期看板 `?batchStatus=TRIP_FINISHED`	当非法值丢弃，退回默认四态	返回待核单团期
`?opsStage=TRIP_FINISHED`	出行完毕团期	待核单团期（桶名保留）
团期主状态「待核单 / 核单中 / 已结算」	各入口直接推进主状态	由整团核单、结算两个状态推导
`/settle`	逐户财务复核并推 ORDER 报账单	子订单只改状态为已结算，不推报账单
`/settle/reopen`	本入口自己退核团	核团退回收进统一写口，本入口与财务内部接口行为一致
发起核单 589564 文案	须为「出行完毕」	须为「待核单」

六.7、影响评估

是否破坏向后兼容: 是。batchStatus / tripSubStatus 的 TRIP_FINISHED 取值改名，按旧值判断的前端代码会静默失效。
前端是否必须同步发布: 是。jw 09-30 定：TEST 先行（后端 09-30 16:31 已部署到 TEST，hl-ui 本次未改），正式环境前后端同批发布。
前端必须改：按状态值做判断的代码（hl-ui origin/v2.1 只读核对，行号以核对时为准）：
- order-v2/batch/detail/index.vue:832 canStartReview：改为判 'PENDING_REVIEW'，不改「发起核单」按钮会消失；
- finance/settlement/components/GroupSettlementPanel.vue:281：「完成核单」可点条件；
- order-v2/batch/detail/components/FinanceTab.vue:309：预支可发起的阶段；
- order-v2/batch/detail/components/GroupVehicleRequirementSection.vue:399：免车声明可用的阶段；
- order-v2/detail/_shared/orderDetailActions.js:24、requirementFreeze.js:16：状态集合；
- order-v2/batch/_shared/batchLifecycle.js:53：状态到节点的映射。
前端必须改：显示用的映射表：GroupSettlementPanel.vue:260、housekeeper/orders/GroupBatchTable.vue:49、housekeeper/room-board/components/boardLabels.js:50（PENDING_REVIEW → 待核单）。
前端建议改：团期详情 / 列表展示 reviewStatusName / settlementStatusName；进度条核单、结算节点渲染新分支（写法与配置节点五条分支相同）。
前端不用改：opsStage=TRIP_FINISHED（旧桶名，后端保留）；NO_VEHICLE_TRIP_FINISHED_CODE（车队错误码常量，与团期状态无关）。
其他返回团期主状态的接口（团期看板 /board、团期统计 /summary、房务看板详情、车务派单相关读口、核团详情 return-detail 的 flowStatus 等）：字段名与结构不变，取值同样由 TRIP_FINISHED 变为 PENDING_REVIEW、中文名变为「待核单」；统计键 TRIP_FINISHED 保留。
BI / 报表 / 外部取数：如按 'TRIP_FINISHED' 取数会取不到，需要改为 PENDING_REVIEW（代码仓 grep 不到这类依赖，无法替使用方确认）。
前端 workaround 清理点: 无。
回滚：先执行后端回滚 SQL 把存量值改回，再回退代码；前端须一起回退。

七、不影响范围

仅影响：团期主状态「出行完毕」这一个取值的名称与中文名；团期详情 / 分页的四个新字段；详情进度条核单、结算分支；时间线两类新事件；三处入参旧值兼容；四个既有写入口对状态与子订单的写入方式。
零影响：
- 其余八个团期主状态取值、六节点 stage 取值、opsStage 七桶与旧桶名；
- 进度条配置节点五条分支、六个主节点的当前节点判定规则；
- 团期状态筛选以外的所有入参；
- 团级核单定稿 / 确认、逐户核单提交、逐户财务复核确认、逐户反确认的接口与行为（对团期子订单不加限制）；
- 时间线事件「出行完毕」BATCH_TRIP_FINISH 的名称；
- 网关：路径未变，无新增路由与权限码。

八、测试环境已验证

2026-09-30 TEST（api.test.1814.love）：合并提交 54e64c50f，部署构建 dev-v3 dd0452916（order-v3 双实例 8086 / 8186），迁移 20260929.8516 于 16:32:13 执行成功。验收团期为本次新建：T26-5936 呼伦贝尔草原3日游·9月26日团、T26-2325 呼伦贝尔草原3日游·9月25日团。证据目录 HL/.evidence/8516/。

AC-03 迁移：两列存在；三处存量 TRIP_FINISHED 均为 0 行，时间线 38 行改名为 PENDING_REVIEW；回填重跑零变化 ✓
AC-09 发起核单首次 alreadyStarted=false、重复与已核单时 true；首笔成本 待核单→核单中并同步；/settle 两种起点均 SETTLED、报账单行数不变；未提交户 589568；/settle/reopen 结算→待结算、户退回 ✓
AC-10 GET /v3/admin/order/group-batch/:groupBatchId 与分页返回四个新字段；核单分支实测 待开始/待核单/核单中/已核单，结算分支实测 待开始/待结算/结算中/已结算；出行节点 label 与 tripSubStatusName 为「待核单」 ✓
AC-11 分页 batchStatus=TRIP_FINISHED 与 PENDING_REVIEW 结果一致（2 条，不筛选 27 条）；房务配房列表 scope=mine/all 只返回待核单团、非法值仍 400；房务看板传旧值返回待核单团、未退回默认筛选；opsStage=TRIP_FINISHED 返回 2 条 ✓
AC-12 GET /v3/admin/order/group-batch/:groupBatchId/status-logs 可见「核单状态变更」「结算状态变更」，操作人与原因正确 ✓

AC	证据
AC-09	`HL/.evidence/8516/AC-09/`
AC-10	`HL/.evidence/8516/AC-10/`
AC-11	`HL/.evidence/8516/AC-11/01-legacy-TRIP_FINISHED.json`、`02-discriminators.json`
AC-12	`HL/.evidence/8516/AC-12/01-status-logs.json`

单元测试：进度条 GroupBatchProgressStepperTest、分桶 GroupBatchStageBucketsTest、转换 GroupBatchConverterTest、看板入参 HouseGroupBatchBoardManagerTest、迁移 GroupBatchReviewSettlementStatusMysqlMigrationTest 等；order-v3 全量两半对照干净 dev-v3 基线，本单新增失败 0。

九、相关历史 PR

PR	Issue	说明	是否仍有效
—	#7190	团期状态新增出行完毕 `TRIP_FINISHED`、看板八桶	⚠️ 状态值已改名 `PENDING_REVIEW`，旧桶名保留
—	#7527	团期发起核单端点	✅ 有效，改为写整团核单状态
—	#8341	团期核单 / 结算 / 反结算同步子订单，结算即整团财务复核并推报账单	⚠️ 部分被本单取代：同步规则按本单，`/settle` 不再推报账单；589568 门禁保留
—	#8478	团期详情分叉进度条	✅ 有效，本单为核单、结算节点加分支
#8650	#8516	整团核单 / 结算独立状态，「出行完毕」改名「待核单」	✅ 最新

十、相关文档

关联 Issue: wx/HL#8516
关联 PR: wx/HL#8650（正文含前端影响说明）
状态机文档：docs/group/实施单/16-团期生命周期与状态机.html（随 PR #8650 同步，提交 30ed15777）；接口文档 docs/group/团期模块接口文档-v2.0.html
财务内部回写接口：changelogs-v2/2026-09/30_8516_团期核单与结算状态财务内部回写接口-新增接口-管理后台.md

53 KiB 原始文件 Blame 文件历史 Unescape Escape

团期：「出行完毕」改名「待核单」，新增整团核单 / 结算状态字段（管理后台）

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. A2 团期详情 GET /v3/admin/order/group-batch/:groupBatchId

使用场景

入参

出参 Result<GroupBatchDetailRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. A1 团期分页 GET /v3/admin/order/group-batch

使用场景

入参

出参 Result<PageResult<GroupBatchPageItemRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 房务配房列表（团期） GET /v3/admin/order/house-allocation/group-batches

使用场景

入参

出参 Result<HouseAllocationGroupPageRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. 房务团期看板列表 GET /v3/admin/house/group-batches

使用场景

入参

出参 Result<PageResult<HouseGroupBatchBoardSimpleRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

5. 团期状态流水（时间线） GET /v3/admin/order/group-batch/:groupBatchId/status-logs

使用场景

入参

出参 Result<List<GroupBatchStatusLogItemVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式

✅ 正确 / ❌ 错误用法对照

切换状态时的必要动作

五、数据库行为

六、边界行为

既有写入口：请求 / 响应契约不变，行为变化

六.5、枚举 / 数据字典

batchStatus（com.hulalv.order.groupbatch.enums.GroupBatchStatus）

tripSubStatus（GroupBatchStageBuckets.TripSubStatus）

reviewStatus（com.hulalv.order.settlement.enums.ReviewStatus，与子订单核单状态同一枚举）

settlementStatus（com.hulalv.order.groupbatch.enums.GroupBatchSettlementStatus）

进度条核单 / 结算分支 status（GroupBatchProgressSubFlowVO.status）

时间线新增 eventType（com.hulalv.order.groupbatch.enums.GroupBatchLogEventType）

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

九、相关历史 PR

十、相关文档

关联 / 联系人

链接

联系人

53 KiB

原始文件 Blame 文件历史

1. A2 团期详情 `GET /v3/admin/order/group-batch/:groupBatchId`

出参 `Result<GroupBatchDetailRespVO>`

2. A1 团期分页 `GET /v3/admin/order/group-batch`

出参 `Result<PageResult<GroupBatchPageItemRespVO>>`

3. 房务配房列表（团期） `GET /v3/admin/order/house-allocation/group-batches`

出参 `Result<HouseAllocationGroupPageRespVO>`

4. 房务团期看板列表 `GET /v3/admin/house/group-batches`

出参 `Result<PageResult<HouseGroupBatchBoardSimpleRespVO>>`

5. 团期状态流水（时间线） `GET /v3/admin/order/group-batch/:groupBatchId/status-logs`

出参 `Result<List<GroupBatchStatusLogItemVO>>`

batchStatus（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）

tripSubStatus（`GroupBatchStageBuckets.TripSubStatus`）

reviewStatus（`com.hulalv.order.settlement.enums.ReviewStatus`，与子订单核单状态同一枚举）

settlementStatus（`com.hulalv.order.groupbatch.enums.GroupBatchSettlementStatus`）

进度条核单 / 结算分支 status（`GroupBatchProgressSubFlowVO.status`）

时间线新增 eventType（`com.hulalv.order.groupbatch.enums.GroupBatchLogEventType`）