# 开发指南

本指南涵盖如何设置开发环境、构建资源和为 Antom Payments for WooCommerce 做贡献。

## 前提条件

- **Node.js**（推荐 LTS 版本 — 18.x 或 20.x）
- **npm**（随 Node.js 捆绑）
- **PHP** 7.2 或更高版本
- **Composer**（用于 PHP 依赖管理和代码检查）
- **WooCommerce**（用于测试的本地安装）
- **WordPress**（用于测试的本地安装）

## 设置

### 1. 克隆仓库

```bash
git clone <repository-url>
cd woo-antom-paymnets
```

### 2. 安装 Node 依赖

```bash
npm install
```

安装的依赖包括：
- `@wordpress/scripts` — WordPress 构建工具链（Webpack、Babel、ESLint）
- `@woocommerce/dependency-extraction-webpack-plugin` — WooBlocks 依赖管理
- `sass` — SCSS 编译
- `@alipay/ams-checkout` — Antom Elements SDK（卡支付）
- `credit-card-type` — 卡品牌检测工具

### 3. 安装 PHP 依赖（用于代码检查）

```bash
composer install
```

## 开发命令

### 启动监听模式

```bash
# 同时运行 Block JS 和 CSS 监听器
npm start

# 或单独运行：
npm run start:blocks   # Webpack 监听模式 → 编译到 assets/blocks/
npm run start:css      # Sass 监听模式 → 编译到 assets/css/
```

### 生产构建

```bash
# 构建 Block JS + CSS（压缩 + 源码映射）
npm run build

# 或单独运行：
npm run build:blocks   # 生产 Webpack 构建
npm run build:css      # 生产 Sass 构建（压缩 + 源码映射）
```

### 代码检查

```bash
# PHP CodeSniffer
npm run lint:php

# 自动修复 PHP 问题
npm run lint:php-fix
```

## 开发目录结构

### 前端源码

```
resource/
├── blocks/          # WooCommerce Block Checkout React 组件
│   ├── alipay_cn.js
│   ├── alipay_hk.js
│   ├── card.js
│   ├── dana.js
│   ├── gcash.js
│   ├── kakao_pay.js
│   ├── naver_pay.js
│   ├── payments.js     # CKP（收银台支付）区块
│   ├── tng.js
│   ├── toss_pay.js
│   └── true_money.js
├── components/      # 共享 React 组件
│   ├── antom-card-fields.js     # 卡字段渲染（Elements SDK）
│   ├── card-pay-fields.js        # 卡支付集成
│   ├── custom-label.js
│   ├── default-content.js
│   ├── dynamic-label.js
│   └── test-mode-warning.js
├── hooks/
│   └── useAntomPaymentsSettings.js
└── css/             # SCSS 源文件
    ├── antom-payments-b27-admin.scss
    ├── antom-payments-b27-frontend.scss
    ├── antom-payments-gateway-admin.scss
    ├── antom-payments-gateway-frontend.scss
    └── antom-settings-payments.scss
```

### 前端构建输出

```
assets/
├── blocks/          # 编译的 Block JS（入口点 + asset.php 清单）
├── css/             # 编译的 CSS（生产环境附带源码映射）
└── js/              # 第三方 JS 库和前端/后端脚本
```

### 添加新的支付方式

要添加新的支付方式：

1. 创建网关类：`includes/gateways/class-wc-gateway-antom-{method}.php`
   - 继承 `WC_Gateway_Antom_Common`
   - 实现 `process_payment()` 和方式特定的逻辑

2. 创建区块支持类：`includes/blocks/class-wc-gateway-antom-{method}-block-support.php`
   - 继承 `WC_Gateway_Antom_Block_Support_Common`

3. 创建区块组件：`resource/blocks/{method}.js`
   - 通过 WooCommerce Blocks 注册表的 `registerPaymentMethod` 注册

4. 在 `includes/antom-payment-gateway-settings.php` 的 `antom_get_payment_methods()` 中注册

5. 添加方式图标：`assets/images/{Method}-A+.svg`

6. 构建资源：
   ```bash
   npm run build
   ```

## PHP 编码标准

本项目遵循 WordPress PHP 编码标准。PHP 代码检查使用带有 `phpcs.xml` 配置文件的 PHP CodeSniffer。

```bash
# 检查 PHP 文件
npm run lint:php

# 自动修复问题
npm run lint:php-fix
```

## JavaScript 构建配置

项目使用 `@wordpress/scripts`（Webpack）构建 JavaScript。`webpack.config.js` 中的关键配置点：

- **入口点** — `resource/blocks/` 中的每个区块 JS 文件都是一个独立的入口点
- **输出** — 编译后的文件输出到 `assets/blocks/`
- **依赖提取** — WooCommerce 和 WordPress 依赖项被外部化（不打包）

## 版本兼容性

| 组件 | 最低版本 | 测试至 |
|---|---|---|
| WordPress | 5.3 | 6.9 |
| WooCommerce | 8.0+ | 9.0.0 |
| PHP | 7.2 | 8.x |
| HPOS | 是 | 最新 |

## 国际化

插件已准备好翻译，文本域为 `antom-payments`。

- 语言文件位置：`/languages/`
- 使用的翻译函数：`__()`、`esc_html__()`、`esc_html_e()`

生成用于翻译的 `.pot` 文件：

```bash
wp i18n make-pot . languages/antom-payments.pot
```

## 测试

### 手动测试

1. 设置本地 WordPress + WooCommerce 安装
2. 在插件设置中启用**测试模式**
3. 使用 Antom 商家门户的沙箱凭据
4. 使用不同的支付方式下测试订单
5. 检查订单状态和 Webhook 通知

### 自动化测试说明

插件目前不包含自动化单元或集成测试。测试覆盖为手动方式。欢迎贡献添加测试覆盖。

## 调试

在 `wp-config.php` 中启用 WordPress 调试模式：

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

日志写入 `/wp-content/debug.log`。记录的关键事件：
- 支付会话创建请求和响应
- Webhook 通知接收
- 支付查询结果
- 退款处理
- 错误条件和异常

## Git 工作流程

```bash
# 创建功能分支
git checkout -b feature/my-feature

# 修改并提交
git add .
git commit -m "feat: description of the change"

# 变基到最新的 master
git checkout master
git pull
git checkout feature/my-feature
git rebase master

# 推送并创建 PR
git push origin feature/my-feature
```

### 提交消息规范

使用约定式提交格式：
- `feat:` — 新功能
- `fix:` — 错误修复
- `chore:` — 维护任务
- `docs:` — 文档变更
- `refactor:` — 代码重构
- `style:` — 代码样式/格式化（非功能性）

## 参见

- [架构概述](architecture.md) — 系统架构
- [Webhook 与 API 参考](webhook-api.md) — API 详情
- [配置指南](configuration.md) — 设置参考