支付系统优化与官方支付接入方案

落地状态（v0.3.85 补注，阅读本文档前必读）

本方案已于 v0.3.82 ~ v0.3.84 分批落地：includes/payment/ 已随包交付，官方支付通道已可用。 本文档保留为历史设计与审计记录，上表"不提升 CMS_VERSION""本轮未改动任何业务代码"， 以及第三节「不做清单」与附录 A 中的同类表述，仅描述编制当时（v0.3.81）的站点状态，不代表当前交付包。

第四节 4.1 的"目标架构"文件名与实际交付的差异如下：

方案中的文件	实际交付形态
AlipayFaceToFaceGateway.php / WechatNativeGateway.php	AlipayGateway.php / WechatGateway.php
Signer.php / Certs.php	PaymentSigner.php / PaymentConfig.php（密钥装载并入 PaymentConfig）
payment-page.php	未单独实现：收款码/动态码由 payment-code.php 承载，下单在 payment-create.php + payment-guide.php
payment-return-alipay.php	未单独实现：同步跳转后的状态确认由 payment-status.php 轮询完成
admin/payment-refund.php	未交付：渠道层 PaymentGateway::refund()（支付宝/微信均已实现）无编排与后台入口，退款需到渠道商户平台人工操作
admin/payment-proof.php	未交付：支付凭证未做受控输出页，凭证以渠道回执/后台订单原始报文为准
cron-payment-reconcile.php / cron-payment-sweep.php	合并为 cron-payment.php：默认 sweep + reconcile，--no-query 只关单不查单，--limit=N 限流
admin/payment-orders.php、payment-create.php、payment-status.php、payment-notify-alipay.php、payment-notify-wechat.php	已交付（与方案同名）

方案之外额外交付：payment-receipt.php（安卓微信收款回执监听，BUG-2026-0016）与 includes/payment/schema.sql（4 张支付表 DDL）。 后者不并入 database.sql，启用官方支付前需手工执行一次，详见 docs/安装配置说明.md 第二节第 5 项。

结论摘要（先读这一段）

1. 本站当前不存在任何支付网关代码。 全站检索 notify_url / out_trade_no / precreate / mchid / WECHATPAY 等关键字，业务代码命中数为 0。现有"支付"= 静态/套餐收款码 + 用户上传转账截图 + 管理员人工点击审核到账。
2. 因此"接入官方支付接口"不是改造，而是新增一条与现有人工流程并行、可灰度、可回退的通道。现有流程必须保留为降级兜底。
3. 存在 3 个硬阻断项（详见第十四节）：无域名/无 HTTPS（微信支付 v3 强制要求 HTTPS 回调）、支付渠道资质与密钥未提供、是否允许引入官方 SDK（当前无 composer、无 vendor/）与新增数据表未确认。
4. 在资质到位前，P0 阶段可立即落地不依赖渠道的加固（凭证裁剪缺陷、并发重复到账、订单号暴露、监控与对账），这些不触及任何外部接口，收益立即可见（详见第十三节）。

一、现状审计

1.1 支付链路实测（含代码级证据）

下单

• 入口：token-recharge.php（POST 处理区 token-recharge.php:47-119）。
• 客户端只提交 package_id / price / pay_method / 可选 pay_proof。
• 服务端做了正确的防篡改处理：套餐订单的金额与 Token 数均从 token_packages 回查（token-recharge.php:75-88），拒绝前端伪造额度——这一点是本项目现存代码的优点，新通道必须沿用同一原则。
• 落库：createTokenOrder()（includes/token-functions.php:254-261）

```sql INSERT INTO token_orders (user_id, package_id, token_amount, price, pay_method, pay_proof, status) VALUES (?, ?, ?, ?, ?, ?, 0) ```

status = 0（待审核）。全站仅此一处创建订单。

• 随后 buildPaymentGuide()（includes/token-functions.php:1107）渲染收款码卡片，pay_method 取值仅 alipay / wechat（token-recharge.php:316-317）。

到账（唯一路径：人工）

• admin/token-orders.php:159-196：

addTokens()（includes/token-functions.php:135-148）为 UPDATE users SET token_balance = COALESCE(token_balance,0) + ?。

• 另一处状态相关写入：includes/token-functions.php:698 附近的过期额度返还（returnExpiredTokens()），与支付渠道无关。

关键缺口（本节结论的支撑）

• 无异步回调端点、无主动查单、无退款、无渠道流水号（token_orders 无 trade_no 类字段）、无与渠道账单的核对。
• 现有"对账"仅 admin/token-dashboard.php 的站内 Token 账目恒等式（消耗/充值/余额自洽），与渠道账单完全脱离——即"用户说付了但没付"这类问题在系统层面无法被自动发现。
• admin/token-orders.php 依赖管理员肉眼识别截图。而截图经过 processIconUpload() 处理后已被裁剪（见 1.4 / P-02）。

