---
schema: "hl-changelog/v2"
ticket: "7398"
title: "应付款已付超额冲正（供应商退回）：申请 / 分次确认到账 / 撤销剩余额度 / 分页"
consumer: "admin"
author: "jw(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "0fa6574f9cceb2f41f5e4208424ce64190da2014"
target_release: ""
verified_at: "2026-09-17"
status_note: "后端交付（hl-finance，随 hl-order-service-v3 部署）。新增 4 个冲正接口与错误码 598814/598815/598816/598817/598818；付款明细新增 REVERSAL 负明细语义；资金流水新增 bizType=PAYMENT_REVERSAL。网关前缀 /admin/finance/** 已存在，无需新路由。前端需新增冲正申请与出纳确认到账两个界面。[mmg 2026-09-17 交付] 原型无冲正 UI，以后端契约为准嵌入应付款模块：①payable.js 冲正节 4 端点+四态字典（分页路径无 /page 后缀，598814-818 等拦截器透 message）；②可冲正额=reversibleAmount(netPaidAmount−amount 2dp，非 −diffAmount，unpaidAmount 不参与，≥0.01 才显入口）；③ReversalApplyModal 申请弹窗（sourceRefKey 原样回传、amount 预填可冲正额、reason 必填，文案明示确认到账后生效）；④PaymentReversalPanel 冲正管理（orderId/supplierId/status 筛选分页，PENDING/PARTIAL 出确认到账/撤销，确认六字段含 ACTIVE 公司户下拉+默认今天+凭证号必填）；⑤三处申请入口（ap-detail 构成明细+两建单面板超额行），统计页头部「冲正管理」进新视图返回强制刷新。api spec +5 例+组件 spec 11 例，scoped checkpoint 13 项全绿。"
updated_at: "2026-09-17"
base: "dev-v3"
---

# finance: 应付款已付超额冲正（供应商退回）

> **存放目录**: changelogs-v2/{YYYY-MM}/（管理后台，二期 finance）
>
> **服务**: hl-order-service-v3（hl-finance 模块同进程）
> **PR**: #7889
> **Issue**: #7398
> **日期**: 2026-09-17
> **影响范围**: 应付款团期住宿付款身份的「已付超出当前应付」处置（申请冲正 → 出纳登记到账 → 统计与建议自动对平）

---

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

1. **598812 有出口了**：团期住宿某付款身份「已付 > 当前应付」时（统计 `status=OVERPAID`、建议行 `netPaidAmount > amount`），财务可发起**冲正申请**，额度 ≤ `netPaidAmount − amount`。
2. **申请不改任何金额**：申请后统计、建议、再建单的结果都与申请前一样；**只有出纳确认到账后**才生效。
3. **确认到账可分次**：酒店分几次退就登记几次，每次一条入账流水 + 一条负明细；剩下不再退的额度可以**撤销**，已登记的部分保留。
4. **确认到账不看当前应付**：钱已经到了就必须能记进来，哪怕房又加回来、应付回升；应付回升产生的新欠付照常在建议里以差额行出现。
5. **统计读法不变**：`paidAmount`（原始已付，不减少）/ `refundedAmount`（已确认退款）/ `netPaidAmount`（净已付）三字段 #7396 已有，冲正确认后自动变化。
6. **凭证号必填且在同一申请内唯一**：重复提交同一次确认返回 598802，账户只入账一次。

---

## 一、背景

#7396 让团期住宿按付款身份 `{orderId}:{stayDate}:{hotelId}:{roomTypeId}` 做金额对账，但「钱已付出、应付降到已付之下」只能报 598812，没有处理终态。本次补上「供应商退回」形态：申请 = 批准冲正额度，出纳每登记一次真实到账，就记一条资金流水（入账）和一条挂在原付款单下的负明细，原付款单不做任何修改。「抵扣下次付款」形态依赖预付域，本次不做。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 申请冲正 | POST | `/admin/finance/payment-reversals` | 新增 | 对已付超额的团期住宿付款身份申请退回额度，落 PENDING |
| 2 | 确认本次到账 | PUT | `/admin/finance/payment-reversals/{id}/confirm` | 新增 | 出纳登记一次真实到账（可分次），记入账流水 + 负明细 |
| 3 | 撤销剩余额度 | PUT | `/admin/finance/payment-reversals/{id}/cancel` | 新增 | 作废未到账的剩余额度，已确认部分保留 |
| 4 | 冲正申请分页 | GET | `/admin/finance/payment-reversals` | 新增 | 按订单 / 供应商 / 状态过滤 |

