---
schema: "hl-changelog/v2"
ticket: "7396"
title: "应付款四入口接团期住宿 + 团期住宿付款身份金额对账 + 新增撤销批准"
consumer: "admin"
author: "jw(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端交付（hl-finance，随 hl-order-service-v3 部署）。4 个应付款读接口返回扩大（新 sourceType=GROUP_BATCH_STAY、sourceRefKey、金额对账字段、统计新字段与 OVERPAID 状态），3 个创建口新增入参 sourceRefKey 与 598812/598813 两个新错误码，草稿编辑口新增归属与额度守卫，新增 PUT /admin/finance/payments/{id}/revoke-approval。网关前缀 /admin/finance/payments 已存在，无需新路由。前端需接新 sourceType / 新字段 / 新状态 / 新错误码 / 撤销批准按钮。"
updated_at: "2026-09-17"
base: "dev-v3"
---

# finance: 应付款四入口接团期住宿 + 团期住宿付款身份金额对账 + 撤销批准

> **存放目录**: changelogs-v2/{YYYY-MM}/（管理后台，二期 finance）
>
> **服务**: hl-order-service-v3（hl-finance 模块同进程）
> **PR**: #7866
> **Issue**: #7396
> **日期**: 2026-09-17
> **影响范围**: 应付款建议（按订单 / 按供应商）、应付款统计（按团 / 按供应商）、付款单创建（单笔 / 按团批量 / 按供应商批量）、草稿编辑；新增撤销批准

---

## 关键变化（给前端 mmg 的一句话）

1. **团期住宿进应付款了**：团期房务（整团订房 + 系统分房到户）的酒店应付，现在在四个入口都能看到，行的 `sourceType` 为 **`GROUP_BATCH_STAY`**，并带 **`sourceRefKey`**（付款身份业务键）。勾选建单时 **`sourceRefKey` 必须原样回传**，`sourceRefId` 回传行上的 `sourceId`。
2. **团期住宿按金额对账防重**：同一付款身份（同订单、同晚、同酒店、同房型）已建单后，建议行 `alreadyGenerated=true`；若应付金额变了，`amountChanged=true`、`diffAmount` 给出差额（正数可再建差额行，负数需先删除 / 驳回 / 撤销批准或等冲正）。
3. **新增两个错误码**：`598812`（已付超出当前应付，需财务冲正）、`598813`（未付占用超出当前应付，提示里列出需处理的单号与状态）。
4. **统计口径变化**：已申请 / 已付改为按付款明细聚合；新增 `refundedAmount` / `netPaidAmount` / `overpaidAmount` / `diffAmount`；`owedAmount` 不再为负；状态新增 **`OVERPAID`**；按供应商统计新增 `unattributedPaidAmount`。
5. **新增撤销批准** `PUT /admin/finance/payments/{id}/revoke-approval`：已批准未付款的单回到待提交草稿，之后可删除或编辑重提。
6. **编辑草稿收紧**：有业务来源的草稿禁止改供应商 / 订单（598808）；多明细草稿金额必须等于明细合计（598805）；团期住宿草稿改金额受额度守卫（598812 / 598813）。

---

## 一、背景

团期房务把住宿从「逐户配房」改成「整团按日订房 + 系统分房到户」后，应付款的三个批量入口（按供应商建议、按团统计、按供应商统计）只读旧配房表，团期住宿应付在这三处恒为 0；按订单建议也没有接入。同时团期分房行 ID 会在人工微调时换新，原「按来源主键判重」可被绕过而重复申请。本次：四入口共用同一读取层；团期住宿以业务键 `{orderId}:{stayDate}:{hotelId}:{roomTypeId}` 作付款身份，并按金额对账防重；统计改从付款明细聚合，已付款不会再算出负欠付。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 撤销批准 | PUT | `/admin/finance/payments/{id}/revoke-approval` | 新增 | APPROVED → PENDING，条件更新防并发，记审核流水 UN_APPROVE |
| 2 | 应付款建议（按订单） | GET | `/admin/finance/payments/suggestions` | 修改 | 新增团期住宿行与孤儿行；新增 sourceRefKey 与金额对账字段 |
| 3 | 应付款建议（按供应商跨团） | GET | `/admin/finance/payments/suggestions/by-supplier` | 修改 | 同上；已取消但仍有活跃团期占用的订单并入候选 |
| 4 | 应付款统计（按团） | GET | `/admin/finance/payments/stats/by-team` | 修改 | 该付含团期住宿；已申请/已付改按明细聚合；新字段与 OVERPAID |
| 5 | 应付款统计（按供应商） | GET | `/admin/finance/payments/stats/by-supplier` | 修改 | 同上；新增 unattributedPaidAmount |
| 6 | 申请付款（单笔） | POST | `/admin/finance/payments` | 修改 | 新增入参 sourceRefKey；带来源时 orderId 必填；团期住宿金额对账 |
| 7 | 勾选批量生成（按团） | POST | `/admin/finance/payments/batch-create` | 修改 | 明细新增 sourceRefKey；团期住宿金额对账 |
| 8 | 按供应商跨团合并建单 | POST | `/admin/finance/payments/batch-create-by-supplier` | 修改 | 明细新增 sourceRefKey；团期住宿金额对账 |
| 9 | 编辑付款草稿 | PUT | `/admin/finance/payments/{id}` | 修改 | 有来源草稿禁改供应商/订单；多明细金额守恒；团期住宿额度守卫 |

---

