wx/hl-api-changelog

派生 0

文件

T

yaosutu 1029581523

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

详情

docs(changelog): 8807 微信商户对账逐笔账单记录出参新增 appid 字段（PR #8808）

2026-10-09 11:01:46 +08:00

8.2 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	8807	微信商户对账·逐笔账单记录出参新增 appid（区分小程序/企业微信收款渠道）	admin	yst	修改接口	merged	not_required	pending			v2.1		后端 PR #8808 已合并 dev-v3（squash 56715ad31e），含 Flyway 迁移 V20261009_001（wx_bill_record 加 appid 列），需部署 order-v3 后新拉取的账单才有值；历史数据与资金账单恒 null	2026-10-09	dev-v3

微信商户对账 · 逐笔账单记录出参新增 appid 字段

面向：管理后台前端（hl-admin）日期：2026-10-09 ｜后端：order-v3，PR 已合并 dev-v3 原始接口契约（同仓）：changelogs-v2/2026-10/01_8690_微信商户对账-新增接口-管理后台.md（本篇只写增量变化，字段表自包含）

1. 接口背景

微信商户对账（#8690 上线的 6 端点之一）的「逐笔原始账单记录」接口，出参每条记录新增 appid 字段，用于区分收款渠道——同一商户号下，钱可能是从小程序（wx...）付的，也可能是企业微信（ww...）收的。此前前端无法从账单记录判断来源渠道，差异排查和渠道维度统计只能靠人工认商户单号。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	逐笔原始账单记录	GET	/v3/admin/payment/wx-bill/records	修改接口	出参 `records[]` 新增字段 `appid`（String，可空）。入参 / 其余出参 / 枚举均无变化

3. 接口详情

3.1 逐笔原始账单记录 GET /v3/admin/payment/wx-bill/records

使用场景：对账汇总行「明细」抽屉，看该商户该日微信账单原始逐笔（交易账单/资金账单统一出参，billType 区分）。
认证：需管理后台 JWT。
幂等性：只读。
限流：无。

4. 接口入参（无变化）

字段	类型	必填	说明	校验规则
page	Integer	否	页码，默认 1	最小 1
pageSize	Integer	否	每页条数，默认 20	1-100
billDate	Date	否	账单日期（yyyy-MM-dd，单日）	—
mchId	String	否	微信商户号（精确匹配）	—
billType	String	否	账单类型	仅 TRADE / FUND_FLOW

5. 出参字段

统一 Result 包装；分页为 PageResult（records / total / page / pageSize）。Long 主键 id 以 JSON 字符串返回。

5.1 账单原始记录行 WxBillRecordRespVO（变化后）

字段	类型	说明
id	String(Long)	记录ID
mchId	String	微信商户号
billDate	Date	账单日期
billType	String	账单类型：TRADE / FUND_FLOW
wxTransactionId	String	微信支付单号（交易账单有，资金账单可空）
outTradeNo	String	商户单号（关联本地支付流水）
fundFlowId	String	资金流水单号（资金账单有，交易账单可空）
tradeTime	DateTime	交易/记账时间
tradeType	String	交易类型/业务类型（如 JSAPI）
tradeState	String	交易状态/收支方向（如 SUCCESS）
amount	BigDecimal	交易金额（元）
payerAmount	BigDecimal	用户实付（元）
feeAmount	BigDecimal	手续费（元）
appid	String，可空	新增：微信公众账号ID。交易账单（billType=TRADE）有值——小程序为 `wx` 前缀（如 `wx4711a76772deff36`）、企业微信为 `ww` 前缀（如 `ww0123456789abcdef`）；资金账单（FUND_FLOW）恒 null

6. 枚举 / 数据字典

本次无枚举/字典变化。appid 返回的是微信原始值字符串，不做翻译。
渠道中文名（小程序 / 企业微信）后期会以数据字典补充；本次前端如需展示渠道名，可自行按前缀映射（wx 开头 = 小程序，ww 开头 = 企业微信），或暂展示原始值等字典。

7. 错误码

