Files

Made-with: Cursor

2026-03-07 22:58:43 +08:00

7.4 KiB

Raw Permalink Blame History

支付相关接口清单

日期: 2026-02-04
说明: 所有支付相关后端API接口的完整清单

✅ 已创建的接口

1. 小程序支付接口

`/api/miniprogram/pay` (POST)

功能: 创建支付订单并调用微信支付

文件: app/api/miniprogram/pay/route.ts

请求参数:

{
  "openId": "oXXXX...",
  "productType": "section",  // 'section' | 'fullbook'
  "productId": "1-1",
  "amount": 9.9,
  "description": "章节1-1",
  "userId": "user_xxx"
}

{
  "success": true,
  "data": {
    "orderSn": "MP20260204123456789012",
    "prepayId": "wx...",
    "payParams": {
      "timeStamp": "...",
      "nonceStr": "...",
      "package": "prepay_id=...",
      "signType": "MD5",
      "paySign": "..."
    }
  }
}

关键逻辑:

✅ 插入订单到 orders 表 (status='created')
✅ 检查是否已有该产品的已支付订单
✅ 调用微信统一下单接口
✅ 返回支付参数

`/api/miniprogram/pay/notify` (POST)

功能: 接收微信支付回调通知

文件: app/api/miniprogram/pay/notify/route.ts

请求: 微信发送XML格式数据

返回: XML格式响应

关键逻辑:

✅ 验证签名
✅ 更新订单状态为 paid（或补记订单）
✅ 解锁用户权限
✅ 分配推荐佣金（90%）
✅ 清理相同产品的其他未支付订单

2. 用户购买状态接口

`/api/user/purchase-status` (GET)

功能: 查询用户的购买状态

文件: app/api/user/purchase-status/route.ts

请求:

GET /api/user/purchase-status?userId=user_xxx

{
  "success": true,
  "data": {
    "hasFullBook": false,
    "purchasedSections": ["1-1", "1-2"],
    "purchasedCount": 2,
    "earnings": 0,
    "pendingEarnings": 0
  }
}

查询逻辑:

-- 1. 查询全书权限
SELECT has_full_book FROM users WHERE id = ?

-- 2. 查询已购章节（基于 orders 表）
SELECT DISTINCT product_id 
FROM orders 
WHERE user_id = ? 
  AND status = 'paid' 
  AND product_type = 'section'

`/api/user/check-purchased` (GET)

功能: 检查用户是否已购买指定产品

文件: app/api/user/check-purchased/route.ts

请求:

GET /api/user/check-purchased?userId=user_xxx&type=section&productId=1-1

{
  "success": true,
  "data": {
    "isPurchased": true,
    "reason": "section_order_exists"
  }
}

可能的 reason 值:

has_full_book: 用户已购买全书
fullbook_order_exists: 有全书的已支付订单
section_order_exists: 有该章节的已支付订单
null: 未购买

查询逻辑:

-- 1. 检查全书权限
SELECT has_full_book FROM users WHERE id = ?

-- 2. 检查是否有该产品的已支付订单
SELECT COUNT(*) as count
FROM orders 
WHERE user_id = ? 
  AND product_type = ? 
  AND product_id = ?
  AND status = 'paid'

3. 通用支付接口（未使用）

`/api/payment/create-order` (POST)

功能: 通用支付订单创建接口

文件: app/api/payment/create-order/route.ts

说明:

⚠️ 小程序实际使用的是 /api/miniprogram/pay
这个接口是为 Web 端设计的通用支付接口
支持多种支付方式（微信、支付宝、USDT）

`/api/payment/wechat/notify` (POST)

功能: 通用微信支付回调

文件: app/api/payment/wechat/notify/route.ts

说明:

⚠️ 小程序实际使用的是 /api/miniprogram/pay/notify
这个接口是为 Web 端设计的

📊 接口调用流程

【小程序支付流程】

1. 用户点击购买
   ↓
