# 架构概述

本文档描述了 Antom Payments for WooCommerce 插件的架构和设计。

## 系统分层

```
┌──────────────────────────────────────────────────────────────┐
│                    WooCommerce 商店                           │
├──────────────┬──────────────────┬────────────────────────────┤
│  经典结算    │  区块结算         │  订单支付页面              │
│  (PHP)       │  (React)         │  (重新支付)                │
├──────────────┴──────────────────┴────────────────────────────┤
│                    支付网关层 (PHP)                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ Payments │ │  Card    │ │ AlipayCN │ │  ...     │        │
│  │  (CKP)   │ │(Elements)│ │(钱包)    │ │(钱包)    │        │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
│       └────────────┼────────────┼────────────┘              │
│                    ▼                                         │
│              ┌───────────┐                                   │
│              │  公共网关  │  process_payment、               │
│              │  (Common)  │  webhook、退款 共享逻辑          │
│              └─────┬─────┘                                   │
│                    ▼                                         │
│  ┌──────────────────────────────────────┐                    │
│  │            SDK 层                    │                    │
│  │  Client → Signature → HTTP RPC       │                    │
│  │  Request Builder (支付/会话/退款)      │                   │
│  └─────────────┬────────────────────────┘                    │
│                ▼                                             │
│  ┌──────────────────────────────────────┐                    │
│  │          数据模型层                  │                    │
│  │  Order / Amount / Buyer / Env /      │                    │
│  │  Settlement / PaymentMethod / Refund │                    │
│  └──────────────────────────────────────┘                    │
└─────────────────────────┬────────────────────────────────────┘
                          │
                          ▼
               ┌─────────────────────┐
               │    Antom API        │
               │  open-sea.alipay    │
               │  .com               │
               └─────────────────────┘
```

## 分层说明

### 1. 表示层

插件支持两种结算模式：

- **经典结算 (Classic Checkout)** — 标准 WooCommerce 结算页面，服务端渲染支付字段
- **区块结算 (Block Checkout)** — 基于 React 的 WooCommerce Block Checkout，具有自定义 JavaScript 前端组件

前端源码位于 `resource/` 目录，编译后输出到 `assets/`。

### 2. 网关层

每种支付方式都是一个独立的 WooCommerce 支付网关类，继承自 `WC_Gateway_Antom_Common`：

| 类名 | 文件 | 支付方式 |
|---|---|---|
| `WC_Gateway_Antom_Payments` | `gateways/class-wc-gateway-antom-payments.php` | 收银台支付 (CKP) — 聚合所有方式 |
| `WC_Gateway_Antom_Card` | `gateways/class-wc-gateway-antom-card.php` | 信用卡/借记卡 (Antom Elements) |
| `WC_Gateway_Antom_Alipay_CN` | `gateways/class-wc-gateway-antom-alipay-cn.php` | 支付宝（中国大陆） |
| `WC_Gateway_Antom_Alipay_HK` | `gateways/class-wc-gateway-antom-alipay-hk.php` | 支付宝（香港） |
| `WC_Gateway_Antom_Dana` | `gateways/class-wc-gateway-antom-dana.php` | DANA（印度尼西亚） |
| `WC_Gateway_Antom_GCash` | `gateways/class-wc-gateway-antom-gcash.php` | GCash（菲律宾） |
| `WC_Gateway_Antom_Kakao_Pay` | `gateways/class-wc-gateway-antom-kakao-pay.php` | Kakao Pay（韩国） |
| `WC_Gateway_Antom_Naver_Pay` | `gateways/class-wc-gateway-antom-naver-pay.php` | Naver Pay（韩国） |
| `WC_Gateway_Antom_Tng` | `gateways/class-wc-gateway-antom-tng.php` | Touch 'n Go（马来西亚） |
| `WC_Gateway_Antom_Toss_Pay` | `gateways/class-wc-gateway-antom-toss-pay.php` | Toss Pay（韩国） |
| `WC_Gateway_Antom_True_Money` | `gateways/class-wc-gateway-antom-true-money.php` | TrueMoney（泰国） |

#### 公共网关 (`WC_Gateway_Antom_Common`)

提供共享功能的抽象基类：

- `process_payment($order_id)` — 核心支付处理
- `payment_notify_handler()` — Webhook 通知处理
- `inquiry_handler()` — 支付状态查询处理
- `process_refund($order_id, $amount, $reason)` — 退款处理
- 币种筛选和显示逻辑
- 设置表单字段生成

#### 区块支持

每个网关都有对应的区块支持类（位于 `includes/blocks/`），通过 WooCommerce Blocks 集成 API 实现区块结算兼容性。

### 3. 区块结算前端

`resource/` 目录包含每种支付方式的 React 组件：

- **区块组件** (`resource/blocks/`) — 每种支付方式一个 JS 文件，注册为 WooCommerce Blocks 支付方式集成
- **共享组件** (`resource/components/`) — 用于卡字段、标签和警告的可复用 React 组件
- **自定义 Hooks** (`resource/hooks/`) — 用于设置和 API 交互的 React hooks
- **CSS** (`resource/css/`) — 编译到 `assets/css/` 的 SCSS 源文件

构建工具链：JavaScript 使用 Webpack（`wp-scripts`），CSS 使用 Sass。

### 4. SDK 层

