# 快速开始指南

本指南帮助你在 10 分钟内完成支付宝订阅产品的基本对接。

## 前置条件

- ✅ 已注册支付宝企业账号
- ✅ 已创建应用并获得 APPID
- ✅ 已配置加签方式和应用网关
- ✅ 已联系支付宝开通订阅产品权限

> 如未完成前置条件，请先参考 [merchant-onboarding.md](merchant-onboarding.md)

---

## 第一步：准备配置

### 1.1 获取密钥

从支付宝开放平台获取：
- AppID
- 商户私钥（本地生成）
- 支付宝公钥（平台获取）

### 1.2 配置文件

```yaml
# config.yaml
alipay:
  app_id: "你的APPID"
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    你的商户私钥
    -----END RSA PRIVATE KEY-----
  alipay_public_key: |
    -----BEGIN PUBLIC KEY-----
    支付宝公钥
    -----END PUBLIC KEY-----
  gateway_url: "https://openapi.alipay.com/gateway.do"
  notify_url: "https://your-domain.com/api/alipay/notify"
  return_url: "https://your-domain.com/subscription/success"
```

---

## 第二步：初始化商品

### 2.1 创建商品

```bash
# 调用 alipay.trade.product.create
curl -X POST 'https://openapi.alipay.com/gateway.do' \
  -d 'app_id=YOUR_APPID' \
  -d 'method=alipay.trade.product.create' \
  -d 'biz_content={"name":"AI会员专业版","description":"包含GPT-4等高级功能"}'
```

**保存返回的 `product_id`**

### 2.2 创建价格

```bash
# 月付价格：99元/月
curl -X POST 'https://openapi.alipay.com/gateway.do' \
  -d 'method=alipay.trade.price.create' \
  -d 'biz_content={
    "product_id":"上面获取的product_id",
    "unit_amount":9900,
    "recurring":{"interval":"MONTH","interval_count":1}
  }'
```

**保存返回的 `price_id`**

---

## 第三步：用户订阅流程

### 3.1 创建客户（用户注册时）

```go
// 用户在你的平台注册时，同步创建支付宝客户
customerResp, _ := alipayClient.CreateCustomer(&service.CustomerCreateRequest{
    Name:  "张三",
    Phone: "15012345678",
    Email: "zhangsan@example.com",
})
// 保存 customer_id 到数据库
```

### 3.2 创建订阅（用户点击订阅）

```go
// 用户选择套餐后，创建订阅
subResp, _ := alipayClient.CreateSubscription(&service.SubscriptionCreateRequest{
    CustomerId: customerID,  // 从数据库获取
    Items: []service.SubscriptionItem{
        {PriceId: priceID},  // 对应套餐的 price_id
    },
    SubscribeTitle: "AI会员专业版-月度订阅",
})

// 返回支付链接给前端
return gin.H{
    "pay_url": subResp.AlipaySchema,  // 前端跳转到此链接
}
```

### 3.3 前端跳转支付

```javascript
// 前端收到 pay_url 后
window.location.href = response.pay_url;
// 或生成二维码让用户扫码
```

---

## 第四步：处理异步通知

### 4.1 实现通知接口

```go
// POST /api/alipay/notify
func (h *WebhookHandler) AlipayNotify(c *gin.Context) {
    // 1. 解析参数
    c.Request.ParseForm()
    params := parseNotifyParams(c.Request.Form)

    // 2. 验证签名
    if !h.alipayClient.VerifyCallback(params) {
        c.String(400, "fail")
        return
    }

    // 3. 幂等处理（重要！）
    notifyID := params["notify_id"]
    if isProcessed(notifyID) {
        c.String(200, "success")
        return
    }

    // 4. 处理业务
    changeType := params["change_type"]
    switch changeType {
    case "active":
        // 首次支付成功，开通权益
        activateSubscription(params["subscription_id"])
    case "period_extend":
        // 续费成功，延长权益
        extendSubscription(params["subscription_id"])
    case "cancel":
        // 用户取消，标记订阅
        cancelSubscription(params["subscription_id"])
    }

    // 5. 标记已处理
    markProcessed(notifyID)

    // 6. 返回成功
    c.String(200, "success")
}
```

### 4.2 配置应用网关

在支付宝开放平台配置：
```
应用详情 → 开发设置 → 应用网关
→ 填写: https://your-domain.com/api/alipay/notify
```

---

## 第五步：查询订阅状态

```go
// 查询用户订阅状态
subResp, _ := alipayClient.QuerySubscription(&service.SubscriptionQueryRequest{
    CustomerId: customerID,
    SubscriptionStatus: "ACTIVE",  // 只查询活跃订阅
})

if len(subResp.Subscriptions) > 0 {
    // 用户有有效订阅
    sub := subResp.Subscriptions[0]
    fmt.Printf("订阅状态: %s, 到期时间: %s",
        sub.SubscriptionStatus,
        sub.CurrentPeriodEnd)
}
```

---

## 完整流程图

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   商户后台   │     │   支付宝    │     │    用户     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │ 1. 创建商品/价格   │                   │
       │──────────────────>│                   │
       │<──────────────────│                   │
       │   product_id      │                   │
       │   price_id        │                   │
       │                   │                   │
       │                   │  2. 用户注册      │
       │<──────────────────────────────────────│
       │                   │                   │
       │ 3. 创建客户       │                   │
       │──────────────────>│                   │
       │<──────────────────│                   │
       │   customer_id     │                   │
       │                   │                   │
       │                   │  4. 用户点击订阅  │
       │<──────────────────────────────────────│
       │                   │                   │
       │ 5. 创建订阅       │                   │
       │──────────────────>│                   │
       │<──────────────────│                   │
       │   pay_url         │                   │
       │                   │                   │
       │                   │  6. 跳转支付      │
       │                   │<──────────────────│
       │                   │                   │
       │ 7. 异步通知       │                   │
       │<──────────────────│                   │
       │                   │                   │
       │ 8. 开通权益       │                   │
       │                   │                   │
       │                   │  9. 支付成功页面  │
       │                   │──────────────────>│
       │                   │                   │
```

---

## 常见问题速查

| 问题 | 解决方案 |
|-----|---------|
| 验签失败 | 检查是否使用「支付宝公钥」验签 |
| items 参数缺失 | `items` 必须是数组：`[{"price_id":"xxx"}]` |
| 收不到通知 | 检查应用网关配置、返回格式是否正确 |
| 重复通知 | 根据 `notify_id` 实现幂等处理 |

详细排查请参考 [troubleshooting.md](troubleshooting.md)

---

## 下一步

- 查看完整 API 示例：[api-examples.md](api-examples.md)
- 了解数据模型：[data-model-reference.md](data-model-reference.md)
- 参考代码实现：[code-example-go.md](code-example-go.md)