wx/hl-api-changelog

派生 0

文件

T

jw和Claude Opus 5.5 1fe976a7a6

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

详情

docs(changelog): #8322 团期预支核单前均可发起+领款人限定主报账人（589557），补 #8270 放宽说明，订正 #7154 错误码 589538/589539→589541/589542

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

2026-09-24 11:51:33 +08:00

27 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	7154	团期财务总览与预支复用订单预支：财务 Tab 三个只读端点 + 预支创建语义改造	admin	jw(GIT)	新增接口	deployed	verified	verified	mmg	af7cc62b	hl-ui@af7cc62b	2026-09-08	后端 PR #7170 已合 dev-v3 并部署测试服(网关 finance/advances/payee-candidates 实测 200),原 backend_status/gateway_status=pending 系 09-06 陈旧快照已修正为 deployed/verified。前端团期财务 Tab 与预支接真已交付:groupBatchFinance.js 五端点+FinanceTab(四金额卡/逐户付款表/预支记录/整团核算口径行)+GroupAdvanceModal+detail 挂财务 Tab+store 键缓存+AdvanceApprovalList scope 筛选;金额全后端权威值零反算。ref af7cc62b,checkpoint 全绿含 Vitest 全量+生产构建。	2026-09-24	dev-v3

团期: 财务总览与预支复用订单预支

服务: hl-order-service-v3 PR: #7170 Issue: #7154 日期: 2026-09-06 影响范围: 管理后台团期详情「财务」Tab、底部操作条「预支」弹窗、财务管理→预支审批列表

⚠️ 关键变化

团期财务 Tab 与团期预支弹窗此前在 hl-ui 里完全不存在（全仓零调用点），本次补齐后端。

四条前端必读：

POST .../group-batch/{id}/advance 入参整体更换。旧契约 {amount, remark} 是后端造了、前端从没接过的端点（已核 hl-ui v2.1 全仓无调用点），故不是破坏性变更；新契约与订单级预支逐字一致，预支弹窗组件可整体复用。
「已预支」拆成三个数，旧 advanceTotal 已废。旧语义是「提交即计入」（无审批），与新口径不等价：展示用 advanceApproved（只计已通过），额度用 advanceAvailable。不要再用一个数。
预支上限一律读后端 advanceAvailable，不要前端自算。订单级弹窗现在是本地 balanceAmount − Σ记录 算的，依赖记录列表已拉全；团期场景该算法不可靠。
「设置报账人」传的是产品侧 productBatchId，从团期详情接口取，不是财务 Tab 路径上的 groupBatchId，两者不同值。该端点后端零改动。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期财务总览	GET	`/v3/admin/order/group-batch/:id/finance`	新增	四张金额卡 + 逐户付款 + 整团合计
2	团期预支记录	GET	`/v3/admin/order/group-batch/:id/advances`	新增	团期级 + 各子订单级逐笔，不分页
3	领款人候选	GET	`/v3/admin/order/group-batch/:id/advance/payee-candidates`	新增	预支弹窗「借款对象」下拉
4	发起团期预支	POST	`/v3/admin/order/group-batch/:id/advance`	修改	路径不变，入参与返回体更换；创建即进待审批
5	预支审批列表	GET	`/v3/admin/order/advance-approvals/page`	修改	容忍团期级行 + `scope` 筛选 + keyword 六路
6	整团核算汇总	GET	`/v3/admin/order/group-batch/:id/settlement/summary`	修改	出参新增两个整团预支只读字段

零改动复用（同一套审批流程，前端无需改）：PUT /v3/admin/order/advance/:id/approve、 PUT /v3/admin/order/advance/:id/reject、DELETE /v3/admin/order/advance/:id、 PUT /v3/admin/group-batch/:id/staff/:id/reporter-rank。

三、接口详情

1. 团期财务总览 `GET /v3/admin/order/group-batch/:id/finance`

VO: GroupBatchFinanceRespVO

使用场景

团期详情切到「财务」Tab 时加载。一次返回顶部四张金额卡、逐户付款表与整团合计、已退团户数、主/次报账人，Tab 全部内容一个请求搞定。