## 三、接口详情

### 1. 撤销批准 `PUT /admin/finance/payments/{id}/revoke-approval`

**VO**: `PaymentRevokeApprovalReqVO → Result<Void>`

#### 使用场景

付款单已批准（APPROVED）、出纳尚未付款时，因应付金额减少等原因需要改单：先撤销批准回到草稿（PENDING），再删除或编辑后重新提交。出纳并发付款时两者只会有一个成功。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| id | Path | Long | 是 | - | 付款单 ID |
| reason | Body | String | 否 | ≤512 字符；请求体整体可省略 | 撤销原因，记入审核流水 opinion |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| code | Integer | 200 成功 |
| data | Void | 恒为 null |

#### 请求示例

```json
{
  "reason": "团期减房 1 间，撤销后改单"
}
```

#### 响应示例

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

#### 空数据 / 降级响应

无查询数据；成功后 `GET /admin/finance/payments/{id}/review-logs` 追加一条 `action=UN_APPROVE`、`fromStatus=APPROVED`、`toStatus=PENDING` 的记录。

#### 错误响应

```json
{
  "code": 598802,
  "message": "应付单状态非法，当前状态不允许此操作",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598801,
  "message": "应付单不存在",
  "data": null,
  "success": false
}
```

#### 业务边界

- 仅 `APPROVED` 可撤销；`PENDING` / `SUBMITTED` / `REJECTED` / `PAID` 一律 598802。
- 条件更新（仅当状态仍为 APPROVED 才改）：与出纳付款并发时恰好一个成功，已付款的单绝不会被改回草稿。
- 撤销后单据退出出纳待付款队列；回到 PENDING 后可删除（`DELETE /admin/finance/payments/{id}`）或编辑后重新提交。
- 同事务写审核流水，流水写失败整体回滚。
- 权限口径与批准接口一致。

---

### 2. 应付款建议（按订单） `GET /admin/finance/payments/suggestions`

**VO**: `PaymentSuggestionRespVO{orderId, rows: List<PaymentSuggestionRowVO>}`

#### 使用场景

填单页按订单拉「该付给供应商」的建议行，勾选后带入创建。本次新增团期住宿行（`sourceType=GROUP_BATCH_STAY`），以及「应付已消失但仍有付款占用」的孤儿行。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Query | Long | 是 | - | 订单 ID |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID |
| rows[].sourceType | String | `NODE` 行程节点 / `HOTEL_ASSIGNMENT` 配房 / **`GROUP_BATCH_STAY` 团期住宿（新增取值）** |
| rows[].sourceId | Long | 来源主键；团期住宿为该付款身份下最小分房行 ID，仅定位用 |
| rows[].sourceRefKey | String | **新增**。仅团期住宿有值：`{orderId}:{yyyy-MM-dd}:{hotelId}:{roomTypeId}`，建单时原样回传 |
| rows[].resourceId | Long | 资源 ID（团期住宿为酒店 ID） |
| rows[].resourceName | String | 资源名（团期住宿为 酒店名/房型名） |
| rows[].quantity | Integer | 数量（团期住宿为该晚该房型分到本户的间数合计） |
| rows[].unitPrice | BigDecimal | 单价（团期住宿为结算价 元/间·晚；同身份单价不一致时为 null） |
| rows[].amount | BigDecimal | 当前应付（团期住宿 = Σ 结算价 × 间数；孤儿行为 0） |
| rows[].paymentMethod | String | `SIGNED` / `COMPANY_PAID` |
| rows[].paymentType | String | 付款类型字典标签预填（团期住宿同配房 = 住宿） |
| rows[].supplierId | Long | 预填供应商（按酒店反查） |
| rows[].supplierName | String | 供应商全称 |
| rows[].payeeAccountId | Long | 默认收款账户 |
| rows[].eligible | boolean | 供应商是否可付款 |
| rows[].eligibleReason | String | 不可付款原因 |
| rows[].alreadyGenerated | boolean | 是否已有活跃付款占用（团期住宿按业务键判定） |
| rows[].paidAmount | BigDecimal | **新增**。已付原值（PAID 明细合计，不扣退款）；仅团期住宿有值 |
| rows[].refundedAmount | BigDecimal | **新增**。已确认退款；仅团期住宿有值 |
| rows[].netPaidAmount | BigDecimal | **新增**。净已付 = paidAmount − refundedAmount；仅团期住宿有值 |
| rows[].unpaidAmount | BigDecimal | **新增**。未付占用（PENDING/SUBMITTED/APPROVED 明细合计，含草稿）；仅团期住宿有值 |
| rows[].generatedAmount | BigDecimal | **新增**。已生成金额 = netPaidAmount + unpaidAmount；仅团期住宿有值 |
| rows[].amountChanged | Boolean | **新增**。已有活跃占用且已生成金额 ≠ 当前应付时为 true（未申请过的行恒 false，此时看 diffAmount 即可申请额）；仅团期住宿有值 |
| rows[].diffAmount | BigDecimal | **新增**。当前应付 − 已生成金额（有符号）；仅团期住宿有值 |

#### 请求示例

