# API接口文档

<cite>
**本文档中引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/schemas/query.py](file://backend/app/schemas/query.py)
- [backend/app/schemas/citation.py](file://backend/app/schemas/citation.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/services/citation.py](file://backend/app/services/citation.py)
- [backend/app/config.py](file://backend/app/config.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)
</cite>

## 更新摘要
**所做更改**
- 完善了认证接口的详细说明，包括注册、登录和用户信息查询
- 更新了查询管理接口的完整功能说明，涵盖CRUD操作和权限控制
- 补充了引用数据接口的统计分析和任务执行功能
- 增强了报告导出接口的CSV格式说明
- 完善了错误处理和状态码说明
- 更新了架构图和数据流图以反映实际实现

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

## 简介
本文件为GEO平台的完整API接口文档，涵盖认证、查询管理、引用数据、报告导出等核心功能模块。文档详细记录了所有RESTful API端点的HTTP方法、URL模式、请求参数与响应格式，并说明了JWT令牌管理、用户注册登录、权限验证机制、任务创建与执行、数据查询与统计分析、以及CSV格式报告导出流程。

## 项目结构
后端采用FastAPI框架，按功能模块组织API路由：认证(/api/v1/auth)、查询词(/api/v1/queries)、引用数据(/api/v1/citations)、报告(/api/v1/reports)。应用启动时初始化数据库模型并启动查询调度器，同时启用CORS允许前端localhost:3000访问。

```mermaid
graph TB
A["应用入口<br/>backend/app/main.py"] --> B["认证路由<br/>backend/app/api/auth.py"]
A --> C["查询路由<br/>backend/app/api/queries.py"]
A --> D["引用数据路由<br/>backend/app/api/citations.py"]
A --> E["报告路由<br/>backend/app/api/reports.py"]
A --> F["依赖注入与认证中间件<br/>backend/app/api/deps.py"]
A --> G["配置中心<br/>backend/app/config.py"]
A --> H["数据库模型<br/>backend/app/models/*.py"]
A --> I["业务服务层<br/>backend/app/services/*.py"]
A --> J["数据传输对象<br/>backend/app/schemas/*.py"]
```

**图表来源**
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [backend/app/api/auth.py:10](file://backend/app/api/auth.py#L10)
- [backend/app/api/queries.py:12](file://backend/app/api/queries.py#L12)
- [backend/app/api/citations.py:21](file://backend/app/api/citations.py#L21)
- [backend/app/api/reports.py:13](file://backend/app/api/reports.py#L13)
- [backend/app/api/deps.py:13](file://backend/app/api/deps.py#L13)

**章节来源**
- [backend/app/main.py:1-57](file://backend/app/main.py#L1-L57)

## 核心组件
- 应用入口与生命周期管理：定义应用标题、版本、CORS策略，注册各模块路由，启动/关闭查询调度器。
- 认证组件：提供注册、登录、当前用户信息查询；基于OAuth2密码流与JWT进行身份验证。
- 查询管理：支持查询词的增删改查、分页列表、频率与下次查询时间计算。
- 引用数据：支持引用记录查询、统计分析（总查询数、引用率、平台分布、趋势）、立即执行查询任务。
- 报告导出：支持CSV格式导出指定查询的引用记录。
- 数据模型与服务：用户、查询、引用记录、查询任务等模型及对应的服务逻辑。

**章节来源**
- [backend/app/main.py:13-57](file://backend/app/main.py#L13-L57)
- [backend/app/api/auth.py:13-42](file://backend/app/api/auth.py#L13-L42)
- [backend/app/api/queries.py:15-85](file://backend/app/api/queries.py#L15-L85)
- [backend/app/api/citations.py:25-77](file://backend/app/api/citations.py#L25-L77)
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)

## 架构概览
下图展示了客户端与后端各模块之间的交互关系，包括认证流程、查询管理、引用数据处理与报告导出。

```mermaid
graph TB
subgraph "客户端"
FE["前端应用<br/>localhost:3000"]
end
subgraph "后端服务"
AUTH["认证模块<br/>/api/v1/auth"]
QUERIES["查询模块<br/>/api/v1/queries"]
CITATIONS["引用数据模块<br/>/api/v1/citations"]
REPORTS["报告模块<br/>/api/v1/reports"]
DEPS["依赖注入与认证中间件"]
MODELS["数据模型层"]
SERVICES["业务服务层"]
CONFIG["配置中心"]
end
FE --> AUTH
FE --> QUERIES
FE --> CITATIONS
FE --> REPORTS
AUTH --> DEPS
QUERIES --> DEPS
CITATIONS --> DEPS
REPORTS --> DEPS
AUTH --> SERVICES
QUERIES --> SERVICES
CITATIONS --> SERVICES
REPORTS --> SERVICES
SERVICES --> MODELS
MODELS --> CONFIG
```

**图表来源**
- [backend/app/main.py:38-51](file://backend/app/main.py#L38-L51)
- [backend/app/api/deps.py:16-42](file://backend/app/api/deps.py#L16-L42)
- [backend/app/services/auth.py:37-68](file://backend/app/services/auth.py#L37-L68)
- [backend/app/services/query.py:12-123](file://backend/app/services/query.py#L12-L123)
- [backend/app/services/citation.py:24-359](file://backend/app/services/citation.py#L24-L359)

## 详细组件分析

### 认证接口
- 接口前缀：/api/v1/auth
- 路由与功能：
  - POST /register：用户注册，返回用户信息
  - POST /login：用户登录，返回JWT访问令牌与用户信息
  - GET /me：获取当前登录用户信息
- 认证机制：
  - 使用OAuth2密码流，令牌类型为bearer
  - 通过依赖注入获取当前用户，校验JWT有效性
  - 用户名/密码验证通过后签发JWT，包含用户ID作为sub字段
- 请求参数与响应格式：
  - 注册：邮箱、密码、姓名
  - 登录：邮箱、密码
  - 当前用户：用户ID、邮箱、姓名、计划、最大查询数、激活状态、创建时间
  - 访问令牌：访问令牌字符串、令牌类型、用户信息
- 错误处理：
  - 注册：邮箱已存在时返回400
  - 登录：凭据无效时返回401
  - 获取当前用户：凭据无效或用户不存在时返回401

```mermaid
sequenceDiagram
participant Client as "客户端"
participant AuthAPI as "认证API"
participant AuthService as "认证服务"
participant DB as "数据库"
Client->>AuthAPI : POST /api/v1/auth/register
AuthAPI->>AuthService : 注册用户
AuthService->>DB : 检查邮箱唯一性
DB-->>AuthService : 结果
AuthService->>DB : 创建用户并存储密码哈希
DB-->>AuthService : 新用户
AuthService-->>AuthAPI : 用户信息
AuthAPI-->>Client : 201 用户信息
Client->>AuthAPI : POST /api/v1/auth/login
AuthAPI->>AuthService : 验证用户名/密码
AuthService->>DB : 查询用户
DB-->>AuthService : 用户
AuthService->>AuthService : 校验密码
AuthService->>AuthService : 生成JWT
AuthService-->>AuthAPI : 访问令牌与用户信息
AuthAPI-->>Client : 200 访问令牌
```

**图表来源**
- [backend/app/api/auth.py:13-37](file://backend/app/api/auth.py#L13-L37)
- [backend/app/services/auth.py:37-68](file://backend/app/services/auth.py#L37-L68)
- [backend/app/api/deps.py:16-42](file://backend/app/api/deps.py#L16-L42)

**章节来源**
- [backend/app/api/auth.py:13-42](file://backend/app/api/auth.py#L13-L42)
- [backend/app/api/deps.py:16-42](file://backend/app/api/deps.py#L16-L42)
- [backend/app/schemas/auth.py:7-34](file://backend/app/schemas/auth.py#L7-L34)
- [backend/app/services/auth.py:37-68](file://backend/app/services/auth.py#L37-L68)

### 查询管理接口
- 接口前缀：/api/v1/queries
- 路由与功能：
  - GET /：分页列出当前用户的查询词
  - POST /：创建新的查询词
  - GET /{query_id}：获取单个查询词详情
  - PUT /{query_id}：更新查询词
  - DELETE /{query_id}：删除查询词
- 权限与限制：
  - 基于当前用户上下文进行资源所有权校验
  - 创建查询时检查用户最大查询数限制
- 请求参数与响应格式：
  - 查询创建：关键词、目标品牌、品牌别名、平台列表、频率
  - 查询更新：可选字段包括关键词、目标品牌、品牌别名、平台列表、频率、状态
  - 查询详情：包含创建/更新时间、状态、下次查询时间等
  - 列表响应：items与total总数
- 错误处理：
  - 未找到查询时返回404
  - 超出查询配额返回403
  - 参数校验失败返回422（Pydantic验证）

```mermaid
flowchart TD
Start(["创建查询"]) --> CheckCount["检查用户查询数量"]
CheckCount --> CountOK{"是否超过上限？"}
CountOK --> |是| Raise403["抛出403 错误"]
CountOK --> |否| CalcNext["根据频率计算下次查询时间"]
CalcNext --> CreateQuery["创建查询记录"]
CreateQuery --> Commit["提交事务"]
Commit --> Return["返回新查询"]
Raise403 --> End(["结束"])
Return --> End
```

**图表来源**
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)

**章节来源**
- [backend/app/api/queries.py:15-85](file://backend/app/api/queries.py#L15-L85)
- [backend/app/schemas/query.py:11-94](file://backend/app/schemas/query.py#L11-L94)
- [backend/app/services/query.py:12-123](file://backend/app/services/query.py#L12-L123)

### 引用数据接口
- 接口前缀：/api/v1/citations
- 路由与功能：
  - GET /：分页查询引用记录，支持按查询ID、平台、时间范围过滤
  - GET /stats：统计分析，返回总查询数、引用率、平均位置、按平台分布、30天趋势
  - POST /{query_id}/run-now：立即触发查询任务，返回任务ID与状态
- 数据模型：
  - 引用记录包含平台、是否引用、引用位置、引用文本、竞争品牌列表、查询时间等
- 统计逻辑：
  - 总查询数与引用数来自关联查询统计
  - 引用率=引用数/总查询数
  - 平均位置仅对有位置的引用记录计算
  - 按平台统计查询数、引用数、引用率与平均位置
  - 趋势按周聚合过去30天的引用数
- 错误处理：
  - 查询所有权校验失败返回404
  - 查询非活跃或未配置平台时返回404
  - 参数校验失败返回422

```mermaid
sequenceDiagram
participant Client as "客户端"
participant CitAPI as "引用数据API"
participant CitService as "引用数据服务"
participant DB as "数据库"
Client->>CitAPI : POST /api/v1/citations/{query_id}/run-now
CitAPI->>CitService : 触发查询任务
CitService->>DB : 校验查询所有权与状态
DB-->>CitService : 查询结果
CitService->>DB : 为每个平台创建任务
DB-->>CitService : 任务集合
CitService-->>CitAPI : 返回首个任务
CitAPI-->>Client : 202 任务信息
```

**图表来源**
- [backend/app/api/citations.py:59-77](file://backend/app/api/citations.py#L59-L77)
- [backend/app/services/citation.py:204-261](file://backend/app/services/citation.py#L204-L261)

**章节来源**
- [backend/app/api/citations.py:25-77](file://backend/app/api/citations.py#L25-L77)
- [backend/app/schemas/citation.py:7-50](file://backend/app/schemas/citation.py#L7-L50)
- [backend/app/services/citation.py:24-359](file://backend/app/services/citation.py#L24-L359)

### 报告导出接口
- 接口前缀：/api/v1/reports
- 路由与功能：
  - GET /export/csv：导出指定查询的引用记录为CSV文件
- 输出格式：
  - 文本CSV，包含列头：日期、平台、是否引用、引用位置、引用文本、竞争品牌
  - 文件名为geo-report-YYYYMMDD.csv
- 错误处理：
  - 不支持的格式返回400
  - 查询所有权校验失败返回404

```mermaid
sequenceDiagram
participant Client as "客户端"
participant ReportAPI as "报告API"
participant ReportService as "报告服务"
participant DB as "数据库"
Client->>ReportAPI : GET /api/v1/reports/export/csv?query_id={id}&format=csv
ReportAPI->>ReportService : 导出CSV
ReportService->>DB : 校验查询所有权并查询记录
DB-->>ReportService : 引用记录列表
ReportService->>ReportService : 写入CSV内容
ReportService-->>ReportAPI : CSV字符串
ReportAPI-->>Client : 200 CSV文件下载
```

**图表来源**
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/services/citation.py:327-359](file://backend/app/services/citation.py#L327-L359)

**章节来源**
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/services/citation.py:327-359](file://backend/app/services/citation.py#L327-L359)

## 依赖分析
- 中间件与认证：
  - OAuth2密码流，令牌URL为/api/v1/auth/login
  - 依赖注入从Header中解析Authorization: Bearer token
  - 通过JWT解码校验用户身份，查询数据库获取用户实体
- 数据模型关系：
  - User与Query一对多，级联删除
  - Query与CitationRecord、QueryTask一对多，级联删除
  - CitationRecord外键关联Query
- 服务层职责：
  - 认证服务：密码哈希、JWT签发与校验、用户注册与登录
  - 查询服务：分页查询、创建/更新/删除、频率与下次查询时间计算
  - 引用服务：引用记录查询、统计分析、立即执行任务、CSV导出

```mermaid
classDiagram
class User {
+UUID id
+string email
+string password_hash
+string name
+string plan
+int max_queries
+boolean is_active
+datetime created_at
+datetime updated_at
}
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
}
class CitationRecord {
+UUID id
+UUID query_id
+string platform
+boolean cited
+int citation_position
+string citation_text
+list competitor_brands
+string raw_response
+datetime queried_at
}
class QueryTask {
+UUID id
+UUID query_id
+string platform
+string status
+string error_message
+datetime scheduled_at
+datetime started_at
+datetime completed_at
}
User "1" --> "many" Query : "拥有"
Query "1" --> "many" CitationRecord : "产生"
Query "1" --> "many" QueryTask : "触发任务"
CitationRecord "many" --> "1" Query : "属于"
```

**图表来源**
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [backend/app/models/citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [backend/app/models/query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)

**章节来源**
- [backend/app/api/deps.py:16-42](file://backend/app/api/deps.py#L16-L42)
- [backend/app/models/user.py:35-40](file://backend/app/models/user.py#L35-L40)
- [backend/app/models/query.py:43-48](file://backend/app/models/query.py#L43-L48)
- [backend/app/models/citation_record.py:35](file://backend/app/models/citation_record.py#L35)
- [backend/app/models/query_task.py:34](file://backend/app/models/query_task.py#L34)

## 性能考虑
- 分页查询：列表接口默认每页20条，支持skip/limit参数，避免一次性加载大量数据。
- 索引优化：查询与引用记录表建立复合索引，提升按用户ID、状态、时间等条件的查询性能。
- 异步数据库：使用异步SQLAlchemy，提高并发处理能力。
- 缓存策略：可在服务层引入Redis缓存热点统计数据，降低重复计算成本。
- 批量操作：任务创建采用批量插入，减少事务开销。

## 故障排除指南
- 认证相关
  - 401 未授权：检查Authorization头是否正确携带Bearer token；确认JWT签名与过期时间有效。
  - 401 凭据无效：检查用户名/密码是否正确；确认用户存在且被激活。
- 查询管理
  - 403 超出配额：检查用户计划与max_queries限制；清理或升级计划以增加配额。
  - 404 未找到：确认query_id归属当前用户；检查路径参数是否正确。
- 引用数据
  - 404 查询不可用：确认查询状态为active且配置了至少一个平台。
  - 统计为空：当按查询ID过滤但无匹配记录时，返回零值统计。
- 报告导出
  - 400 不支持的格式：确保format参数为csv。
  - 404 查询不存在：确认query_id归属当前用户。

**章节来源**
- [backend/app/api/auth.py:26-30](file://backend/app/api/auth.py#L26-L30)
- [backend/app/services/query.py:59-60](file://backend/app/services/query.py#L59-L60)
- [backend/app/api/citations.py:67-71](file://backend/app/api/citations.py#L67-L71)
- [backend/app/api/reports.py:23-27](file://backend/app/api/reports.py#L23-L27)

## 结论
GEO平台API采用清晰的模块化设计，围绕用户、查询、引用与报告四大领域构建RESTful接口。通过JWT认证与严格的资源所有权校验，保障了数据安全；通过统计分析与CSV导出，满足了业务洞察与合规需求。建议在生产环境中进一步完善错误日志、监控指标与缓存策略，持续优化查询性能与用户体验。