# 支付对接配置指南

> 适用版本：LiteMall 轻商城 V1.0
> 更新日期：2026-06-13

---

## 一、系统概述

LiteMall 支付模块支持三种模式：

| 模式 | 说明 | 是否需要商户号 | 适用场景 |
|------|------|---------------|----------|
| **模拟模式**（默认） | 点击确认即支付成功 | 不需要 | 开发测试、演示、著作权核验 |
| **微信支付** | 真实扣款 | 需要微信商户号 | 正式上线 |
| **支付宝支付** | 真实扣款 | 需要支付宝商户号 | 正式上线 |

**模式切换**：系统设置 → 支付配置 → `payment_test_mode` 设为"0"即为生产模式

---

## 二、模拟模式使用（无需配置）

系统默认运行在模拟模式，无需任何配置即可使用：
- 创建订单 → 选择支付方式 → 弹出模拟支付页面 → 点击「模拟支付成功」
- 订单状态自动变为待发货
- 支持退款申请 → 管理员审核 → 退款完成

---

## 三、微信支付正式对接

### 3.1 前置条件

1. 已认证的**微信服务号**（获取 appid）或 **微信小程序**（获取 appid）
2. 已开通的**微信支付商户号**（https://pay.weixin.qq.com）
3. 商户号已关联对应的公众号/小程序 AppId
4. **API 密钥**（商户平台 → 账户中心 → API安全 → 设置API密钥）

### 3.2 配置项

登录管理后台 → **系统设置 → 支付配置**，填写以下参数：

| 配置键 | 字段名 | 说明 | 获取方式 |
|--------|--------|------|----------|
| `wechat_appid` | 微信AppId | 公众号/小程序的AppID | 微信公众平台 → 开发 → 基本配置 |
| `wechat_mchid` | 微信商户号 | 微信支付商户号ID | 微信支付商户平台 → 账户中心 |
| `wechat_key` | 微信API密钥 | 32位密钥，用于签名 | 商户平台 → API安全 → 设置密钥 |
| `wechat_appsecret` | 公众号Secret | JSAPI支付需要 | 公众平台 → 开发 → 基本配置 |
| `wechat_notify_url` | 回调通知URL | 支付结果通知地址 | 系统自动填充：`{站点域名}/api/payment/notify` |
| `wechat_cert_path` | 商户证书路径 | 退款API需要 | 商户平台 → API安全 → 下载证书 |
| `payment_test_mode` | 测试模式 | 设为 **0** 启用正式支付 | — |
| `payment_wechat_enabled` | 微信支付开关 | 设为 **1** 开启 | — |

### 3.3 回调地址配置

在微信商户平台 → 产品中心 → 开发配置，设置支付回调域名：

```
http://您的域名/api/payment/notify   （用于接收支付结果通知）
```

### 3.4 联调测试步骤

```
1. 后台填写微信支付参数，payment_test_mode = 0
2. 前端选择微信支付下单
3. 观察返回参数：
   - JSAPI支付：返回 prepay_id + jsParams 供前端调起微信支付
   - Native支付：返回 code_url，生成二维码扫码支付
4. 完成支付后：
   - 微信异步通知 => /api/payment/notify
   - 订单状态自动变更为 "待发货"
5. 查看支付日志验证回调是否正常
   - GET /api/payment/logs
```

### 3.5 支持的支付方式

| 方式 | 适用场景 | 实现 |
|------|----------|------|
| **JSAPI** | 微信内H5/公众号/小程序 | 前端调用 wx.chooseWXPay() |
| **Native** | PC扫码支付 | 生成二维码链接 |
| **MWEB(H5)** | 手机浏览器支付 | 302跳转到微信中间页 |

---

## 四、支付宝支付正式对接

### 4.1 前置条件

1. 已注册**支付宝开放平台**账号（https://open.alipay.com）
2. 已创建**网页/移动应用**并获取 APPID
3. 已配置**RSA2(SHA256)密钥**（推荐使用开放平台助手生成）
4. 应用已签约**手机网站支付**和/或**电脑网站支付**产品

### 4.2 配置项

| 配置键 | 字段名 | 说明 | 获取方式 |
|--------|--------|------|----------|
| `alipay_appid` | 支付宝APPID | 应用的唯一标识 | 开放平台 → 应用详情 |
| `alipay_private_key` | 应用私钥 | RSA2私钥(PKCS8格式) | 开放平台 → 密钥管理 → 生成 |
| `alipay_public_key` | 支付宝公钥 | 用于验证支付宝通知 | 开放平台 → 密钥管理 → 查看 |
| `alipay_notify_url` | 异步通知URL | 支付结果通知 | 系统自动填充：`{域名}/api/payment/alipay-notify` |
| `alipay_return_url` | 同步跳转URL | 支付成功跳转页 | 可选，如：`{域名}/mobile/#/order` |
| `alipay_sandbox` | 沙箱模式 | 设为1使用沙箱环境 | 开放平台 → 沙箱应用 |
| `payment_test_mode` | 测试模式 | 设为 **0** 启用正式支付 | — |
| `payment_alipay_enabled` | 支付宝支付开关 | 设为 **1** 开启 | — |

