fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/后端系统架构/数据模型设计.md

462 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 数据模型设计
<cite>
**本文档中引用的文件**
- [user.py](file://backend/app/models/user.py)
- [query.py](file://backend/app/models/query.py)
- [citation_record.py](file://backend/app/models/citation_record.py)
- [query_task.py](file://backend/app/models/query_task.py)
- [subscription.py](file://backend/app/models/subscription.py)
- [database.py](file://backend/app/database.py)
- [__init__.py](file://backend/app/models/__init__.py)
- [488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [config.py](file://backend/app/config.py)
- [query.py](file://backend/app/schemas/query.py)
- [citation.py](file://backend/app/schemas/citation.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
GEO平台的数据模型基于SQLAlchemy ORM构建，采用异步PostgreSQL数据库设计。该系统围绕用户查询管理、引用记录跟踪和任务调度构建，支持多平台内容监控和分析功能。数据模型设计遵循以下核心原则：异步数据库访问、强类型字段定义、级联关系管理和性能优化索引策略。
## 项目结构
GEO项目的数据层采用模块化设计，所有ORM模型位于`backend/app/models/`目录下，通过统一的Base类继承实现。数据库连接配置在`database.py`中定义，使用SQLAlchemy的异步引擎和会话管理。
```mermaid
graph TB
subgraph "数据模型层"
User[User模型]
Query[Query模型]
CitationRecord[CitationRecord模型]
QueryTask[QueryTask模型]
Subscription[Subscription模型]
end
subgraph "基础设施层"
Database[数据库引擎]
Config[配置管理]
Alembic[迁移管理]
end
subgraph "应用层"
API[API服务]
Schemas[Schemas验证]
Workers[工作进程]
end
User --> Query
Query --> CitationRecord
Query --> QueryTask
User --> Subscription
Database --> User
Database --> Query
Database --> CitationRecord
Database --> QueryTask
Database --> Subscription
Config --> Database
Alembic --> Database
```
**图表来源**
- [database.py:1-29](file://backend/app/database.py#L1-L29)
- [__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
**章节来源**
- [database.py:1-29](file://backend/app/database.py#L1-L29)
- [config.py:1-17](file://backend/app/config.py#L1-L17)
## 核心组件
GEO平台包含五个核心数据模型，每个模型都经过精心设计以满足特定的业务需求：
### 用户模型(User)
用户模型是整个系统的核心实体，负责管理平台用户的基本信息、订阅状态和查询配额。模型包含完整的身份认证信息和权限控制字段。
### 查询模型(Query)
查询模型代表用户的搜索请求，包含关键词、目标品牌、平台配置和调度参数。该模型支持复杂的JSONB字段存储动态配置数据。
### 引用记录模型(CitationRecord)
引用记录模型用于存储从各个平台抓取的内容引用信息，包括品牌提及、置信度评分和上下文数据。支持文本搜索和位置标记功能。
### 查询任务模型(QueryTask)
查询任务模型管理异步查询任务的生命周期，包括调度状态、执行历史和错误处理。支持多平台并发执行和状态跟踪。
### 订阅模型(Subscription)
订阅模型处理用户付费计划和账单管理，包含计划类型、状态、日期范围和支付信息。与用户模型建立一对一关系。
**章节来源**
- [user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
## 架构概览
GEO平台采用分层架构设计，数据模型层与业务逻辑层分离，确保了良好的可维护性和扩展性。
```mermaid
classDiagram
class User {
+UUID id
+String email
+String password_hash
+String name
+String plan
+Integer max_queries
+Boolean is_active
+DateTime created_at
+DateTime updated_at
+queries : List[Query]
+subscriptions : List[Subscription]
}
class Query {
+UUID id
+UUID user_id
+String keyword
+String target_brand
+List brand_aliases
+List platforms
+String frequency
+String status
+DateTime last_queried_at
+DateTime next_query_at
+DateTime created_at
+DateTime updated_at
+user : User
+citation_records : List[CitationRecord]
+query_tasks : List[QueryTask]
}
class CitationRecord {
+UUID id
+UUID query_id
+String platform
+Boolean cited
+Integer citation_position
+String citation_text
+List competitor_brands
+String raw_response
+DateTime queried_at
+query : Query
}
class QueryTask {
+UUID id
+UUID query_id
+String platform
+String status
+String error_message
+DateTime scheduled_at
+DateTime started_at
+DateTime completed_at
+query : Query
}
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
}
User "1" --> "many" Query : "has"
User "1" --> "many" Subscription : "has"
Query "1" --> "many" CitationRecord : "has"
Query "1" --> "many" QueryTask : "has"
Query "1" --> "1" User : "belongs to"
Subscription "1" --> "1" User : "belongs to"
CitationRecord "1" --> "1" Query : "belongs to"
```
**图表来源**
- [user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
## 详细组件分析
### 用户模型(User)设计
用户模型是系统的基础实体，采用UUID作为主键，确保分布式环境下的唯一性。邮箱字段设置为唯一约束，支持用户名密码认证。
#### 字段设计分析
| 字段名 | 类型 | 约束 | 默认值 | 描述 |
|--------|------|------|--------|------|
| id | UUID | 主键, 唯一 | 自动生成 | 用户唯一标识符 |
| email | String(255) | 唯一, 非空 | - | 用户登录邮箱 |
| password_hash | String(255) | 非空 | - | 密码哈希值 |
| name | String(100) | 可空 | - | 用户姓名 |
| plan | String(20) | 非空 | "free" | 用户套餐类型 |
| max_queries | Integer | 非空 | 5 | 每月最大查询次数 |
| is_active | Boolean | 非空 | True | 账户激活状态 |
#### 关系映射
用户模型与查询模型和订阅模型建立一对多关系，使用级联删除确保数据一致性。
**章节来源**
- [user.py:11-41](file://backend/app/models/user.py#L11-L41)
### 查询模型(Query)设计
查询模型代表用户的搜索请求，支持多平台内容监控和定期执行。
#### 字段设计分析
| 字段名 | 类型 | 约束 | 默认值 | 描述 |
|--------|------|------|--------|------|
| id | UUID | 主键 | 自动生成 | 查询唯一标识符 |
| user_id | UUID | 外键, 非空 | - | 所属用户ID |
| keyword | String(200) | 非空 | - | 搜索关键词 |
| target_brand | String(100) | 非空 | - | 目标品牌名称 |
| brand_aliases | JSONB | 默认空列表 | [] | 品牌别名列表 |
| platforms | JSONB | 非空, 默认["wenxin","kimi"] | ["wenxin","kimi"] | 监控平台列表 |
| frequency | String(20) | 非空 | "weekly" | 查询频率 |
| status | String(20) | 非空 | "active" | 查询状态 |
| last_queried_at | DateTime | 可空 | - | 最后查询时间 |
| next_query_at | DateTime | 可空 | - | 下次查询时间 |
#### 关系映射
查询模型与用户、引用记录和查询任务建立复杂的关系：
- 与用户：一对多，外键约束确保数据完整性
- 与引用记录：一对多，级联删除孤儿记录
- 与查询任务：一对多，支持并行任务执行
#### 索引策略
查询模型包含三个关键索引：
- `idx_queries_user_id`: 加速用户查询
- `idx_queries_status`: 支持状态过滤查询
- `idx_queries_next_query_at`: 优化调度查询
**章节来源**
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
### 引用记录模型(CitationRecord)设计
引用记录模型存储从各平台抓取的品牌提及信息，支持详细的上下文分析。
#### 字段设计分析
| 字段名 | 类型 | 约束 | 默认值 | 描述 |
|--------|------|------|--------|------|
| id | UUID | 主键 | 自动生成 | 记录唯一标识符 |
| query_id | UUID | 外键, 非空 | - | 所属查询ID |
| platform | String(50) | 非空 | - | 内容来源平台 |
| cited | Boolean | 非空, 默认False | False | 是否提及目标品牌 |
| citation_position | Integer | 可空 | - | 内容在结果中的位置 |
| citation_text | Text | 可空 | - | 提及的具体文本内容 |
| competitor_brands | JSONB | 默认空列表 | [] | 竞争对手品牌列表 |
| raw_response | Text | 可空 | - | 原始响应内容 |
| queried_at | DateTime | 非空 | 当前时间 | 记录创建时间 |
#### 关系映射
引用记录模型与查询模型建立一对多关系，支持按查询分组统计分析。
#### 索引策略
引用记录模型包含四个关键索引：
- `idx_citation_records_query_id`: 加速查询关联查询
- `idx_citation_records_queried_at`: 支持时间序列分析
- `idx_citation_records_platform`: 平台维度统计
**章节来源**
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
### 查询任务模型(QueryTask)设计
查询任务模型管理异步查询任务的完整生命周期，支持状态跟踪和错误处理。
#### 字段设计分析
| 字段名 | 类型 | 约束 | 默认值 | 描述 |
|--------|------|------|--------|------|
| id | UUID | 主键 | 自动生成 | 任务唯一标识符 |
| query_id | UUID | 外键, 非空 | - | 所属查询ID |
| platform | String(50) | 非空 | - | 执行平台 |
| status | String(20) | 非空, 默认"pending" | pending | 任务执行状态 |
| error_message | Text | 可空 | - | 错误信息 |
| scheduled_at | DateTime | 非空 | 当前时间 | 任务调度时间 |
| started_at | DateTime | 可空 | - | 任务开始时间 |
| completed_at | DateTime | 可空 | - | 任务完成时间 |
#### 关系映射
查询任务模型与查询模型建立一对多关系，支持任务状态监控和统计分析。
#### 索引策略
查询任务模型包含一个关键索引：
- `idx_query_tasks_status`: 支持任务状态筛选和调度
**章节来源**
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
### 订阅模型(Subscription)设计
订阅模型处理用户付费计划和账单管理，支持灵活的计费周期和状态管理。
#### 字段设计分析
| 字段名 | 类型 | 约束 | 默认值 | 描述 |
|--------|------|------|--------|------|
| id | UUID | 主键 | 自动生成 | 订阅唯一标识符 |
| user_id | UUID | 外键, 非空 | - | 所属用户ID |
| plan | String(20) | 非空 | - | 套餐类型 |
| status | String(20) | 非空, 默认"active" | active | 订阅状态 |
| start_date | Date | 非空 | - | 订阅开始日期 |
| end_date | Date | 非空 | - | 订阅结束日期 |
| amount | Numeric(10,2) | 可空 | - | 支付金额 |
| payment_method | String(50) | 可空 | - | 支付方式 |
| payment_id | String(255) | 可空 | - | 支付ID |
| created_at | DateTime | 非空 | 当前时间 | 创建时间 |
#### 关系映射
订阅模型与用户模型建立一对多关系，支持用户订阅状态查询。
**章节来源**
- [subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
## 依赖关系分析
GEO平台的数据模型之间存在清晰的依赖关系，形成完整的业务数据流。
```mermaid
graph TD
subgraph "用户层"
Users[Users表]
Subscriptions[Subscriptions表]
end
subgraph "查询层"
Queries[Queries表]
QueryTasks[QueryTasks表]
end
subgraph "内容层"
CitationRecords[CitationRecords表]
end
Users --> Queries
Users --> Subscriptions
Queries --> CitationRecords
Queries --> QueryTasks
QueryTasks --> CitationRecords
```
**图表来源**
- [488d0bd5ab01_initial_migration.py:23-111](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L23-L111)
### 外键约束分析
系统采用严格的外键约束确保数据完整性：
- 查询记录删除时自动删除相关引用记录和任务记录
- 用户删除时自动清理其所有查询和订阅信息
- 外键约束支持级联删除，防止悬挂数据
### 级联操作策略
- **查询记录**: 删除查询时级联删除所有相关记录
- **用户信息**: 删除用户时级联清理所有关联数据
- **任务管理**: 支持独立的任务生命周期管理
**章节来源**
- [488d0bd5ab01_initial_migration.py:55](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L55)
- [488d0bd5ab01_initial_migration.py:74](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L74)
- [488d0bd5ab01_initial_migration.py:92](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L92)
## 性能考虑
GEO平台的数据模型在设计时充分考虑了性能优化，采用多种策略提升查询效率和系统吞吐量。
### 索引优化策略
#### 查询模型索引
- `idx_queries_user_id`: 支持按用户快速检索查询
- `idx_queries_status`: 优化状态过滤查询
- `idx_queries_next_query_at`: 加速调度任务查询
#### 引用记录模型索引
- `idx_citation_records_query_id`: 支持按查询分组统计
- `idx_citation_records_queried_at`: 时间序列分析优化
- `idx_citation_records_platform`: 平台维度查询优化
#### 查询任务模型索引
- `idx_query_tasks_status`: 任务状态筛选优化
### 查询优化建议
1. **批量操作**: 使用批量插入和更新减少数据库往返
2. **延迟加载**: 对于大型JSONB字段采用延迟加载策略
3. **分页查询**: 对大量数据采用分页机制避免内存溢出
4. **缓存策略**: 结合Redis缓存热点数据
### 数据库连接管理
系统使用异步数据库连接池，配置如下：
- 连接超时: 60秒
- 连接池大小: 10-20个连接
- 自动重连: 启用连接池重连机制
**章节来源**
- [database.py:6-18](file://backend/app/database.py#L6-L18)
## 故障排除指南
### 常见问题诊断
#### 数据库连接问题
- 检查DATABASE_URL配置是否正确
- 验证PostgreSQL服务可用性
- 确认网络连接和防火墙设置
#### 索引性能问题
- 分析慢查询日志识别瓶颈
- 检查索引使用情况
- 考虑添加复合索引优化查询
#### 数据一致性问题
- 验证外键约束是否正确设置
- 检查级联删除行为
- 确认事务边界设置
### 调试工具使用
1. **数据库监控**: 使用EXPLAIN ANALYZE分析查询计划
2. **连接池监控**: 监控连接池使用率和等待时间
3. **慢查询追踪**: 启用慢查询日志分析性能瓶颈
**章节来源**
- [config.py:7](file://backend/app/config.py#L7)
## 结论
GEO平台的数据模型设计体现了现代Web应用的最佳实践，通过清晰的实体关系、完善的索引策略和异步数据库访问实现了高性能和高可用性。模型设计充分考虑了业务需求的复杂性，支持多平台内容监控、智能调度和详细统计分析。
系统的主要优势包括：
- **强类型设计**: 所有字段都有明确的类型定义和约束
- **关系完整性**: 通过外键约束和级联操作确保数据一致性
- **性能优化**: 合理的索引策略和异步数据库访问
- **扩展性**: 模块化的架构设计便于功能扩展
未来可以考虑的改进方向：
- 添加审计日志支持
- 实现数据分区策略
- 增加数据备份和恢复机制
- 优化大数据量场景下的查询性能
Reference in New Issue View Git Blame Copy Permalink