入参

字段	位置	类型	必填	约束	说明
`id`	path	Long	✓	正整数	团期 ID（订单侧 `order_group_batch.group_batch_id`）

无 query 参数，无请求体。需 group-batch:finance:view 权限码（比 group-batch:view 更严）。

出参

字段	类型	说明
`receivableAmount`	BigDecimal	整团应收 = Σ 活跃子订单（订单金额 + 附加费 − 优惠）
`receivedAmount`	BigDecimal	整团已收 = Σ 已付（累计毛额，不冲抵退款）
`unpaidAmount`	BigDecimal	整团待收 = 应收 − 已收，下限 0，即本期总尾款
`advanceApproved`	BigDecimal	已预支（只计已通过）。第四张卡取此值，不是三个数之和
`advancePending`	BigDecimal	待审批预支，占额度但未出账，不计入「已预支」卡
`advanceAvailable`	BigDecimal	可支取余额 = 尾款池 − (已通过 + 待审批)，下限 0，即预支上限
`withdrawnCount`	Integer	已退团户数（前端只拉活跃集，算不出这个数）
`primaryPayeeName`	String	主报账人姓名，未设置为 `null`（后端不兜底默认导游）
`secondaryPayeeName`	String	次报账人姓名，未设置为 `null`
`totals.totalPrice` / `.paidAmount` / `.unpaidAmount`	BigDecimal	逐户表末行「整团合计」，服务端算，与顶部卡同源
`items[].orderId`	String	子订单 ID（字符串回传防精度丢失）
`items[].orderNo`	String	子订单号
`items[].customerName`	String	客户姓名（不返回手机号与证件号）
`items[].consultantName`	String	定制师姓名
`items[].totalPrice`	BigDecimal	本户应收
`items[].paidAmount`	BigDecimal	本户已付。⚠️ 是全额已付，不是真定金拆分
`items[].unpaidAmount`	BigDecimal	本户待收尾款
`items[].payStatus`	String	仅 `UNPAID` / `DEPOSIT_PAID` / `FULLY_PAID` 三值
`items[].settleStatus`	String	`SETTLED` / `PENDING_BALANCE` / `WITHDRAWN`，状态胶囊取此值
`items[].settleStatusText`	String	结清状态中文，可直接渲染

请求示例

GET /v3/admin/order/group-batch/90211/finance

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "receivableAmount": 40200.00,
    "receivedAmount": 32900.00,
    "unpaidAmount": 7300.00,
    "advanceApproved": 0.00,
    "advancePending": 0.00,
    "advanceAvailable": 7300.00,
    "withdrawnCount": 0,
    "primaryPayeeName": "张领队",
    "secondaryPayeeName": null,
    "totals": { "totalPrice": 40200.00, "paidAmount": 32900.00, "unpaidAmount": 7300.00 },
    "items": [
      { "orderId": "770145", "orderNo": "GT-26-0081", "customerName": "罗敏", "consultantName": "李雯",
        "totalPrice": 12300.00, "paidAmount": 12300.00, "unpaidAmount": 0.00,
        "payStatus": "FULLY_PAID", "settleStatus": "SETTLED", "settleStatusText": "已结清" },
      { "orderId": "770147", "orderNo": "GT-26-0083", "customerName": "汪洋", "consultantName": "陈璐",
        "totalPrice": 12300.00, "paidAmount": 5000.00, "unpaidAmount": 7300.00,
        "payStatus": "DEPOSIT_PAID", "settleStatus": "PENDING_BALANCE", "settleStatusText": "待收尾款" }
    ]
  }
}

空数据 / 降级响应

无活跃子订单时，六个金额字段均为 0.00（不是 null），items 为空数组，withdrawnCount 为 0，两个报账人为 null。

错误响应

码	含义
`589500`	团期不存在或已软删
`589507`	缺 `group-batch:finance:view` 权限

{ "code": 589500, "msg": "团期不存在", "data": null }

业务边界

