From ca7ddcc55eee69a4f7597d28b0c92e1fb8a293ba Mon Sep 17 00:00:00 2001 From: Milky0217 Date: Thu, 16 Apr 2026 13:22:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E4=BB=98=E8=B4=B9?= =?UTF-8?q?=E5=8A=9F=E8=83=BD=E7=B3=BB=E7=BB=9F=E5=AE=8C=E6=95=B4=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增第十二章：付费功能系统 - 支付下单接口 POST /api/payment/create-order - 支付回调接口 POST /api/payment/callback - payment_orders 表结构设计 - 配额查询 API GET /api/user/quota - 定价策略（包月/包年/永久） - 实施优先级和注意事项 --- IMPROVEMENTS.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index 401f3e1..cfc8d45 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -540,6 +540,173 @@ fi --- +## 十二、付费功能系统 + +### 当前状态 + +**已有基础设施：** +- ✅ 数据库字段：`is_paid` (boolean), `paid_expires_at` (timestamp) +- ✅ 配额检查逻辑：`db.rs:15-24` 非付费用户限制 20 条数据 +- ✅ 管理员 API：`PUT /api/admin/users/{id}/payment` 手动设置付费状态 +- ✅ 用户查询 API：`GET /api/user/profile` 返回 `is_paid`, `is_paid_active`, `paid_expires_at` + +**缺失功能：** +- ❌ 支付下单接口 +- ❌ 微信支付回调接口 +- ❌ 前端付费 UI +- ❌ 购买记录表 + +### 12.1 支付下单接口 + +**需求**：用户点击购买后，后端生成微信支付订单。 + +**建议实现**： + +```rust +// POST /api/payment/create-order +// Request +{ + "package_type": "monthly" | "yearly" | "permanent" +} + +// Response +{ + "success": true, + "data": { + "order_id": "wx_order_xxx", + "prepay_id": "wx_prepay_xxx", // 用于调起支付 + "pay_sign": "...", + "expire_time": "2026-05-16T12:00:00Z" + } +} +``` + +**需新增环境变量**： +``` +WECHAT_PAYMENT_MCHID=商户号 +WECHAT_PAYMENT_SECRET=支付密钥 +WECHAT_PAYMENT_NOTIFY_URL=https://your-domain.com/api/payment/callback +``` + +### 12.2 支付回调接口 + +**需求**：接收微信支付成功回调，激活用户付费状态。 + +**建议实现**： + +```rust +// POST /api/payment/callback (微信支付服务器调用) +{ + "event_type": "TRANSACTION.SUCCESS", + "resource": { + "order_id": "wx_order_xxx", + "out_trade_no": "internal_order_xxx", + "trade_state": "SUCCESS", + "amount": { + "total": 100, // 金额（分） + "currency": "CNY" + } + } +} +``` + +**数据库变更**： + +```sql +-- 新增订单表 +CREATE TABLE payment_orders ( + id SERIAL PRIMARY KEY, + user_id INTEGER NOT NULL REFERENCES users(id), + order_no VARCHAR(64) UNIQUE NOT NULL, -- 内部订单号 + wx_order_id VARCHAR(64), -- 微信订单号 + package_type VARCHAR(20) NOT NULL, -- monthly/yearly/permanent + amount INTEGER NOT NULL, -- 金额（分） + status VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending/paid/cancelled/refunded + paid_at TIMESTAMPTZ, -- 支付时间 + created_at TIMESTAMPTZ DEFAULT NOW(), + expires_at TIMESTAMPTZ -- 付费到期时间 +); + +CREATE INDEX idx_payment_orders_user_id ON payment_orders(user_id); +CREATE INDEX idx_payment_orders_order_no ON payment_orders(order_no); +``` + +### 12.3 查询配额 API + +**需求**：前端显示用户已使用的数据条数和上限。 + +**建议实现**： + +```rust +// GET /api/user/quota +// Response +{ + "success": true, + "data": { + "is_paid": true, + "is_paid_active": true, + "paid_expires_at": "2026-12-31T23:59:59Z", + "data_usage": { + "used": 45, + "limit": 20, // 非付费用户限制 + "unlimited": false // 付费用户无限制 + } + } +} +``` + +**需新增**：`db::get_user_quota(pool, user_id) -> QuotaInfo` + +### 12.4 前端付费 UI + +**页面建议**： +``` +pages/ +├── upgrade/ +│ ├── upgrade.js # 购买页面 +│ ├── upgrade.wxml # 套餐选择 + 支付按钮 +│ └── upgrade.json +└── ... +``` + +**功能**： +1. 展示套餐（包月/包年/永久） +2. 调用后端创建订单 +3. 调起微信支付 +4. 支付成功/失败提示 +5. 跳转回首页 + +**首页配额展示**： +- 非付费用户：显示「已用 X/20 条，开通付费解锁无限存储」 +- 付费用户：显示「已用 X 条，无限存储」 + +### 12.5 定价建议 + +| 套餐 | 价格 | 有效期 | 说明 | +|------|------|--------|------| +| 包月 | ¥9.9 | 30天 | 尝鲜用户 | +| 包年 | ¥59 | 365天 | 主流套餐 | +| 永久 | ¥199 | 永久 | 忠实用户 | + +### 12.6 实施优先级 + +| 阶段 | 内容 | 复杂度 | +|------|------|--------| +| P1 | 后端：订单表 + 支付回调 | 中 | +| P1 | 后端：下单接口 + 微信支付集成 | 高 | +| P2 | 后端：配额查询 API | 低 | +| P2 | 前端：升级页面 + 支付流程 | 中 | +| P3 | 前端：首页配额展示 | 低 | + +### 12.7 注意事项 + +1. **支付安全**：回调接口必须验证微信签名 +2. **幂等性**：支付回调需处理重复通知 +3. **退款处理**：需实现退款接口和状态更新 +4. **试用期**：可考虑新用户首月免费 + +--- + ## 十一、检查清单 ### 代码提交前检查