hl-api-changelog/changelogs-v2/2026-09/24_8341_团期核单结算反结算同步子订单与结算589568列未提交户-修改接口-管理后台.md

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	8341	团期核单 / 结算 / 反结算同步子订单：进入核单时待核单户进核单中；团期结算即整团财务复核（逐户结算 + 报账单），有逐户核单未提交的户返 589568 并列出订单 ID；反结算时已结算户退回待结算	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	d2585f3c766c9ad7e102f7409f1a7419792636dd	v2.1	2026-09-24	六节点定案（SRS §0.27.7）：团期单子订单的核单结算状态由团期驱动，与团期状态变更同一事务、全有全无。① 团期进入核单（POST .../review/start 或首次 POST .../settlement/cost 把团期从 TRIP_FINISHED 推到 REVIEWING）：在团户中 flow=PENDING_REVIEW 的户同步为 review IN_PROGRESS / flow REVIEWING，已在核单中或已提交的户不动，幂等命中（alreadyStarted=true / 第二笔成本）不同步。② 团期结算 POST .../settle = 整团财务复核：待结算户逐户做与「财务复核确认结算」相同的写入（settlement COMPLETED / flow SETTLED / settled_at、SETTLEMENT_CONFIRM 日志、推送 BZ 报账单），已结算户跳过；有逐户核单未提交（或定稿后被逐户反确认）的户，整团拒绝 589568「整团核单当前状态不允许该操作：结算需要所有在团订单逐户核单已提交，未提交订单：{订单 ID，「、」分隔}」，零写入。③ 团期反结算 POST .../settle/reopen：已结算户退回 flow PENDING_SETTLE / settlement PENDING、清 settled_at，review 与逐户核单快照不动，已生成的报账单不撤（重新结算按 settlementId 幂等命中）。路径、入参、成功出参均不变；已取消户不受影响。前端需：处理团期结算的 589568 新原因（提示先去对应订单提交逐户核单）；团期结算后不必再引导运营逐户点「结算确认」。 前端已交付并验证：实证对 589568 零按码分支（核团域同码不同场景均透 message），验团成功文案无「引导逐户结算确认」残留，透 message 即达标；settle/reopen/review-start JSDoc 补同步语义与 589568 新原因（禁解析订单 ID 自建链接），AuditTab 注释订正。纯文档零行为改动，hl-admin@d2585f3c。	2026-09-24	dev-v3

团期结算: 核单 / 结算 / 反结算同步子订单（管理后台）

服务: hl-order-service-v3（端口 8086/8186） PR: #8345 Issue: #8341 日期: 2026-09-24 影响范围: 管理后台团期详情「核单 / 结算」节点的发起核单、录共享成本、结算、反结算按钮；子订单列表与订单详情里的核单 / 结算状态展示

---

⚠️ 关键变化

1. 团期结算 = 整团财务复核。点团期「结算」后，在团待结算的户一并变为「已结算」并各生成一张报账单，运营不再逐户点结算确认。
2. 团期结算新增一种 589568 拒绝原因：有户的逐户核单还没提交时，整团拒绝，message 列出这些户的订单 ID。
3. 团期反结算会把子订单一并退回待结算；已生成的报账单保留。
4. 团期进入核单时，待核单的户自动进入核单中，不必等逐户第一次录核单明细。

以上四个接口的路径、入参、成功出参都不变。

---

一、背景

改前团期的核单、结算、反结算只改团期自身，子订单仍要逐户推进：团期「已结算」而子订单还「待结算」、财务侧没有报账单的情况会出现。SRS §0.27.7 定案子订单跟随团期：

团期动作	子订单同步（同一事务）
进入核单（TRIP_FINISHED → REVIEWING）	flow PENDING_REVIEW 的户 → review IN_PROGRESS / flow REVIEWING
逐户核单明细录入与提交	照旧（提交后 flow PENDING_SETTLE、review COMPLETED、settlement PENDING）
结算（REVIEWING → SETTLED）	待结算户逐户财务复核 → settlement COMPLETED / flow SETTLED / settled_at + 报账单
反结算（SETTLED → REVIEWING）	已结算户 → flow PENDING_SETTLE / settlement PENDING，清 settled_at

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	结算归档	POST	/v3/admin/order/group-batch/{groupBatchId}/settle	修改（新增拒绝原因 + 副作用）	逐户结算 + 报账单；有逐户核单未提交的户 589568
2	结算反确认	POST	/v3/admin/order/group-batch/{groupBatchId}/settle/reopen	修改（副作用）	已结算户退回待结算
3	发起核单	POST	/v3/admin/order/group-batch/{groupBatchId}/review/start	修改（副作用）	首次推进时待核单户进核单中
4	录入团期共享成本	POST	/v3/admin/order/group-batch/{groupBatchId}/settlement/cost	修改（副作用 + 事务）	首笔成本推进团期时同上同步；整方法改为单事务

