14 KiB
14 KiB
订阅管理系统
**本文档引用的文件** - [backend/app/api/subscriptions.py](file://backend/app/api/subscriptions.py) - [backend/app/models/subscription.py](file://backend/app/models/subscription.py) - [backend/app/schemas/subscription.py](file://backend/app/schemas/subscription.py) - [backend/app/services/subscription.py](file://backend/app/services/subscription.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/api/deps.py](file://backend/app/api/deps.py) - [backend/app/database.py](file://backend/app/database.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/main.py](file://backend/app/main.py) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx) - [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx) - [docker-compose.yml](file://docker-compose.yml) - [backend/README.md](file://backend/README.md) - [frontend/README.md](file://frontend/README.md)目录
简介
订阅管理系统是GEO平台的核心功能模块，负责管理用户订阅计划、套餐定价和订阅状态。该系统采用前后端分离架构，后端基于FastAPI构建，前端使用Next.js开发，实现了完整的订阅生命周期管理。
系统提供了四种订阅套餐（免费版、入门版、专业版、企业版），每种套餐具有不同的功能权限和查询限制。用户可以通过Web界面轻松管理自己的订阅状态，包括查看当前订阅、升级或降级套餐、取消订阅以及查看订阅历史。
项目结构
整个订阅管理系统采用清晰的分层架构设计：
graph TB
subgraph "前端层 Frontend"
FE_LIB[API客户端 lib/api.ts]
FE_DASHBOARD[仪表盘页面]
FE_CHARTS[图表组件]
end
subgraph "后端层 Backend"
BE_MAIN[应用入口 main.py]
BE_API[API路由 subscriptions.py]
BE_SERVICE[业务逻辑 service]
BE_MODEL[数据模型 model]
BE_SCHEMA[数据验证 schema]
end
subgraph "基础设施 Infrastructure"
DB[(PostgreSQL数据库)]
REDIS[(Redis缓存)]
AUTH[JWT认证]
end
FE_LIB --> BE_API
FE_DASHBOARD --> FE_LIB
FE_CHARTS --> FE_DASHBOARD
BE_MAIN --> BE_API
BE_API --> BE_SERVICE
BE_SERVICE --> BE_MODEL
BE_MODEL --> DB
BE_SERVICE --> AUTH
BE_MAIN --> REDIS
图表来源
章节来源
核心组件
订阅管理系统的核心组件包括：
数据模型层
- Subscription模型：管理订阅记录，包含用户ID、套餐类型、状态、起止日期等字段
- User模型：扩展用户信息，包含当前套餐、最大查询数等订阅相关属性
业务逻辑层
- 订阅服务：实现订阅创建、取消、查询等功能
- 套餐管理：定义四种套餐及其功能特性
API接口层
- 订阅API：提供套餐查询、当前订阅查询、订阅创建、取消订阅、历史记录查询等接口
前端展示层
- 订阅管理界面：用户友好的订阅管理界面
- 数据可视化：订阅状态和使用情况的图表展示
章节来源
- backend/app/models/subscription.py:11-37
- backend/app/models/user.py:11-48
- backend/app/services/subscription.py:25-46
- backend/app/api/subscriptions.py:26-77
架构概览
系统采用RESTful API架构，前后端通过JSON进行数据交换。整体架构遵循分层设计原则：
sequenceDiagram
participant Client as 客户端浏览器
participant Frontend as 前端应用
participant API as 订阅API
participant Service as 业务服务
participant Model as 数据模型
participant DB as 数据库
Client->>Frontend : 访问订阅管理页面
Frontend->>API : GET /api/v1/subscriptions/current
API->>Service : get_current_subscription()
Service->>DB : 查询用户当前订阅
DB-->>Service : 返回订阅记录
Service-->>API : 返回订阅详情
API-->>Frontend : JSON响应
Frontend-->>Client : 渲染订阅状态
Note over Client,DB : 用户操作订阅流程
Client->>Frontend : 点击订阅按钮
Frontend->>API : POST /api/v1/subscriptions/subscribe
API->>Service : subscribe(plan)
Service->>DB : 创建新订阅记录
DB-->>Service : 确认插入
Service-->>API : 返回新订阅
API-->>Frontend : 成功响应
Frontend-->>Client : 更新订阅状态
图表来源
- frontend/lib/api.ts:102-119
- backend/app/api/subscriptions.py:45-67
- backend/app/services/subscription.py:85-117
系统架构特点：
- 异步处理：后端使用异步数据库连接，提升并发性能
- JWT认证：基于Bearer Token的认证机制
- 数据验证：Pydantic模型确保数据完整性
- 错误处理：统一的HTTP状态码和错误消息
章节来源
详细组件分析
订阅模型设计
订阅系统的核心数据模型设计简洁而功能完整：
classDiagram
class Subscription {
+UUID id
+UUID user_id
+string plan
+string status
+date start_date
+date end_date
+float amount
+string payment_method
+string payment_id
+datetime created_at
+user User
}
class User {
+UUID id
+string email
+string plan
+int max_queries
+boolean is_active
+string reset_token
+datetime verification_code_expires
+subscriptions Subscription[]
}
class SubscriptionResponse {
+UUID id
+string plan
+string status
+date start_date
+date end_date
+float amount
+string payment_method
+datetime created_at
}
Subscription --> User : "外键关联"
User --> Subscription : "一对多关系"
图表来源
- backend/app/models/subscription.py:11-37
- backend/app/models/user.py:11-48
- backend/app/schemas/subscription.py:24-36
订阅模型的关键特性：
- UUID主键：使用UUID作为唯一标识符，避免序列号暴露
- 级联删除：用户删除时自动清理订阅记录
- 状态管理：支持active、cancelled等多种状态
- 时间范围：明确的订阅起止日期管理
章节来源
套餐管理系统
系统定义了四种不同级别的套餐，每种套餐都有明确的功能权限和使用限制：
| 套餐级别 | 价格(元/月) | 最大查询次数 | 功能特性 |
|---|---|---|---|
| 免费版 | 0 | 5次 | 基础查询监控、CSV导出 |
| 入门版 | 99 | 20次 | 免费版+PDF报告 |
| 专业版 | 299 | 100次 | 入门版+定时查询+竞品分析 |
| 企业版 | 999 | 500次 | 专业版+API访问+专属支持 |
flowchart TD
START[用户选择套餐] --> CHECK_PLAN{验证套餐ID}
CHECK_PLAN --> |有效| CALCULATE[计算到期日期]
CHECK_PLAN --> |无效| ERROR[抛出错误]
CALCULATE --> CREATE_SUBSCRIPTION[创建订阅记录]
CREATE_SUBSCRIPTION --> UPDATE_USER[更新用户套餐]
UPDATE_USER --> LOG[记录日志]
LOG --> SUCCESS[返回成功响应]
ERROR --> END[结束]
SUCCESS --> END
图表来源
章节来源
API接口设计
订阅管理API提供了完整的RESTful接口：
| 端点 | 方法 | 描述 | 认证要求 |
|---|---|---|---|
/api/v1/subscriptions/plans |
GET | 获取所有可用套餐 | 无需认证 |
/api/v1/subscriptions/current |
GET | 获取当前订阅 | Bearer Token |
/api/v1/subscriptions/subscribe |
POST | 创建新订阅 | Bearer Token |
/api/v1/subscriptions/cancel |
POST | 取消当前订阅 | Bearer Token |
/api/v1/subscriptions/history |
GET | 获取订阅历史 | Bearer Token |
章节来源
前端集成实现
前端通过统一的API客户端与后端进行交互：
sequenceDiagram
participant Dashboard as 仪表盘页面
participant API as API客户端
participant Auth as 认证服务
participant Backend as 后端服务
Dashboard->>Auth : 获取用户会话
Auth-->>Dashboard : 返回JWT Token
Dashboard->>API : 调用订阅接口
API->>Backend : 发送HTTP请求
Backend-->>API : 返回JSON响应
API-->>Dashboard : 处理响应数据
Dashboard-->>Dashboard : 更新UI状态
图表来源
章节来源
依赖关系分析
系统各组件之间的依赖关系清晰明确：
graph TB
subgraph "外部依赖"
FASTAPI[FastAPI框架]
SQLALCHEMY[SQLAlchemy ORM]
PYDANTIC[Pydantic验证]
JWT[jose JWT库]
end
subgraph "内部模块"
MAIN[main.py 应用入口]
DEPS[deps.py 依赖注入]
DB[database.py 数据库连接]
MODELS[models/* 数据模型]
SCHEMAS[schemas/* 数据验证]
SERVICES[services/* 业务逻辑]
APIS[api/* API路由]
end
FASTAPI --> MAIN
SQLALCHEMY --> MODELS
PYDANTIC --> SCHEMAS
JWT --> DEPS
MAIN --> APIS
MAIN --> DB
APIS --> SERVICES
SERVICES --> MODELS
SERVICES --> SCHEMAS
SERVICES --> DEPS
DEPS --> DB
DEPS --> MODELS
图表来源
章节来源
性能考虑
订阅管理系统的性能优化策略：
数据库优化
- 索引设计：在用户ID和创建时间字段上建立索引，优化查询性能
- 连接池：使用异步连接池管理数据库连接
- 批量操作：减少不必要的数据库往返
缓存策略
- Redis集成：利用Redis缓存热门查询结果
- 会话存储：使用Redis存储用户会话信息
API优化
- 异步处理：所有数据库操作采用异步方式
- 错误缓存：对认证失败等错误情况进行适当缓存
- 响应压缩：启用Gzip压缩减少传输体积
故障排除指南
常见问题及解决方案
认证问题
- 症状：401未授权错误
- 原因：JWT Token过期或无效
- 解决：重新登录获取新Token
数据库连接问题
- 症状：500服务器错误
- 原因：数据库连接失败
- 解决：检查数据库服务状态和连接配置
套餐验证错误
- 症状：400错误，提示无效套餐
- 原因：传入的套餐ID不存在
- 解决：确认套餐ID是否在系统中存在
章节来源
调试技巧
- 启用详细日志：在开发环境中启用详细日志输出
- API测试：使用Swagger UI测试API端点
- 数据库监控：监控慢查询和连接池状态
- 前端调试：使用浏览器开发者工具检查网络请求
结论
订阅管理系统是一个设计合理、功能完整的模块化系统。其主要优势包括：
技术优势
- 清晰的分层架构，职责分离明确
- 完善的数据验证和错误处理机制
- 异步处理提升系统性能
- JWT认证确保安全性
业务价值
- 支持多种套餐灵活定价
- 提供完整的订阅生命周期管理
- 用户友好的界面设计
- 可扩展的架构支持未来功能扩展
改进建议
- 集成真实的支付网关
- 添加订阅续费提醒功能
- 实现更详细的使用统计分析
- 增加订阅优惠券系统
该系统为GEO平台提供了坚实的订阅管理基础，能够满足当前业务需求并支持未来的功能扩展。