---

## 三、接口详情

### 1. 申请冲正 `POST /admin/finance/payment-reversals`

**VO**: `PaymentReversalCreateReqVO → Result<PaymentReversalIdRespVO>`

#### 使用场景

建议行或按团统计显示某团期住宿付款身份已付超出当前应付（`status=OVERPAID` / `netPaidAmount > amount`），财务与酒店协商退回后发起申请。`sourceRefKey` 取建议行的 `sourceRefKey`，`orderId` 取建议行 / 统计行的 `orderId`。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| sourceRefType | Body | String | 是 | 本期仅 `GROUP_BATCH_STAY` | 来源类型 |
| sourceRefKey | Body | String | 是 | ≤96；格式 `{orderId}:{yyyy-MM-dd}:{hotelId}:{roomTypeId}`，其中订单须等于 orderId | 付款身份业务键 |
| orderId | Body | Long | 是 | - | 来源订单 ID |
| amount | Body | BigDecimal | 是 | ≥0.01，两位小数，≤ 净已付 − 当前应付 | 申请冲正额度 |
| reason | Body | String | 是 | ≤512，非空白 | 冲正原因 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| data.id | String | 新冲正申请 ID（雪花 ID，字符串输出） |

#### 请求示例

```json
{
  "sourceRefType": "GROUP_BATCH_STAY",
  "sourceRefKey": "2100482262209380353:2027-01-05:2029926133256929282:2029944767501012994",
  "orderId": 2100482262209380353,
  "amount": 800.00,
  "reason": "该户退团，酒店同意退回已付房费"
}
```

#### 响应示例

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

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

无查询数据。申请成功后不产生资金流水、不写付款明细；统计、建议、再建单的结果与申请前逐字段相同（再建单仍 598812）。

#### 错误响应

```json
{
  "code": 598814,
  "message": "冲正金额超出可冲正额 0.00 元（已付超出当前应付的部分）",
  "data": null,
  "success": false
}
```

| code | 触发 |
|------|------|
| 400 | 必填缺失 / amount ≤ 0 / 长度超限 |
| 598808 | sourceRefType 不是 GROUP_BATCH_STAY，或 sourceRefKey 格式非法 / 与 orderId 不一致 |
| 598814 | amount > 净已付 − 当前应付（未超额时可冲正额为 0；已全额退回后再申请同样命中） |
| 598815 | 同一付款身份已有未完结申请（PENDING / PARTIAL） |
| 100503 | 同订单付款写操作正在进行，稍后重试 |

#### 业务边界

- 只处理「已付 > 当前应付」；「未付占用超额」仍走 #7396 的删除 / 驳回 / 撤销批准（598813）。
- 冲正挂在该付款身份下最近一次付讫的原付款单上；原付款单金额、状态、付款时间不变。
- 同一付款身份同时只允许一张未完结申请。
- 与付款单创建 / 编辑共用同一把订单锁，并发时串行执行。

---

### 2. 确认本次到账 `PUT /admin/finance/payment-reversals/{id}/confirm`

**VO**: `PaymentReversalConfirmReqVO → Result<Boolean>`

#### 使用场景

出纳收到酒店退款回单后登记。酒店分几次退就调几次，每次填本次实际到账金额与入账的公司账户。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| id | Path | Long | 是 | - | 冲正申请 ID |
| amount | Body | BigDecimal | 是 | ≥0.01，两位小数 | 本次实际到账金额 |
| fundAccountId | Body | Long | 是 | 须为启用中的公司资金账户 | 入账账户（不会用原付款账户兜底） |
| receivedDate | Body | String | 是 | `yyyy-MM-dd` | 到账日期（写入流水备注） |
| voucherNo | Body | String | 是 | ≤64，非空白；同一申请内唯一 | 银行回单 / 凭证号 |
| voucherUrl | Body | String | 否 | ≤500 | 凭证影像 URL（写入流水） |
| remark | Body | String | 否 | ≤200 | 备注（写入流水备注） |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| data | Boolean | 恒 true |