已取消与已软删子订单不进任何金额、不进 items，只贡献 withdrawnCount。
隐式团（IMPLICIT_SINGLE）按一单退化开放，字段结构不变，前端不得因团类型走两套渲染分支。
顶部「已收（定金）」卡与逐户「已付定金」列，语义都是全额已付，不区分定金/尾款；已结清户该列等于应收。
整团应收与团期详情 totalReceivable、看板列表该行应收三处同源，数值必然一致。

2. 团期预支记录 `GET /v3/admin/order/group-batch/:id/advances`

VO: List<GroupBatchAdvanceItemVO>

使用场景

财务 Tab 下半部「预支记录」区块，以及预支弹窗内的记录列表。

入参

字段	位置	类型	必填	约束	说明
`id`	path	Long	✓	正整数	团期 ID

无 query 参数，不分页，一次返回本期全部。

出参

字段	类型	说明
`id`	String	预支单 ID
`payeeStaffId`	String	领款人主键快照
`payeeName` / `payeeRole` / `payeeRoleText`	String	领款人姓名 / 角色码 / 角色中文
`advanceType`	String	借款类型
`amount`	BigDecimal	预支金额
`purpose` / `voucherUrl`	String	用途说明 / 凭证 URL
`status` / `statusText`	String	`SUBMITTED` / `APPROVED` / `REJECTED` 及其中文
`rejectReason`	String	驳回原因
`createdByName`	String	申请人姓名
`createTime` / `submittedAt` / `approvedAt`	String	创建 / 提交 / 审批时间
`approvedBy`	String	审批人姓名
`scope`	String	`ORDER` 订单级 / `GROUP_BATCH` 团期级（本次新增）
`scopeName`	String	归属维度中文，可直接渲染标签（本次新增）
`orderNo`	String	子订单号，`scope=ORDER` 时非空；团期级为 `null`（本次新增）

请求示例

GET /v3/admin/order/group-batch/90211/advances

响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    { "id": "31005", "scope": "GROUP_BATCH", "scopeName": "团期预支", "orderNo": null,
      "payeeName": "朝鲁门", "payeeRole": "DRIVER", "payeeRoleText": "司机",
      "advanceType": "住宿押金", "amount": 5000.00, "purpose": "沿途住宿押金",
      "status": "APPROVED", "statusText": "已通过", "createdByName": "李雯",
      "submittedAt": "2026-08-18 22:58:26", "approvedAt": "2026-08-19 09:12:03" }
  ]
}

空数据 / 降级响应

无预支时返回空数组 []，前端显示空态文案「暂无预支 · 在底部「预支」发起，记录将在此显示」（文案由前端提供，后端不返回）。

错误响应

码	含义
`589500`	团期不存在
`589507`	缺 `group-batch:finance:view` 权限

{ "code": 589500, "msg": "团期不存在", "data": null }

业务边界

返回团期级 + 各子订单级全部预支，按创建时间倒序。
本接口不返回累计金额，累计取接口 1 的 advanceApproved / advancePending / advanceAvailable。

3. 领款人候选 `GET /v3/admin/order/group-batch/:id/advance/payee-candidates`

VO: List<AdvancePayeeCandidateVO>

使用场景

预支弹窗「借款对象」下拉。

入参

字段	位置	类型	必填	约束	说明
`id`	path	Long	✓	正整数	团期 ID（订单侧），服务端内部换算成产品侧，前端不感知

出参

字段	类型	说明
`id`	Long	候选 ID，即创建预支的 `payeeStaffId`（资源域 `staff.staff_id`）
`staffName`	String	姓名
`staffRole`	String	角色代码
`staffRoleText`	String	角色中文
`reporterRank`	String	`PRIMARY` / `SECONDARY` / `NONE`
`isDefault`	Boolean	主报账人为 `true`，前端默认选中

请求示例

GET /v3/admin/order/group-batch/90211/advance/payee-candidates

响应示例

{
  "code": 0, "msg": "success",
  "data": [
    { "id": 88101, "staffName": "张领队", "staffRole": "GUIDE", "staffRoleText": "导游",
      "reporterRank": "PRIMARY", "isDefault": true },
    { "id": 88102, "staffName": "朝鲁门", "staffRole": "DRIVER", "staffRoleText": "司机",
      "reporterRank": "NONE", "isDefault": false }
  ]
}

