重置项目上下文与规范文档

docs/integrations/wechat/README.md

@@ -0,0 +1,34 @@
+# 微信生态接入契约
+
+## 元数据
+
+- Owner：支付与微信生态维护人
+- 实现：`pkg/wechat/`
+- SDK：`github.com/ArtisanCloud/PowerWeChat/v3 v3.4.38`
+- 核验日期：2026-08-07
+
+## 当前实际使用范围
+
+系统使用公众号 OAuth、小程序 `code2session`、微信支付 JSAPI/H5 下单、查单、关单和支付通知。支付同时存在 PowerWeChat/v3 适配与仅配置 APIv2 Key 时使用的 v2 XML 适配；不得仅凭 SDK 文档推断其他微信能力。
+
+## 端点、配置与关键字段
+
+- 小程序：`GET https://api.weixin.qq.com/sns/jscode2session`，参数为 AppID、AppSecret、临时 code 和固定 `authorization_code`；响应必须含 OpenID、SessionKey，可选 UnionID；超时 10 秒。
+- 支付 v2：`POST https://api.mch.weixin.qq.com/pay/unifiedorder` 和 `/pay/orderquery`，XML + MD5 签名；关键字段为商户订单号、金额（分）、OpenID、交易类型、通知地址和客户端 IP。
+- 支付 v3/SDK：使用 AppID、商户号、APIv3 Key、证书序列号、私钥及通知地址，支持 JSAPI/H5、Query、Close 和 Notify。
+
+配置来自支付配置记录，不在本文列出具体值。v2 下单同时要求 `return_code=SUCCESS` 与 `result_code=SUCCESS`；查单以商户订单号关联本地支付。
+
+## 回调、幂等、失败与重试
+
+v2 按 API Key 验签，v3 按平台证书验签并解密通知。商户订单号是渠道幂等标识；通知还需核对金额、配置和本地状态，并以状态条件更新避免重复入账。小程序 `errcode!=0`、关键字段缺失、HTTP/解析失败均映射统一微信错误。
+
+适配器没有对创建支付做盲目自动重试；查单可由业务流程补偿，关单和回调按原商户订单号及状态保持幂等。
+
+## 安全与验证
+
+AppSecret、API Key、私钥、证书内容、SessionKey、完整 OpenID 和通知原文不得进入文档或普通日志。可复现静态证据：`pkg/wechat/miniapp.go`、`pkg/wechat/payment.go`、`pkg/wechat/payment_v2.go`、`internal/handler/callback/payment.go`。真实验收需隔离商户验证 JSAPI/H5、查关单、签名失败、金额不符与重复通知；本次不调用真实渠道。
+
+官方参考：<https://pay.weixin.qq.com/doc/v3/merchant/4012065342>
+
+SDK、API 版本、认证、通知或重试语义变化时更新本文。