# 数据库设计

<cite>
**本文档引用的文件**
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py)
- [backend/app/models/query_task.py](file://backend/app/models/query_task.py)
- [backend/app/models/subscription.py](file://backend/app/models/subscription.py)
- [backend/app/models/__init__.py](file://backend/app/models/__init__.py)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/config.py](file://backend/app/config.py)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/services/citation.py](file://backend/app/services/citation.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
</cite>

## 更新摘要
**变更内容**
- 新增用户管理相关字段的数据库迁移（email_verified、verification_code、reset_token等）
- 更新User模型以支持完整的用户认证和管理功能
- 新增用户注册、登录、邮箱验证、密码重置等认证API
- 增强用户角色管理，支持管理员权限控制
- 更新数据库迁移版本链，从初始版本到最新版本

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为 GEO 智能检索与引用监测平台的数据库设计文档，聚焦于基于 PostgreSQL 的关系型数据库架构，涵盖：
- 表结构设计与实体关系映射（ER）
- 索引策略与查询优化
- SQLAlchemy ORM 模型实现（模型定义、关系配置、查询封装）
- 数据库迁移管理、版本控制与部署策略
- 数据完整性约束、事务处理与并发控制
- 性能优化、查询分析与缓存策略
- 备份、恢复与维护最佳实践

## 项目结构
后端采用 FastAPI + SQLAlchemy Async + Alembic 迁移的典型分层架构：
- 配置层：读取环境变量，提供数据库连接字符串
- 数据库引擎与会话：异步连接池与会话工厂
- ORM 模型层：用户、查询、引用记录、任务、订阅
- 迁移层：Alembic 初始化迁移脚本
- 服务层：业务查询封装，统一事务边界
- 容器编排：Docker Compose 启动 Postgres 与 Redis

```mermaid
graph TB
subgraph "应用层"
AuthAPI["API: 认证<br/>backend/app/api/auth.py"]
API["API: 引用<br/>backend/app/api/citations.py"]
Reports["API: 报告<br/>backend/app/api/reports.py"]
end
subgraph "服务层"
SvcAuth["服务: 认证<br/>backend/app/services/auth.py"]
SvcQ["服务: 查询<br/>backend/app/services/query.py"]
SvcC["服务: 引用<br/>backend/app/services/citation.py"]
end
subgraph "ORM 层"
MUser["模型: 用户<br/>backend/app/models/user.py"]
MQuery["模型: 查询<br/>backend/app/models/query.py"]
MCit["模型: 引用记录<br/>backend/app/models/citation_record.py"]
MTask["模型: 查询任务<br/>backend/app/models/query_task.py"]
MSub["模型: 订阅<br/>backend/app/models/subscription.py"]
end
subgraph "基础设施"
DB["PostgreSQL 数据库"]
RD["Redis 缓存"]
end
Cfg["配置: DATABASE_URL<br/>backend/app/config.py"]
Eng["引擎与会话<br/>backend/app/database.py"]
Alembic["迁移: Alembic<br/>backend/alembic/*"]
Cfg --> Eng
Eng --> DB
AuthAPI --> SvcAuth
API --> SvcC
Reports --> SvcC
SvcAuth --> Eng
SvcQ --> Eng
SvcC --> Eng
MUser --> Eng
MQuery --> Eng
MCit --> Eng
MTask --> Eng
MSub --> Eng
Alembic --> DB
SvcAuth --> RD
SvcC --> RD
```

图表来源
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/user.py:1-48](file://backend/app/models/user.py#L1-L48)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

章节来源
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 核心组件
- 数据库引擎与会话
  - 使用异步引擎与会话工厂，开启自动提交、自动刷新、自动回滚等参数，确保事务一致性与资源释放。
  - 提供依赖注入式 get_db 生成器，保证每个请求生命周期内复用同一会话。
- ORM 模型
  - 所有模型继承自统一的 Base，表名与字段类型均在模型中显式声明。
  - 关系通过 relationship 显式配置，支持级联删除与孤儿对象清理。
- 迁移与版本控制
  - Alembic 环境集成 SQLAlchemy Base 元数据，支持离线/在线迁移。
  - 初始迁移脚本定义了用户、查询、引用记录、查询任务、订阅五张表及必要索引。
  - 新增迁移版本支持confidence和match_type字段，增强报告功能。
  - **新增** 最新迁移版本添加用户管理相关字段，支持完整的用户认证和管理功能。
- 服务层封装
  - 查询与引用统计、导出等业务逻辑封装在服务层，统一执行 SQL 并返回结果。
  - 对外暴露清晰的查询接口，内部进行权限校验与计数限制。
  - **新增** 认证服务封装用户注册、登录、验证等功能。

章节来源
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:1-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L1-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:1-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L1-L37)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py:1-41](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py#L1-L41)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/services/citation.py:1-429](file://backend/app/services/citation.py#L1-L429)
- [backend/app/services/auth.py:1-175](file://backend/app/services/auth.py#L1-L175)

## 架构总览
下图展示数据库层与应用层的交互关系，以及迁移与容器编排对数据库的影响。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant AuthAPI as "认证API"
participant API as "FastAPI 应用"
participant SvcAuth as "认证服务"
participant SvcC as "引用服务"
participant Reports as "报告服务"
participant DB as "PostgreSQL"
participant Alembic as "迁移工具"
Client->>AuthAPI : 请求 /auth/register 登录
AuthAPI->>SvcAuth : 调用认证服务
SvcAuth->>DB : 执行用户注册/验证
Client->>API : 请求 /citations 或 /reports
API->>SvcC : 调用引用服务
SvcC->>DB : 执行查询/统计/插入
API->>Reports : 调用报告服务
Reports->>DB : 执行导出查询
DB-->>Reports : 返回统计数据
DB-->>SvcC : 返回引用记录
DB-->>SvcAuth : 返回用户信息
Reports-->>API : 返回CSV内容
SvcC-->>API : 返回查询列表/详情
SvcAuth-->>AuthAPI : 返回认证结果
AuthAPI-->>Client : 响应认证数据
Note over Alembic,DB : 首次启动或升级时执行迁移
```

图表来源
- [backend/app/services/citation.py:1-429](file://backend/app/services/citation.py#L1-L429)
- [backend/app/services/auth.py:1-175](file://backend/app/services/auth.py#L1-L175)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)

## 详细组件分析

### 实体关系映射（ER）
- 用户（users）：主键 id，唯一邮箱，计划与配额字段，活跃状态，**新增**邮箱验证状态、验证码及其过期时间、重置令牌及其过期时间、头像URL、管理员权限，时间戳。
- 查询（queries）：外键 user_id，关键词、目标品牌、别名列表、平台列表、频率、状态、下次查询时间，时间戳。
- 引用记录（citation_records）：外键 query_id，平台、是否引用、引用位置、引用文本、竞争品牌列表、原始响应、匹配置信度、匹配类型、查询时间。
- 查询任务（query_tasks）：外键 query_id，平台、状态、错误信息、调度/开始/完成时间。
- 订阅（subscriptions）：外键 user_id，计划、状态、起止日期、金额、支付方式与流水号，时间戳。

**更新** 用户表新增完整的用户管理字段，支持邮箱验证、密码重置、头像管理和管理员权限控制。

```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
integer max_queries
boolean is_active
boolean email_verified
string verification_code
timestamptz verification_code_expires
string reset_token
timestamptz reset_token_expires
string avatar_url
boolean is_admin
timestamptz created_at
timestamptz updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamptz last_queried_at
timestamptz next_query_at
timestamptz created_at
timestamptz updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
boolean cited
integer citation_position
text citation_text
jsonb competitor_brands
text raw_response
float confidence
string match_type
timestamptz queried_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
timestamptz scheduled_at
timestamptz started_at
timestamptz completed_at
}
SUBSCRIPTIONS {
uuid id PK
uuid user_id FK
string plan
string status
date start_date
date end_date
numeric amount
string payment_method
string payment_id
timestamptz created_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"
QUERIES ||--o{ QUERY_TASKS : "触发"
USERS ||--o{ SUBSCRIPTIONS : "订阅"
```

图表来源
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
- [backend/app/models/query.py:11-48](file://backend/app/models/query.py#L11-L48)
- [backend/app/models/citation_record.py:11-44](file://backend/app/models/citation_record.py#L11-L44)
- [backend/app/models/query_task.py:11-34](file://backend/app/models/query_task.py#L11-L34)
- [backend/app/models/subscription.py:11-36](file://backend/app/models/subscription.py#L11-L36)

章节来源
- [backend/app/models/user.py:1-48](file://backend/app/models/user.py#L1-L48)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)

### 索引策略
- 查询表（queries）
  - idx_queries_user_id：按用户过滤
  - idx_queries_status：按状态过滤
  - idx_queries_next_query_at：按下次查询时间调度
- 引用记录表（citation_records）
  - idx_citation_records_query_id：按查询聚合
  - idx_citation_records_queried_at：按时间排序/范围
  - idx_citation_records_platform：按平台统计
  - **新增** idx_citation_records_confidence：按匹配置信度过滤（建议）
  - **新增** idx_citation_records_match_type：按匹配类型过滤（建议）
- **新增** 用户表（users）
  - idx_users_email：按邮箱快速查找
  - idx_users_verification_code：按验证码快速验证
  - idx_users_reset_token：按重置令牌快速验证

**更新** 新增针对用户管理字段的索引建议，支持高效的用户认证和验证操作。

这些索引覆盖了常见查询路径与统计场景，有助于提升分页、过滤、排序与聚合的性能。

章节来源
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:57-94](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L57-L94)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py:21-41](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py#L21-L41)
- [backend/app/models/query.py:50-54](file://backend/app/models/query.py#L50-L54)
- [backend/app/models/citation_record.py:37-44](file://backend/app/models/citation_record.py#L37-L44)
- [backend/app/models/query_task.py:36-38](file://backend/app/models/query_task.py#L36-L38)

### SQLAlchemy ORM 模型实现
- 字段类型与默认值
  - UUID 主键与外键，JSONB 存储数组/字典，布尔、整数、文本、数值、时间戳等。
  - 默认值通过 server_default/onupdate 设置，减少应用层重复逻辑。
  - **新增** email_verified字段（Boolean类型，默认False）用于邮箱验证状态。
  - **新增** verification_code字段（String类型，长度6，nullable=True）用于存储6位验证码。
  - **新增** verification_code_expires字段（DateTime类型，nullable=True）用于验证码过期时间。
  - **新增** reset_token字段（String类型，长度255，nullable=True）用于密码重置令牌。
  - **新增** reset_token_expires字段（DateTime类型，nullable=True）用于重置令牌过期时间。
  - **新增** avatar_url字段（String类型，长度500，nullable=True）用于用户头像URL。
  - **新增** is_admin字段（Boolean类型，默认False）用于管理员权限控制。
  - **新增** confidence字段（Float类型，nullable=True）用于存储匹配的可信度评分。
  - **新增** match_type字段（String类型，长度20，nullable=True）用于标识匹配类型。
- 关系配置
  - 用户与查询、订阅为一对多；查询与引用记录、任务为一对多。
  - 级联删除与孤儿对象清理（delete-orphan），避免悬挂数据。
- 查询封装
  - 服务层使用 select + func + join 封装复杂查询，统一处理分页与计数。
  - 权限校验：仅允许访问当前用户的资源，防止越权。

**更新** User模型新增完整的用户管理字段，支持邮箱验证、密码重置、头像管理和管理员权限控制。

```mermaid
classDiagram
class User {
+id : uuid
+email : string
+password_hash : string
+name : string
+plan : string
+max_queries : int
+is_active : bool
+email_verified : bool
+verification_code : string
+verification_code_expires : datetime
+reset_token : string
+reset_token_expires : datetime
+avatar_url : string
+is_admin : bool
+created_at : datetime
+updated_at : datetime
+queries
+subscriptions
}
class Query {
+id : uuid
+user_id : uuid
+keyword : string
+target_brand : string
+brand_aliases : list
+platforms : list
+frequency : string
+status : string
+last_queried_at : datetime
+next_query_at : datetime
+created_at : datetime
+updated_at : datetime
+user
+citation_records
+query_tasks
}
class CitationRecord {
+id : uuid
+query_id : uuid
+platform : string
+cited : bool
+citation_position : int
+citation_text : text
+competitor_brands : list
+raw_response : text
+confidence : float
+match_type : string
+queried_at : datetime
+query
}
class QueryTask {
+id : uuid
+query_id : uuid
+platform : string
+status : string
+error_message : text
+scheduled_at : datetime
+started_at : datetime
+completed_at : datetime
+query
}
class Subscription {
+id : uuid
+user_id : uuid
+plan : string
+status : string
+start_date : date
+end_date : date
+amount : float
+payment_method : string
+payment_id : string
+created_at : datetime
+user
}
User "1" <-- "many" Query : "拥有"
Query "1" <-- "many" CitationRecord : "产生"
Query "1" <-- "many" QueryTask : "触发"
User "1" <-- "many" Subscription : "订阅"
```

图表来源
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
- [backend/app/models/query.py:11-48](file://backend/app/models/query.py#L11-L48)
- [backend/app/models/citation_record.py:11-44](file://backend/app/models/citation_record.py#L11-L44)
- [backend/app/models/query_task.py:11-34](file://backend/app/models/query_task.py#L11-L34)
- [backend/app/models/subscription.py:11-36](file://backend/app/models/subscription.py#L11-L36)

章节来源
- [backend/app/models/user.py:1-48](file://backend/app/models/user.py#L1-L48)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)

### 数据库迁移管理、版本控制与部署策略
- 迁移入口
  - Alembic 环境加载 Base 元数据，支持离线/在线迁移。
  - 在线迁移通过异步引擎连接数据库，避免阻塞。
- 迁移版本
  - **初始版本** (488d0bd5ab01)：创建 users、queries、citation_records、query_tasks、subscriptions 表，并建立必要索引。
  - **版本2** (b2c4d6e8fa10)：向 citation_records 表添加 confidence 和 match_type 字段，支持增强的报告功能。
  - **新增版本3** (c3d5e7f9ab12)：向 users 表添加 email_verified、verification_code、verification_code_expires、reset_token、reset_token_expires、avatar_url、is_admin 等用户管理字段。
  - 外键约束与级联删除策略明确，确保数据一致性。
- 部署策略
  - Docker Compose 启动 PostgreSQL 与 Redis，应用容器依赖数据库健康检查。
  - 生产环境建议将数据库与缓存分离，使用独立卷持久化数据。

**更新** 新增c3d5e7f9ab12迁移版本，支持完整的用户管理功能。

```mermaid
flowchart TD
Start(["开始"]) --> CheckEnv["检查 DATABASE_URL"]
CheckEnv --> LoadBase["加载 Base 元数据"]
LoadBase --> Mode{"运行模式"}
Mode --> |离线| Offline["配置 URL 与元数据"]
Mode --> |在线| Online["创建异步引擎并连接"]
Offline --> RunMigs["执行迁移"]
Online --> RunMigs
RunMigs --> Version{"检查版本"}
Version --> |488d0bd5ab01| InitMigration["初始迁移"]
Version --> |b2c4d6e8fa10| AddConfidence["添加置信度字段"]
Version --> |c3d5e7f9ab12| AddUserFields["添加用户管理字段"]
InitMigration --> AddConfidence --> AddUserFields --> Done(["完成"])
```

图表来源
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:21-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L21-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py:21-41](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py#L21-L41)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

章节来源
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:1-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L1-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:1-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L1-L37)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py:1-41](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py#L1-L41)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

### 数据完整性约束、事务处理与并发控制
- 完整性约束
  - 唯一约束：用户邮箱唯一
  - 外键约束：查询、任务、订阅均对用户做级联删除
  - JSONB 字段默认值：空数组/字典，避免 NULL 导致的条件判断复杂化
  - **新增** email_verified字段默认False，is_admin字段默认False
  - **新增** verification_code长度限制为6位，reset_token长度限制为255位
  - **新增** avatar_url长度限制为500字符，match_type长度限制为20字符
- 事务处理
  - 服务层方法在单个事务内执行插入/更新/删除，提交后刷新对象状态
  - 会话工厂设置 expire_on_commit=False，减少后续查询的额外开销
- 并发控制
  - 异步连接池与会话隔离，避免阻塞
  - 服务层在执行前进行权限校验与配额检查，降低并发冲突概率

**更新** 新增用户管理字段的完整性约束说明，包括长度限制和默认值设置。

章节来源
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:36-111](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L36-L111)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py:21-41](file://backend/alembic/versions/c3d5e7f9ab12_add_user_management_fields.py#L21-L41)
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/database.py:12-18](file://backend/app/database.py#L12-L18)

### 查询流程与优化要点
- 查询列表与计数
  - 分页查询与计数分离，避免重复扫描全表
  - 使用索引覆盖 user_id 与 created_at 排序
  - **新增** 支持按confidence和match_type过滤查询
- 引用统计
  - 使用 JOIN 查询限定到用户所属的查询
  - 按平台分组统计，利用索引加速 queried_at 与 platform
  - **新增** 支持按匹配置信度和匹配类型进行统计分析
- 导出 CSV
  - 以查询为维度导出，先验证所有权再执行导出
  - **新增** 输出confidence和match_type字段到CSV文件
- **新增** 用户管理查询
  - 支持按邮箱验证状态、管理员权限等条件过滤用户
  - 支持验证码和重置令牌的有效性检查

**更新** 增强查询流程，支持新的用户管理字段和认证功能。

```mermaid
sequenceDiagram
participant AuthAPI as "认证API"
participant SvcAuth as "认证服务"
participant DB as "数据库"
AuthAPI->>SvcAuth : register_user(email, password, name)
SvcAuth->>DB : INSERT INTO users (email, password_hash, name)
DB-->>SvcAuth : 新用户ID
SvcAuth->>DB : SELECT * FROM users WHERE email = ?
DB-->>SvcAuth : 用户信息
SvcAuth-->>AuthAPI : UserResponse
```

图表来源
- [backend/app/services/auth.py:40-56](file://backend/app/services/auth.py#L40-L56)

章节来源
- [backend/app/services/query.py:12-32](file://backend/app/services/query.py#L12-L32)
- [backend/app/services/citation.py:30-79](file://backend/app/services/citation.py#L30-L79)
- [backend/app/services/auth.py:40-56](file://backend/app/services/auth.py#L40-L56)

### 报告功能增强
- **匹配置信度分析**
  - confidence字段用于存储匹配的可信度评分（0.0-1.0）
  - 支持按置信度区间进行统计分析
  - 在CSV导出中显示详细的置信度信息
- **匹配类型分类**
  - match_type字段标识匹配类型：exact（精确匹配）、alias（别名匹配）、fuzzy（模糊匹配）
  - 支持按匹配类型进行分组统计
  - 在报告中提供中文显示（精确匹配、别名匹配、模糊匹配）
- **增强的统计指标**
  - 支持按置信度和匹配类型的组合进行交叉分析
  - 提供更精细的引用质量评估

**新增** 报告功能章节，详细介绍新增的confidence和match_type字段的应用。

章节来源
- [backend/app/services/citation.py:298-308](file://backend/app/services/citation.py#L298-L308)
- [backend/app/services/citation.py:342-429](file://backend/app/services/citation.py#L342-L429)
- [backend/app/schemas/citation.py:7-18](file://backend/app/schemas/citation.py#L7-L18)

### 用户管理功能
- **邮箱验证系统**
  - email_verified字段跟踪邮箱验证状态
  - verification_code和verification_code_expires字段管理验证码
  - 支持验证码重发和过期检查
- **密码重置系统**
  - reset_token和reset_token_expires字段管理重置令牌
  - 支持安全的密码重置流程
- **用户资料管理**
  - name字段存储用户姓名
  - avatar_url字段存储用户头像URL
  - 支持资料更新和头像上传
- **管理员权限控制**
  - is_admin字段标识管理员身份
  - 支持管理员专用功能和权限控制

**新增** 用户管理功能章节，详细介绍新增的用户管理字段和相关API。

章节来源
- [backend/app/services/auth.py:74-107](file://backend/app/services/auth.py#L74-L107)
- [backend/app/services/auth.py:110-140](file://backend/app/services/auth.py#L110-L140)
- [backend/app/schemas/auth.py:8-55](file://backend/app/schemas/auth.py#L8-L55)
- [backend/app/api/auth.py:33-115](file://backend/app/api/auth.py#L33-L115)

## 依赖分析
- 模块耦合
  - 模型层仅依赖 Base 与 SQLAlchemy 类型，低耦合
  - 服务层依赖模型与会话，职责清晰
  - Alembic 依赖 Base 与配置，迁移脚本与模型同步演进
  - **新增** API层依赖服务层，提供RESTful接口
  - **新增** 认证API依赖认证服务，处理用户注册、登录、验证等
- 外部依赖
  - PostgreSQL 异步驱动（asyncpg）
  - Redis（用于缓存，如需要）

**更新** 新增API层依赖关系，支持新的认证和报告功能接口。

```mermaid
graph LR
Cfg["配置<br/>config.py"] --> DB["数据库引擎<br/>database.py"]
DB --> Models["ORM 模型<br/>models/*"]
Models --> Services["服务层<br/>services/*"]
Services --> AuthAPI["认证API<br/>api/auth.py"]
Services --> API["API层<br/>api/*"]
Alembic["迁移<br/>alembic/*"] --> DB
Docker["编排<br/>docker-compose.yml"] --> DB
```

图表来源
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

章节来源
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 性能考虑
- 索引优化
  - 为高频过滤字段建立单列索引（user_id/status/next_query_at/platform/queried_at/confidence/match_type）
  - 对 JSONB 字段可考虑 GIN 索引（如需复杂查询），当前迁移脚本未启用
  - **新增** 为用户管理字段建立索引：email、verification_code、reset_token
  - **新增** 建议为confidence和match_type字段建立单独索引，支持高效过滤
- 查询优化
  - 分页与计数分离，避免重复扫描
  - 使用 JOIN 限定用户范围，减少全表扫描
  - 时间范围查询使用索引覆盖
  - **新增** 支持按confidence范围和match_type进行高效过滤
  - **新增** 支持按邮箱验证状态和管理员权限进行高效过滤
- 缓存策略
  - 引用统计与趋势数据可缓存至 Redis，设置合理过期时间
  - 导出 CSV 可缓存热点查询结果，降低数据库压力
  - **新增** 认证令牌和用户会话可缓存，提高认证效率
  - **新增** 报告统计数据可缓存，提高频繁访问的响应速度
- 连接与并发
  - 使用异步连接池，避免阻塞
  - 控制并发度，避免大量写入导致锁争用

**更新** 新增针对用户管理字段和新功能的性能优化建议。

## 故障排查指南
- 迁移失败
  - 检查 DATABASE_URL 是否正确，Alembic 配置与环境变量一致
  - 确认数据库已初始化且用户具备权限
  - **新增** 检查新字段的默认值和约束条件
  - **新增** 验证用户管理字段的数据类型和长度限制
- 查询异常
  - 核对服务层权限校验逻辑，确认 user_id 与查询归属一致
  - 检查索引是否存在，必要时重建索引
  - **新增** 验证confidence和match_type字段的数据类型和取值范围
  - **新增** 检查用户管理字段的验证逻辑和过期时间
- 导出失败
  - 确认查询所有权校验通过
  - 检查 CSV 写入逻辑与字符编码
  - **新增** 验证新字段在导出过程中的处理逻辑
- **新增** 认证功能故障
  - 检查JWT密钥配置和令牌生成
  - 验证验证码和重置令牌的有效性
  - 确认邮箱验证流程的正确性

**更新** 新增针对用户管理功能和新字段的故障排查指导。

章节来源
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/app/services/citation.py:14-22](file://backend/app/services/citation.py#L14-L22)
- [backend/app/services/auth.py:74-107](file://backend/app/services/auth.py#L74-L107)

## 结论
本数据库设计围绕用户、查询、引用记录、任务与订阅五大实体展开，采用 PostgreSQL + SQLAlchemy Async + Alembic 的成熟技术栈，具备良好的扩展性与可维护性。通过合理的索引策略、事务边界与服务层封装，能够满足日常查询、统计与导出需求。

**更新** 新增的用户管理功能显著增强了系统的完整性和安全性，提供了完整的认证、授权和用户管理能力。新增的confidence和match_type字段显著增强了报告功能，提供了更精细的引用质量分析能力。建议在生产环境中进一步引入缓存与监控，持续优化查询路径与索引覆盖。

## 附录
- 部署与运维
  - 使用 Docker Compose 启动数据库与应用，确保数据库健康检查通过后再启动应用
  - 生产环境建议使用独立数据库实例与只读副本，配合连接池与慢查询日志
  - **新增** 升级时确保迁移脚本按顺序执行，从初始版本到最新版本
  - **新增** 配置JWT密钥和Redis缓存，确保认证功能正常运行
- 备份与恢复
  - 使用 pg_dump/pg_restore 进行逻辑备份与恢复
  - 对关键表定期增量备份，结合 WAL 归档实现点-in-time 恢复
  - **新增** 新字段变更需要纳入备份策略，确保数据完整性
  - **新增** 用户管理字段包含敏感信息，需要特别注意备份安全
- 监控与告警
  - 监控连接数、查询延迟、索引命中率与慢查询
  - 对迁移脚本变更进行版本化管理与回滚演练
  - **新增** 监控新字段的使用情况和性能影响
  - **新增** 监控用户认证和验证功能的运行状态

**更新** 新增针对用户管理功能和新字段的部署和运维指导。