---
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）