空数据 / 降级响应

团期未配人员时返回空数组 []；此时预支无法提交（借款对象必填）。

错误响应

码	含义
`589500`	团期不存在
`589507`	缺 `group-batch:finance:view` 权限

{ "code": 589500, "msg": "团期不存在", "data": null }

业务边界

候选 = 本团全部人员（与订单级「可选本单任一人员」口径一致），排序：主报账人 → 次报账人 → 其余。
不返回手机号，与订单级候选保持一致。

4. 发起团期预支 `POST /v3/admin/order/group-batch/:id/advance`

VO: OrderAdvanceRespVO

使用场景

财务 Tab 底部操作条「预支」→ 弹窗填写 → 「申请预支」。

入参

字段	位置	类型	必填	约束	说明
`id`	path	Long	✓	正整数	团期 ID
`payeeStaffId`	body	Long	✓	须属本团人员	借款对象，取候选下拉项的 `id`
`advanceType`	body	String	✓	字典 `advance_type` 的 `dictValue`	借款类型
`amount`	body	BigDecimal	✓	> 0 且 ≤ `advanceAvailable`	预支金额
`purpose`	body	String	—	≤ 255	用途说明
`voucherUrl`	body	String	—	≤ 512	凭证 URL

⚠️ 旧入参 {amount, remark} 已废除。remark 无对应字段，改用 purpose。

出参

字段	类型	说明
`id`	String	新建的预支单 ID（旧实现返回 `Void`，现在回传）
`payeeStaffId`	String	领款人主键快照（团期级存资源域 `staff.staff_id`）
`payeeName` / `payeeRole` / `payeeRoleText`	String	领款人姓名 / 角色码 / 角色中文
`advanceType`	String	借款类型
`amount`	BigDecimal	预支金额
`purpose` / `voucherUrl`	String	用途说明 / 凭证 URL
`status` / `statusText`	String	创建后恒为 `SUBMITTED` / 「待审批」
`createdByName`	String	申请人姓名
`createTime` / `submittedAt`	String	创建 / 提交时间

请求示例

POST /v3/admin/order/group-batch/90211/advance
{
  "payeeStaffId": 88102,
  "advanceType": "住宿押金",
  "amount": "3000.00",
  "purpose": "沿途住宿押金",
  "voucherUrl": null
}

响应示例

{
  "code": 0, "msg": "success",
  "data": {
    "id": "31006", "payeeStaffId": "88102", "payeeName": "朝鲁门",
    "payeeRole": "DRIVER", "payeeRoleText": "司机",
    "advanceType": "住宿押金", "amount": 3000.00, "purpose": "沿途住宿押金",
    "status": "SUBMITTED", "statusText": "待审批",
    "createdByName": "李雯", "submittedAt": "2026-09-06 15:20:11"
  }
}

空数据 / 降级响应

数据字典服务不可用时，借款类型校验降级为服务端内置集合，不影响正常类型提交。

错误响应

码	含义
`589500`	团期不存在
`589507`	缺 `group-batch:finance:advance` 权限
`589541`	团期状态不可发起预支。⚠️ 2026-09-24 订正：原文误写为 `589538`（号段顺延后实际落 589541）；允许状态已两次放宽，现为「进入核单前都可以」（#8270 / #8322）
`589542`	房 / 车 / 导 / 摄四项未配齐。⚠️ 2026-09-24 订正：原文误写为 `589539`（该号实为 #7178「名额调整量不能为 0」）；#8270 起本码不再返回
`585003`	预支金额必须大于 0
`585004`	预支金额超过可用余额上限
`585006`	借款类型非法
`585007`	借款对象不属于本团期人员

{ "code": 585004, "msg": "预支金额超过可用余额上限", "data": null }

业务边界

