diff --git a/changelogs-v2/2026-10/09_8807_wx-bill-record加appid-修改接口-管理后台.md b/changelogs-v2/2026-10/09_8807_wx-bill-record加appid-修改接口-管理后台.md new file mode 100644 index 00000000..799ae7dc --- /dev/null +++ b/changelogs-v2/2026-10/09_8807_wx-bill-record加appid-修改接口-管理后台.md @@ -0,0 +1,215 @@ +--- +schema: "hl-changelog/v2" +ticket: "8807" +title: "微信商户对账·逐笔账单记录出参新增 appid（区分小程序/企业微信收款渠道）" +consumer: "admin" +author: "yst" +change_type: "修改接口" +backend_status: "merged" +gateway_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "v2.1" +verified_at: "" +status_note: "后端 PR #8808 已合并 dev-v3（squash 56715ad31e），含 Flyway 迁移 V20261009_001（wx_bill_record 加 appid 列），需部署 order-v3 后新拉取的账单才有值；历史数据与资金账单恒 null" +updated_at: "2026-10-09" +base: "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）： + +```json +{ + "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）**： + +```json +{ + "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 +``` + +```json +{ + "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 +``` + +```json +{ + "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. 注意事项 + +1. **appid 是原始值，不是中文名**：展示渠道名需前端自行按前缀映射或等后期数据字典。 +2. **判空再渲染**：资金账单恒 null，未部署时全量 null，务必可空处理。 +3. **Long id 字符串化**不变：records[].id 仍是 JSON 字符串。 +4. 接口其余 5 个对账端点（summaries / diffs / diffs 详情 / handle / reconcile/run）本次**无任何变化**。 + +## 13. 关联 / 联系人 + +- Issue：https://git.1814.love/wx/HL/issues/8807 +- PR：https://git.1814.love/wx/HL/pulls/8808 +- Commit：https://git.1814.love/wx/HL/commit/56715ad31e +- 后端负责人：腰苏图（yst）