404 lines
14 KiB
Markdown
404 lines
14 KiB
Markdown
# 订阅管理系统
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
|
||
订阅管理系统是GEO平台的核心功能模块，负责管理用户订阅计划、套餐定价和订阅状态。该系统采用前后端分离架构，后端基于FastAPI构建，前端使用Next.js开发，实现了完整的订阅生命周期管理。
|
||
|
||
系统提供了四种订阅套餐（免费版、入门版、专业版、企业版），每种套餐具有不同的功能权限和查询限制。用户可以通过Web界面轻松管理自己的订阅状态，包括查看当前订阅、升级或降级套餐、取消订阅以及查看订阅历史。
|
||
|
||
## 项目结构
|
||
|
||
整个订阅管理系统采用清晰的分层架构设计：
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
|
||
- [backend/app/api/subscriptions.py:1-77](file://backend/app/api/subscriptions.py#L1-L77)
|
||
- [frontend/lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
|
||
|
||
**章节来源**
|
||
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
|
||
- [frontend/README.md:1-170](file://frontend/README.md#L1-L170)
|
||
- [backend/README.md:148-257](file://backend/README.md#L148-L257)
|
||
|
||
## 核心组件
|
||
|
||
订阅管理系统的核心组件包括：
|
||
|
||
### 数据模型层
|
||
- **Subscription模型**：管理订阅记录，包含用户ID、套餐类型、状态、起止日期等字段
|
||
- **User模型**：扩展用户信息，包含当前套餐、最大查询数等订阅相关属性
|
||
|
||
### 业务逻辑层
|
||
- **订阅服务**：实现订阅创建、取消、查询等功能
|
||
- **套餐管理**：定义四种套餐及其功能特性
|
||
|
||
### API接口层
|
||
- **订阅API**：提供套餐查询、当前订阅查询、订阅创建、取消订阅、历史记录查询等接口
|
||
|
||
### 前端展示层
|
||
- **订阅管理界面**：用户友好的订阅管理界面
|
||
- **数据可视化**：订阅状态和使用情况的图表展示
|
||
|
||
**章节来源**
|
||
- [backend/app/models/subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
|
||
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
|
||
- [backend/app/services/subscription.py:25-46](file://backend/app/services/subscription.py#L25-L46)
|
||
- [backend/app/api/subscriptions.py:26-77](file://backend/app/api/subscriptions.py#L26-L77)
|
||
|
||
## 架构概览
|
||
|
||
系统采用RESTful API架构，前后端通过JSON进行数据交换。整体架构遵循分层设计原则：
|
||
|
||
```mermaid
|
||
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](file://frontend/lib/api.ts#L102-L119)
|
||
- [backend/app/api/subscriptions.py:45-67](file://backend/app/api/subscriptions.py#L45-L67)
|
||
- [backend/app/services/subscription.py:85-117](file://backend/app/services/subscription.py#L85-L117)
|
||
|
||
系统架构特点：
|
||
- **异步处理**：后端使用异步数据库连接，提升并发性能
|
||
- **JWT认证**：基于Bearer Token的认证机制
|
||
- **数据验证**：Pydantic模型确保数据完整性
|
||
- **错误处理**：统一的HTTP状态码和错误消息
|
||
|
||
**章节来源**
|
||
- [backend/app/main.py:39-84](file://backend/app/main.py#L39-L84)
|
||
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)
|
||
- [backend/app/config.py:9-23](file://backend/app/config.py#L9-L23)
|
||
|
||
## 详细组件分析
|
||
|
||
### 订阅模型设计
|
||
|
||
订阅系统的核心数据模型设计简洁而功能完整：
|
||
|
||
```mermaid
|
||
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](file://backend/app/models/subscription.py#L11-L37)
|
||
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
|
||
- [backend/app/schemas/subscription.py:24-36](file://backend/app/schemas/subscription.py#L24-L36)
|
||
|
||
订阅模型的关键特性：
|
||
- **UUID主键**：使用UUID作为唯一标识符，避免序列号暴露
|
||
- **级联删除**：用户删除时自动清理订阅记录
|
||
- **状态管理**：支持active、cancelled等多种状态
|
||
- **时间范围**：明确的订阅起止日期管理
|
||
|
||
**章节来源**
|
||
- [backend/app/models/subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
|
||
- [backend/app/models/user.py:42-47](file://backend/app/models/user.py#L42-L47)
|
||
|
||
### 套餐管理系统
|
||
|
||
系统定义了四种不同级别的套餐，每种套餐都有明确的功能权限和使用限制：
|
||
|
||
| 套餐级别 | 价格(元/月) | 最大查询次数 | 功能特性 |
|
||
|---------|------------|-------------|----------|
|
||
| 免费版 | 0 | 5次 | 基础查询监控、CSV导出 |
|
||
| 入门版 | 99 | 20次 | 免费版+PDF报告 |
|
||
| 专业版 | 299 | 100次 | 入门版+定时查询+竞品分析 |
|
||
| 企业版 | 999 | 500次 | 专业版+API访问+专属支持 |
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [backend/app/services/subscription.py:85-117](file://backend/app/services/subscription.py#L85-L117)
|
||
- [backend/app/services/subscription.py:25-46](file://backend/app/services/subscription.py#L25-L46)
|
||
|
||
**章节来源**
|
||
- [backend/app/services/subscription.py:15-66](file://backend/app/services/subscription.py#L15-L66)
|
||
- [backend/app/services/subscription.py:85-117](file://backend/app/services/subscription.py#L85-L117)
|
||
|
||
### 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 |
|
||
|
||
**章节来源**
|
||
- [backend/app/api/subscriptions.py:26-77](file://backend/app/api/subscriptions.py#L26-L77)
|
||
|
||
### 前端集成实现
|
||
|
||
前端通过统一的API客户端与后端进行交互：
|
||
|
||
```mermaid
|
||
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状态
|
||
```
|
||
|
||
**图表来源**
|
||
- [frontend/lib/api.ts:102-119](file://frontend/lib/api.ts#L102-L119)
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:23-47](file://frontend/app/(dashboard)/dashboard/page.tsx#L23-L47)
|
||
|
||
**章节来源**
|
||
- [frontend/lib/api.ts:102-119](file://frontend/lib/api.ts#L102-L119)
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:23-47](file://frontend/app/(dashboard)/dashboard/page.tsx#L23-L47)
|
||
|
||
## 依赖关系分析
|
||
|
||
系统各组件之间的依赖关系清晰明确：
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [backend/app/main.py:12-22](file://backend/app/main.py#L12-L22)
|
||
- [backend/app/api/deps.py:1-13](file://backend/app/api/deps.py#L1-L13)
|
||
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
|
||
|
||
**章节来源**
|
||
- [backend/app/main.py:12-22](file://backend/app/main.py#L12-L22)
|
||
- [backend/app/api/deps.py:1-13](file://backend/app/api/deps.py#L1-L13)
|
||
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
|
||
|
||
## 性能考虑
|
||
|
||
订阅管理系统的性能优化策略：
|
||
|
||
### 数据库优化
|
||
- **索引设计**：在用户ID和创建时间字段上建立索引，优化查询性能
|
||
- **连接池**：使用异步连接池管理数据库连接
|
||
- **批量操作**：减少不必要的数据库往返
|
||
|
||
### 缓存策略
|
||
- **Redis集成**：利用Redis缓存热门查询结果
|
||
- **会话存储**：使用Redis存储用户会话信息
|
||
|
||
### API优化
|
||
- **异步处理**：所有数据库操作采用异步方式
|
||
- **错误缓存**：对认证失败等错误情况进行适当缓存
|
||
- **响应压缩**：启用Gzip压缩减少传输体积
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题及解决方案
|
||
|
||
**认证问题**
|
||
- **症状**：401未授权错误
|
||
- **原因**：JWT Token过期或无效
|
||
- **解决**：重新登录获取新Token
|
||
|
||
**数据库连接问题**
|
||
- **症状**：500服务器错误
|
||
- **原因**：数据库连接失败
|
||
- **解决**：检查数据库服务状态和连接配置
|
||
|
||
**套餐验证错误**
|
||
- **症状**：400错误，提示无效套餐
|
||
- **原因**：传入的套餐ID不存在
|
||
- **解决**：确认套餐ID是否在系统中存在
|
||
|
||
**章节来源**
|
||
- [backend/app/api/subscriptions.py:37-41](file://backend/app/api/subscriptions.py#L37-L41)
|
||
- [backend/app/services/subscription.py:89-90](file://backend/app/services/subscription.py#L89-L90)
|
||
|
||
### 调试技巧
|
||
|
||
1. **启用详细日志**：在开发环境中启用详细日志输出
|
||
2. **API测试**：使用Swagger UI测试API端点
|
||
3. **数据库监控**：监控慢查询和连接池状态
|
||
4. **前端调试**：使用浏览器开发者工具检查网络请求
|
||
|
||
## 结论
|
||
|
||
订阅管理系统是一个设计合理、功能完整的模块化系统。其主要优势包括：
|
||
|
||
**技术优势**
|
||
- 清晰的分层架构，职责分离明确
|
||
- 完善的数据验证和错误处理机制
|
||
- 异步处理提升系统性能
|
||
- JWT认证确保安全性
|
||
|
||
**业务价值**
|
||
- 支持多种套餐灵活定价
|
||
- 提供完整的订阅生命周期管理
|
||
- 用户友好的界面设计
|
||
- 可扩展的架构支持未来功能扩展
|
||
|
||
**改进建议**
|
||
- 集成真实的支付网关
|
||
- 添加订阅续费提醒功能
|
||
- 实现更详细的使用统计分析
|
||
- 增加订阅优惠券系统
|
||
|
||
该系统为GEO平台提供了坚实的订阅管理基础，能够满足当前业务需求并支持未来的功能扩展。 |