update pay function

2025-11-19 19:41:26 +08:00
parent 17c04211bb
commit a4d16e7686
12 changed files with 4667 additions and 140 deletions
--- a/docs/NEW_PAYMENT_SYSTEM_DESIGN.md
+++ b/docs/NEW_PAYMENT_SYSTEM_DESIGN.md
@@ -0,0 +1,576 @@
+# 订阅支付系统重新设计方案
+
+## 📊 问题分析
+
+### 现有系统的问题
+
+1. **价格配置混乱**
+   - 季付和月付价格相同（配置错误）
+   - `monthly_price` 和 `yearly_price` 字段命名不清晰
+   - 缺少季付、半年付等周期的价格配置
+
+2. **升级逻辑复杂且不合理**
+   - 计算剩余价值折算（按天计算 `remaining_value`）
+   - 用户难以理解升级价格
+   - 续费用户和新用户价格不一致
+   - 逻辑复杂,容易出错
+
+3. **按钮文案不清晰**
+   - 已订阅用户应显示"续费 Pro"/"续费 Max"
+   - 而不是"升级至 Pro"/"切换至 Pro"
+
+4. **数据库表设计问题**
+   - `SubscriptionUpgrade` 表记录升级,但逻辑过于复杂
+   - `PaymentOrder` 表缺少必要字段
+   - 价格配置分散在多个字段
+
+---
+
+## ✨ 新设计方案
+
+### 核心原则
+
+1. **简化续费逻辑**: **续费用户与新用户价格完全一致**,不做任何折算
+2. **清晰的价格体系**: 每个套餐每个周期都有明确的价格
+3. **统一的用户体验**: 无论是新购还是续费,价格透明一致
+4. **独立的订阅记录**: 每次支付都创建新的订阅记录(历史可追溯)
+
+---
+
+## 📐 数据库表设计
+
+### 1. `subscription_plans` - 订阅套餐表（重构）
+
+```sql
+CREATE TABLE subscription_plans (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    plan_code VARCHAR(20) NOT NULL UNIQUE COMMENT '套餐代码: pro, max',
+    plan_name VARCHAR(50) NOT NULL COMMENT '套餐名称: Pro专业版, Max旗舰版',
+    description TEXT COMMENT '套餐描述',
+    features JSON COMMENT '功能列表',
+
+    -- 价格配置（所有周期价格）
+    price_monthly DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '月付价格',
+    price_quarterly DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '季付价格(3个月)',
+    price_semiannual DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '半年付价格(6个月)',
+    price_yearly DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '年付价格(12个月)',
+
+    -- 状态字段
+    is_active BOOLEAN DEFAULT TRUE COMMENT '是否启用',
+    display_order INT DEFAULT 0 COMMENT '展示顺序',
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    INDEX idx_plan_code (plan_code),
+    INDEX idx_active_order (is_active, display_order)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订阅套餐配置表';
+```
+
+**示例数据**:
+```sql
+INSERT INTO subscription_plans (plan_code, plan_name, description, price_monthly, price_quarterly, price_semiannual, price_yearly) VALUES
+('pro', 'Pro 专业版', '为专业投资者打造', 299.00, 799.00, 1499.00, 2699.00),
+('max', 'Max 旗舰版', '旗舰级体验', 599.00, 1599.00, 2999.00, 5399.00);
+```
+
+---
+
+### 2. `user_subscriptions` - 用户订阅记录表（重构）
+
+```sql
+CREATE TABLE user_subscriptions (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    user_id INT NOT NULL COMMENT '用户ID',
+    subscription_id VARCHAR(32) UNIQUE NOT NULL COMMENT '订阅ID(唯一标识)',
+
+    -- 订阅基本信息
+    plan_code VARCHAR(20) NOT NULL COMMENT '套餐代码: pro, max',
+    billing_cycle VARCHAR(20) NOT NULL COMMENT '计费周期: monthly, quarterly, semiannual, yearly',
+
+    -- 订阅时间
+    start_date DATETIME NOT NULL COMMENT '订阅开始时间',
+    end_date DATETIME NOT NULL COMMENT '订阅结束时间',
+
+    -- 订阅状态
+    status VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '状态: active(有效), expired(已过期), cancelled(已取消)',
+    is_current BOOLEAN DEFAULT FALSE COMMENT '是否为当前生效的订阅',
+
+    -- 支付信息
+    payment_order_id INT COMMENT '关联的支付订单ID',
+    paid_amount DECIMAL(10,2) NOT NULL COMMENT '实际支付金额',
+    original_price DECIMAL(10,2) NOT NULL COMMENT '原价',
+    discount_amount DECIMAL(10,2) DEFAULT 0 COMMENT '优惠金额',
+
+    -- 订阅类型
+    subscription_type VARCHAR(20) DEFAULT 'new' COMMENT '订阅类型: new(新购), renew(续费)',
+    previous_subscription_id VARCHAR(32) COMMENT '上一个订阅ID(续费时记录)',
+
+    -- 自动续费
+    auto_renew BOOLEAN DEFAULT FALSE COMMENT '是否自动续费',
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    INDEX idx_user_id (user_id),
+    INDEX idx_subscription_id (subscription_id),
+    INDEX idx_user_current (user_id, is_current),
+    INDEX idx_status (status),
+    INDEX idx_end_date (end_date),
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户订阅记录表';
+```
+
+**设计说明**:
+- 每次支付都创建新的订阅记录
+- 通过 `is_current` 标识当前生效的订阅
+- 支持订阅历史追溯
+- 续费时记录 `previous_subscription_id` 形成订阅链
+
+---
+
+### 3. `payment_orders` - 支付订单表（重构）
+
+```sql
+CREATE TABLE payment_orders (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    order_no VARCHAR(32) UNIQUE NOT NULL COMMENT '订单号',
+    user_id INT NOT NULL COMMENT '用户ID',
+
+    -- 订阅信息
+    plan_code VARCHAR(20) NOT NULL COMMENT '套餐代码',
+    billing_cycle VARCHAR(20) NOT NULL COMMENT '计费周期',
+    subscription_type VARCHAR(20) DEFAULT 'new' COMMENT '订阅类型: new(新购), renew(续费)',
+
+    -- 价格信息
+    original_price DECIMAL(10,2) NOT NULL COMMENT '原价',
+    discount_amount DECIMAL(10,2) DEFAULT 0 COMMENT '优惠金额',
+    final_amount DECIMAL(10,2) NOT NULL COMMENT '实付金额',
+
+    -- 优惠码
+    promo_code_id INT COMMENT '优惠码ID',
+    promo_code VARCHAR(50) COMMENT '优惠码',
+
+    -- 支付信息
+    payment_method VARCHAR(20) DEFAULT 'wechat' COMMENT '支付方式: wechat, alipay',
+    payment_channel VARCHAR(50) COMMENT '支付渠道详情',
+    transaction_id VARCHAR(64) COMMENT '第三方交易号',
+    qr_code_url TEXT COMMENT '支付二维码URL',
+
+    -- 订单状态
+    status VARCHAR(20) DEFAULT 'pending' COMMENT '状态: pending(待支付), paid(已支付), expired(已过期), cancelled(已取消)',
+
+    -- 时间信息
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    paid_at TIMESTAMP NULL COMMENT '支付时间',
+    expired_at TIMESTAMP NULL COMMENT '过期时间',
+
+    -- 备注
+    remark TEXT COMMENT '备注信息',
+
+    INDEX idx_order_no (order_no),
+    INDEX idx_user_id (user_id),
+    INDEX idx_status (status),
+    INDEX idx_created_at (created_at),
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    FOREIGN KEY (promo_code_id) REFERENCES promo_codes(id) ON DELETE SET NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='支付订单表';
+```
+
+---
+
+### 4. `promo_codes` - 优惠码表（保持不变,微调）
+
+```sql
+CREATE TABLE promo_codes (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    code VARCHAR(50) UNIQUE NOT NULL COMMENT '优惠码',
+    description VARCHAR(200) COMMENT '描述',
+
+    -- 折扣类型
+    discount_type VARCHAR(20) NOT NULL COMMENT '折扣类型: percentage(百分比), fixed_amount(固定金额)',
+    discount_value DECIMAL(10,2) NOT NULL COMMENT '折扣值',
+
+    -- 适用范围
+    applicable_plans JSON COMMENT '适用套餐: ["pro", "max"] 或 null(全部)',
+    applicable_cycles JSON COMMENT '适用周期: ["monthly", "yearly"] 或 null(全部)',
+    min_amount DECIMAL(10,2) COMMENT '最低消费金额',
+
+    -- 使用限制
+    max_total_uses INT COMMENT '最大使用次数(总)',
+    max_uses_per_user INT DEFAULT 1 COMMENT '每用户最大使用次数',
+    current_uses INT DEFAULT 0 COMMENT '当前使用次数',
+
+    -- 有效期
+    valid_from TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '生效时间',
+    valid_until TIMESTAMP NULL COMMENT '过期时间',
+
+    -- 状态
+    is_active BOOLEAN DEFAULT TRUE COMMENT '是否启用',
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    INDEX idx_code (code),
+    INDEX idx_active (is_active),
+    INDEX idx_valid_period (valid_from, valid_until)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='优惠码表';
+```
+
+---
+
+### 5. `promo_code_usage` - 优惠码使用记录表（保持不变）
+
+```sql
+CREATE TABLE promo_code_usage (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    promo_code_id INT NOT NULL,
+    user_id INT NOT NULL,
+    order_id INT NOT NULL,
+    discount_amount DECIMAL(10,2) NOT NULL COMMENT '实际优惠金额',
+    used_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    INDEX idx_promo_code (promo_code_id),
+    INDEX idx_user_id (user_id),
+    INDEX idx_order_id (order_id),
+
+    FOREIGN KEY (promo_code_id) REFERENCES promo_codes(id) ON DELETE CASCADE,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    FOREIGN KEY (order_id) REFERENCES payment_orders(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='优惠码使用记录表';
+```
+
+---
+
+### 6. 删除不必要的表
+
+**删除 `subscription_upgrades` 表** - 不再需要复杂的升级逻辑
+
+---
+
+## 💡 业务逻辑设计
+
+### 1. 价格计算逻辑（简化版）
+
+```python
+def calculate_subscription_price(plan_code, billing_cycle, promo_code=None):
+    """
+    计算订阅价格（新购和续费价格完全一致）
+
+    Args:
+        plan_code: 套餐代码 (pro/max)
+        billing_cycle: 计费周期 (monthly/quarterly/semiannual/yearly)
+        promo_code: 优惠码（可选）
+
+    Returns:
+        dict: {
+            'plan_code': 'pro',
+            'billing_cycle': 'yearly',
+            'original_price': 2699.00,
+            'discount_amount': 0,
+            'final_amount': 2699.00,
+            'promo_code': None,
+            'promo_error': None
+        }
+    """
+    # 1. 查询套餐价格
+    plan = SubscriptionPlan.query.filter_by(plan_code=plan_code, is_active=True).first()
+    if not plan:
+        return {'error': '套餐不存在'}
+
+    # 2. 获取对应周期的价格
+    price_field = f'price_{billing_cycle}'
+    original_price = getattr(plan, price_field, 0)
+
+    if original_price <= 0:
+        return {'error': '价格配置错误'}
+
+    result = {
+        'plan_code': plan_code,
+        'plan_name': plan.plan_name,
+        'billing_cycle': billing_cycle,
+        'original_price': float(original_price),
+        'discount_amount': 0,
+        'final_amount': float(original_price),
+        'promo_code': None,
+        'promo_error': None
+    }
+
+    # 3. 应用优惠码（如果有）
+    if promo_code:
+        promo, error = validate_promo_code(promo_code, plan_code, billing_cycle, original_price, user_id)
+        if promo:
+            discount = calculate_discount(promo, original_price)
+            result['discount_amount'] = float(discount)
+            result['final_amount'] = float(original_price - discount)
+            result['promo_code'] = promo.code
+        elif error:
+            result['promo_error'] = error
+
+    return result
+```
+
+**关键点**:
+- ✅ 不再计算 `remaining_value`（剩余价值）
+- ✅ 不再区分新购/续费价格
+- ✅ 逻辑简单,易于维护
+- ✅ 用户体验清晰透明
+
+---
+
+### 2. 创建订单逻辑
+
+```python
+def create_subscription_order(user_id, plan_code, billing_cycle, promo_code=None):
+    """
+    创建订阅支付订单
+    """
+    # 1. 计算价格
+    price_result = calculate_subscription_price(plan_code, billing_cycle, promo_code)
+    if 'error' in price_result:
+        return {'success': False, 'error': price_result['error']}
+
+    # 2. 判断是新购还是续费
+    current_sub = get_current_subscription(user_id)
+
+    subscription_type = 'new'
+    if current_sub and current_sub.plan_code in ['pro', 'max']:
+        subscription_type = 'renew'
+
+    # 3. 创建支付订单
+    order = PaymentOrder(
+        order_no=generate_order_no(user_id),
+        user_id=user_id,
+        plan_code=plan_code,
+        billing_cycle=billing_cycle,
+        subscription_type=subscription_type,
+        original_price=price_result['original_price'],
+        discount_amount=price_result['discount_amount'],
+        final_amount=price_result['final_amount'],
+        promo_code=promo_code,
+        status='pending',
+        expired_at=datetime.now() + timedelta(minutes=30)
+    )
+
+    db.session.add(order)
+    db.session.commit()
+
+    # 4. 生成支付二维码（微信支付）
+    qr_code_url = generate_wechat_qr_code(order)
+    order.qr_code_url = qr_code_url
+    db.session.commit()
+
+    return {'success': True, 'order': order.to_dict()}
+```
+
+---
+
+### 3. 支付成功后的订阅激活逻辑
+
+```python
+def activate_subscription_after_payment(order_id):
+    """
+    支付成功后激活订阅
+    """
+    order = PaymentOrder.query.get(order_id)
+    if not order or order.status != 'paid':
+        return {'success': False, 'error': '订单状态错误'}
+
+    user_id = order.user_id
+    plan_code = order.plan_code
+    billing_cycle = order.billing_cycle
+
+    # 1. 计算订阅周期
+    cycle_days = {
+        'monthly': 30,
+        'quarterly': 90,
+        'semiannual': 180,
+        'yearly': 365
+    }
+    days = cycle_days.get(billing_cycle, 30)
+
+    # 2. 获取当前订阅
+    current_sub = UserSubscription.query.filter_by(
+        user_id=user_id,
+        is_current=True
+    ).first()
+
+    # 3. 计算开始和结束时间
+    now = datetime.now()
+
+    if current_sub and current_sub.end_date > now:
+        # 续费：从当前订阅结束时间开始
+        start_date = current_sub.end_date
+    else:
+        # 新购：从当前时间开始
+        start_date = now
+
+    end_date = start_date + timedelta(days=days)
+
+    # 4. 创建新订阅记录
+    new_subscription = UserSubscription(
+        user_id=user_id,
+        subscription_id=generate_subscription_id(),
+        plan_code=plan_code,
+        billing_cycle=billing_cycle,
+        start_date=start_date,
+        end_date=end_date,
+        status='active',
+        is_current=True,
+        payment_order_id=order.id,
+        paid_amount=order.final_amount,
+        original_price=order.original_price,
+        discount_amount=order.discount_amount,
+        subscription_type=order.subscription_type,
+        previous_subscription_id=current_sub.subscription_id if current_sub else None
+    )
+
+    # 5. 将旧订阅标记为非当前
+    if current_sub:
+        current_sub.is_current = False
+
+    db.session.add(new_subscription)
+    db.session.commit()
+
+    return {'success': True, 'subscription': new_subscription.to_dict()}
+```
+
+**关键特性**:
+- ✅ 续费时从**当前订阅结束时间**开始,避免浪费
+- ✅ 每次支付都创建新的订阅记录
+- ✅ 保留历史订阅记录（通过 `previous_subscription_id` 形成链）
+- ✅ 逻辑清晰,易于理解
+
+---
+
+### 4. 按钮文案逻辑
+
+```python
+def get_subscription_button_text(user, plan_code, billing_cycle):
+    """
+    获取订阅按钮文字
+
+    Args:
+        user: 用户对象
+        plan_code: 套餐代码 (pro/max)
+        billing_cycle: 计费周期
+
+    Returns:
+        str: 按钮文字
+    """
+    current_sub = get_current_subscription(user.id)
+
+    # 1. 如果没有订阅或订阅已过期
+    if not current_sub or current_sub.plan_code == 'free' or current_sub.status != 'active':
+        return f"选择 {get_plan_display_name(plan_code)}"
+
+    # 2. 如果是当前套餐且周期相同
+    if current_sub.plan_code == plan_code and current_sub.billing_cycle == billing_cycle:
+        return f"续费 {get_plan_display_name(plan_code)}"
+
+    # 3. 如果是当前套餐但周期不同
+    if current_sub.plan_code == plan_code:
+        return f"切换至{get_cycle_display_name(billing_cycle)}"
+
+    # 4. 如果是不同套餐
+    return f"选择 {get_plan_display_name(plan_code)}"
+
+def get_plan_display_name(plan_code):
+    names = {'pro': 'Pro 专业版', 'max': 'Max 旗舰版'}
+    return names.get(plan_code, plan_code)
+
+def get_cycle_display_name(billing_cycle):
+    names = {
+        'monthly': '月付',
+        'quarterly': '季付',
+        'semiannual': '半年付',
+        'yearly': '年付'
+    }
+    return names.get(billing_cycle, billing_cycle)
+```
+
+**示例**:
+- 免费用户看 Pro 年付: "选择 Pro 专业版"
+- Pro 月付用户看 Pro 年付: "切换至年付"
+- Pro 年付用户看 Pro 年付: "续费 Pro 专业版"
+- Pro 用户看 Max 年付: "选择 Max 旗舰版"
+
+---
+
+## 📊 价格配置示例
+
+### Pro 专业版价格设定
+
+| 计费周期 | 价格 | 原价 | 折扣 | 月均价格 |
+|---------|------|------|------|---------|
+| 月付 | ¥299 | - | - | ¥299 |
+| 季付(3个月) | ¥799 | ¥897 | 11% | ¥266 |
+| 半年付(6个月) | ¥1499 | ¥1794 | 16% | ¥250 |
+| 年付(12个月) | ¥2699 | ¥3588 | 25% | ¥225 |
+
+### Max 旗舰版价格设定
+
+| 计费周期 | 价格 | 原价 | 折扣 | 月均价格 |
+|---------|------|------|------|---------|
+| 月付 | ¥599 | - | - | ¥599 |
+| 季付(3个月) | ¥1599 | ¥1797 | 11% | ¥533 |
+| 半年付(6个月) | ¥2999 | ¥3594 | 17% | ¥500 |
+| 年付(12个月) | ¥5399 | ¥7188 | 25% | ¥450 |
+
+---
+
+## 🔄 迁移方案
+
+### 数据迁移 SQL
+
+参见 `database_migration.sql`
+
+### 代码迁移步骤
+
+1. **备份现有数据库**
+2. **执行数据库迁移 SQL**
+3. **更新数据库模型** (`models.py`)
+4. **更新价格计算逻辑** (`calculate_price.py`)
+5. **更新 API 路由** (`routes.py`)
+6. **更新前端组件** (`SubscriptionContentNew.tsx`)
+7. **测试完整流程**
+8. **灰度发布**
+
+---
+
+## ✅ 优势总结
+
+### 相比旧系统的改进
+
+1. **价格透明** - 续费用户和新用户价格完全一致
+2. **逻辑简化** - 不再计算剩余价值,代码减少 50%+
+3. **易于理解** - 用户体验更清晰
+4. **灵活扩展** - 轻松添加新的计费周期
+5. **历史追溯** - 完整的订阅历史记录
+6. **数据完整** - 每次支付都有完整的记录
+
+### 用户体验改进
+
+1. **按钮文案清晰** - "续费 Pro"/"选择 Pro"明确表达意图
+2. **价格一致性** - 所有用户看到的价格都一样
+3. **无隐藏费用** - 不会因为"升级折算"产生困惑
+4. **透明计费** - 支付金额 = 显示价格 - 优惠码折扣
+
+---
+
+## 📝 后续优化建议
+
+1. **自动续费** - 到期前自动扣款续费
+2. **订阅提醒** - 到期前 7 天、3 天、1 天发送通知
+3. **订阅暂停** - 允许用户暂停订阅
+4. **订阅降级** - 从 Max 降级到 Pro（当前周期结束后生效）
+5. **发票管理** - 支持开具电子发票
+6. **支付方式扩展** - 支持支付宝、银行卡等
+
+---
+
+**设计时间**: 2025-11-19
+**设计者**: Claude Code
+**版本**: v2.0.0