本次无新增错误码。沿用 #8690 既有：参数校验错误（billType 非法值等）走统一参数校验响应。

8. 示例

8.1 典型成功（交易账单，小程序收款）

请求：

GET /v3/admin/payment/wx-bill/records?billDate=2026-10-08&billType=TRADE&page=1&pageSize=20

响应（节选一条 records）：

{
  "code": 0,
  "data": {
    "records": [
      {
        "id": "1976123456789012345",
        "mchId": "1600000001",
        "billDate": "2026-10-08",
        "billType": "TRADE",
        "wxTransactionId": "4200001234202610081234567890",
        "outTradeNo": "HL20261008120000123456",
        "fundFlowId": null,
        "tradeTime": "2026-10-08 12:00:01",
        "tradeType": "JSAPI",
        "tradeState": "SUCCESS",
        "amount": 1280.00,
        "payerAmount": 1280.00,
        "feeAmount": 7.68,
        "appid": "wx4711a76772deff36"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

8.2 边界情况

8.2a 企业微信收款（ww 前缀 appid）：

{
  "billType": "TRADE",
  "tradeType": "JSAPI",
  "tradeState": "SUCCESS",
  "amount": 500.00,
  "appid": "ww0123456789abcdef"
}

8.2b 资金账单（appid 恒 null）：

GET /v3/admin/payment/wx-bill/records?billDate=2026-10-08&billType=FUND_FLOW

{
  "billType": "FUND_FLOW",
  "wxTransactionId": null,
  "fundFlowId": "110000000120261008000001",
  "tradeState": "IN",
  "amount": 1280.00,
  "appid": null
}

8.3 业务失败（billType 非法值）

GET /v3/admin/payment/wx-bill/records?billType=FOO

{
  "code": 400001,
  "msg": "请求参数不合法",
  "data": null
}

（错误码数值以线上实际为准，属统一参数校验段位；非法 billType 只允许 TRADE / FUND_FLOW）

9. 业务边界

适用：汇总行「明细」抽屉展示逐笔账单时，可按 appid 前缀区分/标注收款渠道。
仅交易账单有值：appid 只在 billType=TRADE 的记录上有值；资金账单（FUND_FLOW）没有公众账号维度，恒为 null，前端不要对资金账单渲染渠道。
部署时序：本字段依赖 Flyway 迁移 V20261009_001（wx_bill_record 表加 appid 列）。order-v3 未部署到本版本前，前端拿到的响应里该字段为 null（或缺失）；部署后新拉取的账单才有值，已落库的历史账单不回填。
null 兼容：前端渲染时 appid 一律按可空处理。

10. 修改前后对比

10.1 字段级

字段	原来	现在
records[].appid	不存在	新增，String 可空；TRADE 有值（wx/ww 前缀），FUND_FLOW 恒 null

10.2 行为级

项	原来	现在
入参	—	无变化
其余出参字段	—	无变化
渠道识别	无法从账单记录判断收款渠道	可按 appid 前缀（wx=小程序 / ww=企业微信）区分

11. 影响评估 / 回滚

破坏性：无。纯出参字段新增，不改名、不删字段、不改类型、不改枚举。前端不接此字段可完全无感。
前端同步上线：不要求。前端按自己节奏接入即可；未接期间字段躺平不影响现有功能。
回滚方案：如需回滚，order-v3 回退到 #8808 之前的版本即可——appid 字段消失，已接前端按可空读取自动退化为原行为，无需前端配合回滚。DB 列保留无害（Flyway 不做列回退）。

12. 注意事项

appid 是原始值，不是中文名：展示渠道名需前端自行按前缀映射或等后期数据字典。
判空再渲染：资金账单恒 null，未部署时全量 null，务必可空处理。
Long id 字符串化不变：records[].id 仍是 JSON 字符串。
接口其余 5 个对账端点（summaries / diffs / diffs 详情 / handle / reconcile/run）本次无任何变化。

13. 关联 / 联系人

Issue：wx/HL#8807
PR：wx/HL#8808
Commit：https://git.1814.love/wx/HL/commit/56715ad31e
后端负责人：腰苏图（yst）

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