2. 前端调用 /api/user/purchase-status
   (查询是否已购买)
   ↓
3. 如果未购买，前端调用 /api/miniprogram/pay
   (创建订单 + 获取支付参数)
   ↓
4. 小程序调起微信支付
   ↓
5. 用户完成支付
   ↓
6. 微信回调 /api/miniprogram/pay/notify
   (更新订单 + 解锁权限 + 分配佣金 + 清理无效订单)
   ↓
7. 前端支付成功后调用 /api/user/purchase-status
   (刷新用户购买状态)

🔧 测试命令

1. 测试查询购买状态

curl "http://localhost:30006/api/user/purchase-status?userId=user_xxx"

预期结果:

{
  "success": true,
  "data": {
    "hasFullBook": false,
    "purchasedSections": [],
    "purchasedCount": 0,
    "earnings": 0,
    "pendingEarnings": 0
  }
}

2. 测试检查是否已购买

curl "http://localhost:30006/api/user/check-purchased?userId=user_xxx&type=section&productId=1-1"

预期结果:

{
  "success": true,
  "data": {
    "isPurchased": false,
    "reason": null
  }
}

3. 测试创建支付订单

curl -X POST http://localhost:30006/api/miniprogram/pay \
  -H "Content-Type: application/json" \
  -d '{
    "openId": "oXXXX...",
    "productType": "section",
    "productId": "1-1",
    "amount": 9.9,
    "description": "测试章节",
    "userId": "user_xxx"
  }'

预期结果: 返回支付参数

⚠️ 常见错误

1. "缺少 userId 参数"

原因: 请求参数中未传递 userId

解决: 确保 URL 参数或请求体中包含 userId

2. "用户不存在"

原因: 数据库中找不到对应的用户记录

解决:

检查 userId 是否正确
确认用户已登录并创建了账号
查询数据库: SELECT * FROM users WHERE id = 'user_xxx'

3. "订单创建失败"

原因:

数据库连接失败
缺少必要字段
openId 格式错误

解决:

检查服务器日志
确认数据库连接正常
验证请求参数完整性

4. 接口404

原因:

Next.js 服务器未重启
文件路径错误

解决:

重启 Next.js 服务器: npm run dev
检查文件是否存在于正确路径
清除 .next 缓存后重启

📝 数据库表结构

orders 表

字段	类型	说明
`id`	VARCHAR	订单ID（同 order_sn）
`order_sn`	VARCHAR	订单号
`user_id`	VARCHAR	用户ID
`open_id`	VARCHAR	微信openId
`product_type`	VARCHAR	产品类型 (section/fullbook)
`product_id`	VARCHAR	产品ID
`amount`	DECIMAL	金额（元）
`description`	TEXT	订单描述
`status`	VARCHAR	状态 (created/paid/expired)
`transaction_id`	VARCHAR	微信交易号
`pay_time`	DATETIME	支付时间
`created_at`	DATETIME	创建时间
`updated_at`	DATETIME	更新时间

users 表（购买相关字段）

字段	类型	说明
`has_full_book`	BOOLEAN	是否购买全书
`purchased_sections`	JSON	已购章节列表
`earnings`	DECIMAL	已结算收益
`pending_earnings`	DECIMAL	待结算收益

🎉 接口状态总结

接口	状态	用途
`/api/miniprogram/pay`	✅ 已实现	创建支付订单
`/api/miniprogram/pay/notify`	✅ 已实现	支付回调
`/api/user/purchase-status`	✅ 已实现	查询购买状态
`/api/user/check-purchased`	✅ 已实现	检查是否已购买
`/api/payment/create-order`	⚠️ 未使用	Web 端通用接口
`/api/payment/wechat/notify`	⚠️ 未使用	Web 端回调接口

所有小程序支付相关接口已完成！ 🎉

重启 Next.js 服务器后生效: npm run dev

7.4 KiB Raw Permalink Blame History Unescape Escape