fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/API接口文档/API接口文档.md

416 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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导出，满足了业务洞察与合规需求。建议在生产环境中进一步完善错误日志、监控指标与缓存策略，持续优化查询性能与用户体验。
Reference in New Issue View Git Blame Copy Permalink