1.2 数据模型现状

实测表结构（SHOW COLUMNS）：

token_orders（11 列）

status = 1 同时表示"已到账"，没有"已支付待入账"这一中间态——这是引入网关后必须拆分的关键点。

token_packages（8 列）：id / name / token_amount / price / sort_order / status / created_at / updated_at。

settings：key_name VARCHAR(60) PRIMARY KEY，value TEXT；实测 54 项。约束：新增配置键名必须 ≤ 60 字符，且沿用现有命名前缀风格（pay_qr_*、token_*）。

1.3 环境与基础设施事实（实测）

1.4 已就绪、可直接复用的资产

1.5 待实测项（本方案中标注为「未验证」）

二、问题清单（分级）

级别定义：P0 = 造成资金/数据错误或安全风险，需优先修复；P1 = 影响可用性、对账或人工成本；P2 = 体验与工程规范。

说明：P-02 在本轮被重新实证确认（此前为待复核项）。结论：gd 已加载 → resizeIconToSquare(..., 48) 必然执行 → 支付凭证被裁成 48×48 中心方块。

三、优化目标与范围

3.1 目标（可量化）

3.2 方案范围

包含：审计与问题清单；目标架构与模块划分；数据模型（4 张新表）；订单状态机与合法迁移；三层幂等；重试与补偿；日志/监控/告警；灰度与回滚；官方接口接入要点（支付宝当面付、微信支付 v3 Native）；订单号与金额规则；接口清单；请求/响应示例；错误码；安全合规要点；测试用例；验收标准；上线与监控；实施路线图。

不包含（明确不做）：

• ❌ 任何非官方、破解、绕过风控的方案：聚合个人码、伪造支付回调、"免签约/免资质"通道、修改渠道 SDK 校验、关闭验签、verify=false。
• ❌ 本项目内不实施代码改动（本轮仅交付方案；实施需另行确认）。
• ❌ 不修改面板核心、不触碰授权机制（data/.license_warnings 必须保持 count:10、属主 www:www）。
• ❌ 不提升 CMS_VERSION（维持 v0.3.81）。
• ❌ 不引入新依赖（除非用户明确批准，见 5.4）。
• ❌ 不做用户资金托管/钱包化（不改变"余额 = Token 记账"的既有模型）。

3.3 设计原则

1. 客户端不可信：金额、Token 数一律服务端按 package_id 回查；客户端只允许传 package_id 与渠道。
2. 渠道不可全信：回调必须验签 + 校验金额/商户号/应用 ID + 校验本地订单存在且状态合法。
3. 钱账分离：支付事实（渠道）与记账事实（站内 Token）分表，二者通过幂等键关联。
4. 只增不删：新表新字段只做增量；旧流程保留，通过开关切换。
5. 一切可回退：关闭开关即回到"人工收款码 + 人工审核"，无需数据回滚。

四、目标架构

4.1 模块划分与目录

includes/payment/
├── PaymentGateway.php            接口定义：createOrder/queryOrder/closeOrder/refund/verifyNotify/ackNotify
├── AlipayFaceToFaceGateway.php   支付宝当面付实现（RSA2 签名/验签）
├── WechatNativeGateway.php       微信支付 v3 Native 实现（SHA256-RSA2048 + AES-256-GCM）
├── PaymentService.php            编排层：下单/入账/退款/关单（事务、幂等、状态机唯一入口）
├── PaymentStore.php              数据访问：payment_orders/notifies/refunds/reconcile
├── Signer.php                    渠道无关的签名/验签原语（RSA2、SHA256withRSA、AES-256-GCM）
├── Certs.php                     密钥与证书装载（落盘读取、序列号解析、轮换校验）
└── Ledger.php                    站内记账：调用 addTokens()、写 token_orders(status=1)、审计

payment-create.php                下单（登录 + CSRF）
payment-status.php                状态轮询（登录 + 仅限本人订单）
payment-page.php                  收银台（展示二维码/跳转，轮询状态）
payment-notify-alipay.php         支付宝异步通知（无登录，验签后处理）
payment-notify-wechat.php         微信 v3 异步通知（无登录，验签+解密后处理）
payment-return-alipay.php         支付宝同步跳转回执（仅做展示，不作为入账依据）
admin/payment-orders.php          管理端：订单列表/手动补单/手动关单/查看原始报文
admin/payment-refund.php          管理端：发起退款（requireAdmin + CSRF + 限额 + 二次确认）
admin/payment-proof.php           管理端：受控输出支付凭证（替代 Web 直读）
cron-payment-reconcile.php        查单补偿 + T+1 账单对账 + 告警
cron-payment-sweep.php            超时关单 + 长期未决订单转人工

