148 行
7.3 KiB
Markdown
148 行
7.3 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8673"
|
||
title: "应付款：列表默认只看欠款 + 付款明细补全量支付状态（#8673）"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "not_required"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "hl-admin(claude-opus-4-8)"
|
||
frontend_ref: "1be140db4ac9fde579b06e934078c0675db1b6b8"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-10-01"
|
||
status_note: "应付款两处调整。①【破坏性】按团号/按供应商列表默认空 status 从「全部」改为「只看欠付 OWED」：已付清/金额归零的团和供应商默认不再返回，需显式传 status=PAID 或 ALL 回看；status 过滤从内存过滤下沉 SQL，修复了分页 total 与返回行数不一致的 bug。②付款建议明细出参新增 payableAmount/paidAmount/appliedAmount/payStatus 四件套（additive），入参新增 includePaid（默认 false）；includePaid=true 时已付清行也返回（payStatus=PAID 置灰），点付款可看到「哪些已付、哪些未付」全景。payStatus 判据=无可申请余额即 PAID（覆盖真已付清 + applied 全额占用）。前端已交付：统计列表筛选项对齐 OWED/PAID/ALL、默认显式钉 OWED 只看欠款（回看切 PAID/ALL）；两个付款面板与应付款详情均 includePaid=true 全景，PAID 行置灰禁勾显「已付清」、PARTIAL 显「部分已付」。"
|
||
updated_at: "2026-10-01"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# finance：应付款列表默认只看欠款 + 付款明细补全量支付状态（管理后台）
|
||
|
||
> ⚠️ **破坏性变更**：`GET /admin/finance/payments/stats/by-team` 和 `/by-supplier` 不传 `status` 时，从「返回全部（含已付清）」改为「只返回有欠付（OWED）的行」。已付清的团/供应商默认从列表消失，需显式传 `status=PAID` 或 `status=ALL` 回看。
|
||
> ✅ **additive**：付款建议明细出参新增 4 字段、入参新增 `includePaid`，旧前端不传不受影响。
|
||
|
||
## 1. 接口背景
|
||
|
||
财务「应付款」按团号/按供应商两个列表，原把头表所有行（含已付清、金额归零）都返回，干扰财务看「还欠谁的」；且 status 过滤是后端内存过滤，只滤当前页导致分页 total 不准。点付款时的明细只给「剩余可申请余额」，看不到每个资源「该付多少、付了多少、还差多少」，已付清的资源行直接被滤掉。
|
||
|
||
本次：列表默认只看欠款 + 修 total 不准；付款明细补全量支付状态。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 变更 | 类型 |
|
||
|---|---|---|---|
|
||
| 1 | GET /payments/stats/by-team | 默认空 status=只看 OWED；status 新增 ALL；过滤下沉修 total | ⚠️ 行为变更 |
|
||
| 2 | GET /payments/stats/by-supplier | 同上 | ⚠️ 行为变更 |
|
||
| 3 | GET /payments/suggestions | 出参加 4 字段；入参加 includePaid | ✅ additive |
|
||
| 4 | GET /payments/suggestions/by-supplier | 同上 | ✅ additive |
|
||
|
||
## 3. 接口详情
|
||
|
||
统一前缀 `GET /admin/finance/payments/**`（业务调用**不带**服务前缀，网关按 `/admin/finance/**` 路由）。
|
||
|
||
## 4. 入参
|
||
|
||
### 4.1 列表（by-team / by-supplier）
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| keyword | 团号/产品名/客人名（by-team）或供应商名（by-supplier）模糊 |
|
||
| status | ⚠️ `OWED` 有欠付 / `PAID` 已付款 / `ALL` 全部；**空=默认只看 OWED（新）** |
|
||
|
||
### 4.2 付款建议（suggestions / by-supplier）
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| orderId / supplierId | 必填 |
|
||
| includePaid | 新增，默认 `false`；`true` 时返回含已付清行的全量明细 |
|
||
|
||
## 5. 出参
|
||
|
||
### 5.1 列表行（不变）
|
||
by-team：`teamNo, productName, customerName, orderNos, departDate, returnDate, payableAmount, appliedAmount, paidAmount, owedAmount, supplierCount, status`
|
||
by-supplier：`supplierId, supplierName, category, payableAmount, appliedAmount, paidAmount, owedAmount, teamCount, status`
|
||
|
||
### 5.2 付款建议行（PaymentSuggestionRowVO 新增 4 字段）
|
||
原字段 + 新增：
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| payableAmount | 该行该付总额 |
|
||
| paidAmount | 已付金额 |
|
||
| appliedAmount | 已申请占用金额（在途付款单） |
|
||
| payStatus | `UNPAID` 未付 / `PARTIAL` 部分已付 / `PAID` 已付清（无可申请余额） |
|
||
|
||
## 6. 枚举/数据字典
|
||
|
||
### status（列表筛选 + 行出参）
|
||
| 值 | 含义 |
|
||
|---|---|
|
||
| OWED | 有欠付（欠付 > 0） |
|
||
| PAID | 已付款（欠付 <= 0，含金额归零） |
|
||
| ALL | 全部（仅筛选用，回看已付清） |
|
||
|
||
### payStatus（付款建议行出参，新增）
|
||
| 值 | 含义 |
|
||
|---|---|
|
||
| UNPAID | 未付（已付=0，仍可申请） |
|
||
| PARTIAL | 部分已付（已付>0 且仍有可申请余额） |
|
||
| PAID | 无可申请余额（含真已付清 + applied 全额占用，置灰不可再勾选） |
|
||
|
||
## 7. 错误码
|
||
无新增。
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 典型：默认只看欠款
|
||
```http
|
||
GET /admin/finance/payments/stats/by-team
|
||
→ 只返回有欠付的团，已付清团不出现；total 与返回行数一致
|
||
```
|
||
|
||
### 8.2 回看已付清
|
||
```http
|
||
GET /admin/finance/payments/stats/by-team?status=ALL
|
||
→ 返回全部（含已付清团，status=PAID）
|
||
```
|
||
|
||
### 8.3 点付款看全量（含已付清行置灰）
|
||
```http
|
||
GET /admin/finance/payments/suggestions?orderId=66001&includePaid=true
|
||
→ rows 含已付清行：
|
||
{"resourceName":"呼和塔拉草原","payableAmount":240.00,"paidAmount":240.00,"appliedAmount":0,"payStatus":"PAID",...}
|
||
{"resourceName":"阿尔山门票","payableAmount":500.00,"paidAmount":100.00,"appliedAmount":0,"payStatus":"PARTIAL",...}
|
||
{"resourceName":"白桦林","payableAmount":300.00,"paidAmount":0,"appliedAmount":0,"payStatus":"UNPAID",...}
|
||
```
|
||
|
||
## 9. 业务边界
|
||
|
||
- 列表默认 OWED 视图下，金额归零（行全取消）的团因 owed<=0 归 PAID，自然隐藏。
|
||
- includePaid=true 返回的已付清行（payStatus=PAID）**不可再发起付款申请**，前端置灰禁勾选。
|
||
- 列表 status 过滤已下沉 SQL，分页 total 与返回行严格一致。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
| 项 | 修改前 | 修改后 |
|
||
|---|---|---|
|
||
| 列表空 status | 返回全部（含已付清/归零） | 只返回有欠付 OWED |
|
||
| status 过滤 | 内存过滤，total 不准 | SQL 下沉，total 准确 |
|
||
| status 取值 | OWED/PAID | OWED/PAID/ALL |
|
||
| 付款明细行金额 | 只有余额 amount | 加 payable/paid/applied/payStatus |
|
||
| 已付清资源行 | 被滤掉看不到 | includePaid=true 可见（置灰） |
|
||
|
||
## 11. 影响评估/回滚
|
||
|
||
- **列表默认变更**：老前端不传 status 时已付清行消失，需前端确认是否接受/补 status 控件。
|
||
- **付款明细**：additive，旧前端不传 includePaid、不读新字段则零影响。
|
||
- 回滚：恢复 selectPage 旧签名 + Service 默认口径即可。
|
||
|
||
## 12. 注意事项
|
||
|
||
- ⚠️ 列表默认只看欠款是**破坏性变更**，前端若依赖「默认看到已付清历史」需改为显式传 status=ALL。
|
||
- payStatus=PAID 的语义是「无可申请余额」（含 applied 全额占用），非严格「已付清」，前端置灰即可。
|
||
- 供应商维度中 supplierId= null 的降级行计入团头但不计入任何供应商，两视图金额可能对不上（历史口径，本次未改）。
|
||
|
||
## 13. 关联/联系人
|
||
- Issue：https://git.1814.love/wx/HL/issues/8673
|
||
- PR：https://git.1814.love/wx/HL/pulls/8674
|
||
- merge commit：a8cf8e13109ea713c28e8be527d0a27d0f2e63fb
|
||
- 后端负责人：腰苏图
|