```http
GET /admin/finance/payments/suggestions?orderId=2100244780104425473
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "2100244780104425473",
    "rows": [
      {
        "sourceType": "GROUP_BATCH_STAY",
        "sourceId": "2100244786240692225",
        "sourceRefKey": "2100244780104425473:2026-11-18:2029956939232808961:2029956939333472258",
        "resourceId": "2029956939232808961",
        "resourceName": "测试酒店/标准间",
        "quantity": 1,
        "unitPrice": 519.00,
        "amount": 519.00,
        "paymentMethod": "COMPANY_PAID",
        "paymentType": "住宿",
        "supplierId": null,
        "supplierName": null,
        "payeeAccountId": null,
        "eligible": false,
        "eligibleReason": "资源未关联供应商，请手选",
        "alreadyGenerated": false,
        "paidAmount": 0,
        "refundedAmount": 0,
        "netPaidAmount": 0,
        "unpaidAmount": 0,
        "generatedAmount": 0,
        "amountChanged": false,
        "diffAmount": 519.00
      }
    ]
  },
  "success": true
}
```

#### 空数据 / 降级响应

无应付行返回 `rows: []`。供应商反查 / 可付款判定 / 字典不可用时行仍返回，`eligible=false` 并给出 `eligibleReason`，不打塌整单。

```json
{
  "code": 200,
  "message": "成功",
  "data": { "orderId": "2100244780104425473", "rows": [] },
  "success": true
}
```

#### 错误响应

```json
{
  "code": 400,
  "message": "orderId 不能为空",
  "data": null,
  "success": false
}
```

#### 业务边界

- 团期住宿只取「计划行已确认 + 结算方式为签单/公司付款 + 结算价非空」且分房行有效的数据；现付（cash）不进应付。
- 团期启用前已冻结的历史旧户只出 `HOTEL_ASSIGNMENT` 行，不出团期住宿行，同订单不会两类并存。
- 孤儿行：某身份已有活跃付款占用但当前已无应付（如计划行被删）时，输出一行 `amount=0`、`alreadyGenerated=true`、`diffAmount` 为负。
- `NODE` / `HOTEL_ASSIGNMENT` 行的新增金额字段为 null，判重口径不变。
- 金额类字段均为数值（BigDecimal），ID 类字段为字符串。

---

### 3. 应付款建议（按供应商跨团） `GET /admin/finance/payments/suggestions/by-supplier`

**VO**: `SupplierSuggestionRespVO{supplierId, rows: List<SupplierSuggestionRowVO>}`

#### 使用场景

按供应商列出跨团欠付明细，勾选后走按供应商合并建单。本次新增团期住宿行（改前恒无）与孤儿行。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| supplierId | Query | Long | 是 | - | 供应商 ID |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| supplierId | Long | 供应商 ID |
| rows[] | SupplierSuggestionRowVO | 继承按订单建议行全部字段（含本次新增的 sourceRefKey 与金额对账字段） |
| rows[].orderId | Long | 来源订单 ID（建单时回传） |
| rows[].teamNo | String | 来源团号 |
| rows[].orderNo | String | 来源订单号 |

#### 请求示例

```http
GET /admin/finance/payments/suggestions/by-supplier?supplierId=88001
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "supplierId": "88001",
    "rows": [
      {
        "orderId": "2100244780104425473",
        "teamNo": "26-3509",
        "orderNo": "HL2026091701",
        "sourceType": "GROUP_BATCH_STAY",
        "sourceId": "2100244786240692225",
        "sourceRefKey": "2100244780104425473:2026-11-18:2029956939232808961:2029956939333472258",
        "amount": 800.00,
        "alreadyGenerated": true,
        "paidAmount": 800.00,
        "refundedAmount": 0,
        "netPaidAmount": 800.00,
        "unpaidAmount": 0,
        "generatedAmount": 800.00,
        "amountChanged": false,
        "diffAmount": 0
      }
    ]
  },
  "success": true
}
```

#### 空数据 / 降级响应

```json
{
  "code": 200,
  "message": "成功",
  "data": { "supplierId": "88001", "rows": [] },
  "success": true
}
```

#### 错误响应

```json
{
  "code": 400,
  "message": "supplierId 不能为空",
  "data": null,
  "success": false
}
```

#### 业务边界

- 候选订单 = 未核单且未取消的订单，**另并入「已取消但仍有活跃团期住宿付款占用」的订单**；已取消订单不再计应付，只呈现已付与占用（孤儿行）。
- 只保留资源反查出的供应商等于入参的行；孤儿行按付款明细上的供应商过滤。
- 核单已完成的订单不进候选（按订单建议入口仍可见）。

---

### 4. 应付款统计（按团） `GET /admin/finance/payments/stats/by-team`

**VO**: `PaymentStatsByTeamReqVO → PageResult<PaymentStatsByTeamRowVO>`

#### 使用场景

按订单（团）看该付、已申请、已付、欠付。本次该付含团期住宿；已申请/已付改为按付款**明细**的订单归属聚合（按供应商合并付款的单能正确分摊到各团）。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| page | Query | Integer | 否 | ≥1，默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 1-100，默认 20 | 每页条数 |
| keyword | Query | String | 否 | - | 团号 / 产品名模糊 |
| status | Query | String | 否 | `OWED` / `OVERPAID` / `PAID` | 状态筛选（页内过滤） |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID |
| teamNo | String | 团号 |
| productName | String | 产品名 |
| customerName | String | 客人 |
| orderNo | String | 订单号 |
| departDate | LocalDate | 出团日期 |
| returnDate | LocalDate | 返团日期 |
| payableAmount | BigDecimal | 该付（**含团期住宿**；已取消孤儿订单为 0） |
| appliedAmount | BigDecimal | 已申请（SUBMITTED/APPROVED 明细合计，草稿不计） |
| paidAmount | BigDecimal | 已付原值（PAID 明细合计，不扣退款、永不减少） |
| owedAmount | BigDecimal | 欠付 = max(该付 − 净已付, 0)，**不再为负** |
| refundedAmount | BigDecimal | **新增**。已确认退款 |
| netPaidAmount | BigDecimal | **新增**。净已付 = paidAmount − refundedAmount |
| overpaidAmount | BigDecimal | **新增**。已付超出 = max(净已付 − 该付, 0) |
| diffAmount | BigDecimal | **新增**。该付 − 净已付（有符号） |
| supplierCount | Integer | 供应商数 |
| status | String | `OWED` 有欠付 / **`OVERPAID` 已付超出待冲正（新增）** / `PAID` 已付清 |

