wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
441a01d6eac66443a187ca5cdd813e7f24056b41
hl-api-changelog/changelogs-v2/2026-10/01_8690_微信商户对账-新增接口-管理后台.md
T
Mimingguang e3fe98b1f2
changelog-filename-gate / validate (push) Failing after 1s
详情
chore(changelog): #8690 回写前端 implemented(微信商户对账页,8175316c)
2026-10-02 14:49:36 +08:00

19 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 8690 微信商户对账：账单下载解析比对落库+差异处理+手动补跑（6 端点） admin yst(GIT) 新增接口 merged not_required implemented mmg 8175316c88d4f555538d7e65d3744102bccfee90 v2.1 2026-10-02 前端交付(2026-10-02,用户拍板已部署):新建 finance/wx-bill 页(hiddenRoute 先行,sys_menu 未下挂;汇总台账 dateRange 拆 billDateFrom/To/差异笔数>0 飘红/手动补跑 billDate 必填+锁占用 data=null 按契约文案提示)+BillRecordsDrawer 逐笔快照+BillDiffsDrawer 差异处理(先拉详情防 582404/结论仅 CONFIRMED·IGNORED/只改标记不调账)+api/finance/wx-bill.js(分页 page 非 pageNo 已钉),spec 8 例全绿,提交 8175316c。 2026-10-02 dev-v3

