17 KiB

Raw Blame History

API接口文档

**本文档中引用的文件** - [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)

更新摘要

所做更改

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

简介

本文件为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访问。

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:1-57

核心组件

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

章节来源

架构概览

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

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

图表来源

详细组件分析

认证接口

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

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 访问令牌

图表来源

章节来源

查询管理接口

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

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

章节来源

引用数据接口

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

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 任务信息

图表来源

章节来源

报告导出接口

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

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文件下载

图表来源

章节来源

依赖分析

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

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 : "属于"

图表来源

章节来源

性能考虑

分页查询：列表接口默认每页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归属当前用户。

章节来源

结论

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

17 KiB Raw Blame History Unescape Escape

API接口文档

更新摘要

目录

简介

项目结构

核心组件

架构概览

详细组件分析

认证接口

查询管理接口

引用数据接口

报告导出接口

依赖分析

性能考虑

故障排除指南

结论

17 KiB

Raw Blame History