207 行
8.8 KiB
Markdown
207 行
8.8 KiB
Markdown
---
|
||
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
|