网关无改动；无新增权限码；无新增错误码；无 DB schema 变更。

---

三、接口详情

1. 结算归档 POST /v3/admin/order/group-batch/{groupBatchId}/settle

VO: GroupBatchSettleReqVO → Result<Void>

使用场景

团期详情「核单」节点的「结算」按钮（REVIEWING → SETTLED）。本次起同时完成全团子订单的财务复核，逐户生成报账单。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
checkNote	Body	String	否	-	结算意见（请求体整体可省略，不变）；本次起也写进逐户财务复核日志的备注

出参

字段	类型	说明
data	Void	成功返回 null（不变）

请求示例

{
  "checkNote": "成本已逐项核对"
}

响应示例

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

空数据 / 降级响应

无列表出参。团期没有在团子订单时跳过子订单同步，团期照常结算：

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

错误响应

有在团户逐户核单未提交（本次新增的原因，码值与前缀不变）：

{
  "code": 589568,
  "message": "整团核单当前状态不允许该操作：结算需要所有在团订单逐户核单已提交，未提交订单：2103023889187799042",
  "success": false,
  "data": null
}

已结算归档（不变）：

{
  "code": 589555,
  "message": "该团期已结算归档，不可重复结算",
  "success": false,
  "data": null
}

业务边界

• 判定顺序：判权（589507）→ 团期状态（589555 / 589501）→ 整团核单前置（589567 / 589568，不变）→ 团期 CAS → 子订单同步 → 时间线。
• 在团户分三类：待结算（flow PENDING_SETTLE + settlement PENDING + review COMPLETED）逐户复核；已结算（flow SETTLED + settlement COMPLETED）跳过、不重复推报账单；其余一律视为「逐户核单未提交」→ 589568。
• 589568 在任何逐户写入之前判，拒绝时零写入；列出的是订单 ID（不是订单号），以「、」分隔。
• 逐户复核的写入与副作用与 POST /v3/admin/order/{orderId}/settlement/confirm（财务复核）同源；任一户复核失败，其业务码原样返回，整团回滚（含已推的报账单）。
• 团期结算不对每户再做订单数据范围判定：财务角色结算整团不会被逐户 581008 挡住；判权仍是团期结算原有的角色判据。
• 已取消户不在「在团户」内，全程不受影响。

---

2. 结算反确认 POST /v3/admin/order/group-batch/{groupBatchId}/settle/reopen

VO: Result<Void>（无请求体）

使用场景

团期详情「结算」节点的「反结算」按钮（SETTLED → REVIEWING）。本次起已结算的子订单一并退回待结算。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变

无请求体（不变）。

出参

字段	类型	说明
data	Void	成功返回 null（不变）

请求示例

POST /v3/admin/order/group-batch/2097250563497385985/settle/reopen HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <admin token>

响应示例

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

空数据 / 降级响应

无列表出参；没有已结算子订单时只退团期，不报错：

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

错误响应

团期当前不是已结算（不变）：

{
  "code": 589501,
  "message": "团期状态不允许当前操作",
  "success": false,
  "data": null
}

业务边界

• 只退「财务复核」这一步：flow SETTLED → PENDING_SETTLE、settlement COMPLETED → PENDING、清 settled_at；review 保持 COMPLETED，逐户核单终态快照与核单汇总不动。
• 不在已结算的户（未结算 / 已被逐户反确认）不命中，不写。
• 已生成的报账单不撤；重新结算时按核单汇总 ID 幂等命中既有报账单，不重复生成。反结算期间出纳仍可能处理这些报账单。
• 本接口未新增错误码。

---

3. 发起核单 POST /v3/admin/order/group-batch/{groupBatchId}/review/start

VO: GroupBatchReviewStartRespVO

使用场景

团期详情「出行完毕」节点的「发起核单」按钮（TRIP_FINISHED → REVIEWING）。本次起首次推进时同事务把待核单的户带进核单中。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变

无请求体（不变）。

出参

