7.3 KiB
7.3 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 8673 | 应付款：列表默认只看欠款 + 付款明细补全量支付状态（#8673） | admin | yst(GIT) | 修改接口 | deployed | not_required | implemented | hl-admin(claude-opus-4-8) | 1be140db4ac9fde579b06e934078c0675db1b6b8 | v2.1 | 2026-10-01 | 应付款两处调整。①【破坏性】按团号/按供应商列表默认空 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 显「部分已付」。 | 2026-10-01 | 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 典型：默认只看欠款
GET /admin/finance/payments/stats/by-team
→ 只返回有欠付的团，已付清团不出现；total 与返回行数一致
8.2 回看已付清
GET /admin/finance/payments/stats/by-team?status=ALL
→ 返回全部（含已付清团，status=PAID）
8.3 点付款看全量（含已付清行置灰）
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：wx/HL#8673
- PR：wx/HL#8674
- merge commit：a8cf8e13109ea713c28e8be527d0a27d0f2e63fb
- 后端负责人：腰苏图