#### 请求示例

```http
GET /admin/finance/payments/stats/by-team?page=1&pageSize=20&keyword=26-3509
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "orderId": "2100244780104425473",
        "teamNo": "26-3509",
        "payableAmount": 800.00,
        "appliedAmount": 0,
        "paidAmount": 800.00,
        "owedAmount": 0,
        "refundedAmount": 0,
        "netPaidAmount": 800.00,
        "overpaidAmount": 0,
        "diffAmount": 0,
        "supplierCount": 1,
        "status": "PAID"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}
```

#### 空数据 / 降级响应

无候选订单返回空列表、`total=0`。供应商反查失败只影响 `supplierCount`，该付照常计入。

```json
{
  "code": 200,
  "message": "成功",
  "data": { "list": [], "total": 0, "page": 1, "pageSize": 20 },
  "success": true
}
```

#### 错误响应

```json
{
  "code": 400,
  "message": "每页条数最大为100",
  "data": null,
  "success": false
}
```

#### 业务边界

- 候选订单同按供应商建议（含已取消孤儿订单并入），在 SQL 层合并，`total` 与分页一致。
- 已付 / 已申请只看付款**明细**，付款主单金额不再参与聚合；按供应商合并付款的单按明细订单分摊到各团。
- 无订单归属的付款（如合并单的出纳差额行）不进按团统计，只进按供应商统计。
- `status` 筛选在页内过滤（与改前一致）。

---

### 5. 应付款统计（按供应商） `GET /admin/finance/payments/stats/by-supplier`

**VO**: `PaymentStatsBySupplierReqVO → PageResult<PaymentStatsBySupplierRowVO>`

#### 使用场景

按供应商看名下各团合计的该付、已申请、已付、欠付。本次该付含团期住宿；已申请/已付改按明细的供应商归属；新增无团归属已付额。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| page | Query | Integer | 否 | ≥1，默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 1-100，默认 20 | 每页条数 |
| keyword | Query | String | 否 | - | 供应商名称模糊 |
| status | Query | String | 否 | `OWED` / `OVERPAID` / `PAID` | 状态筛选 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| supplierId | Long | 供应商 ID |
| supplierName | String | 供应商全称 |
| category | String | 类别标签（多类别以 / 拼接） |
| payableAmount | BigDecimal | 该付（**含团期住宿**） |
| appliedAmount | BigDecimal | 已申请（SUBMITTED/APPROVED 明细合计） |
| paidAmount | BigDecimal | 已付原值（PAID 明细合计） |
| owedAmount | BigDecimal | 欠付 = max(该付 − 净已付, 0) |
| refundedAmount | BigDecimal | **新增**。已确认退款 |
| netPaidAmount | BigDecimal | **新增**。净已付 |
| overpaidAmount | BigDecimal | **新增**。已付超出 |
| diffAmount | BigDecimal | **新增**。该付 − 净已付（有符号） |
| unattributedPaidAmount | BigDecimal | **新增**。已付但明细无订单归属的金额；恒等式：Σ 该供应商各团已付 + 本值 = paidAmount |
| teamCount | Integer | 涉及团数 |
| status | String | `OWED` / **`OVERPAID`（新增）** / `PAID` |

#### 请求示例

```http
GET /admin/finance/payments/stats/by-supplier?page=1&pageSize=20&keyword=呼籁
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "supplierId": "88001",
        "supplierName": "呼籁酒店",
        "category": "住宿",
        "payableAmount": 1600.00,
        "appliedAmount": 0,
        "paidAmount": 1700.00,
        "owedAmount": 0,
        "refundedAmount": 0,
        "netPaidAmount": 1700.00,
        "overpaidAmount": 100.00,
        "diffAmount": -100.00,
        "unattributedPaidAmount": 100.00,
        "teamCount": 2,
        "status": "OVERPAID"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}
```

#### 空数据 / 降级响应

```json
{
  "code": 200,
  "message": "成功",
  "data": { "list": [], "total": 0, "page": 1, "pageSize": 20 },
  "success": true
}
```

#### 错误响应

```json
{
  "code": 400,
  "message": "页码最小为1",
  "data": null,
  "success": false
}
```

#### 业务边界

- 已取消孤儿订单的付款占用按明细供应商建桶后并入，已付不会被丢掉。
- 供应商行为内存聚合后分页，`total` = 筛选后供应商行数。
- `unattributedPaidAmount` 只来自已付款且明细无订单的行（例如按供应商合并单的存量出纳差额回填行）。

---

### 6. 申请付款（单笔） `POST /admin/finance/payments`

**VO**: `PaymentCreateReqVO → PaymentIdRespVO`

#### 使用场景