#### 请求示例

```json
{
  "amount": 400.00,
  "fundAccountId": 2100482405474148354,
  "receivedDate": "2026-09-17",
  "voucherNo": "HD-20260917-001",
  "voucherUrl": "https://oss.example.com/voucher/001.png",
  "remark": "酒店财务转账"
}
```

#### 响应示例

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

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

无查询数据。成功后：申请 `confirmedAmount` 累加、状态变 PARTIAL（未满额）或 CONFIRMED（满额）；资金流水新增一条 `direction=IN`、`bizType=PAYMENT_REVERSAL`、`bizId=冲正申请ID`；付款明细新增一条 `itemKind=REVERSAL`、金额为负的明细。

#### 错误响应

```json
{
  "code": 598817,
  "message": "确认到账金额超出冲正申请剩余额度 0.00 元",
  "data": null,
  "success": false
}
```

```json
{
  "code": 595006,
  "message": "账户已停用",
  "data": null,
  "success": false
}
```

| code | 触发 |
|------|------|
| 400 | 必填缺失（含 fundAccountId / voucherNo / receivedDate）/ amount ≤ 0 |
| 598818 | 冲正申请不存在 |
| 598802 | 申请已撤销；或同一申请下该凭证号已登记（重复提交）；或并发下状态已被推进 |
| 598817 | 累计到账超过申请额度（含已全额确认后再确认） |
| 598816 | 本次到账超过该付款身份当前净已付 |
| 595001 / 595006 | 入账账户不存在 / 已停用 |
| 100503 | 同订单付款写操作正在进行，稍后重试 |

#### 业务边界

- **不复核当前应付**：房务把房加回、应付回升后仍可登记到账；由此产生的欠付在建议里 `diffAmount > 0`，按 #7396 规则再建单。
- 任一校验失败整体回滚：不入账、不写明细、不累加额度。
- 两次不同凭证号的到账并发提交会先后成功；同凭证号只会成功一次。
- 入账账户余额按本次金额增加，原付款账户不变。

---

### 3. 撤销剩余额度 `PUT /admin/finance/payment-reversals/{id}/cancel`

**VO**: `PaymentReversalCancelReqVO → Result<Boolean>`

#### 使用场景

酒店明确不再退款（或应付已恢复、钱没有退）时，作废申请剩余未到账的额度。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| id | Path | Long | 是 | - | 冲正申请 ID |
| reason | Body | String | 是 | ≤512，非空白 | 撤销原因 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| data | Boolean | 恒 true |

#### 请求示例

```json
{
  "reason": "酒店余款不再退回"
}
```

#### 响应示例

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

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

无查询数据。成功后状态变 CANCELLED，`confirmedAmount` 不变，已登记的流水与负明细不变。

#### 错误响应

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

| code | 触发 |
|------|------|
| 400 | reason 缺失或空白 |
| 598818 | 冲正申请不存在 |
| 598802 | 申请已 CONFIRMED 或已 CANCELLED；或与确认并发时确认先完成 |

#### 业务边界

- 仅 PENDING / PARTIAL 可撤销；已全额确认的申请不能撤销（已发生的资金事实只能另行红冲，本期不提供）。
- 与确认并发时只有一个成功。

---

### 4. 冲正申请分页 `GET /admin/finance/payment-reversals`

**VO**: `PaymentReversalPageReqVO → Result<PageResult<PaymentReversalRespVO>>`

#### 使用场景

