---
schema: "hl-changelog/v2"
ticket: "8070"
title: "应付款建议清单/统计页切流读推送台账，出参补 applied/paid/owed 口径字段"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "7fa22462cb04658b36bfa2370c9e8673bcf289ab"
target_release: "v2.1"
verified_at: "2026-09-22"
status_note: "backend_status: deployed - hl-order-service-v3 已部署测试服（dev-v3，含 finance 同进程），Epic #8070 三轮 E2E PASS + 最终验收已交付（2026-09-21 取证）; gateway_status: not_required - 零网关改动，/admin/finance/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，后端不代填。 前端核验(2026-09-22): #7396/#7398 交付时已消费 appliedAmount/owedAmount 并处理 eligible 禁勾+eligibleReason 直显,台账口径切换纯服务端零行为增量;唯一冲突为旧注释「欠付后端保证非负」,已订正为 owed 可为负=多付(PayableStatsList.vue 头注+payable.js 三态注释),owedAmount 全消费点 money() 纯展示无钳制;ref=hl-admin 7fa22462(docs 注释订正,checkpoint 全量 13 项全绿)。"
updated_at: "2026-09-22"
base: "dev-v3"
---

# 财务：应付款建议清单/统计页切流读推送台账（Epic #8070 PR-5）

> 应付款「申请建议清单」与「按供应商/按团统计」接口的数据源由实时扫订单切换为读应付款推送台账（`fin_payable_line/team/supplier` 三表），出参补充申请中/已付/欠款口径字段，并前置台账锁定闸。

## ① 接口背景

应付款域此前「建议清单」「统计页」靠实时聚合订单/配房/行程节点数据计算，口径分散、与台账不一致。Epic #8070 建立应付款推送台账星型模型（明细行 `fin_payable_line` + 团头 `fin_payable_team` + 供应商头 `fin_payable_supplier`），订单确认/配房确认即推送台账。PR-5 把**读侧**（申请建议清单 + 统计页）切流到台账，让申请、审批、统计共用同一套 applied（申请中）/paid（已付）/owed（欠款）口径，并加 `isLocked` 前置闸（审批中行锁定禁重复申请）。

## ② 变更清单

| 类型 | 接口 | 变更 |
|---|---|---|
| 修改 | `GET /admin/finance/payments/suggestion` 申请建议清单 | 数据源切台账；行出参补口径/资格字段 |
| 修改 | `GET /admin/finance/payments/stats/by-supplier` 按供应商统计 | 数据源切台账头表；出参补 applied/owed |
| 修改 | `GET /admin/finance/payments/stats/by-team` 按团统计 | 数据源切台账头表；出参补 applied/owed |

> 申请/审批写入侧（建单占用 applied、付讫转 paid、驳回释放）同步切台账，属内部实现，接口签名不变。

## ③ 接口详情

### 3.1 申请建议清单

```
GET /admin/finance/payments/suggestion?...
```

返回可申请的应付款明细行（来自台账 NORMAL 行），每行带是否可申请资格与原因，已被申请占用或审批锁定的行不可重复申请。

### 3.2 按供应商统计 / 按团统计

```
GET /admin/finance/payments/stats/by-supplier?...
GET /admin/finance/payments/stats/by-team?...
```

返回台账头表聚合的应付/申请中/已付/欠款四口径，与明细行求和一致。

## ④ 入参

入参字段与旧版一致（分页 + 既有筛选条件），无新增/无删除。

## ⑤ 出参

### 5.1 建议清单行 `PaymentSuggestionRowVO`（关键字段）

| 字段 | 类型 | 说明 |
|---|---|---|
| `sourceType` | string | 来源类型（配房/行程节点等） |
| `sourceId` | Long(string) | 来源单据 ID |
| `resourceId` / `resourceName` | Long / string | 资源 ID / 名称 |
| `qty` / `unitPrice` / `amount` | number | 数量 / 单价 / 应付金额 |
| `payWay` | string | 付款方式 |
| `paymentType` | string | 付款类型（fin_payment_type 字典标签） |
| `supplierId` / `supplierName` | Long / string | 供应商 ID / 名称（降级行可空） |
| `payeeAccountId` | Long(string) | 供应商生效收款账户 |
| `eligible` | boolean | 是否可申请（false 时看 `eligibleReason`） |
| `eligibleReason` | string | 不可申请原因（已占用/审批锁定/无价等） |
| `alreadyGenerated` | boolean | 是否已生成付款单 |

### 5.2 按供应商统计行 `PaymentStatsBySupplierRowVO`