手工直填或从建议清单单条勾选建付款草稿。本次：团期住宿需回传 `sourceRefKey`；任何单笔创建都会同时写出一条付款明细（带来源写来源明细，手工直填写系统内部的 MANUAL 明细），占用即时生效。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| supplierId | Body | Long | 是 | - | 供应商 ID |
| payeeAccountId | Body | Long | 是 | 供应商生效账户 | 收款账户 |
| amount | Body | BigDecimal | 是 | >0 | 付款金额 |
| paymentType | Body | String | 是 | ≤32，字典标签 | 付款类型 |
| reason | Body | String | 是 | ≤512 | 付款事由 |
| teamNo | Body | String | 否 | ≤32 | 团号 |
| orderId | Body | Long | 条件必填 | 带来源时必填 | 关联订单 |
| resourceId | Body | Long | 否 | - | 关联资源 |
| sourceRefType | Body | String | 否 | `NODE` / `HOTEL_ASSIGNMENT` / `GROUP_BATCH_STAY`；**不可传 MANUAL** | 来源类型，须与 sourceRefId 成对 |
| sourceRefId | Body | Long | 否 | 与 sourceRefType 成对 | 来源主键（团期住宿传建议行 sourceId） |
| sourceRefKey | Body | String | 条件必填 | ≤96；`GROUP_BATCH_STAY` 必填且其中订单须等于 orderId；其余类型必须为空 | **新增**。建议行 sourceRefKey 原样回传 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| paymentId | Long | 新付款单 ID |

#### 请求示例

```json
{
  "supplierId": "88001",
  "payeeAccountId": "90001",
  "amount": 800.00,
  "paymentType": "住宿",
  "reason": "团期 26-3509 11/18 住宿",
  "teamNo": "26-3509",
  "orderId": "2100244780104425473",
  "resourceId": "2029956939232808961",
  "sourceRefType": "GROUP_BATCH_STAY",
  "sourceRefId": "2100244786240692225",
  "sourceRefKey": "2100244780104425473:2026-11-18:2029956939232808961:2029956939333472258"
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": { "paymentId": "2100260000000000001" },
  "success": true
}
```

#### 空数据 / 降级响应

无查询数据。供应商可付款判定 / 账户接口不可用时失败关闭（598803 / 598804），不落任何数据。

#### 错误响应

```json
{
  "code": 598809,
  "message": "该来源配置已生成付款单，请勿重复生成",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598813,
  "message": "未付占用超出当前应付 800.00 元，请先删除 / 驳回 / 撤销批准：FK-202609170003(APPROVED)",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598812,
  "message": "已付金额超出当前应付 400.00 元，需财务冲正",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598808,
  "message": "来源配置引用非法",
  "data": null,
  "success": false
}
```

#### 业务边界

- 团期住宿判据（Σ = 同身份净已付 + 未付占用，A = 当前应付，x = 本次金额）：
  - 净已付 > A → **598812**（message 带超出额）；
  - Σ > A → **598813**（message 列出未付单「单号(状态)」，PENDING 删除 / SUBMITTED 驳回 / APPROVED 撤销批准即可）；
  - Σ = A → **598809**（A 与 Σ 均为 0，即该身份不在应付范围 → 598808）；
  - Σ + x > A → **598813**；
  - 否则成功：Σ 为 0 建首笔，Σ > 0 建差额行。
- `NODE` / `HOTEL_ASSIGNMENT` 仍按来源主键存在性判重（598809），行为不变。
- 598808 触发：来源类型不在取值域或传了 MANUAL；sourceRefType 与 sourceRefId 不成对；带来源未传 orderId；团期住宿 sourceRefKey 缺失、格式错误、日期非法或其中订单 ≠ orderId；非团期住宿传了 sourceRefKey。
- 同一订单的四个建单 / 编辑写口串行执行，抢锁超时返回 `100503 资源被占用,请稍后重试`。

---

### 7. 勾选批量生成（按团） `POST /admin/finance/payments/batch-create`

**VO**: `PaymentBatchCreateReqVO → PaymentBatchCreateRespVO`

#### 使用场景

按订单建议清单勾选多行，按供应商拆单批量生成。本次明细新增 `sourceRefKey`，团期住宿走金额对账。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Body | Long | 是 | - | 来源订单 |
| items | Body | List | 是 | 至少 1 条 | 勾选明细 |
| items[].sourceRefType | Body | String | 是 | `NODE` / `HOTEL_ASSIGNMENT` / `GROUP_BATCH_STAY` | 来源类型 |
| items[].sourceRefId | Body | Long | 是 | - | 来源主键（团期住宿传 sourceId） |
| items[].sourceRefKey | Body | String | 条件必填 | ≤96；团期住宿必填且订单须等于 orderId；其余类型为空 | **新增** |
| items[].supplierId | Body | Long | 是 | - | 供应商（拆单键） |
| items[].amount | Body | BigDecimal | 是 | >0 | 明细金额 |
| items[].paymentType | Body | String | 是 | ≤32 | 付款类型 |
| items[].resourceId | Body | Long | 否 | - | 资源快照 |
| items[].resourceName | Body | String | 否 | ≤128 | 资源名快照 |
| payeeAccountId | Body | Long | 否 | - | 收款账户 |
| reason | Body | String | 是 | ≤512 | 付款事由 |
| submit | Body | Boolean | 是 | - | true 直接提交 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| groups[].paymentId | Long | 付款单 ID |
| groups[].paymentNo | String | 付款单号 |
| groups[].batchNo | String | 批次号 |
| groups[].supplierId | Long | 供应商 ID |
| groups[].supplierName | String | 供应商名 |
| groups[].amount | BigDecimal | 单据金额 |
| groups[].status | String | PENDING / SUBMITTED |