双前置闸门：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。⚠️ 已变更：#8270 删除四项配齐门，#8322 起进入核单前都可发起，且领款人限定为本团主报账人（589557），见 24_8322_… 条目。
上限走团期统一池：团期级与各子订单级共扣一池。团期把整团尾款预支满后，该团任一子订单再发起订单级预支同样会被 585004 拒——这是本次修复的超支漏洞。
创建后进入站内财务审批，走既有 advance-approvals 列表与 approve / reject / 撤回三端点，与订单级完全一致。
一期仍只记账不出款，实际出款走财务既有付款流程。
同一团期 + 同一金额 5 秒内重复提交只成功一次（幂等）。

5. 预支审批列表 `GET /v3/admin/order/advance-approvals/page`

VO: PageResult<AdvanceApprovalPageItemRespVO>

使用场景

财务管理 → 预支审批。团期级预支与订单级预支混排在同一列表、走同一审批流程。

入参

新增一个可选 query 参数，其余入参不变：

字段	位置	类型	必填	约束	说明
`scope`	query	String	—	`ALL` / `ORDER` / `GROUP_BATCH`	归属维度筛选，缺省 `ALL`（两类混排，与改造前行为一致）

keyword 语义扩展：由「订单号 / 团号 / 产品名」三路扩为六路，另加「团期号 / 团期名 / 团期产品名」。改造前搜索框标着「团号 / 产品」却搜不出团期级预支。

出参

每行新增四个字段，其余不变：

字段	类型	说明
`scope`	String	`ORDER` / `GROUP_BATCH`
`scopeName`	String	归属维度中文
`batchStatus`	String	团期状态编码，仅 `scope=GROUP_BATCH` 时非空
`batchStatusName`	String	团期状态中文

既有字段按 scope 择一填充，前端零改动即可显示：

字段	`scope=ORDER`	`scope=GROUP_BATCH`
`teamNo`（团号列）	订单团号	团期号
`productName`	订单产品名	团期产品名
`departDate` / `returnDate`（行程列）	订单出行日期	团期出团 / 返程日
`orderAmount` / `paidAmount`	本单应收 / 已收	整团应收 / 已收
`orderNo` / `consultantName`	有值	`null`（前端显「—」）
`orderStatus` / `flowStatus` / `payStatus` / `settlementStatus`	有值	`null`，改看 `batchStatus`

请求示例

GET /v3/admin/order/advance-approvals/page?status=SUBMITTED&scope=GROUP_BATCH&page=1&pageSize=20

响应示例

{
  "code": 0, "msg": "success",
  "data": {
    "records": [
      { "id": "31006", "scope": "GROUP_BATCH", "scopeName": "团期预支",
        "orderNo": null, "teamNo": "GT-26-05", "productName": "呼伦贝尔草原 5 日游",
        "departDate": "2026-09-20", "returnDate": "2026-09-24", "consultantName": null,
        "orderStatus": null, "batchStatus": "PENDING_DEPARTURE", "batchStatusName": "待出发",
        "orderAmount": 40200.00, "paidAmount": 32900.00,
        "payeeName": "朝鲁门", "advanceType": "住宿押金", "amount": 3000.00,
        "status": "SUBMITTED", "statusText": "待审批" }
    ],
    "total": 1, "page": 1, "pageSize": 20
  }
}

空数据 / 降级响应

无匹配记录时 records 为空数组，total 为 0。

错误响应

沿用改造前，本次未新增错误码。

{ "code": 589507, "msg": "无操作权限", "data": null }

业务边界

前端必须容忍 orderId / orderNo 为 null（团期级行不挂订单）。
审批通过 / 驳回 / 撤回三个端点零改动，对团期级行行为与订单级完全一致。
团期级预支走站内财务审批（资金审批），与流团 / 退单户的企微 OA 业务审批是两条线，不合并。

6. 整团核算汇总 `GET /v3/admin/order/group-batch/:id/settlement/summary`

VO: GroupBatchSettlementSummaryRespVO

使用场景

整团核算页。本次新增两个只读字段，用于核单时把整团预支从主报账人代收的尾款中扣回。

入参

字段	位置	类型	必填	约束	说明
`id`	path	Long	✓	正整数	团期 ID。入参未变

