# 数据模型设计

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

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

未来可以考虑的改进方向：
- 添加审计日志支持
- 实现数据分区策略
- 增加数据备份和恢复机制
- 优化大数据量场景下的查询性能