# 安装与测试说明

版本 0.1.0。WooCommerce / EDD 已通过生产小额支付、原生订单入账和重复回调验证；WHMCS 仍为测试适配版。需要 PHP 8.1+、cURL、HTTPS、持久文件目录；启用前请核对自己的平台版本和结账方式。

## 共同配置

1. 解压插件，将 `config.example.php` 复制到网站公开目录之外，例如 `/home/shop-private/uugate.php`。
2. 填写商户自己的 `merchant_uid`、`api_key`，配置其中一种受支持的 `asset`。
3. 创建独立、持久、仅 PHP 运行用户可读写的订单目录，例如 `/home/shop-private/uugate-orders`。设置 `state_dir` 指向该目录，建议目录权限 0700。备份时必须同时备份店铺数据库与这个目录；多台店铺节点必须共享支持可靠文件锁的同一目录。不要使用临时目录或公开上传目录。
4. 在店铺 PHP 运行环境中设置 `UUGATE_CONFIG_FILE` 为该配置文件的绝对路径。例如 PHP-FPM 池配置：`env[UUGATE_CONFIG_FILE] = /home/shop-private/uugate.php`。由店铺维护者按自己的环境加载配置。
5. 每个店铺和测试环境使用不同 `store_id`。创建订单后不要更改店铺标识、资产或商户 UID；密钥轮换时先处理完未完成订单。下单与回调验签共用同一个 `api_key`，无需额外密钥。
6. 店铺以所选稳定币计价即可使用。若店铺以 USD 计价，须将 `usd_at_par` 显式设为 `true`，表示商户接受 1 USD = 1 USDT/USDC 的计价政策。这不是汇率报价或法币兑换。其他法币会被拒绝。

## WooCommerce

目标接口：WooCommerce 的 `WC_Payment_Gateway`、订单 CRUD、HPOS 和 Checkout Blocks。已在 WordPress 7.1 / WooCommerce 11.1.0 / PHP 8.2.9 / MySQL 5.7.26 验证原生订单和 HTTP 网关回调；Checkout Blocks 的浏览器完整结账及其他版本兼容仍待验收。

1. WordPress 后台“插件 → 安装插件 → 上传插件”上传 WooCommerce ZIP，启用。
2. WooCommerce“设置 → 付款”启用 UUGate，可修改结账名称和说明。
3. 回调地址为店铺的 `?wc-api=uugate`，由插件传给 UUGate。
4. 分别验证经典结账和区块结账。只有有效回调才能调用 `payment_complete`；不提前清空待付款订单或按浏览器跳转发货。

## Easy Digital Downloads

目标接口：EDD 3.x 的兼容 `EDD_Payment` API。已在 WordPress 7.1 / EDD 3.7.0 / PHP 8.2.9 / MySQL 5.7.26 验证原生订单和 HTTP 网关回调；其他版本兼容仍待验收。不支持循环订阅。

1. WordPress 后台上传 EDD ZIP，启用插件。
2. EDD“设置 → 支付”启用 UUGate。
3. 回调地址为店铺的 `?edd-listener=uugate`。
4. 验证待付款订单不会开放付费下载，验签并确认足额完成后才变为 complete。

## WHMCS

目标接口：WHMCS 8.x 第三方支付网关 API；完整平台版本兼容尚未实测。不支持自动续费扣款。

1. 解压，把 `modules/` 合并到 WHMCS 根目录。
2. 在 WHMCS“支付网关”中启用 UUGate。
3. 回调路径：`/modules/gateways/callback/uugate.php`，由插件根据 WHMCS 系统 URL 生成。
4. 未付款账单显示支付链接。回调按当前账单未付余额核对；付款期间若账单被部分支付、取消或切换网关，将进入人工核对，不自动重复入账。

## 异常恢复

UUGate 当前创建订单接口没有商户订单号查单/幂等重试保证，因此网络超时后不能直接重发下单。

- `creating`：创建结果不确定。先在 UUGate 按文件中的 `merchantOrderNo` 查找订单。若已收款，有效回调可补齐平台订单号；若仍待付款，维护者核实后补回 `orderNo`、`cashierUrl` 并设 `phase=pending`。只有确认平台没有创建订单后才能设 `phase=rejected` 允许再次尝试。
- `applying`：已验证付款，但店铺写入中断。先按 `orderNo` 核对原生店铺付款记录、发货/下载记录。确认所有入账操作成功后才能设为 `completed`；只有确认没有发生副作用、或已按店铺原生事务回滚后，才能改为 `pending` 并重放回调。存在部分完成时由店铺维护者补全，不能直接重试。
- 已过期订单保留原始记录，不自动创建第二笔付款单。维护者核对无付款后按业务需要新建店铺订单。

只在停止处理对应订单时维护日志文件，保留备份。普通签名错误、金额不符、平台尚未确认等不会更新店铺付款状态。

## 验收边界

本地测试覆盖 PHP 语法、支付协议、金额/状态校验、重复通知保护，以及 WooCommerce / EDD 的真实平台代码、隔离数据库和 HTTP 下单 / 回调入口。2026-09-15 已通过原生插件调用生产 UUGate 下单，完成两笔真实 TRC20-USDT 付款；保留原签名的真实通知转送本机 HTTP 插件入口，首次与重复回调均返回 200，两平台各只有一条付款记录且交易号匹配。验证使用官方开发者接收器转送到本机；商户实际公网部署、其他链路和平台版本、Checkout Blocks 的浏览器完整流程仍需按自己的环境验收。WHMCS 只有平台接口模拟，保留测试版。不支持自动退款或循环扣款。