【新增接口·管理后台】微信商户对账（6 端点）(#8690)

PR: #8703 | 服务: hl-order-service-v3（8086） | 更新时间: 2026-10-02

1. 接口背景

微信支付此前只有「支付回调」这一条正向链路：微信回调成功 → 本地记成功流水。一旦回调丢失、金额异常或微信侧状态变化，本地无任何反向核对手段，资金敞口不可见。

本次建设微信商户对账能力：每日 T-1 自动拉取微信商户交易账单（tradebill）+ 资金账单（fundflowbill），下载解析后与本地支付流水逐笔比对落库，差异打标并通过 FINANCE 站内信告警，不自动调账（差异一律人工核实处理）。

本 changelog 覆盖管理后台消费的 6 个新端点（对账执行本体由定时任务触发，不在本接口面）。菜单归属：财务管理 → 资金账户 → 微信商户对账。单视图「对账汇总」台账，逐笔明细 / 差异走抽屉下钻（records / diffs 接口）。

2. 变更清单

# 接口 方法 路径 变更类型 说明
1 对账汇总分页列表 GET /v3/admin/payment/wx-bill/summaries 新增接口 主视图台账，每日每商户每账单类型一行
2 逐笔原始账单记录 GET /v3/admin/payment/wx-bill/records 新增接口 汇总行「明细」抽屉数据源
3 差异分页列表 GET /v3/admin/payment/wx-bill/diffs 新增接口 「看差异」抽屉数据源
4 差异详情 GET /v3/admin/payment/wx-bill/diffs/{diffId} 新增接口 单条差异完整信息（含处理记录）
5 处理差异 POST /v3/admin/payment/wx-bill/diffs/{diffId}/handle 新增接口 财务人工确认/忽略 + 备注，不自动调账
6 手动触发对账补跑 POST /v3/admin/payment/wx-bill/reconcile/run 新增接口 运维补账入口，与定时任务同逻辑同锁

3. 接口详情

3.1 对账汇总分页列表 GET /v3/admin/payment/wx-bill/summaries

  • 使用场景：主视图台账。每行 = 一个商户 + 一个账单日期 + 一种账单类型的对账结论（总笔数/总金额/对平/差异/结果）。
  • 认证：需管理后台 JWT。
  • 幂等性：只读。
  • 限流：无。

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

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

3.3 差异分页列表 GET /v3/admin/payment/wx-bill/diffs

  • 使用场景：「看差异」抽屉 / 差异工作台。支持按日期范围、差异类型、处理状态、商户号、账单类型过滤。
  • 认证：需管理后台 JWT。
  • 幂等性：只读。
  • 限流：无。

3.4 差异详情 GET /v3/admin/payment/wx-bill/diffs/{diffId}

  • 使用场景：差异行点开的详情（本地金额 vs 账单金额、差异说明、处理人/处理时间/备注）。
  • 认证：需管理后台 JWT。
  • 幂等性：只读。
  • 限流：无。

3.5 处理差异 POST /v3/admin/payment/wx-bill/diffs/{diffId}/handle

  • 使用场景：财务人工核实差异后标记「已确认」或「已忽略」并留备注。只做标记，不自动调账（调账动作走财务调账域，不在本接口）。
  • 认证：需管理后台 JWT。
  • 幂等性：否。仅 PENDING 状态可处理；重复处理报 582404（已处理不可重复处理），天然防重。
  • 限流：无。

3.6 手动触发对账补跑 POST /v3/admin/payment/wx-bill/reconcile/run

  • 使用场景：运维补账——定时任务失败 / 账单迟到后，手动对指定账单日期补跑一次。与 internal 定时任务同逻辑、同一把分布式锁（key=wx-bill-reconcile:{billDate}）。
  • 认证：需管理后台 JWT。
  • 幂等性：是（业务侧）。重跑零重复：原始记录按键集只插缺失、汇总查到即覆盖、差异按指纹去重。但同一账单日期对账执行中时（锁被占用）不重复执行，返回提示文案且 data=null。
  • 限流：无。

4. 接口入参

4.1 对账汇总分页列表（Query）

字段 类型 必填 说明 校验规则
page Integer 否 页码，默认 1 最小 1
pageSize Integer 否 每页条数，默认 20 1-100
billDateFrom Date 否 账单日期起（yyyy-MM-dd） —
billDateTo Date 否 账单日期止（yyyy-MM-dd） —
mchId String 否 微信商户号（精确匹配） —
billType String 否 账单类型 仅 TRADE / FUND_FLOW，非法值报参数校验错误
reconcileStatus String 否 对账结果 仅 OK / HAS_DIFF / FETCH_FAILED，非法值报参数校验错误

4.2 逐笔原始账单记录（Query）

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

4.3 差异分页列表（Query）

字段 类型 必填 说明 校验规则
page Integer 否 页码，默认 1 最小 1
pageSize Integer 否 每页条数，默认 20 1-100
billDateFrom Date 否 账单日期起（yyyy-MM-dd） —
billDateTo Date 否 账单日期止（yyyy-MM-dd） —
mchId String 否 微信商户号（精确匹配） —
billType String 否 账单类型 仅 TRADE / FUND_FLOW
diffType String 否 差异类型 仅 LOCAL_MISSING / BILL_MISSING / AMOUNT_MISMATCH / STATE_MISMATCH / FETCH_FAILED
handleStatus String 否 处理状态 仅 PENDING / CONFIRMED / IGNORED

4.4 差异详情（Path）

字段 类型 必填 说明
diffId Long 是 差异ID（path）

4.5 处理差异（Path + Body）

Path：

字段 类型 必填 说明
diffId Long 是 差异ID（path）

请求体：

字段 类型 必填 说明 校验规则
handleStatus String 是 处理状态 仅 CONFIRMED（已确认）/ IGNORED（已忽略），不能传 PENDING
remark String 否 处理备注 最长 255 字符

4.6 手动触发对账补跑（Body）

字段 类型 必填 说明 校验规则
billDate Date 是 账单日期（yyyy-MM-dd） 建议传 T-1 或更早（微信当日账单 T+1 上午才生成）
mchId String 否 微信商户号 可空 = 全部已配置商户
billType String 否 账单类型 仅 TRADE / FUND_FLOW；可空 = 交易+资金都跑

5. 出参（响应）

统一 Result 包装；分页为 PageResult（records / total / page / pageSize）。

⚠️ Long 主键字符串化：id（汇总/记录/差异）与 localTransactionId 均以 JSON 字符串返回（防 JS 精度丢失），前端按字符串处理，回传 path 参数时原样带回即可。handledBy 为普通数字。

5.1 对账汇总行 WxBillSummaryRespVO

字段 类型 说明
id String(Long) 汇总ID
mchId String 微信商户号
billDate Date 账单日期（yyyy-MM-dd）
billType String 账单类型：TRADE / FUND_FLOW
totalCount Integer 账单总笔数
totalAmount BigDecimal 账单总金额（元）
matchedCount Integer 对平笔数
diffCount Integer 差异笔数
reconcileStatus String 对账结果：OK / HAS_DIFF / FETCH_FAILED
createTime DateTime 创建时间（yyyy-MM-dd HH:mm:ss）

5.2 账单原始记录行 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 手续费（元）

5.3 差异行 / 差异详情 WxBillDiffRespVO

字段 类型 说明
id String(Long) 差异ID
mchId String 微信商户号
billDate Date 账单日期
diffType String 差异类型（见 6.2）
billType String 账单类型：TRADE / FUND_FLOW
outTradeNo String 商户单号
wxTransactionId String 微信支付单号
localAmount BigDecimal 本地金额（元），本地缺失类差异可空
billAmount BigDecimal 账单金额（元），账单缺失类差异可空
localTransactionId String(Long) 本地支付流水ID，本地缺失类差异可空
diffDetail String 差异说明（人读文案）
handleStatus String 处理状态：PENDING / CONFIRMED / IGNORED
handleRemark String 处理备注，未处理为空
handledBy Long(数字) 处理人ID，未处理为空
handledAt DateTime 处理时间，未处理为空
createTime DateTime 创建时间

处理差异接口的响应体同为 WxBillDiffRespVO（处理后的最新状态）。

5.4 手动触发对账执行结果 WxBillReconcileRunRespVO

字段 类型 说明
billDate Date 对账账单日期
merchantCount Integer 参与对账的商户数
diffCount Integer 本次对账差异总笔数（含历史未清）
fetchFailedCount Integer 账单拉取失败的商户类型数

⚠️ 锁占用特例：当日该账单日期对账正在执行中时，本接口返回 code=0、msg="当日对账正在执行中，请稍后重试"、data=null——属正常跳过，非错误，前端按提示文案展示即可。

6. 枚举 / 数据字典

6.1 billType（账单类型）

值 中文 说明
TRADE 交易账单 微信 tradebill，逐笔交易（含支付/退款）
FUND_FLOW 资金账单 微信 fundflowbill，逐笔资金收支（含手续费/结算）

6.2 diffType（差异类型）

值 中文 说明
LOCAL_MISSING 本地缺失 账单有该单（SUCCESS）但本地无成功流水——回调丢失，高危，优先处理
BILL_MISSING 账单缺失 本地有成功流水但账单无该单——可疑（本地虚单/未结算）
AMOUNT_MISMATCH 金额不符 两边都有但金额不一致
STATE_MISMATCH 状态不符 账单状态非 SUCCESS（REFUND/CLOSED）但本地仍 SUCCESS
FETCH_FAILED 拉取失败 该商户该类型账单下载/申请失败，根本没对上，需重跑

6.3 handleStatus（处理状态）

值 中文 说明
PENDING 待处理 默认状态，仅此状态可调用处理接口
CONFIRMED 已确认 人工已核实确认
IGNORED 已忽略 人工核实后忽略（如已线下解决）

6.4 reconcileStatus（对账结果）

值 中文 说明
OK 对平 全部对平，0 差异
HAS_DIFF 有差异 对出差异，需人工处理
FETCH_FAILED 拉取失败 账单没拉到，根本没对上，需重跑

7. 错误码

code 含义 触发场景
400 参数校验失败 枚举字段传非法值 / 必填缺失 / remark 超 255 字符（HTTP 200 + Result.error(400)，msg 为具体校验文案）
582400 微信账单申请失败 微信侧拒绝 / 无当日账单（对账执行期，管理端查询不直接触发）
582401 微信账单下载失败 账单下载票/文件拉取失败（对账执行期）
582402 微信账单解析失败 账单文件解析失败（对账执行期）
582403 对账差异记录不存在 差异详情 / 处理差异时 diffId 查无此记录
582404 该差异已处理，不可重复处理 处理差异时该差异已非 PENDING
582405 找不到商户配置 手动补跑指定的 mchId 无微信支付商户配置
582406 对账汇总记录不存在 汇总记录查无（预留）

8. 示例

8.1 典型成功（对账汇总列表 + 差异处理）

请求：

GET /v3/admin/payment/wx-bill/summaries?billDateFrom=2026-09-01&billDateTo=2026-09-30&reconcileStatus=HAS_DIFF&page=1&pageSize=20
Authorization: Bearer <token>

响应：

{
  "code": 0,
  "data": {
    "records": [
      {
        "id": "1890000000000000001",
        "mchId": "1246532201",
        "billDate": "2026-09-30",
        "billType": "TRADE",
        "totalCount": 25,
        "totalAmount": 12800.00,
        "matchedCount": 24,
        "diffCount": 1,
        "reconcileStatus": "HAS_DIFF",
        "createTime": "2026-10-01 08:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "msg": ""
}

处理差异请求：

POST /v3/admin/payment/wx-bill/diffs/1890000000000000009/handle
Authorization: Bearer <token>
Content-Type: application/json

{
  "handleStatus": "CONFIRMED",
  "remark": "已核实回调丢失，手动补登记"
}

处理差异响应：

{
  "code": 0,
  "data": {
    "id": "1890000000000000009",
    "mchId": "1246532201",
    "billDate": "2026-09-30",
    "diffType": "LOCAL_MISSING",
    "billType": "TRADE",
    "outTradeNo": "HL20260930120000001234",
    "wxTransactionId": "4200001234202609301234567890",
    "localAmount": null,
    "billAmount": 500.00,
    "localTransactionId": null,
    "diffDetail": "账单SUCCESS本地无成功流水，疑似支付回调丢失",
    "handleStatus": "CONFIRMED",
    "handleRemark": "已核实回调丢失，手动补登记",
    "handledBy": 1,
    "handledAt": "2026-10-01 10:00:00",
    "createTime": "2026-10-01 08:30:00"
  },
  "msg": ""
}

8.2 边界（差异列表空结果 + 手动补跑锁占用）

空差异页请求（对平的日期段）：

GET /v3/admin/payment/wx-bill/diffs?billDateFrom=2026-09-01&billDateTo=2026-09-30&handleStatus=PENDING&page=1&pageSize=20

响应（空页为正常结果，非错误）：

{
  "code": 0,
  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
  "msg": ""
}

手动补跑（当日对账执行中）请求：

POST /v3/admin/payment/wx-bill/reconcile/run
Content-Type: application/json

{ "billDate": "2026-09-30" }

响应（锁被占用，data=null，按 msg 提示展示）：

{
  "code": 0,
  "data": null,
  "msg": "当日对账正在执行中，请稍后重试"
}

8.3 业务失败（重复处理差异，582404）

请求（对一条已 CONFIRMED 的差异再次处理）：

POST /v3/admin/payment/wx-bill/diffs/1890000000000000009/handle
Content-Type: application/json

{ "handleStatus": "IGNORED", "remark": "重复操作" }

响应：

{ "code": 582404, "msg": "该差异已处理，不可重复处理", "data": null }

9. 业务边界

  • 适用：查询/处理已由对账任务落库的数据——每日 T-1 定时任务（早晨）跑完后，对应账单日期的汇总/记录/差异才可见；手动补跑成功后立即可见。
  • 不适用：
    • 当日（T 日）账单——微信当日账单 T+1 上午才生成，对当日日期查/跑只会得到 FETCH_FAILED 或空；
    • 期望接口实时向微信拉账单展示——records 展示的是落库快照，不是实时微信数据。
  • 特殊：
    • LOCAL_MISSING（本地缺失）= 回调丢失高危差异，建议财务优先处理；
    • 差异处理只改标记不改账——确认/忽略不会触发任何资金或订单侧动作；
    • FETCH_FAILED 类汇总/差异的正确处理动作是重跑（手动补跑接口），不是人工确认。

10. 修改前后对比

新增接口，无修改前版本。本组 6 端点全部为首次交付，无旧路径、无字段变更。

11. 影响评估 / 回滚

  • 是否破坏向后兼容：否（纯新增端点 + 纯新增表，无既有接口/字段改动）。
  • 前端是否必须同步上线：否（不接入不影响任何既有功能；接入后提供「微信商户对账」视图）。
  • 回滚方式：revert PR #8703 即可下线 6 端点；三张新表（wx_bill_record / wx_bill_diff / wx_bill_summary）为独立新表，不回滚也不影响既有功能。

12. 注意事项

  • Long 字符串化：id / localTransactionId 为 JSON 字符串（见 §5 开头），表格 key、路由参数、处理接口 path 回传时不要 Number() 转换。
  • 处理差异非幂等但防重：重复处理报 582404，前端提交后可禁按钮防连点，收到 582404 时刷新该行为宜。
  • 手动补跑是重操作：逐商户下载微信账单 + 全量比对，锁 TTL 30 分钟；触发后建议稍后刷新汇总列表看结果，不要连续点击（锁占用会返回 data=null 提示）。
  • 枚举值严格校验：Query 中的 billType / reconcileStatus / diffType / handleStatus 传非法值会被参数校验拦截（HTTP 200 + code 400），下拉框请只渲染 §6 列出的值。
  • 出参中可空字段（如资金账单的 wxTransactionId、交易账单的 fundFlowId、未处理差异的 handleRemark / handledBy / handledAt）返回 null，展示需做空值兜底。

13. 关联 / 联系人

在新工单中引用 查看 Git Blame 复制永久链接