出参

新增两个字段，其余不变：

字段	类型	说明
`groupAdvanceApproved`	BigDecimal	整团已拨付预支（只含团期级），核算时单独成一行扣回
`groupAdvancePending`	BigDecimal	整团待审批预支，占额度未出账，仅提示

请求示例

GET /v3/admin/order/group-batch/90211/settlement/summary

响应示例

{
  "code": 0, "msg": "success",
  "data": {
    "settledOrderCount": 3, "totalActiveOrderCount": 3,
    "subOrderTotalActualCost": 21000.00, "sharedCostTotal": 6000.00,
    "grandTotalCost": 27000.00,
    "groupAdvanceApproved": 5000.00,
    "groupAdvancePending": 0.00
  }
}

空数据 / 降级响应

无团期级预支时两个字段均为 0.00（不是 null）。

错误响应

沿用改造前。

{ "code": 589500, "msg": "团期不存在", "data": null }

业务边界

🚫 只含团期级预支，不含子订单级。子订单级预支已进各户的核单报销单与对账，整团层再算一次会同一笔钱扣两遍。
🚫 不计入 grandTotalCost。预支是资金拨付不是成本，计入会与核销后的真实成本科目重复计成本。前端渲染为「整团成本 X ／其中已拨付预支 Y」的独立一行，不参与任何成本或毛利公式。
逐户报销单与逐户对账一个字未改。

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

财务 Tab 一次请求拿全：接口 1 已含四张卡、逐户表、整团合计、退团户数、报账人，不要再拼 /orders。
金额一律用服务端给的值。整团合计由服务端算并与四张卡同源；前端自行 sum 会与卡片对不上。
预支上限读 advanceAvailable，不要用「待收尾款 − 记录之和」本地推算。
状态胶囊读 settleStatus，不要用 payStatus 推——后者只有三值，表达的是支付事件不是结清与否，已退团户用它渲染会显示成「已付定金」。
设置报账人用产品侧 productBatchId（团期详情接口取），不是财务 Tab 路径上的 groupBatchId。

五、数据库行为

只写外部可观察行为。

动作	可观察结果
发起团期预支	新增一条待审批预支记录，立即出现在本团期预支记录列表与预支审批列表；团期与订单的任何金额字段均不变动（预支不改应收/已收/待收）
审批通过	该记录转为「已通过」，财务 Tab 的「已预支」增加、「待审批预支」减少、「可支取余额」不变（原本就已占额度）
审批驳回 / 撤回	该记录转为「已驳回」或从列表消失，占用的额度当场释放，「可支取余额」回升
上线迁移（一次性）	存量团期原有的累计预支金额，会转成一条「已通过」的期初结转记录出现在预支记录列表，金额与迁移前的累计值相等；该记录无领款人与凭证，按借款类型「期初结转」可识别

幂等：同一团期 + 同一金额 5 秒内重复提交只成功一次。

并发：同一团期的预支申请串行处理，两个管理员同时提交不会双双突破可支取余额。

六、边界行为

场景	行为
团期无活跃子订单	六个金额字段 `0.00`，`items` 空数组
子订单已取消	不进金额、不进 `items`，只计入 `withdrawnCount`
未设置报账人	`primaryPayeeName` 为 `null`，后端不兜底默认导游
团期状态为招募中 / 核单中	发起预支返回 `589541`（2026-09-24 订正码值；#8322 起招募中已可发起，仅核单中及之后返回）
四项资源缺任一	原返回 `589542`（2026-09-24 订正码值）；#8270 起不再拦截
团期尾款池已被预支占满	团期级与该团任一子订单级预支均返回 `585004`
数据字典服务不可用	借款类型降级到内置集合校验，正常类型仍可提交
审批列表出现团期级行	`orderId` / `orderNo` / `consultantName` / 订单四态均为 `null`

七、不影响范围