### 4.3 密钥生成（重要）

**推荐使用支付宝开放平台助手**（https://opendocs.alipay.com/common/02kipk）

```
1. 下载"支付宝开放平台开发助手"
2. 选择密钥长度：RSA2
3. 生成并保存私钥（PKCS8格式）→ 填写到 alipay_private_key
4. 上传公钥到开放平台 → 获取支付宝公钥 → 填写到 alipay_public_key
```

### 4.4 回调地址配置

支付宝开放平台 → 应用详情 → 开发配置：

```
接口加签方式：公钥模式
应用网关：http://您的域名
授权回调地址：http://您的域名/api/payment/alipay-notify
```

### 4.5 联调测试步骤

```
1. 后台填写支付宝参数，payment_test_mode = 1（先用沙箱）
2. 前端选择支付宝支付下单
3. /api/payment/create 返回 pay_url 或 pay_form
4. 用户跳转到支付宝页面完成支付
5. 支付宝异步通知 => /api/payment/alipay-notify
6. 订单状态自动变更为 "待发货"
7. 测试通过后，payment_test_mode = 0 切换为正式
```

---

## 五、支付能力检测

前端可通过以下接口获取当前支付能力：

```http
GET /api/payment/capabilities
```

返回示例：
```json
{
  "code": 0,
  "data": {
    "mode": "simulate",
    "is_simulate": true,
    "wechat_configured": false,
    "alipay_configured": false,
    "wechat_enabled": true,
    "alipay_enabled": true
  }
}
```

- `mode`: `simulate`（模拟）或 `production`（生产）
- `wechat_configured`: 微信商户号是否已配置
- `alipay_configured`: 支付宝APPID是否已配置
- `wechat_enabled` / `alipay_enabled`: 是否显示该支付选项

---

## 六、API接口清单

| 接口 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/payment/create` | POST | 创建支付 | 用户 |
| `/api/payment/notify` | POST | 微信/支付宝统一回调 | 无 |
| `/api/payment/alipay-notify` | POST | 支付宝独立回调 | 无 |
| `/api/payment/status/:orderNo` | GET | 查询支付状态 | 用户 |
| `/api/payment/capabilities` | GET | 支付能力检测 | 无 |
| `/api/payment/mock-pay` | GET | 模拟支付页面 | 无 |
| `/api/payment/mock-notify` | POST | 模拟支付通知 | 无 |
| `/api/payment/h5-pay` | GET | 微信H5支付跳转 | 无 |
| `/api/payment/query/:tradeNo` | GET | 交易查询 | 管理 |
| `/api/payment/refund/create` | POST | 创建退款 | 用户 |
| `/api/payment/refund/process` | POST | 审核退款 | 管理 |
| `/api/payment/refunds` | GET | 退款列表 | 管理 |
| `/api/payment/refund/my` | GET | 我的退款 | 用户 |
| `/api/payment/timeout-cancel` | POST | 超时关单 | 无 |
| `/api/payment/logs` | GET | 支付日志 | 管理 |

---

## 七、架构文件清单

```
server/src/lib/payment/
├── index.js          # 统一入口（策略选择、错误降级）
├── wechat.js         # 微信支付 SDK（统一下单/验签/查询/退款）
├── alipay.js         # 支付宝 SDK（页面支付/验签/查询/退款）
├── utils.js          # 工具函数（签名/XML/HTTP/随机数）
├── logger.js         # 支付日志（数据库+控制台双输出）
```

---

## 八、注意事项

1. **线上切换**：先 `payment_test_mode = 1` 在沙箱/测试环境验证，确认回调正常再切正式
2. **回调安全**：微信/支付宝的回调接口 `/notify` 和 `/alipay-notify` 包含签名验证，请勿修改
3. **日志排查**：支付异常先查 `/api/payment/logs` 了解错误详情
4. **退款流程**：生产模式下，退款审核通过后会异步调起微信/支付宝退款API
5. **证书**：微信退款需要商户证书（p12/pem），不配置证书时退款仅本地标记，不退实际款项
6. **超时关单**：系统每5分钟自动检查，30分钟未支付订单自动关闭