字段	类型	说明
groupBatchId	String	团期主订单 ID（不变）
batchStatus	String	恒为 REVIEWING（不变）
batchStatusDesc	String	恒为「核单中」（不变）
alreadyStarted	Boolean	true = 幂等命中，零写入（不变；本次起幂等命中也不同步子订单）

请求示例

POST /v3/admin/order/group-batch/2097250563497385985/review/start HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <admin token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2097250563497385985",
    "batchStatus": "REVIEWING",
    "batchStatusDesc": "核单中",
    "alreadyStarted": false
  },
  "success": true
}

空数据 / 降级响应

重复点击返回 alreadyStarted=true，团期与子订单都不写（不变）：

{
  "code": 200,
  "message": "成功",
  "data": { "groupBatchId": "2097250563497385985", "batchStatus": "REVIEWING", "batchStatusDesc": "核单中", "alreadyStarted": true },
  "success": true
}

错误响应

团期不在出行完毕（不变）：

{
  "code": 589564,
  "message": "当前团期状态不可发起核单（须为「出行完毕」）",
  "success": false,
  "data": null
}

业务边界

• 只推 flow PENDING_REVIEW 的户（review PENDING / IN_PROGRESS、settlement 为空或 NONE）；已在核单中、已提交、已结算的户不动。
• flow 仍早于待核单的户（如未完成出行同步的存量户）跳过并记日志，不阻断团期进入核单；这些户日后第一次录核单明细时仍会自己进入核单中。
• 权限码 group-batch:finance:advance 与各错误码（589507 / 589564 / 589565 / 589566）不变。

---

4. 录入团期共享成本 POST /v3/admin/order/group-batch/{groupBatchId}/settlement/cost

VO: RecordBatchCostReqVO → Result<Long>

使用场景

团期核单页录大巴 / 领队 / 摄影等共享成本。团期在出行完毕时录第一笔会顺带把团期推进核单中；本次起这一推进同时同步子订单（与接口 3 同一逻辑）。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
costType	Body	String	✅	BUS / LEADER / PHOTOGRAPHER / OTHER	不变
amount	Body	BigDecimal	✅	≥ 0	不变
source	Body	String	否	MANUAL / FLEET_CALLBACK	默认 MANUAL（不变）
sourceRefNo	Body	String	否	FLEET_CALLBACK 时必填	幂等键（不变）
remark	Body	String	否	≤ 255 字符	不变

出参

字段	类型	说明
data	Long	新成本明细 ID（不变）

请求示例

{
  "costType": "BUS",
  "amount": 1200.00,
  "source": "MANUAL",
  "remark": "大巴费用"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": 90412,
  "success": true
}

空数据 / 降级响应

第二笔及以后的成本（团期已在核单中）只插明细，不再同步子订单（不变的推进口径）：

{ "code": 200, "message": "成功", "data": 90413, "success": true }

错误响应

团期不在可录成本的状态（不变）：

{
  "code": 589501,
  "message": "团期状态不允许当前操作",
  "success": false,
  "data": null
}

业务边界

• 本接口由「无事务」改为整方法单事务：团期推进、子订单同步、明细插入全有全无（改前 CAS 与 INSERT 各自提交，插入失败时团期可能已被推进）。
• 权限码 group-batch:finance:advance 与错误码不变。

---

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

✅ 正确 / ❌ 错误调用对照

场景	调用
✅ 团期结算	各户提交逐户核单 → 整团核单提交核算（ALLOCATED）→ settle，子订单一并结算
❌ 有户逐户核单未提交就结算	settle → 589568「…未提交订单：{订单 ID}」
❌ 团期结算后再逐户点「结算确认」	不再需要；已结算户逐户复核会被既有状态门拒绝
✅ 结算后发现问题	settle/reopen → 改整团核单 → 重新 settle（报账单幂等，不重复）

589568 的区分

589568 码值同时用于「整团核单状态不对」与本次新增的「逐户核单未提交」。前端可直接展示 message；如要分支，message 含「未提交订单：」即为本次新增原因，出路是去对应订单提交逐户核单。

---

五、数据库行为

前端动作	外部可观察的写入（同一事务）
review/start 首次成功 / 首笔 settlement/cost	团期 REVIEWING + 待核单户 review IN_PROGRESS / flow REVIEWING（CAS，按行）
review/start 幂等命中	零写入
settle 成功	核单 CHECKED + 团期 SETTLED + 待结算户 settlement COMPLETED / flow SETTLED / settled_at、订单日志 SETTLEMENT_CONFIRM（备注「团期结算（整团财务复核）[：结算意见]」）、每户一张 BZ 报账单
settle 被 589568 拒	零写入
settle/reopen 成功	团期 REVIEWING + 核单退回 + 已结算户 flow PENDING_SETTLE / settlement PENDING / 清 settled_at；报账单保留

