微信支付对账自动化 · 实操运行版

概述

微信支付对账自动化 · 付费 Skill

功能描述

本技能提供付费的微信支付对账自动化服务。每次调用需支付少量费用（发布时设定，演示模式免费），支付完成后自动执行对账并返回结构化报告：

• 自动对账：拉取微信交易/资金账单 → 解析 → 交易对账（按 out_trade_no 匹配金额/状态）+ 资金对账（实际入账 vs 应收）→ 异常标记（金额差异/单边账/状态异常/资金差异）→ 报表。
• 退款自动化：发起退款 → 状态联动 → 记录列表。
• 会员自动解绑：退款成功触发解约、到期自动扫描清理、微信侧解约回调同步。

付费前置检查

调用本 Skill 前，检查当前 Agent 是否已安装 weixinpay 插件（extension）：

• 已安装：可继续提供付费服务。
• 未安装：向用户提示「当前 Agent 暂不支持微信支付付费能力」，终止流程。

部署说明：本 Skill 的付费入口是一个 HTTP 商户服务（scripts/pay_server.py，Flask）。付费服务已部署在 https://weixinduizhang.shucejishu.cn，Agent 向 https://weixinduizhang.shucejishu.cn/api/resource 发起请求即触发付费流程。

工作流程

无需填写任何微信支付配置表单：本 Skill 默认使用内置演示数据生成对账报告，不需要你填写 MCHID / APPID / 证书序列号 / APIv3Key / 商户私钥 / 回调地址。这些字段属于「终端商户接入 SaaS 后台」场景；本 Skill 作为付费调用入口，只需服务端 .env 中配置作者/商户自己的微信支付商户号（用于向 Skill 调用者收费）。

第一步：请求资源

向商户服务发起 POST 请求（首次请求，无支付头）。最简请求体只需一个 query 字段：

curl -X POST https://weixinduizhang.shucejishu.cn/api/resource 
  -H "Content-Type: application/json" 
  -d '{"query": "reconcile"}'

也支持空对象 {}（默认走 demo 模式、对账日期为昨天）。请求体字段：

生产环境如需做真实账单对账，建议由你的 SaaS 后台保存终端商户凭证，再调用本服务时透传；本 Skill 本身不强制要求用户填写这些凭证。

第二步：处理 402 响应（支付触发标识，由插件完成）

如果收到 HTTP 402 响应，weixinpay 插件会拦截并完成支付流程，无需手动调用支付接口。

402 响应中通过 Header 和 Body 返回支付信息：

• Header WeixinPay-Required：支付凭证码（插件用于完成支付）
• Header X-Out-Trade-No：商户订单号

支付过程由 weixinpay 插件处理，Skill 无需关心支付细节。

第三步：支付成功后获取资源（⚠️ 支付后重试，必须执行）

支付成功后，必须重新发起请求获取付费内容。重试规则：

• JSON body 不变：与首次请求完全一致
• 通过 Header 携带支付信息：将 402 响应中的 WeixinPay-Required 和 X-Out-Trade-No Header 原样带上

POST https://weixinduizhang.shucejishu.cn/api/resource
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

{"query": "reconcile"}

注意：body 与第一步完全一致，不要修改 body 中的任何字段。支付信息通过 Header 传递（订单号传递）。

成功响应（HTTP 200）示例：

{
  "code": "SUCCESS",
  "out_trade_no": "WX402_20260723...",
  "transaction_id": "420000...",
  "already_fulfilled": false,
  "content": {
    "_summary": {"matched": 25, "amount_diff": 1, "single_side": 1, "status_anomaly": 1, "fund_diff": 1, "alerts": 2},
    "matched": [...], "amount_diff": [...], "single_side": [...], "status_anomaly": [...], "fund_diff": [...], "alerts": [...]
  }
}

第四步：处理退款 / 异常响应（退款 / 异常处理）

计费点（发布时设置）

• 每次「完整对账执行」计 1 次付费额度；演示验证（mode=demo）免费。
• 具体价格与计费模式（按次 / 包月）在 SkillHub 发布表单填写。

部署：商户服务（pay_server.py）

付费 Skill 必须是一个 HTTP 商户服务。本仓库 scripts/pay_server.py 已实现完整 X402 链路：

• POST /api/resource —— 首次返回 402 + WeixinPay-Required + X-Out-Trade-No；携带 X-Out-Trade-No 重试时查单验证并履约返回对账报告（幂等）。
• POST /api/pay/notify / POST /api/refund/notify —— 微信支付结果回调（验签 + 状态更新）。
• /health —— 健康检查。

运行：

cd scripts
pip install -r ../requirements.txt
# 本地无真凭证调试（完整跑通 402→支付→200，不真实扣费）
SKILLHUB_DEMO=1 python pay_server.py
# 生产：填真实凭证（见 .env.example）后
python pay_server.py

生产常驻部署（推荐，自有 Ubuntu 服务器）：本仓库 deploy/ 已提供 nginx_site.conf + pay_server.service（systemd）+ DEPLOY.md（逐行命令），用 **nginx + gunicorn + systemd** 常驻运行；pay_server.py 通过同目录 .env 自动加载密钥（含多行 PEM）。付费服务已部署并对外暴露为 https://weixinduizhang.shucejishu.cn`（备案通过后生效）。

环境变量（详见 .env.example）：

两套密钥务必区分：微信支付 API 证书（签名算法 WECHATPAY2-SHA256-RSA2048）用于 Native 下单/查单/退款；SkillHub 开发者密钥（签名算法 SKILLHUB-SHA256-RSA2048）仅用于 AI 预下单签名。AI 预下单请求体为 L1/L2 两层结构，L2 业务 JSON 经 Base64 后放入 L1 的 payment_required 字段，签名串格式为 POSTn/palmpayminiapp/clawagentpay/preordern{timestamp}n{nonce_str}n{payment_required}n。

文件结构（scripts/）

以下为作者自部署资产，不随 SkillHub 公开包分发。Skill 调用者无需在本机运行任何脚本——付费服务已由作者托管于 https://weixinduizhang.shucejishu.cn，下载即用。如需自托管，请从私有仓库获取源码。

参考：references/real-mode-setup.md（真实凭证接入、验签、回调接线、合规红线）。

本地联调（无真凭证）

cd scripts
SKILLHUB_DEMO=1 python pay_server_test.py   # 21 项全通过即链路正确

关键实现要点

• 金额单位：微信 V3 退款/金额统一为「分」；演示订单 amount 为「元」，转换时注意。
• 对账匹配键：优先 out_trade_no（商户订单号）精确匹配；金额单位两侧必须一致。
• 幂等：同一 out_trade_no 只履约一次，重复请求返回缓存结果（already_fulfilled=true）。
• 合规红线（任何改动不得突破）：平台不碰资金（直连商户模式）；回调必须验签；不做二清/资金归集。

演示数据里的刻意差异（验证用）

• 1 笔金额差异（商户少记 1 元）
• 1 笔单边账（微信有、商户无）
• 1 笔状态异常（微信 SUCCESS、商户 FAILED）
• 退款行约 8%，触发退款率/大额告警阈值可按 config.large_amount_threshold 调小观察