| 字段 | 类型 | 说明 |
|---|---|---|
| `supplierId` / `supplierName` | Long / string | 供应商 ID / 名称 |
| `category` | string | 类别（fin_payment_type 字典标签） |
| `payableAmount` | number | 应付总额 |
| `appliedAmount` | number | **申请中金额（新增/真值化）** |
| `paidAmount` | number | 已付金额 |
| `owedAmount` | number | **欠款 = 应付 − 已付（可为负=多付）** |
| `teamCount` | int | 涉及团数 |
| `status` | string | 状态 |

### 5.3 按团统计行 `PaymentStatsByTeamRowVO`

| 字段 | 类型 | 说明 |
|---|---|---|
| `teamNo` | string | 团号 |
| `productName` / `customerName` / `orderNos` | string | 产品 / 客户 / 订单号 |
| `departDate` / `returnDate` | string(date) | 出团 / 回团日期 |
| `payableAmount` | number | 应付总额 |
| `appliedAmount` | number | **申请中金额（新增/真值化）** |
| `paidAmount` | number | 已付金额 |
| `owedAmount` | number | **欠款 = 应付 − 已付** |
| `supplierCount` | int | 涉及供应商数 |
| `status` | string | 状态 |

## ⑥ 枚举/数据字典

- `paymentType` / `category` 走 `fin_payment_type` 字典标签：住宿 / 门票·游玩 / 餐食 / 车辆 / 导游 / 摄影 / 保险 / 其他支出 / 退款 / 其他应付。
- 台账行 `line_type`：`NORMAL` 正常 / `CLOSED` 红冲（建议清单只出 NORMAL）。
- 台账行 `close_status` / `recover_status` 为内部治理字段，不外透出参。

## ⑦ 错误码

本批为读侧切流，无新增对外错误码。台账推送/占用相关错误码（5996xx 段）见既有应付款推送台账 changelog。

## ⑧ 示例

### 8.1 按供应商统计

请求 `GET /admin/finance/payments/stats/by-supplier?pageNo=1&pageSize=10`：

```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "supplierId": "2096854417461403650",
        "supplierName": "呼伦贝尔羊和远方牧业有限公司",
        "category": "住宿",
        "payableAmount": 3000.00,
        "appliedAmount": 800.00,
        "paidAmount": 1200.00,
        "owedAmount": 1800.00,
        "teamCount": 3,
        "status": "NORMAL"
      }
    ],
    "total": 1
  }
}
```

### 8.2 建议清单（含不可申请资格）

```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "sourceType": "GROUP_BATCH_STAY",
        "sourceId": "2100484891404648449",
        "resourceName": "呼和诺尔湖景房",
        "amount": 800.00,
        "paymentType": "住宿",
        "supplierId": "2096854417461403650",
        "supplierName": "呼伦贝尔羊和远方牧业有限公司",
        "eligible": false,
        "eligibleReason": "已存在审批中付款单，行已锁定",
        "alreadyGenerated": true
      }
    ]
  }
}
```

### 8.3 边界：降级行（供应商未绑定）

配资源时供应商未绑定/反查失败的行，`supplierId`/`supplierName` 为 null，落台账待绑定区，不阻断主流程：

```json
{ "sourceId": "...", "supplierId": null, "supplierName": null, "eligible": false, "eligibleReason": "供应商待绑定" }
```

## ⑨ 业务边界

- **applied 占用口径**：建单（PENDING）即占用，付讫转 paid，驳回/删除释放；防止同一应付行被重复申请。
- **isLocked 前置闸**：存在审批中付款单的台账行锁定，建议清单 `eligible=false`。
- **无价节点不推送**：结算价 NULL 或 0 的资源不推送台账（不炸订单确认）。
- **owed 可为负**：多付/台账外付款时 owed 为负，属正确表达。

## ⑩ 修改前后对比

| 项 | 修改前 | 修改后 |
|---|---|---|
| 数据源 | 实时扫订单/配房/节点 | 读推送台账三表 |
| 申请中金额 | 无独立口径 | `appliedAmount` 真值化 |
| 欠款 | 各页自算、口径不一 | `owedAmount = payable − paid` 统一 |
| 重复申请 | 可能重复 | isLocked 闸拦截 |

## ⑪ 影响评估 / 回滚

- **出参新增字段**（appliedAmount/owedAmount 等）为增量，旧前端不读取不受影响；但**数值口径变化**（切台账后与旧实时聚合可能有差），前端需以台账口径为准。
- **回滚**：读侧切回实时聚合需回退代码；台账数据保留。

## ⑫ 注意事项

- 台账为「订单确认/配房确认」时推送，历史未推送的老订单不在台账内（开发阶段老数据可清，生产上线另起迁移）。
- 供应商降级行（supplierId null）不累计供应商头表。

## ⑬ 关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/8070
- PR：#8071 / #8075 / #8079 / #8081 / #8083 / #8092（本批切流）/ #8097 / #8109
- 负责人：yst