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

2026-10-09 11:01:06 +08:00
@@ -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）