订单级预支全链路行为零变化：创建 / 审批 / 驳回 / 撤回 / 本单列表五个端点与改造前逐字一致（底表 order_id 由非空放宽为可空，但既有查询全是等值匹配，空值行天然不命中）。
逐户核单报销单与逐户对账未改：仍只含本户预支。
审批通过 / 驳回 / 撤回三端点未改。
设置报账人端点未改。
前端页面、打印导出、发票区、预支实际出款均不在本次范围。

八、测试环境已验证

⏳ 尚未验证。本文档随 PR #7170 提交，待合并并部署测试服后过网关实测，届时更新 backend_status / gateway_status / verified_at 并补本节实测结果。

计划实测要点：

财务 Tab 四张卡与逐户表末行合计一致，且与团期详情、看板列表三处应收同源。
超支被堵死：团期级把整团尾款预支满 → 该团任一子订单再发起订单级预支被 585004 拒。
核单零重复扣：团期级预支 5,000 通过 + 某户订单级预支 2,000 通过 → 该户报销单含 2,000，整团 groupAdvanceApproved 仍是 5,000；grandTotalCost 不变。
两道闸门各拒一次（589541 / 589542，2026-09-24 订正码值）。
团期级预支出现在预支审批列表，「团号 / 产品」「行程」两列有值，按团期号搜得到，就地通过 / 驳回 / 撤回正常。
订单级预支五端点回归无变化。

十、相关文档

团期模块接口文档 v2.0 §0B（预支权威契约）、§0A.3（金额口径）、卡片 GB-ADM-040 / 041 / 042 / 043
团期模块数据模型 §A.11（预支复用订单预支）、§A.11.10（团期层单独对账）
团期模块表结构 v1.2 §4-5（order_advance 改造 DDL）

待回写正式稿（本次实现与文档不一致处）：

处	文档现状	实际
§0B.9 错误码	「统一用 `AdvanceErrorCode`（585 段）」	改落 `589541` / `589542`（原拟 589538 / 589539，被 #7158 / #7178 先占后顺延，2026-09-24 订正）；585 段被 v2/v3 整段重叠声明且 585001-585010 已被 order-v2 实占
GB-ADM-040 出参	`payStatus` 写五值含 `REFUNDING` / `REFUNDED`	代码只有三值；结清状态另出 `settleStatus` 字段
GB-ADM-040 出参	含 `advanceTotal`	已废，改三个数
GB-ADM-042	返回 `GroupBatchWriteResultVO`、不回传 `advanceId`	改返 `OrderAdvanceRespVO` 并回传 `advanceId`
§0A.3	「金额缺口是本期 P0，详情恒返回 0.00」	已被 #6905 / #6902 实时聚合关闭
§0B.6	「查询键列名骗人，必须进 CR checklist」	`V20260904_001` 改名后该坑消失

关联 / 联系人

Issue: #7154
PR: #7170（base dev-v3）
后端: jw
前端: 待认领（三个新端点 + 预支弹窗入参更换 + 审批列表 scope 标签）

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

团期: 财务总览与预支复用订单预支

⚠️ 关键变化

二、变更接口清单

三、接口详情

1. 团期财务总览 GET /v3/admin/order/group-batch/:id/finance

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期预支记录 GET /v3/admin/order/group-batch/:id/advances

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 领款人候选 GET /v3/admin/order/group-batch/:id/advance/payee-candidates

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. 发起团期预支 POST /v3/admin/order/group-batch/:id/advance

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

5. 预支审批列表 GET /v3/admin/order/advance-approvals/page

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

6. 整团核算汇总 GET /v3/admin/order/group-batch/:id/settlement/summary

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

27 KiB

原始文件 Blame 文件历史

1. 团期财务总览 `GET /v3/admin/order/group-batch/:id/finance`

2. 团期预支记录 `GET /v3/admin/order/group-batch/:id/advances`

3. 领款人候选 `GET /v3/admin/order/group-batch/:id/advance/payee-candidates`

4. 发起团期预支 `POST /v3/admin/order/group-batch/:id/advance`

5. 预支审批列表 `GET /v3/admin/order/advance-approvals/page`

6. 整团核算汇总 `GET /v3/admin/order/group-batch/:id/settlement/summary`