#### 请求示例

```json
{
  "orderId": "2100244780104425473",
  "reason": "团期住宿",
  "submit": false,
  "items": [
    {
      "sourceRefType": "GROUP_BATCH_STAY",
      "sourceRefId": "2100244786240692225",
      "sourceRefKey": "2100244780104425473:2026-11-18:2029956939232808961:2029956939333472258",
      "supplierId": "88001",
      "amount": 400.00,
      "paymentType": "住宿"
    }
  ]
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "groups": [
      {
        "paymentId": "2100260000000000002",
        "paymentNo": "FK-202609170004",
        "batchNo": "BATCH-2100260000000000003",
        "supplierId": "88001",
        "supplierName": "呼籁酒店",
        "amount": 400.00,
        "status": "PENDING"
      }
    ]
  },
  "success": true
}
```

#### 空数据 / 降级响应

无查询数据；任一明细校验失败整批回滚，不落任何单据。

#### 错误响应

```json
{
  "code": 598809,
  "message": "该来源配置已生成付款单，请勿重复生成",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598813,
  "message": "未付占用超出当前应付 1200.00 元，请先删除 / 驳回 / 撤销批准：FK-202609170005(PENDING)",
  "data": null,
  "success": false
}
```

#### 业务边界

- 团期住宿判据同单笔创建；同一请求内重复勾选同一身份 → 598809。
- 598812 / 598808 触发条件同单笔创建。

---

### 8. 按供应商跨团合并建单 `POST /admin/finance/payments/batch-create-by-supplier`

**VO**: `PaymentBatchCreateBySupplierReqVO → PaymentBatchCreateRespVO`

#### 使用场景

按供应商建议勾选跨团明细合并成一张付款单。本次明细新增 `sourceRefKey`，团期住宿走金额对账，多订单按订单号升序串行加锁。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| supplierId | Body | Long | 是 | 全部明细须同属该供应商 | 供应商 |
| items | Body | List | 是 | 至少 1 条 | 勾选明细 |
| items[].orderId | Body | Long | 是 | - | 来源订单 |
| items[].sourceRefType | Body | String | 是 | `NODE` / `HOTEL_ASSIGNMENT` / `GROUP_BATCH_STAY` | 来源类型 |
| items[].sourceRefId | Body | Long | 是 | - | 来源主键 |
| items[].sourceRefKey | Body | String | 条件必填 | ≤96；团期住宿必填且订单须等于 items[].orderId | **新增** |
| items[].supplierId | Body | Long | 是 | 等于入参 supplierId | 供应商 |
| items[].amount | Body | BigDecimal | 是 | >0 | 明细金额 |
| items[].paymentType | Body | String | 是 | ≤32 | 付款类型 |
| payeeAccountId | Body | Long | 否 | - | 收款账户 |
| reason | Body | String | 是 | ≤512 | 付款事由 |
| submit | Body | Boolean | 是 | - | true 直接提交 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| groups[] | GroupResult | 单元素，字段同按团批量 |

#### 请求示例

```json
{
  "supplierId": "88001",
  "reason": "11 月团期住宿合并付款",
  "submit": true,
  "items": [
    {
      "orderId": "2100244780104425473",
      "sourceRefType": "GROUP_BATCH_STAY",
      "sourceRefId": "2100244786240692225",
      "sourceRefKey": "2100244780104425473:2026-11-18:2029956939232808961:2029956939333472258",
      "supplierId": "88001",
      "amount": 800.00,
      "paymentType": "住宿"
    }
  ]
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "groups": [
      {
        "paymentId": "2100260000000000006",
        "paymentNo": "FK-202609170006",
        "batchNo": "BATCH-2100260000000000007",
        "supplierId": "88001",
        "supplierName": "呼籁酒店",
        "amount": 800.00,
        "status": "SUBMITTED"
      }
    ]
  },
  "success": true
}
```

#### 空数据 / 降级响应

无查询数据；校验失败整单回滚。

#### 错误响应

```json
{
  "code": 598811,
  "message": "勾选明细含其他供应商，请按供应商分批勾选",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598809,
  "message": "该来源配置已生成付款单，请勿重复生成",
  "data": null,
  "success": false
}
```

#### 业务边界

- 合并单主单无订单归属，金额按明细订单分摊到按团统计。
- 团期住宿判据同单笔创建（598809 / 598812 / 598813 / 598808）。

---

### 9. 编辑付款草稿 `PUT /admin/finance/payments/{id}`

**VO**: `PaymentUpdateReqVO → Result<Void>`

#### 使用场景

编辑 PENDING 草稿。本次新增：有业务来源的草稿不允许改供应商与订单；明细金额 / 归属跟随主单同步；团期住宿草稿改金额受额度守卫。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| id | Path | Long | 是 | - | 付款单 ID |
| supplierId | Body | Long | 是 | 有来源草稿须等于原值 | 供应商（**请回传原值**） |
| payeeAccountId | Body | Long | 是 | 供应商生效账户 | 收款账户 |
| amount | Body | BigDecimal | 是 | >0；多明细草稿须等于明细合计 | 付款金额 |
| paymentType | Body | String | 是 | ≤32 | 付款类型 |
| reason | Body | String | 是 | ≤512 | 付款事由 |
| teamNo | Body | String | 否 | ≤32 | 团号 |
| orderId | Body | Long | 否 | 有来源草稿须等于原值（原值为空则传空） | 关联订单 |
| resourceId | Body | Long | 否 | - | 关联资源 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| code | Integer | 200 成功 |
| data | Void | 恒为 null |