无 schema 变更。

---

六、边界行为

• 未登录 → 401（网关拦截）；团期不存在 → 589500。
• 已取消户全程不受影响；重复触发不重复写（各写入均带状态 CAS）。
• 二次结算（反结算后再结算）报账单不重复、settlement_id 不变。
• 首次结算后逐户反确认会被 584330（报账单已进入出纳）拒绝（既有行为，不变）。
• 逐户财务复核入口对团期单仍开放；已被逐户复核过的户在团期结算时跳过。

---

六.6、修改前后对比

字段级对比

字段	改前	改后
settle 589568 message	仅整团核单状态类原因	新增「结算需要所有在团订单逐户核单已提交，未提交订单：{订单 ID}」
子订单 settlement_status / flow_status / settled_at（团期结算后）	不变（待结算）	COMPLETED / SETTLED / 结算时间
子订单 review / flow（团期进入核单后）	PENDING / PENDING_REVIEW	IN_PROGRESS / REVIEWING

行为级对比

行为	改前	改后
团期结算	只改团期与整团核单	另做整团财务复核，逐户结算 + 报账单
团期反结算	只改团期与整团核单	另把已结算户退回待结算
团期进入核单	不碰子订单	待核单户进核单中
录共享成本事务	无事务	单事务

六.7、影响评估

• 是否破坏向后兼容: 部分。路径、入参、成功出参不变；settle 多一种 589568 原因，逐户核单未提交的团原先能结算、现在被拒。
• 前端是否必须同步上线: 否。后端已自行完成子订单同步；前端未改时 589568 按原样弹 message 即可理解。
• 前端 workaround 清理点: 团期结算后引导运营逐户「结算确认」的提示可移除；子订单列表刷新即可看到已结算。

---

七、不影响范围

• 仅影响: 团期发起核单、首笔共享成本、结算、反结算四个动作对子订单的联动。
• 零影响:
  • 逐户核单明细录入与提交（/v3/admin/order/{orderId}/settlement/**）
  • 逐户财务复核 POST /v3/admin/order/{orderId}/settlement/confirm 的入参出参与判权
  • 整团核单（核算、分摊）各端点
  • 散客单的核单结算
  • 小程序端

---

八、测试环境已验证

部署：hl-order-service-v3 = dev-v3 @ f55840cb5（含 PR #8345），TEST 环境实测 2026-09-24 16:05–16:11（证据见工单 #8341 验收评论）；工单 #8341 已验收关单。

#	场景	结果
1	团期进入核单	活跃户 review IN_PROGRESS / flow REVIEWING；重复调用状态不变
2	逐户核单定稿 + 整团核单 ALLOCATED 后团期结算	四户 settlement COMPLETED / flow SETTLED / settled_at；报账单每户 1 张（BZ-202609240001～0004）
3	团期反结算	四户回 flow PENDING_SETTLE / settlement PENDING，settled_at 清空；报账单保留
4	已取消户 / 二次结算	已取消户全程未动；二次结算报账单不重复、settlement_id 不变
5	逐户核单未提交时整团结算（SQL 构造）	589568「…未提交订单：2103023889187799042」，整团回滚

本地：相关单测 / H2 IT / ArchUnit 314 例 0 失败；Docker IT GroupBatchAuditVersionCasMySqlIT 10 例、FlowStatusP1cIntegrationTest 4 例 0 失败。

---

九、相关历史 PR

PR	Issue	说明	是否仍有效
—	#7456	团期结算归档 / 反确认端点	✅ 端点不变，本单加子订单联动
—	#7527	发起核单端点	✅ 端点不变，本单加子订单联动
本 PR #8345	#8341	核单 / 结算 / 反结算同步子订单	✅ 最新

---

十、相关文档

• 关联 Issue: wx/HL#8341
• 关联 PR: wx/HL#8345
• 定案文档：SRS §0.27.7（PR #8338）
• 同批条目：团期确认联动子订单确认行程（#8339）

关联 / 联系人

链接

• Issue: #8341
• PR: #8345
• Merge commit: 454e2da4b

联系人

• 后端负责人: @jw