冲正申请列表 / 出纳待确认列表（`status=PENDING` 或 `PARTIAL`）。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Query | Long | 否 | - | 订单 ID |
| supplierId | Query | Long | 否 | - | 供应商 ID |
| status | Query | String | 否 | PENDING / PARTIAL / CONFIRMED / CANCELLED | 状态 |
| page | Query | Integer | 否 | ≥1，默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 1~100，默认 20 | 每页条数 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| records[].reversalId | String | 冲正申请 ID |
| records[].reversalNo | String | 冲正单号（RF-yyyyMMdd####） |
| records[].sourceRefType | String | 来源类型 |
| records[].sourceRefKey | String | 付款身份业务键 |
| records[].orderId | String | 订单 ID |
| records[].teamNo | String | 团号快照 |
| records[].supplierId | String | 供应商 ID |
| records[].supplierName | String | 供应商全称快照 |
| records[].paymentId | String | 被冲的原付款单 ID |
| records[].amount | BigDecimal | 申请额度 |
| records[].confirmedAmount | BigDecimal | 累计已确认到账 |
| records[].remainingAmount | BigDecimal | 剩余可确认额度（CANCELLED / CONFIRMED 为 0） |
| records[].status | String | PENDING / PARTIAL / CONFIRMED / CANCELLED |
| records[].reason | String | 冲正原因 |
| records[].appliedBy | String | 申请人 ID |
| records[].appliedByName | String | 申请人姓名 |
| records[].cancelReason | String | 撤销原因 |
| records[].cancelledBy | String | 撤销人 ID |
| records[].cancelledAt | String | 撤销时间 |
| records[].createTime | String | 申请时间 |
| total / page / pageSize | Long / Integer / Integer | 分页信息 |

#### 请求示例

```http
GET /admin/finance/payment-reversals?orderId=2100482262209380353&status=CONFIRMED&page=1&pageSize=20
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "reversalId": "2100483176424972289",
        "reversalNo": "RF-202609170002",
        "sourceRefType": "GROUP_BATCH_STAY",
        "sourceRefKey": "2100482262209380353:2027-01-05:2029926133256929282:2029944767501012994",
        "orderId": "2100482262209380353",
        "supplierId": "2096854417461403650",
        "paymentId": "2100482264935604226",
        "amount": 800.00,
        "confirmedAmount": 800.00,
        "remainingAmount": 0,
        "status": "CONFIRMED",
        "reason": "#7398 验收冲正"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}
```

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

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

#### 错误响应

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

#### 业务边界

- 按申请 ID 倒序（最新在前）。
- 单次到账明细（入账账户、金额、时间、凭证、经办人）在资金流水查询中按 `bizType=PAYMENT_REVERSAL`、`bizId=reversalId` 查看。

---

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

- 申请的 `sourceRefKey` / `orderId` 必须原样取自建议行或统计行，不要前端拼接。
- 可冲正额 = 建议行 `netPaidAmount − amount`（≤0 时不应展示申请入口）。
- 确认到账时 `amount` 填**本次**实际到账金额，不是申请额；分次到账逐次调用，每次换一个凭证号。
- 所有 ID 按字符串处理，避免精度丢失。
- 统计与建议无需新接口：确认后 `refundedAmount` 增加、`netPaidAmount` 减少，`paidAmount` 不变。

---

## 五、数据库行为

| 表 | 动作 | 说明 |
|---|---|---|
| `fin_payment_reversal` | 新建表（V20260917_114） | 冲正申请：amount 额度、confirmed_amount 累计到账、status 四态；申请 INSERT，确认 / 撤销按旧值条件更新 |
| `fin_payment_item` | 新增列 `reversal_id` + 索引 `idx_reversal`（V20260917_114） | 确认时 INSERT 一条 `item_kind=REVERSAL`、金额为负、`payment_id`=原付款单、`reversal_id`=申请、`remark`=凭证号 |
| `fin_fund_flow` | INSERT | 确认时一条 `direction=IN`、`biz_type=PAYMENT_REVERSAL`、`biz_id`=申请 ID |
| `fin_fund_account` | UPDATE balance | 入账账户余额 + 本次金额 |
| `fin_payment` | 不变 | 原付款单任何字段不改 |

---

## 六、边界行为

- 申请后、到账前：金额口径完全不变，再建单仍 598812。
- 到账后应付回升：确认照常成功，建议 `diffAmount` 出现正差额，按 #7396 建单。
- 部分到账后剩余不退：调撤销；统计中已退部分保留。
- 合并付款单（一张付多户）：冲正只作用于申请的那一户，负明细 `orderId` 为该户，挂在合并付款单下；另一户统计不变。
- 已全额确认后不可撤销、不可再确认（598802 / 598817）。

## 六.5、枚举

### 冲正申请状态（status）