SDK 处理与 Antom API 的所有通信：

| 组件 | 文件 | 职责 |
|---|---|---|
| `Antom_Alipay_Client` | `sdk/antom-alipay-client.php` | HTTP 客户端：签名、请求、响应处理 |
| `Antom_Signature_Tool` | `sdk/antom-signature-tool.php` | RSA-SHA256 签名生成和验证 |
| `Antom_Http_Rpc_Result` | `sdk/antom-http-rpc-result.php` | RPC 响应解析 |
| `SDK_Antom_Alipay_Request` | `sdk/sdk-antom-alipay-request.php` | 基础请求构建器 |
| `SDK_Antom_Alipay_Online_Request` | `sdk/sdk-antom-alipay-online-request.php` | 在线支付请求构建器 |
| `SDK_Antom_Alipay_Inquiry_Request` | `sdk/sdk-antom-alipay-inquiry-request.php` | 支付查询请求构建器 |

**请求流程：**

1. 网关使用订单数据调用 SDK
2. 请求构建器构造包含所需参数的 API 请求
3. 签名工具生成 RSA-SHA256 签名
4. HTTP 客户端将签名后的请求发送到 Antom API
5. 接收响应并验证签名
6. 结果解析后返回给网关

### 5. 数据模型层

数据模型封装了请求/响应数据结构：

- **订单模型** — 订单金额、买家信息、环境、支付方式、结算策略
- **退款模型** — 退款请求/响应数据

### 6. 管理后台层

`Antom_Admin` 类（单例模式）处理：

- 欢迎页面渲染（新安装时）
- 核心设置页面渲染和保存
- 订单列表筛选器和栏目
- 支付方式排序和可见性
- 异常订单警告

## 关键流程

### 支付流程（数字钱包）

```
客户点击"下订单"
        │
        ▼
Gateway::process_payment()
        │
        ├─► 构建订单模型（金额、买家、环境等）
        ├─► SDK::create_payment_session()
        │       │
        │       └─► Antom API → 返回 paymentUrl / formHtml
        │
        └─► 返回跳转 URL 或支付表单
                │
                ▼
        客户在 Antom 收银台页面完成支付
                │
                ▼
        Antom 发送 Webhook 通知
        ──► payment_notify_handler()
                │
                ├─► 验证签名
                ├─► 更新订单状态
                └─► 跳转到订单接收页面
```

### 卡支付流程（Antom Elements）

```
客户输入卡信息
        │
        ▼
Antom Elements SDK（客户端加密）
        │
        ▼
AJAX → antom_ajax_create_payment_session()
        │
        ├─► SDK::create_payment_session()
        └─► 返回 paymentSession 数据
                │
                ▼
客户确认支付
        │
        ▼
Gateway::process_payment() → SDK → Antom API
        │
        ▼
处理支付结果
```

### 退款流程

```
管理员在 WooCommerce 中点击"退款"
        │
        ▼
Gateway::process_refund()
        │
        ├─► 构建退款模型
        ├─► SDK → Antom API（退款请求）
        └─► 更新订单为已退款状态
```

## 插件启动

插件入口文件为 `antom-payments-gateway.php`：

1. **定义常量** — 插件文件路径、版本、URL
2. **WooCommerce 检查** — 激活时验证 WooCommerce 是否已启用
3. **文件加载** (`antom_includes()`)：
   - 工具类（选项管理、请求检查器）
   - 设置和常量定义
   - 公共函数
   - 管理后台或前端类
   - 所有网关类（在 `antom_get_payment_methods()` 中注册）
   - 区块支持类
   - 表单 API
4. **国际化** — 加载文本域以支持多语言

## 支付方式注册

支付方式在 `antom_get_payment_methods()` (`includes/antom-payment-gateway-settings.php`) 中定义。每种方式包括：

- `gateway_file` — PHP 网关类文件路径
- `gateway_class` — WooCommerce 网关类名
- `block_file` — 区块支持类文件路径
- `block_support_class` — 区块支持类名
- `slug` — 唯一标识符（例如 `antom_alipay_cn`）
- `payment_method_type` — Antom API 支付方式类型（例如 `ALIPAY_CN`）
- `support_currencies` — 支持的币种代码数组
- `icon` — 支付方式图标 URL

列表可通过 `antom_payment_gateway_settings` 钩子进行过滤。

## 安全架构

- **卡数据** — 所有卡数据通过 Antom Elements SDK 在客户端加密；无明文卡数据触及商家服务器
- **API 签名** — 所有请求使用商家的 RSA 私钥签名；响应使用 Antom 公钥验证
- **Nonce 验证** — AJAX 端点使用 WordPress nonce 进行 CSRF 防护
- **输入消毒** — 所有用户输入通过 WordPress 核心函数（`sanitize_text_field`、`absint` 等）消毒
- **支付请求 ID** — 每笔支付使用唯一 ID 以防止重放攻击

## 配置存储

插件设置存储在 WordPress `wp_options` 表中，前缀为 `antom_payment_gateway_`，由单例类 `Antom_Payment_Gateways_Options` 管理。

## 参见

- [支付方式](payment-methods.md) — 支持的方式和币种
- [Webhook 与 API 参考](webhook-api.md) — Webhook 和 SDK API 详情
- [开发指南](development.md) — 构建和开发