#### 请求示例

```json
{
  "supplierId": "88001",
  "payeeAccountId": "90001",
  "amount": 300.00,
  "paymentType": "住宿",
  "reason": "差额改为 300",
  "teamNo": "26-3509",
  "orderId": "2100244780104425473"
}
```

#### 响应示例

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

#### 空数据 / 降级响应

无查询数据；任一校验失败主单与明细零变化。

#### 错误响应

```json
{
  "code": 598808,
  "message": "来源配置引用非法",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598805,
  "message": "金额无效（付款金额须大于0）",
  "data": null,
  "success": false
}
```

```json
{
  "code": 598813,
  "message": "未付占用超出当前应付 1200.00 元，请先删除 / 驳回 / 撤销批准：无未付占用，本次申请金额超出可申请差额",
  "data": null,
  "success": false
}
```

#### 业务边界

- 有来源明细（NODE / HOTEL_ASSIGNMENT / GROUP_BATCH_STAY）的草稿：改 supplierId 或 orderId → 598808；单明细同步明细金额；多明细要求 amount 等于明细合计，否则 598805。
- 团期住宿单明细草稿：同身份其他占用 + 新金额 ≤ 当前应付，否则按净已付是否超额报 598812 / 598813。
- 手工草稿（无来源）：可自由改供应商 / 订单 / 团号 / 资源，系统同步其内部 MANUAL 明细的归属，资源名快照置空。
- 仅 PENDING 可编辑，否则 598802。

---

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

| 场景 | 做法 |
|------|------|
| 团期住宿勾选建单 | `sourceRefType=GROUP_BATCH_STAY`、`sourceRefId=行.sourceId`、`sourceRefKey=行.sourceRefKey` 原样回传，单笔还须带 `orderId` |
| 团期住宿应付增加 | 行上 `amountChanged=true` 且 `diffAmount>0` → 以 `diffAmount` 为金额再建一笔（差额行） |
| 团期住宿应付减少、原单未付 | 598813 提示里列出的单：PENDING 删除 / SUBMITTED 驳回 / APPROVED 先调撤销批准再删或改 |
| 团期住宿应付减少、原单已付 | 598812，需财务冲正（后续能力），前端提示即可 |
| 编辑有来源草稿 | supplierId / orderId 回传原值，不提供修改入口 |
| 统计状态筛选 | 新增 `OVERPAID` 选项；`owedAmount` 不会再出现负数 |
| 建议行新字段 | 仅 `GROUP_BATCH_STAY` 行有值，其余类型为 null，前端需判空 |

---

## 五、数据库行为

| 操作 | 表 | 行为 |
|------|-----|------|
| 迁移 V20260917_110 | `fin_payment_item` | 加列 `source_ref_key VARCHAR(96) NULL`、`item_kind VARCHAR(16) NOT NULL DEFAULT 'FULL'`，加索引 `idx_source_ref_key(source_ref_type, source_ref_key)`；幂等 |
| 迁移 V20260917_111 | `fin_payment_item` | 存量回填：无明细的付款单补一条明细（无来源记 MANUAL）；已付单明细合计与出账流水不一致时补一条 `CASHIER_ADJ`；不改付款主单与资金流水，重复执行零新增 |
| 单笔创建 | `fin_payment` + `fin_payment_item` | 同事务写主单 + 1 条明细（来源明细或 MANUAL） |
| 批量创建 | `fin_payment` + `fin_payment_item` | 团期住宿明细写 `source_ref_key`；`item_kind` 为 FULL（首笔）或 ADJUST（差额） |
| 编辑草稿 | `fin_payment` + `fin_payment_item` | 同步唯一明细金额；手工单同步明细归属 |
| 撤销批准 | `fin_payment` + `fin_payment_review_log` | 条件更新 APPROVED→PENDING + 插入 UN_APPROVE 流水 |
| 出纳付款 | `fin_payment_item` | 主单实付与明细合计不一致时追加一条 `CASHIER_ADJ` 明细（新数据正常不会触发） |
| 四个读接口 | 只读 | 新读 `group_batch_room_plan` / `group_batch_room_allocation` / `order_group_batch_house_legacy` |

---

## 六、边界行为

- 未登录 → 401；无权限 → 403。
- 团期计划行结算价为空 → 该行不进应付（记告警日志）。
- 同一身份跨计划行单价不一致 → `unitPrice=null`，`amount` 按各行累加。
- 已核单完成的订单不进三个批量入口的候选，按订单建议仍可见。
- 抢不到同订单写锁 → 100503。
- 撤销批准与出纳付款并发 → 只有一个成功，另一方 598802 或出纳侧状态错误。

---

## 六.5、枚举

### 来源类型（sourceType / sourceRefType）

**所属字段**: PaymentSuggestionRowVO.sourceType、各创建入参 sourceRefType | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| NODE | 行程节点 | 既有 |
| HOTEL_ASSIGNMENT | 配房 | 既有 |
| GROUP_BATCH_STAY | 团期住宿 | **新增**，按业务键金额对账 |
| MANUAL | 手工 | 系统内部明细类型，前端不可传、建议行不出现 |

