wx/hl-api-changelog

派生 0

文件

T

Mimingguang a10d36f13b

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): #8070 frontmatter 回写 verified(注释级交付,ref 7fa22462)

2026-09-22 10:01:50 +08:00

8.8 KiB

原始文件 Blame 文件历史

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	8070	应付款建议清单/统计页切流读推送台账，出参补 applied/paid/owed 口径字段	admin	yst(GIT)	修改接口	deployed	not_required	verified	mmg	7fa22462cb04658b36bfa2370c9e8673bcf289ab	v2.1	2026-09-22	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 项全绿)。	2026-09-22	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：

{
  "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 建议清单（含不可申请资格）

{
  "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，落台账待绑定区，不阻断主流程：

{ "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

8.8 KiB 原始文件 Blame 文件历史 Unescape Escape