分层约束：PaymentService 是唯一允许修改 payment_orders.status 与调用 Ledger 的入口；admin/* 与 cron-* 只能调用 PaymentService；网关实现类不得直接写库。

4.2 数据模型（新表 DDL）

字符集 utf8mb4 / utf8mb4_unicode_ci，引擎 InnoDB，与现网一致。MySQL 5.7 兼容。

-- 支付单：一次"支付尝试"的全部事实
CREATE TABLE `payment_orders` (
  `id`                INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `out_trade_no`      VARCHAR(32)  NOT NULL COMMENT '我方订单号，渠道不重复',
  `user_id`           INT UNSIGNED NOT NULL,
  `package_id`        INT UNSIGNED NOT NULL DEFAULT 0,
  `token_amount`      DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '下单时快照',
  `amount_fen`        INT UNSIGNED NOT NULL COMMENT '应付金额（分），避免浮点',
  `currency`          CHAR(3)      NOT NULL DEFAULT 'CNY',
  `channel`           VARCHAR(16)  NOT NULL COMMENT 'alipay / wechat',
  `subject`           VARCHAR(128) NOT NULL DEFAULT '',
  `status`            VARCHAR(16)  NOT NULL DEFAULT 'INIT'
                      COMMENT 'INIT/PENDING/PAID/CREDITED/CLOSED/REFUNDING/REFUNDED/PARTIAL_REFUNDED/REVIEW/FAILED',
  `channel_trade_no`  VARCHAR(64)  NOT NULL DEFAULT '',
  `token_order_id`    INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '入账后生成的 token_orders.id（0=未入账）',
  `code_url`          TEXT         NULL COMMENT '渠道返回的二维码内容',
  `client_ip`         VARCHAR(45)  NOT NULL DEFAULT '',
  `time_expire`       DATETIME     NULL,
  `paid_at`           DATETIME     NULL,
  `credited_at`       DATETIME     NULL,
  `closed_at`         DATETIME     NULL,
  `refunded_fen`      INT UNSIGNED NOT NULL DEFAULT 0,
  `error_code`        VARCHAR(32)  NOT NULL DEFAULT '',
  `error_msg`         VARCHAR(255) NOT NULL DEFAULT '',
  `attach`            TEXT         NULL COMMENT 'JSON：下单上下文（套餐名等）',
  `channel_raw`       TEXT         NULL COMMENT 'JSON：最近一次渠道应答（脱敏）',
  `reconcile_state`   VARCHAR(16)  NOT NULL DEFAULT 'NONE' COMMENT 'NONE/MATCH/DIFF',
  `created_at`        TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at`        TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_out_trade_no` (`out_trade_no`),
  KEY `idx_status_created` (`status`, `created_at`),
  KEY `idx_user` (`user_id`),
  KEY `idx_channel_trade` (`channel`, `channel_trade_no`),
  KEY `idx_token_order` (`token_order_id`),
  KEY `idx_paid` (`paid_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 渠道通知/查单原始报文（审计与幂等依据）
CREATE TABLE `payment_notifies` (
  `id`               BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `channel`          VARCHAR(16) NOT NULL,
  `source`           VARCHAR(16) NOT NULL COMMENT 'notify / query / refund_notify',
  `notify_key`       VARCHAR(128) NOT NULL COMMENT '幂等键：渠道通知ID 或 交易号+事件类型',
  `out_trade_no`     VARCHAR(32) NOT NULL DEFAULT '',
  `channel_trade_no` VARCHAR(64) NOT NULL DEFAULT '',
  `sign_verified`    TINYINT(1)  NOT NULL DEFAULT 0,
  `payload`          TEXT NULL COMMENT '原始报文（脱敏）',
  `headers`          TEXT NULL COMMENT '需要的请求头（脱敏）',
  `processed`        TINYINT(1)  NOT NULL DEFAULT 0,
  `process_result`   VARCHAR(255) NOT NULL DEFAULT '',
  `created_at`       TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_channel_notifykey` (`channel`, `notify_key`),
  KEY `idx_out_trade_no` (`out_trade_no`),
  KEY `idx_processed_created` (`processed`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 退款单
CREATE TABLE `payment_refunds` (
  `id`                INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `out_refund_no`     VARCHAR(32)  NOT NULL COMMENT '退款请求号（渠道幂等键）',
  `out_trade_no`      VARCHAR(32)  NOT NULL,
  `channel`           VARCHAR(16)  NOT NULL,
  `refund_amount_fen` INT UNSIGNED NOT NULL,
  `reason`            VARCHAR(128) NOT NULL DEFAULT '',
  `status`            VARCHAR(16)  NOT NULL DEFAULT 'INIT'
                      COMMENT 'INIT/PENDING/SUCCESS/FAILED/CLOSED',
  `channel_refund_id` VARCHAR(64)  NOT NULL DEFAULT '',
  `operator_admin_id` INT UNSIGNED NOT NULL DEFAULT 0,
  `channel_raw`       TEXT NULL,
  `created_at`        TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at`        TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_out_refund_no` (`out_refund_no`),
  KEY `idx_out_trade_no` (`out_trade_no`),
  KEY `idx_status_created` (`status`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- T+1 对账结果
CREATE TABLE `payment_reconcile` (
  `id`               INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `bill_date`        DATE NOT NULL,
  `channel`          VARCHAR(16) NOT NULL,
  `bill_count`       INT NOT NULL DEFAULT 0,
  `bill_amount_fen`  BIGINT NOT NULL DEFAULT 0,
  `local_count`      INT NOT NULL DEFAULT 0,
  `local_amount_fen` BIGINT NOT NULL DEFAULT 0,
  `diff_count`       INT NOT NULL DEFAULT 0,
  `diff_detail`      TEXT NULL COMMENT 'JSON：{only_channel:[],only_local:[],amount_mismatch:[]}',
  `file_hash_ok`     TINYINT(1) NOT NULL DEFAULT 0,
  `status`           VARCHAR(16) NOT NULL DEFAULT 'OK' COMMENT 'OK/DIFF/FAILED',
  `created_at`       TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_date_channel` (`bill_date`, `channel`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

关于 token_orders：本方案不做结构变更。

理由（最小改动原则）：

• 渠道到账时直接创建 token_orders 行并置 status=1、admin_note='渠道自动到账'，同事务内 addTokens()——人工审核队列不会被未支付订单污染。
• 两者的关联通过 payment_orders.token_order_id 反向查询/JOIN 实现。

若用户要求双向可见，再追加一列 token_orders.out_trade_no VARCHAR(32) DEFAULT ''（可空、只增）。此项列为待确认（见第十四节）。

4.3 调用链路

A. 下单（用户 → 渠道）

用户选择套餐
  → POST /payment-create.php  （登录校验 + CSRF + 频控）
  → PaymentService::create()
      1. 校验 package_id 存在且 status=1；服务端取 price/token_amount 快照
      2. 生成 out_trade_no（规则见 5.3），INSERT payment_orders(status=INIT)
      3. 调 Gateway::createOrder()  →  渠道返回 code_url
      4. UPDATE status=PENDING, code_url=..., time_expire=now()+15min
  → 返回 {out_trade_no, code_url, amount_fen}
  → 跳转 /payment-page.php?out_trade_no=xxx 展示二维码

B. 支付成功（渠道 → 我方，主路径）

渠道异步通知
  → POST /payment-notify-{channel}.php
  → 1) 验签（RSA2 / SHA256withRSA）
     2) 幂等占位：INSERT payment_notifies（uk: channel+notify_key），
        重复 → 直接按渠道格式应答"成功"并结束（不再入账）
     3) 校验：app_id/mchid 匹配、金额与 payment_orders.amount_fen 一致、
        本地订单存在且 status ∈ {INIT,PENDING}
     4) PaymentService::markPaid()
          BEGIN
            SELECT * FROM payment_orders WHERE out_trade_no=? FOR UPDATE
            UPDATE payment_orders SET status='PAID', channel_trade_no=?, paid_at=? 
              WHERE id=? AND status IN ('INIT','PENDING')
            Ledger::credit()  ← 同事务内：INSERT token_orders(status=1) + addTokens()
            UPDATE payment_orders SET status='CREDITED', credited_at=NOW() WHERE id=?
          COMMIT
     5) 应答：支付宝返回纯文本 `success`；微信返回 200 + {"code":"SUCCESS","message":"成功"}

C. 回调丢失（渠道 → 我方，补偿路径）

cron-payment-reconcile.php（每分钟）
  → 取 status=PENDING 且 created_at < now()-2min 的订单
  → Gateway::queryOrder()
      渠道=已支付 → 复用 B 的 markPaid()（同一幂等键，天然安全）
      渠道=已关闭 → status=CLOSED
      渠道=未知/异常 → 记录失败次数，指数退避（2m→5m→15m→30m），
                       超过 24h 仍未知 → status=REVIEW + 告警

D. 超时关单

cron-payment-sweep.php（每分钟）
  → status=PENDING 且 time_expire < now() 的订单
  → Gateway::closeOrder()
      成功 → status=CLOSED
      渠道报"订单已支付" → 立刻走查询补偿（先付款后关单的竞态）

E. 退款（仅管理员）

POST /admin/payment-refund.php（requireAdmin + CSRF + 二次确认 + 单笔/日限额）
  → 校验 out_trade_no 状态 ∈ {PAID, CREDITED}、refund_amount ≤ amount_fen - refunded_fen
  → 生成 out_refund_no（渠道幂等键），INSERT payment_refunds(status=INIT)
  → Gateway::refund()  → status=PENDING, 记 channel_refund_id
  → 退款通知/查询确认 → status=SUCCESS
  → 同事务：扣减 users.token_balance（Ledger::debit），
             payment_orders.refunded_fen += refund_amount_fen，
             全额则 status=REFUNDED，部分则 PARTIAL_REFUNDED
  → 写 admin 审计日志

F. T+1 对账

cron-payment-reconcile.php（每日，建议 09:30）
  → 支付宝：alipay.data.dataservice.bill.downloadurl.query 取账单下载地址 → 下载 CSV/ZIP
  → 微信：GET /v3/bill/tradebill?bill_date=D&bill_type=ALL
           → 校验下载文件 SHA1（渠道返回 hash）→ 解压 CSV（gzip）
  → 与本库 payment_orders（status ∈ PAID/CREDITED/REFUND*）逐笔比对
  → 差异全量写 payment_reconcile.diff_detail，diff_count>0 即告警

4.4 状态机与合法迁移表

                    ┌──────── 下单失败 ────────┐
                    ▼                          │
  [INIT] ──渠道下单成功──▶ [PENDING] ──渠道确认支付──▶ [PAID] ──入账成功──▶ [CREDITED]
     │                       │  │                                              │
     │                       │  └──超时/关单──▶ [CLOSED]                       │
     │                       └──异常──▶ [REVIEW] ──人工──▶ [CLOSED]/[CREDITED] │
     └──渠道拒绝/参数错──▶ [FAILED]                                             │
                                                                              │
  [CREDITED] ──全额退款──▶ [REFUNDED] ◀──[REFUNDING] ◀──发起退款───────────────┘
             ──部分退款──▶ [PARTIAL_REFUNDED]

合法迁移表（PaymentService 强制校验，非法迁移一律抛 PAY_1014/PAY_1006）

关键约束：

• PAID → CREDITED 必须满足 credited_at IS NULL，用条件更新保证影响行数 = 1。
• CLOSED 可回到 PAID：这是唯一允许"逆向"的迁移，因为渠道的支付事实优先于我方关单动作。
• REFUNDED 后禁止再次退款（refunded_fen >= amount_fen 即拒绝）。

4.5 三层幂等

L3 是唯一能产生 addTokens() 的路径。人工审核路径（admin/token-orders.php）同时加固为 UPDATE ... WHERE id=? AND status=0 校验影响行数（修复 P-04）。

4.6 重试与补偿

补偿原则：所有对外调用使用幂等键（下单用 out_trade_no、退款用 out_refund_no、通知用 notify_key），因此"重试"在任何时候都安全。

4.7 日志、监控与告警

日志分级

脱敏要求：日志与 payload 中不得出现私钥、APIv3 密钥、证书内容、完整 buyer_logon_id/openid（保留前 4 后 4）、手机号、真实姓名。

监控指标（4 项必备）

告警通道：优先复用 includes/Mailer.php（需先配置 smtp_*，当前为空——见 U-4）；同时写入宝塔面板通知。告警需含 out_trade_no 与运维动作建议。

4.8 灰度发布与回滚

灰度开关：新增配置键（≤ 60 字符）

灰度阶段

1. 阶段 0（单测/沙箱）：payment_gateway_enabled=1 但 payment_channels=""，仅跑单元与沙箱测试。
2. 阶段 1（内部）：payment_gray_users 加入 2~3 个内部账号，金额限制为最低套餐，人工核对每笔。
3. 阶段 2（5%）：payment_gray_percent=5，观察 3 天：回调成功率、入账时延、告警数。
4. 阶段 3（全量）：payment_gray_percent=100；人工收款码入口保留但降级为折叠项（老用户/异常兜底）。

回滚

五、官方接口接入要点

以下均为官方开放接口，按官方文档实现签名/验签；禁止任何绕过风控或非官方通道的做法。

5.1 支付宝当面付（F2F）

• 网关：https://openapi.alipay.com/gateway.do
• 签名算法：sign_type=RSA2（SHA256withRSA），应用私钥（PKCS8 PEM）签名，支付宝公钥验签。
• 签名串构造（请求）：除 sign 外全部请求参数，按参数名 ASCII 升序，k=v 以 & 连接，值为未 URL 编码的原始值；无值参数不参与。
• 公共参数：app_id、method、format=JSON、charset=utf-8、sign_type=RSA2、timestamp（Y-m-d H:i:s，Asia/Shanghai）、version=1.0、notify_url、biz_content（JSON 字符串）、sign。
• 接口清单

• 应答验签：sign 为顶层字段，被签名内容是响应中的业务节点（如 alipay_trade_precreate_response）的原始 JSON 片段。必须先验签再解析业务字段。
• 异步通知（notify_url）：application/x-www-form-urlencoded POST。校验顺序：

1. 用支付宝公钥对通知参数（剔除 sign、sign_type，值为解码后的明文）按 ASCII 排序拼串验签；
2. 校验 app_id 与本应用一致；
3. 校验 seller_id 与签约商户一致；
4. 校验 total_amount 与本地 payment_orders.amount_fen（元）一致；
5. 校验 out_trade_no 在本地存在；
6. 仅在 trade_status ∈ {TRADE_SUCCESS, TRADE_FINISHED} 时入账。

• 应答格式：纯文本 success（无 BOM、无 HTML、无 JSON 包裹、无多余空白），否则支付宝将持续重试。
• 注意：同一 out_trade_no 可能收到多次 TRADE_SUCCESS（业务方可能多次 notify），必须幂等（L2/L3）。

5.2 微信支付 v3（Native 扫码）

• 域名：https://api.mch.weixin.qq.com
• 请求签名（Authorization: WECHATPAY2-SHA256-RSA2048）

``` mchid="1900000001",nonce_str="...",signature="...",timestamp="...",serial_no="..." ```

签名串（每行以 \n 结尾，共 5 行）：

``` HTTP方法\n URL（含 query，如 /v3/pay/transactions/native）\n 时间戳（秒）\n 随机串\n 请求体原文\n ```

算法：RSA-SHA256 + 商户 API 私钥（apiclient_key.pem，PKCS1v15）；serial_no = 商户 API 证书序列号。

• 应答验签：用微信支付平台证书公钥（或平台公钥）验证，签名串 = 时间戳\n随机串\n响应体\n，请求头 Wechatpay-Timestamp / Wechatpay-Nonce / Wechatpay-Signature / Wechatpay-Serial。必须验签后才解析业务数据。
• 接口清单

• 回调处理：

1. 验签（同上，用平台证书/平台公钥）；
2. 解密 resource：

``` algorithm = AEAD_AES_256_GCM key = APIv3 密钥（32 字节） iv = resource.nonce（12 字节） aad = resource.associated_data plain = AES-256-GCM-decrypt(resource.ciphertext, key, iv, aad, tag[末尾16字节]) ```

1. 校验 event_type == "TRANSACTION.SUCCESS"、明文中的 appid/mchid/out_trade_no/amount.total（分）；
2. 入账（复用 L2/L3 幂等）。

• 应答格式：HTTP 200，body {"code":"SUCCESS","message":"成功"}；失败返回 4xx/5xx + {"code":"FAIL","message":"..."}。渠道重试节奏：15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h，累计约 24 小时（以官方文档为准）。
• 证书轮换：平台证书有效期约 5 年但微信会不定期更新；建议使用平台公钥模式（公钥 ID）以简化轮换；若用平台证书，cron-payment-reconcile.php 每日检查 serial_no 是否变化并告警（PAY_1016）。
• ⚠️ 硬约束：notify_url 必须为 HTTPS（当前站点为 http://39.96.90.85）→ 微信通道在取得域名与证书前无法上线（P-10）。

5.3 金额与订单号规则

订单号 out_trade_no（同时满足两渠道最严约束：微信 6~32 字符、仅数字/大小写字母/_-|*@；支付宝 ≤ 64 字符、字母数字下划线）

T + yyMMddHHmmss + 4位随机(字母数字) + 3位自增
示例：T260930143005K7Q0021
长度：1 + 12 + 4 + 3 = 20 字符

• 前缀固定 T（不使用下划线，避免日志/CSV 转义问题）；
• 唯一性由 uk_out_trade_no 兜底，冲突则重新生成（最多 3 次）；
• 退款单号同规则，前缀改 R。

金额

校验规则：amount_fen > 0；回调金额与本地金额必须完全相等（不等 → PAY_1004 → 转 REVIEW，绝不入账）；退款金额 ≤ amount_fen - refunded_fen。

5.4 官方 SDK 依赖策略（当前无 composer）

站点不存在 composer.json 与 vendor/。两条路径：

本方案默认按 方案 A 设计（不引入任何依赖）。若用户批准方案 B，需在实施前单独确认安装范围与来源。

六、接口清单

6.1 站内 HTTP 接口

6.2 定时任务

均需 cli 运行（参考既有 cron-token-expiry.php 的实现风格），并加文件锁（flock）防止重入。

6.3 外部渠道接口（只读引用，见第五节）

支付宝：alipay.trade.precreate / alipay.trade.query / alipay.trade.close / alipay.trade.refund / alipay.trade.cancel / alipay.data.dataservice.bill.downloadurl.query

微信：/v3/pay/transactions/native / /v3/pay/transactions/out-trade-no/{no} / .../close / /v3/refund/domestic/refunds / /v3/bill/tradebill / /v3/certificates

七、请求/响应示例

7.1 站内：下单

请求

POST /payment-create.php HTTP/1.1
Host: 39.96.90.85
Content-Type: application/x-www-form-urlencoded
Cookie: PHPSESSID=***

package_id=2&channel=alipay&csrf_token=***

成功响应

{
  "success": true,
  "out_trade_no": "T260930143005K7Q0021",
  "channel": "alipay",
  "amount_fen": 9900,
  "amount_text": "99.00",
  "token_amount": "1000.00",
  "code_url": "https://qr.alipay.com/bax08xxxxxxxxxxxxxxxxxx",
  "time_expire": "2026-09-30 14:45:05",
  "pay_page": "/payment-page.php?out_trade_no=T260930143005K7Q0021"
}

失败响应

{ "success": false, "error_code": "PAY_1003", "message": "渠道下单失败，请稍后重试" }

7.2 支付宝：异步通知（渠道 → 我方）

请求（form-urlencoded，节选）

notify_time=2026-09-30+14%3A32%3A11
notify_type=trade_status_sync
notify_id=ac05099524730693a8b330c5ecf72da9786
app_id=2021000000000000
out_trade_no=T260930143005K7Q0021
trade_no=2026093022001441911000000001
trade_status=TRADE_SUCCESS
total_amount=99.00
seller_id=2088000000000001
gmt_payment=2026-09-30+14%3A32%3A05
sign_type=RSA2
sign=***

我方应答（必须为纯文本，无 BOM）

success

处理失败时（促发渠道重试）

failure

7.3 微信 v3：下单与回调

下单请求

POST /v3/pay/transactions/native HTTP/1.1
Host: api.mch.weixin.qq.com
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000001",nonce_str="A1B2C3D4E5",signature="***",timestamp="1759213925",serial_no="4A3B2C1D..."
Content-Type: application/json
Accept: application/json

{
  "appid": "wx0000000000000000",
  "mchid": "1900000001",
  "description": "奇点中文网-Token充值-1000",
  "out_trade_no": "T260930143005K7Q0021",
  "notify_url": "https://pay.example.com/payment-notify-wechat.php",
  "time_expire": "2026-09-30T14:45:05+08:00",
  "amount": { "total": 9900, "currency": "CNY" }
}

下单响应

{ "code_url": "weixin://wxpay/bizpayurl?pr=AbCdEfG" }

回调请求体

{
  "id": "EV-2026093014320512345678",
  "create_time": "2026-09-30T14:32:05+08:00",
  "event_type": "TRANSACTION.SUCCESS",
  "resource_type": "encrypt-resource",
  "summary": "支付成功",
  "resource": {
    "original_type": "transaction",
    "algorithm": "AEAD_AES_256_GCM",
    "ciphertext": "***",
    "associated_data": "transaction",
    "nonce": "Ab1Cd2Ef3Gh"
  }
}

解密后明文（节选）

{
  "mchid": "1900000001",
  "appid": "wx0000000000000000",
  "out_trade_no": "T260930143005K7Q0021",
  "transaction_id": "4200001234202609301234567890",
  "trade_type": "NATIVE",
  "trade_state": "SUCCESS",
  "success_time": "2026-09-30T14:32:00+08:00",
  "amount": { "total": 9900, "payer_total": 9900, "currency": "CNY" }
}

我方应答

{ "code": "SUCCESS", "message": "成功" }

7.4 退款

请求（管理端）

POST /admin/payment-refund.php HTTP/1.1
Host: 39.96.90.85
Content-Type: application/x-www-form-urlencoded
Cookie: PHPSESSID=***

out_trade_no=T260930143005K7Q0021&refund_amount=99.00&reason=用户申请&confirm=1&csrf_token=***

响应

{ "success": true, "out_refund_no": "R260930150000X9Z0001", "status": "PENDING", "message": "退款已提交，结果以渠道回调为准" }

八、错误码表

九、安全与合规要点

9.1 密钥与证书管理

9.2 回调安全

1. 强制验签，失败一律拒绝（不允许"调试模式跳过验签"这类开关）。
2. 金额、商户号、应用 ID 三项核对，任一不符即不入账并转 REVIEW。
3. 时间窗校验：通知时间与本机时间偏差 > 5 分钟 → 拒绝（防重放；仅在证据充分时放宽）。
4. 幂等：uk_channel_notifykey 唯一键在最前，重复直接返回成功。
5. 限流：回调入口按 IP 与 out_trade_no 频控（如 60 次/分钟），防刷。
6. 只接受 POST（支付宝通知/微信通知均为 POST），其他方法返回 405。
7. 应答严格：支付宝必须纯文本 success；微信必须 HTTP 200 + {"code":"SUCCESS","message":"成功"}。
8. 日志脱敏：payment_notifies.payload 存储前按白名单字段筛选并掩码 PII。

9.3 传输与管理端

• 出网 TLS 校验开启（curl.cainfo 已配置，禁止 CURLOPT_SSL_VERIFYPEER=false）。
• notify_url 必须 HTTPS；payment_site_base_url 仅允许 https:// 前缀，否则拒绝保存。
• 管理端退款：requireAdmin() + CSRF + 二次确认 + 单笔限额 + 日累计限额 + 完整审计（操作者 ID、时间、金额、原因、结果）。
• 凭证访问：admin/payment-proof.php 做 requireAdmin() + 路径白名单 + realpath() 前缀校验（防目录穿越）+ Content-Disposition: inline。
• 订单查询：payment-status.php 必须先 WHERE user_id = 当前用户（防越权遍历）。

9.4 合规

1. 停止使用个人收款码做经营性收款（P-11）：个人码无法开具商户凭证、不支持对账、易触发风控，且与"正版支付接口"目标冲突。网关上线后，收款码降级为异常兜底并逐步下线。
2. 交易凭证留存 ≥ 3 年（渠道流水号、原始报文、金额、时间）——落 payment_notifies 与 payment_reconcile。
3. 用户协议与退款政策需明示：支付渠道、到账时效、退款条件与处理时限。
4. 主体一致：支付商户主体应与站点运营主体一致；不一致时需在页面明示收款方，避免投诉。
5. 不得：使用非官方通道、伪造/篡改回调、绕过渠道风控、为他人代收（二清风险）。
6. 个人信息：回调中的买家标识（buyer_logon_id / openid）属个人信息，按最小必要存储并脱敏。

十、测试用例

10.1 单元测试（不依赖网络）

10.2 集成测试（沙箱）

10.3 幂等与并发测试（重点）

10.4 异常与安全测试

10.5 补偿与边界测试

十一、验收标准

十二、上线与监控方案

12.1 上线前准备清单

12.2 上线步骤

1. 执行建表（仅新增，不回滚旧结构）。
2. 部署代码（全部为新增文件，不动既有业务文件）。
3. 配置密钥与 settings（payment_gateway_enabled=0）。
4. 跑沙箱/小额真实交易验证 IT-01 ~ IT-06。
5. 按 4.8 节灰度阶段 1 → 2 → 3 推进。
6. 每阶段结束后核对：payment_reconcile（差异 0）、payment_notifies（无 sign_verified=0 聚集）、告警数。

12.3 监控与告警落地

12.4 回滚与应急预案

12.5 例行运维

• 每日：查看对账结果、REVIEW 队列、告警。
• 每周：抽查 5 笔退款与 5 笔入账的原始报文完整性。
• 每月：核对密钥/证书有效期；复核退款限额与审计日志；清理 payment_notifies 中超过保留期（建议 12 个月）的 payload（保留统计字段）。

十三、实施路线图

立即可做：P0-A 与 P0-B 不依赖任何渠道资质、域名或 HTTPS，且直接消除当前最严重的资金风险（P-04 重复到账、P-02 凭证不可读）。建议优先执行。

十四、需用户补充的阻断信息

以下信息缺失将导致对应模块无法实施（不是"可以猜"的问题）。请逐项确认。

14.1 硬阻断（缺失则无法接入官方支付）

14.2 业务规则（缺失则先按建议默认值实施并在文档标注）

14.3 现网风险确认

十五、假设清单

以下为本方案在信息不足时主动标注的假设。若与实情不符，需相应调整方案。

附录 A：本次交付边界声明

1. 本轮仅交付"审计 + 方案"文档，位于 docs/支付系统优化与官方支付接入方案.md。
2. 未改动任何业务代码、未新增/修改任何数据表、未新增依赖、未写生产库、未改 CMS_VERSION（仍为 v0.3.81）、未触碰面板核心与授权机制。
3. 文中的代码行号与表结构均来自本轮实际只读读取；环境能力（扩展、OpenSSL、MySQL 版本、nginx 配置、目录内容）均为实测。
4. 标注为「未验证」的内容（第五、1.5 节）无法在本环境完成验证：无真实渠道账号、无浏览器、无管理凭据。
5. 实施任何代码改动、建表、依赖引入前，需用户按第十四节确认阻断信息。

附录 B：与本项目既有 BUG 文档的关系