25 KiB

Raw Blame History

数据库设计

**本文档引用的文件** - [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.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/schemas/citation.py](file://backend/app/schemas/citation.py) - [backend/app/api/citations.py](file://backend/app/api/citations.py) - [backend/app/api/reports.py](file://backend/app/api/reports.py)

更新摘要

变更内容

新增数据库迁移版本，添加confidence和match_type字段到citation_records表
更新CitationRecord模型以支持新的字段定义
增强报告功能，支持匹配置信度和匹配类型的统计分析
更新CSV导出功能，包含新的字段输出

简介

本文件为 GEOF 智能检索与引用监测平台的数据库设计文档，聚焦于基于 PostgreSQL 的关系型数据库架构，涵盖：

表结构设计与实体关系映射（ER）
索引策略与查询优化
SQLAlchemy ORM 模型实现（模型定义、关系配置、查询封装）
数据库迁移管理、版本控制与部署策略
数据完整性约束、事务处理与并发控制
性能优化、查询分析与缓存策略
备份、恢复与维护最佳实践

项目结构

后端采用 FastAPI + SQLAlchemy Async + Alembic 迁移的典型分层架构：

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

graph TB
subgraph "应用层"
SvcQ["服务: 查询<br/>backend/app/services/query.py"]
SvcC["服务: 引用<br/>backend/app/services/citation.py"]
API["API: 引用<br/>backend/app/api/citations.py"]
Reports["API: 报告<br/>backend/app/api/reports.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
SvcQ --> Eng
SvcC --> Eng
API --> SvcC
Reports --> SvcC
MUser --> Eng
MQuery --> Eng
MCit --> Eng
MTask --> Eng
MSub --> Eng
Alembic --> DB
SvcQ --> RD
SvcC --> RD

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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

图表来源

详细组件分析

实体关系映射（ER）

用户（users）：主键 id，唯一邮箱，计划与配额字段，活跃状态，时间戳。
查询（queries）：外键 user_id，关键词、目标品牌、别名列表、平台列表、频率、状态、下次查询时间，时间戳。
引用记录（citation_records）：外键 query_id，平台、是否引用、引用位置、引用文本、竞争品牌列表、原始响应、匹配置信度、匹配类型、查询时间。
查询任务（query_tasks）：外键 query_id，平台、状态、错误信息、调度/开始/完成时间。
订阅（subscriptions）：外键 user_id，计划、状态、起止日期、金额、支付方式与流水号，时间戳。

更新新增confidence和match_type字段到引用记录表，支持增强的报告功能。

erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
integer max_queries
boolean is_active
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 : "订阅"

图表来源

章节来源

索引策略

查询表（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：按匹配类型过滤（建议）

更新新增针对confidence和match_type字段的索引建议，支持更精细的查询过滤。

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

章节来源

SQLAlchemy ORM 模型实现

字段类型与默认值
- UUID 主键与外键，JSONB 存储数组/字典，布尔、整数、文本、数值、时间戳等。
- 默认值通过 server_default/onupdate 设置，减少应用层重复逻辑。
- 新增 confidence字段（Float类型，nullable=True）用于存储匹配的可信度评分。
- 新增 match_type字段（String类型，长度20，nullable=True）用于标识匹配类型。
关系配置
- 用户与查询、订阅为一对多；查询与引用记录、任务为一对多。
- 级联删除与孤儿对象清理（delete-orphan），避免悬挂数据。
查询封装
- 服务层使用 select + func + join 封装复杂查询，统一处理分页与计数。
- 权限校验：仅允许访问当前用户的资源，防止越权。

更新 CitationRecord模型新增confidence和match_type字段定义，支持增强的报告功能。

classDiagram
class User {
+id : uuid
+email : string
+password_hash : string
+name : string
+plan : string
+max_queries : int
+is_active : 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 : "订阅"

图表来源

章节来源

数据库迁移管理、版本控制与部署策略

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

更新新增b2c4d6e8fa10迁移版本，支持confidence和match_type字段的添加。

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| AddFields["添加新字段"]
InitMigration --> Done(["完成"])
AddFields --> Done

图表来源

章节来源

数据完整性约束、事务处理与并发控制

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

更新新增对confidence和match_type字段的完整性约束说明。

章节来源

查询流程与优化要点

查询列表与计数
- 分页查询与计数分离，避免重复扫描全表
- 使用索引覆盖 user_id 与 created_at 排序
- 新增支持按confidence和match_type过滤查询
引用统计
- 使用 JOIN 查询限定到用户所属的查询
- 按平台分组统计，利用索引加速 queried_at 与 platform
- 新增支持按匹配置信度和匹配类型进行统计分析
导出 CSV
- 以查询为维度导出，先验证所有权再执行导出
- 新增输出confidence和match_type字段到CSV文件

更新增强查询流程，支持新的字段过滤和统计功能。

sequenceDiagram
participant API as "API"
participant Svc as "服务"
participant DB as "数据库"
API->>Svc : get_citations(user_id, query_id?, platform?, dates?, confidence?, match_type?)
Svc->>DB : SELECT ... FROM citation_records JOIN queries WHERE ...
DB-->>Svc : 记录集
Svc->>DB : COUNT ... FROM citation_records JOIN queries WHERE ...
DB-->>Svc : 总数
Svc-->>API : 结果与总数

图表来源

backend/app/services/citation.py:30-79

章节来源

报告功能增强

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

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

章节来源

依赖分析

模块耦合
- 模型层仅依赖 Base 与 SQLAlchemy 类型，低耦合
- 服务层依赖模型与会话，职责清晰
- Alembic 依赖 Base 与配置，迁移脚本与模型同步演进
- 新增 API层依赖服务层，提供RESTful接口
外部依赖
- PostgreSQL 异步驱动（asyncpg）
- Redis（用于缓存，如需要）

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

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

图表来源

章节来源

性能考虑

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

更新新增针对confidence和match_type字段的性能优化建议。

故障排查指南

迁移失败
- 检查 DATABASE_URL 是否正确，Alembic 配置与环境变量一致
- 确认数据库已初始化且用户具备权限
- 新增检查新字段的默认值和约束条件
查询异常
- 核对服务层权限校验逻辑，确认 user_id 与查询归属一致
- 检查索引是否存在，必要时重建索引
- 新增验证confidence和match_type字段的数据类型和取值范围
导出失败
- 确认查询所有权校验通过
- 检查 CSV 写入逻辑与字符编码
- 新增验证新字段在导出过程中的处理逻辑

更新新增针对新字段的故障排查指导。

章节来源

结论

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

更新新增的confidence和match_type字段显著增强了报告功能，提供了更精细的引用质量分析能力。建议在生产环境中进一步引入缓存与监控，持续优化查询路径与索引覆盖。

附录

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

更新新增针对新字段的部署和运维指导。

25 KiB Raw Blame History Unescape Escape

数据库设计

更新摘要

目录

简介

项目结构

核心组件

架构总览

详细组件分析

实体关系映射（ER）

索引策略

SQLAlchemy ORM 模型实现

数据库迁移管理、版本控制与部署策略

数据完整性约束、事务处理与并发控制

查询流程与优化要点

报告功能增强

依赖分析

性能考虑

故障排查指南

结论

附录

25 KiB

Raw Blame History