16 KiB

Raw Blame History

数据模型设计

**本文档中引用的文件** - [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)

简介

GEO平台的数据模型基于SQLAlchemy ORM构建，采用异步PostgreSQL数据库设计。该系统围绕用户查询管理、引用记录跟踪和任务调度构建，支持多平台内容监控和分析功能。数据模型设计遵循以下核心原则：异步数据库访问、强类型字段定义、级联关系管理和性能优化索引策略。

项目结构

GEO项目的数据层采用模块化设计，所有ORM模型位于backend/app/models/目录下，通过统一的Base类继承实现。数据库连接配置在database.py中定义，使用SQLAlchemy的异步引擎和会话管理。

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

图表来源

章节来源

核心组件

GEO平台包含五个核心数据模型，每个模型都经过精心设计以满足特定的业务需求：

用户模型(User)

用户模型是整个系统的核心实体，负责管理平台用户的基本信息、订阅状态和查询配额。模型包含完整的身份认证信息和权限控制字段。

查询模型(Query)

查询模型代表用户的搜索请求，包含关键词、目标品牌、平台配置和调度参数。该模型支持复杂的JSONB字段存储动态配置数据。

引用记录模型(CitationRecord)

引用记录模型用于存储从各个平台抓取的内容引用信息，包括品牌提及、置信度评分和上下文数据。支持文本搜索和位置标记功能。

查询任务模型(QueryTask)

查询任务模型管理异步查询任务的生命周期，包括调度状态、执行历史和错误处理。支持多平台并发执行和状态跟踪。

订阅模型(Subscription)

订阅模型处理用户付费计划和账单管理，包含计划类型、状态、日期范围和支付信息。与用户模型建立一对一关系。

章节来源

架构概览

GEO平台采用分层架构设计，数据模型层与业务逻辑层分离，确保了良好的可维护性和扩展性。

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)设计

用户模型是系统的基础实体，采用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

查询模型(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

引用记录模型(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

查询任务模型(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

订阅模型(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

依赖关系分析

GEO平台的数据模型之间存在清晰的依赖关系，形成完整的业务数据流。

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

外键约束分析

系统采用严格的外键约束确保数据完整性：

查询记录删除时自动删除相关引用记录和任务记录
用户删除时自动清理其所有查询和订阅信息
外键约束支持级联删除，防止悬挂数据

级联操作策略

查询记录: 删除查询时级联删除所有相关记录
用户信息: 删除用户时级联清理所有关联数据
任务管理: 支持独立的任务生命周期管理

章节来源

性能考虑

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: 任务状态筛选优化

查询优化建议

批量操作: 使用批量插入和更新减少数据库往返
延迟加载: 对于大型JSONB字段采用延迟加载策略
分页查询: 对大量数据采用分页机制避免内存溢出
缓存策略: 结合Redis缓存热点数据

数据库连接管理

系统使用异步数据库连接池，配置如下：

连接超时: 60秒
连接池大小: 10-20个连接
自动重连: 启用连接池重连机制

章节来源

database.py:6-18

故障排除指南

常见问题诊断

数据库连接问题

检查DATABASE_URL配置是否正确
验证PostgreSQL服务可用性
确认网络连接和防火墙设置

索引性能问题

分析慢查询日志识别瓶颈
检查索引使用情况
考虑添加复合索引优化查询

数据一致性问题

验证外键约束是否正确设置
检查级联删除行为
确认事务边界设置

调试工具使用

数据库监控: 使用EXPLAIN ANALYZE分析查询计划
连接池监控: 监控连接池使用率和等待时间
慢查询追踪: 启用慢查询日志分析性能瓶颈

章节来源

config.py:7

结论

GEO平台的数据模型设计体现了现代Web应用的最佳实践，通过清晰的实体关系、完善的索引策略和异步数据库访问实现了高性能和高可用性。模型设计充分考虑了业务需求的复杂性，支持多平台内容监控、智能调度和详细统计分析。

系统的主要优势包括：

强类型设计: 所有字段都有明确的类型定义和约束
关系完整性: 通过外键约束和级联操作确保数据一致性
性能优化: 合理的索引策略和异步数据库访问
扩展性: 模块化的架构设计便于功能扩展

未来可以考虑的改进方向：

添加审计日志支持
实现数据分区策略
增加数据备份和恢复机制
优化大数据量场景下的查询性能

16 KiB Raw Blame History Unescape Escape

数据模型设计

目录

简介

项目结构

核心组件

用户模型(User)

查询模型(Query)

引用记录模型(CitationRecord)

查询任务模型(QueryTask)

订阅模型(Subscription)

架构概览

详细组件分析

用户模型(User)设计

字段设计分析

关系映射

查询模型(Query)设计

字段设计分析

关系映射

索引策略

引用记录模型(CitationRecord)设计

字段设计分析

关系映射

索引策略

查询任务模型(QueryTask)设计

字段设计分析

关系映射

索引策略

订阅模型(Subscription)设计

字段设计分析

关系映射

依赖关系分析

外键约束分析

级联操作策略

性能考虑

索引优化策略

查询模型索引

引用记录模型索引

查询任务模型索引

查询优化建议

数据库连接管理

故障排除指南

常见问题诊断

数据库连接问题

索引性能问题

数据一致性问题

调试工具使用

结论

16 KiB

Raw Blame History