| 值 | 含义 |
|---|---|
| PENDING | 待到账 |
| PARTIAL | 部分到账 |
| CONFIRMED | 全额到账 |
| CANCELLED | 已撤销剩余额度 |

### 新增取值

| 字段 | 新值 | 含义 |
|---|---|---|
| 付款明细 `itemKind` | REVERSAL | 冲正负明细（金额为负） |
| 资金流水 `bizType` | PAYMENT_REVERSAL | 应付款冲正入账 |

---

## 七、不影响范围

- 付款单创建 / 编辑 / 提交 / 批准 / 驳回 / 撤销批准 / 出纳付款的入参出参与判据不变。
- 建议与统计接口结构不变（相关字段 #7396 已提供）。
- 非团期住宿来源（行程节点 / 配房 / 手工）不支持冲正。
- 前端：新增「冲正申请」（统计 / 建议超额行入口）与「出纳确认到账」两个界面，由 mmg 承接。

---

## 八、测试环境已验证

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

| 场景 | 结果 |
|---|---|
| 迁移 | `V20260917_114` 执行成功；`fin_payment_item.reversal_id` 与 `idx_reversal` 存在；新表不含账户 / 到账日 / 凭证列 |
| 真实取消户闭环 | 已付 800、订单已取消应付 0：申请前后建单均 598812；申请 800 → 确认 800 → 入账流水 800、负明细 −800、Σ=0、统计 PAID、建议 overpaid 归零；原付款单逐字段不变 |
| 申请不生效 | 申请后付款明细零新增，建议 / 统计 / 再建单结果与申请前逐字段相同 |
| 入账账户 | 入 Y：Y +800、原付款账户 X 不变；fundAccountId 为空 → 400；停用账户 → 595006 且零流水零明细；重复提交同凭证 → 598802、余额只加一次 |
| 上界 | 超额申请 598814；重复申请 598815；全额确认后再申请 598814、再确认 598817；净已付不足时确认 598816（零流水零明细）；已确认 400 再确认 400 → 200 |
| 分次到账 | 800 分两次 400：PARTIAL → CONFIRMED，两条流水两条负明细，统计 800/400/400 → 800/800/0 |
| 应付回升 | 申请后未到账、应付恢复 → 撤销 200、零流水、再建单 598809；已到账、应付恢复 → 确认 200、统计 OWED 欠付 800、差额单 800 → 200；部分到账叠加回升同样可确认，剩余可撤销 |
| 退后再建 | 退完后应付变 400 → 四入口差额 400 → 建单提交后统计欠付 400、在途 400、OWED → 再建 598809 → 付款后 PAID |
| 合并付款 | 1600 合并单只退户 1：户 1 800/800/0、户 2 800/0/800；负明细挂 1600 主单、订单为户 1；供应商统计已退 +800 |
| 并发 | 同申请并发两次确认 400 均成功、流水恰 2；三次并发恰 2 成功 1 次 598817；并发确认与申请 → 申请 598815；撤销与确认并发 8 轮均恰一方成功（PENDING / PARTIAL 两个分支、CANCELLED / CONFIRMED 两个终态都出现），撤销后已确认部分保留 |

```
POST /admin/finance/payment-reversals → 200 {"id":"2100483176424972289"}
PUT /admin/finance/payment-reversals/2100483176424972289/confirm → 200 true
PUT /admin/finance/payment-reversals/2100483176424972289/confirm（同凭证）→ 598802
PUT /admin/finance/payment-reversals/2100483176424972289/cancel → 598802
```

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

---

## 十、相关文档

- Issue: [#7398](https://git.1814.love:8443/wx/HL/issues/7398)
- PR: [#7889](https://git.1814.love:8443/wx/HL/pulls/7889)
- 前置: [#7396](https://git.1814.love:8443/wx/HL/issues/7396)（付款身份与金额对账）

## 关联 / 联系人

### 链接

- **Issue**: [#7398](https://git.1814.love:8443/wx/HL/issues/7398)
- **PR**: [#7889](https://git.1814.love:8443/wx/HL/pulls/7889)
- **关联**: #7396（598812 的来源）、#7325（团期单户退团 / 取消）

### 联系人

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