### 统计状态（status）

**所属字段**: PaymentStatsByTeamRowVO.status、PaymentStatsBySupplierRowVO.status | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| OWED | 有欠付 | owedAmount > 0 |
| OVERPAID | 已付超出 | **新增**，overpaidAmount > 0，待冲正 |
| PAID | 已付清 | 其余 |

---

## 六.6、修改前后对比

| 项 | 改前 | 改后 |
|----|------|------|
| 团期住宿应付 | 按订单建议之外三处恒为 0 | 四处一致 |
| 团期住宿判重 | 按分房行 ID，微调换 ID 可重复申请 | 按业务键金额对账 |
| 统计已付来源 | 付款主单金额，按主单订单归属 | 付款明细金额，按明细订单归属 |
| 统计欠付 | 可为负数 | 不为负，超出部分进 overpaidAmount |
| 统计状态 | OWED / PAID | OWED / OVERPAID / PAID |
| 单笔创建 | 不写明细，不参与防重 | 同事务写明细，立即占用 |
| 编辑草稿 | 可任意改供应商/订单/金额，明细不跟随 | 有来源禁改归属；明细跟随；团期住宿守额度 |
| 已批准单改单 | 无出口（驳回只收 SUBMITTED） | 可撤销批准回到草稿 |
| 错误码 | 无 598812 / 598813 | 新增 |

---

## 六.7、影响评估

- **是否破坏向后兼容**: 部分。读接口只增字段与取值（`GROUP_BATCH_STAY`、`OVERPAID`）；写接口团期住宿必须带 `sourceRefKey`；有来源草稿不能再改供应商 / 订单。
- **前端是否必须同步上线**: 建议同步。不接也不报错，但团期住宿行无法正确建单（缺 sourceRefKey 会 598808），且看不到金额变化提示与撤销批准入口。
- **前端需做**: 建议行展示 `GROUP_BATCH_STAY` 与金额对账字段；建单回传 `sourceRefKey`；统计加 `OVERPAID` 与新金额列；按供应商统计展示 `unattributedPaidAmount`；已批准单加「撤销批准」按钮；598812 / 598813 文案映射；有来源草稿的供应商 / 订单置为只读。

---

## 七、不影响范围

- 行程节点、配房两类来源的判重口径不变。
- 出纳付款接口入参 / 出参不变（仅可能追加内部明细）。
- 付款单分页、详情、提交、批准、驳回、删除接口契约不变。
- C 端与小程序零影响。

---

## 八、测试环境已验证

TEST（`https://api.test.1814.love:9443`，`hl-order-service-v3` = **dev-v3@75d77eefe**，含合并提交 `a37bd669f`；真实网关 + 管理员 token），2026-09-17：

| 场景 | 结果 |
|---|---|
| 迁移 | `V20260917_110` / `V20260917_111` 执行成功；存量无明细单回填 7 条（6 MANUAL + 1 带来源），重复执行第①段零新增 |
| 四入口金额一致 | 纯团期户 2 间 × 400（sign）：按订单建议 / 按供应商建议 / 按团统计均 800，按供应商统计应付 +800；改前按订单建议 0 行 |
| 客户自付与旧户 | 改 cash 后四处同时归 0；旧户只出 `HOTEL_ASSIGNMENT` 行、不双计 |
| 防重 | 单笔建单写出 1 行明细；再以单笔 / `batch-create` / `batch-create-by-supplier` 各建一次均 598809；H10 拆行与核单重绑后仍 598809 |
| 金额变化 | 增额可建差额行（ADJUST）；未付超额 598813（列出单号与状态）；已付超额 598812；草稿编辑超额 598813、改供应商/订单 598808、多明细改金额 598805 |
| 撤销批准 | `PUT /admin/finance/payments/{id}/revoke-approval` → 200、回到 PENDING、出纳队列消失、审核流水出现 `UN_APPROVE`；再撤 598802；与出纳付款并发 12 轮均恰一方成功 |
| 统计口径 | 已付后应付消失 → owed 0 / overpaid 800 / OVERPAID；合并付款按团各归各（800+800），出纳异额合并单 `unattributedPaidAmount=100` 且 800+800+100=1700 |
| 来源锁 | 同订单并发 create 与 update 8 轮均恰一个成功，Σ 不超过应付 |

```
GET /admin/finance/payments/suggestions?orderId=2100421247786545153 → 200，rows[0].sourceType=GROUP_BATCH_STAY，amount=800
POST /admin/finance/payments（同 sourceRefKey 第二次）→ 598809
PUT /admin/finance/payments/{id}/revoke-approval → 200；GET /admin/finance/payments/{id}/review-logs → 含 UN_APPROVE
```

逐条验收记录见工单 #7396 验收评论。

---

## 十、相关文档

- Issue: [#7396](https://git.1814.love:8443/wx/HL/issues/7396)
- PR: [#7866](https://git.1814.love:8443/wx/HL/pulls/7866)
- 核查 SQL: `docs/finance/7396-payment-item-reconcile-check.sql`（HL 仓库）

## 关联 / 联系人

### 链接

- **Issue**: [#7396](https://git.1814.love:8443/wx/HL/issues/7396)
- **PR**: [#7866](https://git.1814.love:8443/wx/HL/pulls/7866)
- **关联**: #7327（团期核单与月报）、#7398（退款 / 冲正，598812 的后续出口）

### 联系人

- **后端负责人**: @jw
- **前端负责人**: @mmg