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

1032 lines
45 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/subscriptions.py](file://backend/app/api/subscriptions.py)
- [backend/app/api/admin.py](file://backend/app/api/admin.py)
- [backend/app/api/agents.py](file://backend/app/api/agents.py)
- [backend/app/api/analytics.py](file://backend/app/api/analytics.py)
- [backend/app/api/lifecycle.py](file://backend/app/api/lifecycle.py)
- [backend/app/api/knowledge.py](file://backend/app/api/knowledge.py)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
- [backend/app/middleware/rate_limit.py](file://backend/app/middleware/rate_limit.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/schemas/subscription.py](file://backend/app/schemas/subscription.py)
- [backend/app/schemas/analytics.py](file://backend/app/schemas/analytics.py)
- [backend/app/schemas/lifecycle.py](file://backend/app/schemas/lifecycle.py)
- [backend/app/schemas/knowledge.py](file://backend/app/schemas/knowledge.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/services/subscription.py](file://backend/app/services/subscription.py)
- [backend/app/services/admin.py](file://backend/app/services/admin.py)
- [backend/app/services/analytics/insights.py](file://backend/app/services/analytics/insights.py)
- [backend/app/services/analytics/tracker.py](file://backend/app/services/analytics/tracker.py)
- [backend/app/services/knowledge/rag_service.py](file://backend/app/services/knowledge/rag_service.py)
- [backend/app/services/knowledge/chunker.py](file://backend/app/services/knowledge/chunker.py)
- [backend/app/services/knowledge/embedder.py](file://backend/app/services/knowledge/embedder.py)
- [backend/app/services/knowledge/retriever.py](file://backend/app/services/knowledge/retriever.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)
- [backend/app/models/subscription.py](file://backend/app/models/subscription.py)
- [backend/app/models/agent.py](file://backend/app/models/agent.py)
- [backend/app/models/lifecycle.py](file://backend/app/models/lifecycle.py)
- [backend/app/models/knowledge.py](file://backend/app/models/knowledge.py)
</cite>
## 更新摘要
**所做更改**
- 新增代理管理API模块，支持AI Agent的注册、配置管理、任务分发与监控
- 新增分析监控API模块，提供内容发布追踪、效果指标管理、洞察生成与排行榜功能
- 新增生命周期管理API模块，支持品牌项目全生命周期管理与阶段进度跟踪
- 新增知识库API模块，提供知识库CRUD、文档管理、向量化检索与RAG服务
- 更新架构图以反映新增的四个核心API模块
- 完善错误处理和状态码说明，新增各模块特有的错误场景
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文件为GEO平台的完整API接口文档，涵盖认证、查询管理、引用数据、报告导出、订阅管理、管理员管理、代理管理、分析监控、生命周期管理和知识库等核心功能模块。文档详细记录了所有RESTful API端点的HTTP方法、URL模式、请求参数与响应格式，并说明了JWT令牌管理、用户注册登录、权限验证机制、任务创建与执行、数据查询与统计分析、CSV和PDF格式报告导出流程，以及订阅管理、系统管理、AI代理调度、内容分析追踪、项目生命周期管理和智能知识检索功能。
## 项目结构
后端采用FastAPI框架，按功能模块组织API路由：认证(/api/v1/auth)、查询词(/api/v1/queries)、引用数据(/api/v1/citations)、报告(/api/v1/reports)、订阅管理(/api/v1/subscriptions)、管理员(/api/v1/admin)、代理管理(/api/v1/agents)、分析监控(/api/v1/analytics)、生命周期管理(/api/v1/lifecycle)、知识库(/api/v1/knowledge)。应用启动时初始化数据库模型并启动查询调度器，同时启用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/subscriptions.py"]
A --> G["管理员路由<br/>backend/app/api/admin.py"]
A --> H["代理管理路由<br/>backend/app/api/agents.py"]
A --> I["分析监控路由<br/>backend/app/api/analytics.py"]
A --> J["生命周期管理路由<br/>backend/app/api/lifecycle.py"]
A --> K["知识库路由<br/>backend/app/api/knowledge.py"]
A --> L["依赖注入与认证中间件<br/>backend/app/api/deps.py"]
A --> M["限流中间件<br/>backend/app/middleware/rate_limit.py"]
A --> N["配置中心<br/>backend/app/config.py"]
A --> O["数据库模型<br/>backend/app/models/*.py"]
A --> P["业务服务层<br/>backend/app/services/*.py"]
A --> Q["数据传输对象<br/>backend/app/schemas/*.py"]
```
**图表来源**
- [backend/app/main.py:12-78](file://backend/app/main.py#L12-L78)
- [backend/app/api/auth.py:30](file://backend/app/api/auth.py#L30)
- [backend/app/api/agents.py:29](file://backend/app/api/agents.py#L29)
- [backend/app/api/analytics.py:26](file://backend/app/api/analytics.py#L26)
- [backend/app/api/lifecycle.py:24](file://backend/app/api/lifecycle.py#L24)
- [backend/app/api/knowledge.py:38](file://backend/app/api/knowledge.py#L38)
**章节来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
## 核心组件
- 应用入口与生命周期管理：定义应用标题、版本、CORS策略，注册各模块路由，启动/关闭查询调度器，配置安全响应头、限流中间件和请求日志中间件。
- 认证组件：提供注册、登录、当前用户信息查询、忘记密码、重置密码、邮箱验证、密码修改、资料更新等完整认证功能；基于OAuth2密码流与JWT进行身份验证。
- 查询管理：支持查询词的增删改查、分页列表、频率与下次查询时间计算。
- 引用数据：支持引用记录查询、统计分析（总查询数、引用率、平台分布、趋势）、立即执行查询任务。
- 报告导出：支持CSV和PDF格式导出指定查询的引用记录。
- 订阅管理：提供套餐查询、订阅创建、取消订阅、历史记录查看等功能，支持多层级权限控制。
- 管理员管理：提供系统统计、用户管理、权限控制、计划更新等后台管理功能。
- 代理管理：支持AI Agent的注册、配置管理、任务分发与监控，提供任务创建、状态查询、日志查看和取消功能。
- 分析监控：提供内容发布追踪、效果指标管理、洞察生成与排行榜功能，支持组织级别的数据分析。
- 生命周期管理：支持品牌项目的全生命周期管理，包括项目快速启动、阶段进度跟踪、时间线事件和统计分析。
- 知识库管理：提供知识库CRUD、文档管理、向量化检索与RAG服务，支持多种文档源和智能搜索。
- 数据模型与服务：用户、查询、引用记录、查询任务、订阅、代理、分析、生命周期、知识库等模型及对应的服务逻辑。
**章节来源**
- [backend/app/main.py:39-84](file://backend/app/main.py#L39-L84)
- [backend/app/api/auth.py:33-115](file://backend/app/api/auth.py#L33-L115)
- [backend/app/api/agents.py:66-299](file://backend/app/api/agents.py#L66-L299)
- [backend/app/api/analytics.py:47-243](file://backend/app/api/analytics.py#L47-L243)
- [backend/app/api/lifecycle.py:85-297](file://backend/app/api/lifecycle.py#L85-L297)
- [backend/app/api/knowledge.py:81-502](file://backend/app/api/knowledge.py#L81-L502)
- [backend/app/middleware/rate_limit.py:10-83](file://backend/app/middleware/rate_limit.py#L10-L83)
## 架构概览
下图展示了客户端与后端各模块之间的交互关系，包括认证流程、查询管理、引用数据处理、报告导出、订阅管理、管理员管理、代理调度、分析监控、生命周期管理和知识库检索。
```mermaid
graph TB
subgraph "客户端"
FE["前端应用<br/>localhost:3000"]
ENDUSER["终端用户"]
end
subgraph "后端服务"
AUTH["认证模块<br/>/api/v1/auth"]
QUERIES["查询模块<br/>/api/v1/queries"]
CITATIONS["引用数据模块<br/>/api/v1/citations"]
REPORTS["报告模块<br/>/api/v1/reports"]
SUBSCRIPTIONS["订阅管理模块<br/>/api/v1/subscriptions"]
ADMIN["管理员模块<br/>/api/v1/admin"]
AGENTS["代理管理模块<br/>/api/v1/agents"]
ANALYTICS["分析监控模块<br/>/api/v1/analytics"]
LIFECYCLE["生命周期管理模块<br/>/api/v1/lifecycle"]
KNOWLEDGE["知识库模块<br/>/api/v1/knowledge"]
DEPS["依赖注入与认证中间件"]
RATELIMIT["限流中间件"]
LOGGING["请求日志中间件"]
MODELS["数据模型层"]
SERVICES["业务服务层"]
CONFIG["配置中心"]
end
FE --> AUTH
FE --> QUERIES
FE --> CITATIONS
FE --> REPORTS
FE --> SUBSCRIPTIONS
FE --> ADMIN
FE --> AGENTS
FE --> ANALYTICS
FE --> LIFECYCLE
FE --> KNOWLEDGE
ENDUSER --> AGENTS
ENDUSER --> ANALYTICS
ENDUSER --> LIFECYCLE
ENDUSER --> KNOWLEDGE
AUTH --> DEPS
QUERIES --> DEPS
CITATIONS --> DEPS
REPORTS --> DEPS
SUBSCRIPTIONS --> DEPS
ADMIN --> DEPS
AGENTS --> DEPS
ANALYTICS --> DEPS
LIFECYCLE --> DEPS
KNOWLEDGE --> DEPS
AUTH --> RATELIMIT
QUERIES --> RATELIMIT
CITATIONS --> RATELIMIT
REPORTS --> RATELIMIT
SUBSCRIPTIONS --> RATELIMIT
ADMIN --> RATELIMIT
AGENTS --> RATELIMIT
ANALYTICS --> RATELIMIT
LIFECYCLE --> RATELIMIT
KNOWLEDGE --> RATELIMIT
AUTH --> LOGGING
QUERIES --> LOGGING
CITATIONS --> LOGGING
REPORTS --> LOGGING
SUBSCRIPTIONS --> LOGGING
ADMIN --> LOGGING
AGENTS --> LOGGING
ANALYTICS --> LOGGING
LIFECYCLE --> LOGGING
KNOWLEDGE --> LOGGING
AUTH --> SERVICES
QUERIES --> SERVICES
CITATIONS --> SERVICES
REPORTS --> SERVICES
SUBSCRIPTIONS --> SERVICES
ADMIN --> SERVICES
AGENTS --> SERVICES
ANALYTICS --> SERVICES
LIFECYCLE --> SERVICES
KNOWLEDGE --> SERVICES
SERVICES --> MODELS
MODELS --> CONFIG
```
**图表来源**
- [backend/app/main.py:67-78](file://backend/app/main.py#L67-L78)
- [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：获取当前登录用户信息
- POST /forgot-password：发送密码重置链接
- POST /reset-password：重置密码
- POST /verify-email：邮箱验证
- POST /resend-verification：重新发送验证码
- PUT /change-password：修改密码
- PUT /profile：更新用户资料
- 认证机制：
- 使用OAuth2密码流，令牌类型为bearer
- 通过依赖注入获取当前用户，校验JWT有效性
- 用户名/密码验证通过后签发JWT，包含用户ID作为sub字段
- 支持邮箱验证和密码重置功能
- 请求参数与响应格式：
- 注册：邮箱、密码、姓名
- 登录：邮箱、密码
- 忘记密码：邮箱
- 重置密码：令牌、新密码
- 邮箱验证：邮箱、验证码
- 修改密码：旧密码、新密码
- 更新资料：姓名、头像等
- 当前用户：用户ID、邮箱、姓名、计划、最大查询数、激活状态、创建时间
- 访问令牌：访问令牌字符串、令牌类型、用户信息
- 错误处理：
- 注册：邮箱已存在时返回400
- 登录：凭据无效时返回401
- 获取当前用户：凭据无效或用户不存在时返回401
- 忘记密码：邮箱不存在时返回400
- 重置密码：无效令牌或已过期时返回400
- 验证码：无效或已过期时返回400
```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:33-57](file://backend/app/api/auth.py#L33-L57)
- [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:33-115](file://backend/app/api/auth.py#L33-L115)
- [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文件
- GET /export/pdf：导出指定查询的引用记录为PDF报告
- 输出格式：
- CSV：文本CSV，包含列头：查询关键词、目标品牌、查询日期、查询平台、是否引用、引用位置、引用文本、匹配置信度、匹配类型、竞争品牌
- PDF：完整的品牌曝光度分析报告，包含封面、汇总统计、平台分布、详细数据表格等
- 文件名为geo-report-YYYYMMDD.csv或geo-report-YYYYMMDD.pdf
- 错误处理：
- 不支持的格式返回400
- 查询所有权校验失败返回404
```mermaid
sequenceDiagram
participant Client as "客户端"
participant ReportAPI as "报告API"
participant ReportService as "报告服务"
participant DB as "数据库"
Client->>ReportAPI : GET /api/v1/reports/export/pdf?query_id={id}
ReportAPI->>ReportService : 导出PDF
ReportService->>DB : 校验查询所有权并查询记录
DB-->>ReportService : 引用记录列表
ReportService->>ReportService : 生成PDF内容
ReportService-->>ReportAPI : PDF字节流
ReportAPI-->>Client : 200 PDF文件下载
```
**图表来源**
- [backend/app/api/reports.py:51-75](file://backend/app/api/reports.py#L51-L75)
- [backend/app/services/citation.py:343-466](file://backend/app/services/citation.py#L343-L466)
**章节来源**
- [backend/app/api/reports.py:18-75](file://backend/app/api/reports.py#L18-L75)
- [backend/app/services/citation.py:343-466](file://backend/app/services/citation.py#L343-L466)
### 订阅管理接口
- 接口前缀：/api/v1/subscriptions
- 路由与功能：
- GET /plans：获取所有可用套餐详情
- GET /current：获取当前订阅信息
- POST /subscribe：创建新订阅
- POST /cancel：取消当前订阅
- GET /history：获取订阅历史记录
- 套餐与功能：
- free：免费版，5个查询配额，基础查询监控、CSV导出
- starter：入门版，99元/月，20个查询配额，PDF报告、定时查询
- pro：专业版，299元/月，100个查询配额，竞品分析、API访问
- enterprise：企业版，999元/月，500个查询配额，专属支持
- 权限与限制：
- 需要登录用户权限
- 取消订阅会自动降级到免费版
- 请求参数与响应格式：
- 套餐详情：套餐ID、名称、价格、最大查询数、功能列表
- 订阅创建：套餐ID
- 订阅响应：订阅ID、套餐、状态、开始/结束日期、金额、支付方式
- 订阅历史：订阅记录列表与总数
- 错误处理：
- 无效套餐ID返回400
- 无订阅记录返回404
- 参数校验失败返回422
```mermaid
flowchart TD
Start(["订阅创建"]) --> ValidatePlan["验证套餐ID"]
ValidatePlan --> PlanValid{"套餐是否存在？"}
PlanValid --> |否| Raise400["抛出400 错误"]
PlanValid --> |是| CreateSub["创建订阅记录"]
CreateSub --> UpdateUser["更新用户套餐与配额"]
UpdateUser --> Commit["提交事务"]
Commit --> Return["返回订阅信息"]
Raise400 --> End(["结束"])
Return --> End
```
**图表来源**
- [backend/app/services/subscription.py:85-117](file://backend/app/services/subscription.py#L85-L117)
**章节来源**
- [backend/app/api/subscriptions.py:26-77](file://backend/app/api/subscriptions.py#L26-L77)
- [backend/app/schemas/subscription.py:12-41](file://backend/app/schemas/subscription.py#L12-L41)
- [backend/app/services/subscription.py:56-155](file://backend/app/services/subscription.py#L56-L155)
### 管理员接口
- 接口前缀：/api/v1/admin
- 路由与功能：
- GET /stats：获取系统统计信息
- GET /users：分页获取用户列表，支持搜索
- GET /users/{user_id}：获取用户详细信息
- POST /users/{user_id}/toggle-active：切换用户激活状态
- PUT /users/{user_id}/update-plan：更新用户套餐
- 权限控制：
- 需要管理员权限（is_admin=true）
- 非管理员访问返回403
- 请求参数与响应格式：
- 系统统计：总用户数、总查询数、总引用数、引用率、今日活跃用户数
- 用户列表：用户信息列表与总数
- 用户详情：用户基本信息、查询历史、最近引用记录
- 用户状态：用户ID、激活状态、操作消息
- 套餐更新：用户ID、新套餐、最大查询数、操作消息
- 错误处理：
- 非管理员权限返回403
- 用户不存在返回404
- 缺少必要参数返回400
```mermaid
sequenceDiagram
participant Admin as "管理员客户端"
participant AdminAPI as "管理员API"
participant AdminService as "管理员服务"
participant DB as "数据库"
Admin->>AdminAPI : GET /api/v1/admin/users?skip=0&limit=20
AdminAPI->>AdminService : 验证管理员权限
AdminService->>DB : 检查用户权限
DB-->>AdminService : 管理员信息
AdminService->>DB : 查询用户列表
DB-->>AdminService : 用户数据
AdminService-->>AdminAPI : 用户列表与总数
AdminAPI-->>Admin : 200 用户列表
```
**图表来源**
- [backend/app/api/admin.py:29-45](file://backend/app/api/admin.py#L29-L45)
- [backend/app/services/admin.py:14-46](file://backend/app/services/admin.py#L14-L46)
**章节来源**
- [backend/app/api/admin.py:29-108](file://backend/app/api/admin.py#L29-L108)
- [backend/app/services/admin.py:14-188](file://backend/app/services/admin.py#L14-L188)
### 代理管理接口
- 接口前缀：/api/v1/agents
- 路由与功能：
- GET /：列出所有Agent，支持按类型和状态筛选
- GET /{agent_name}：获取Agent详情
- GET /{agent_name}/config：获取Agent配置
- PUT /{agent_name}/config：更新Agent配置
- GET /tasks/：列出任务，支持按Agent、状态、类型筛选
- POST /tasks/：创建任务（分发给Agent），支持优先级、回调URL、超时设置
- GET /tasks/{task_id}：获取任务状态
- POST /tasks/{task_id}/cancel：取消任务
- GET /tasks/{task_id}/logs：获取任务日志
- 权限与限制：
- 需要登录用户权限
- 任务分发需要有效的Agent名称和配置
- 请求参数与响应格式：
- Agent列表：items数组与total总数
- Agent详情：包含名称、类型、状态、描述、版本、端点、能力等
- 配置更新：返回更新的键列表和成功消息
- 任务创建：返回任务ID、初始状态和成功消息
- 任务状态：包含状态、错误消息、开始/完成时间等
- 任务日志：包含日志级别、消息、元数据和时间戳
- 错误处理：
- Agent不存在返回404
- 任务不存在返回404
- 任务分发错误返回400
- 参数校验失败返回422
```mermaid
sequenceDiagram
participant Client as "客户端"
participant AgentsAPI as "代理管理API"
participant Dispatcher as "任务调度器"
participant Registry as "Agent注册表"
participant DB as "数据库"
Client->>AgentsAPI : POST /api/v1/agents/tasks/
AgentsAPI->>Dispatcher : 创建任务消息
Dispatcher->>Registry : 查找可用Agent
Registry-->>Dispatcher : Agent信息
Dispatcher->>DB : 存储任务记录
DB-->>Dispatcher : 任务ID
Dispatcher-->>AgentsAPI : 任务ID与状态
AgentsAPI-->>Client : 201 任务信息
```
**图表来源**
- [backend/app/api/agents.py:186-222](file://backend/app/api/agents.py#L186-L222)
- [backend/app/models/agent.py:98-155](file://backend/app/models/agent.py#L98-L155)
**章节来源**
- [backend/app/api/agents.py:66-299](file://backend/app/api/agents.py#L66-L299)
- [backend/app/models/agent.py:12-206](file://backend/app/models/agent.py#L12-L206)
### 分析监控接口
- 接口前缀：/api/v1/analytics
- 路由与功能：
- POST /publish：记录内容发布，支持内容标题、ID、平台、URL、状态、发布时间
- PUT /metrics/{publish_id}：更新内容效果指标（追加快照），支持浏览量、点赞数、评论数、分享数、书签数、AI引用数、搜索展示量、搜索点击量、平均阅读时长、阅读完成率
- GET /overview：获取全局效果概览，包含发布总数、总浏览量、总互动数、总AI引用数、平均参与率、平台分布
- GET /content/{publish_id}：获取单条内容详细表现
- GET /top：获取表现最好内容排行，支持按浏览量、点赞数、评论数、分享数、AI引用数、阅读完成率排序
- GET /insights：获取洞察列表，支持限制数量和类型筛选
- POST /insights/generate：触发AI生成洞察建议
- POST /insights/{insight_id}/apply：标记洞察已应用
- 权限与限制：
- 需要用户关联组织权限
- 发布记录必须属于当前组织
- 请求参数与响应格式：
- 发布记录：包含组织ID、内容标题、内容ID、平台、URL、状态、发布时间、创建时间
- 指标更新：返回更新后的指标快照
- 全局概览：包含统计指标和平台分布
- 内容表现：包含最新指标和历史指标列表
- 洞察列表：包含洞察ID、类型、标题、描述、建议、严重程度、应用状态
- 错误处理：
- 用户未关联组织返回403
- 发布记录不存在或无权限返回404
- 参数校验失败返回422
```mermaid
sequenceDiagram
participant Client as "客户端"
participant AnalyticsAPI as "分析监控API"
participant Tracker as "分析追踪器"
participant Generator as "洞察生成器"
participant DB as "数据库"
Client->>AnalyticsAPI : POST /api/v1/analytics/publish
AnalyticsAPI->>Tracker : 记录发布
Tracker->>DB : 存储发布记录
DB-->>Tracker : 发布ID
Tracker-->>AnalyticsAPI : 发布记录
AnalyticsAPI-->>Client : 201 发布记录
Client->>AnalyticsAPI : POST /api/v1/analytics/insights/generate
AnalyticsAPI->>Generator : 生成洞察
Generator->>DB : 查询数据分析
DB-->>Generator : 分析结果
Generator-->>AnalyticsAPI : 洞察建议
AnalyticsAPI-->>Client : 洞察列表
```
**图表来源**
- [backend/app/api/analytics.py:47-60](file://backend/app/api/analytics.py#L47-L60)
- [backend/app/api/analytics.py:206-212](file://backend/app/api/analytics.py#L206-L212)
**章节来源**
- [backend/app/api/analytics.py:47-243](file://backend/app/api/analytics.py#L47-L243)
- [backend/app/schemas/analytics.py:14-145](file://backend/app/schemas/analytics.py#L14-L145)
- [backend/app/services/analytics/insights.py](file://backend/app/services/analytics/insights.py)
- [backend/app/services/analytics/tracker.py](file://backend/app/services/analytics/tracker.py)
### 生命周期管理接口
- 接口前缀：/api/v1/lifecycle
- 路由与功能：
- GET /projects/stats：获取项目统计信息，包含项目总数、活跃项目数、阶段分布、完成率
- GET /projects/{project_id}/timeline：获取项目时间线事件，包含创建事件和各阶段开始/完成事件
- POST /projects/quick-start：项目快速启动，创建品牌基建阶段的项目
- GET /projects/{project_id}/stages：获取项目阶段列表
- PUT /projects/{project_id}/stages/{stage_number}：更新项目阶段状态，支持开始时间、完成时间、备注、指标
- 权限与限制：
- 需要用户关联组织权限
- 项目必须属于当前组织
- 请求参数与响应格式：
- 项目统计：包含总数、活跃数、阶段分布、完成率
- 时间线事件：包含事件类型、描述、时间戳、阶段编号
- 项目创建：返回创建的项目和成功消息
- 阶段更新：返回更新后的阶段详情
- 错误处理：
- 用户未关联组织返回404
- 项目不存在返回404
- 阶段不存在返回404
```mermaid
sequenceDiagram
participant Client as "客户端"
participant LifecycleAPI as "生命周期API"
participant DB as "数据库"
Client->>LifecycleAPI : POST /api/v1/lifecycle/projects/quick-start
LifecycleAPI->>DB : 创建组织如不存在
DB-->>LifecycleAPI : 组织ID
LifecycleAPI->>DB : 创建项目
DB-->>LifecycleAPI : 项目ID
LifecycleAPI->>DB : 创建5个阶段
DB-->>LifecycleAPI : 阶段列表
LifecycleAPI-->>Client : 201 项目详情
```
**图表来源**
- [backend/app/api/lifecycle.py:190-230](file://backend/app/api/lifecycle.py#L190-L230)
**章节来源**
- [backend/app/api/lifecycle.py:85-297](file://backend/app/api/lifecycle.py#L85-L297)
- [backend/app/schemas/lifecycle.py:9-68](file://backend/app/schemas/lifecycle.py#L9-L68)
- [backend/app/models/lifecycle.py:12-92](file://backend/app/models/lifecycle.py#L12-L92)
### 知识库接口
- 接口前缀：/api/v1/knowledge
- 路由与功能：
- POST /bases：创建知识库，支持名称、类型、描述
- GET /bases：列出知识库，支持按类型筛选
- GET /bases/{kb_id}：获取知识库详情
- DELETE /bases/{kb_id}：删除知识库（级联删除文档和块）
- POST /bases/{kb_id}/documents：上传文档，支持文本、URL、Markdown源
- GET /bases/{kb_id}/documents：列出文档
- DELETE /bases/{kb_id}/documents/{doc_id}：删除文档（级联删除块）
- GET /bases/{kb_id}/documents/{doc_id}/chunks：预览文档块
- POST /search：知识库搜索，支持查询、知识库ID列表、返回数量
- 权限与限制：
- 需要用户关联组织权限
- 文档上传需要有效的知识库ID
- 请求参数与响应格式：
- 知识库创建：返回知识库ID、名称、类型、描述、文档数量、状态、创建时间
- 文档上传：返回文档ID、标题、源类型、URL、块数量、状态、错误消息、创建时间
- 搜索结果：包含块ID、内容、分数、文档ID、标题、元数据
- 错误处理：
- 用户未关联组织返回400
- 知识库不存在返回404
- 文档不存在返回404
- URL内容获取失败返回400
```mermaid
sequenceDiagram
participant Client as "客户端"
participant KnowledgeAPI as "知识库API"
participant RAGService as "RAG服务"
participant DB as "数据库"
Client->>KnowledgeAPI : POST /api/v1/knowledge/search
KnowledgeAPI->>RAGService : 执行向量搜索
RAGService->>DB : 查询相似文档
DB-->>RAGService : 匹配结果
RAGService-->>KnowledgeAPI : 搜索结果
KnowledgeAPI->>DB : 记录搜索日志
DB-->>KnowledgeAPI : 日志ID
KnowledgeAPI-->>Client : 200 搜索结果
```
**图表来源**
- [backend/app/api/knowledge.py:424-501](file://backend/app/api/knowledge.py#L424-L501)
**章节来源**
- [backend/app/api/knowledge.py:81-502](file://backend/app/api/knowledge.py#L81-L502)
- [backend/app/schemas/knowledge.py:9-77](file://backend/app/schemas/knowledge.py#L9-L77)
- [backend/app/models/knowledge.py:22-213](file://backend/app/models/knowledge.py#L22-L213)
### 限流中间件
- 功能特性：
- 基于内存的简易限流中间件，无需Redis依赖
- 多层级限流策略：认证接口、查询执行、全局限流
- 健康检查和文档页面不限流
- 限流规则：
- 认证接口（/api/v1/auth/login, /api/v1/auth/register, /api/v1/auth/forgot-password）：每分钟5次
- 查询执行（/run-now）：每小时10次
- 全局：每分钟100次
- 实现机制：
- 使用时间窗口算法，自动清理过期请求记录
- 基于客户端IP地址进行限流
- 返回429状态码和友好提示信息
- 特殊处理：
- /health、/docs、/openapi 路径不限流
- 每个规则独立计数，互不影响
```mermaid
flowchart TD
Start(["请求进入"]) --> HealthCheck{"健康检查/文档？"}
HealthCheck --> |是| PassThrough["直接通过"]
HealthCheck --> |否| CheckAuth{"认证接口？"}
CheckAuth --> |是| AuthKey["auth:{client_ip}"]
AuthKey --> CheckAuthRate{"认证限流？"}
CheckAuthRate --> |超限| Return429["返回429 Too Many Requests"]
CheckAuthRate --> |正常| CheckQueryRun{"查询执行？"}
CheckQueryRun --> |是| QueryKey["query_run:{client_ip}"]
QueryKey --> CheckQueryRate{"查询限流？"}
CheckQueryRate --> |超限| Return429
CheckQueryRate --> |正常| GlobalKey["global:{client_ip}"]
CheckGlobal{"全局限流？"}
CheckGlobal --> |超限| Return429
CheckGlobal --> |正常| Next["继续处理"]
PassThrough --> Next
```
**图表来源**
- [backend/app/middleware/rate_limit.py:34-69](file://backend/app/middleware/rate_limit.py#L34-L69)
**章节来源**
- [backend/app/middleware/rate_limit.py:10-83](file://backend/app/middleware/rate_limit.py#L10-L83)
## 依赖分析
- 中间件与认证：
- OAuth2密码流，令牌URL为/api/v1/auth/login
- 依赖注入从Header中解析Authorization: Bearer token
- 通过JWT解码校验用户身份，查询数据库获取用户实体
- 管理员权限通过is_admin字段验证
- 数据模型关系：
- User与Query一对多，级联删除
- User与Subscription一对多，级联删除
- Query与CitationRecord、QueryTask一对多，级联删除
- CitationRecord外键关联Query
- AgentRegistry与AgentConfig、AgentTask、AgentTaskLog一对多，级联删除
- LifecycleProject与ProjectStage一对多，级联删除
- KnowledgeBase与KnowledgeDocument、KnowledgeChunk一对多，级联删除
- 服务层职责：
- 认证服务：密码哈希、JWT签发与校验、用户注册与登录、密码重置、邮箱验证
- 查询服务：分页查询、创建/更新/删除、频率与下次查询时间计算
- 引用服务：引用记录查询、统计分析、立即执行任务、CSV和PDF导出
- 订阅服务：套餐管理、订阅创建与取消、历史记录查询
- 管理员服务：系统统计、用户管理、权限控制、计划更新
- 代理服务：Agent注册表管理、任务调度、配置管理、日志记录
- 分析服务：发布追踪、指标管理、洞察生成、排行榜计算
- 生命周期服务：项目管理、阶段跟踪、统计分析
- 知识库服务：文档管理、向量化处理、RAG检索、搜索日志
```mermaid
classDiagram
class User {
+UUID id
+string email
+string password_hash
+string name
+string plan
+int max_queries
+boolean is_active
+boolean email_verified
+boolean is_admin
+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
+string match_type
+float confidence
+datetime queried_at
}
class QueryTask {
+UUID id
+UUID agent_id
+string task_type
+string status
+int priority
+dict input_data
+dict output_data
+string error_message
+UUID organization_id
+UUID project_id
+datetime scheduled_at
+datetime started_at
+datetime completed_at
+datetime created_at
}
class Subscription {
+UUID id
+UUID user_id
+string plan
+string status
+date start_date
+date end_date
+float amount
+string payment_method
+datetime created_at
}
class AgentRegistry {
+UUID id
+string name
+string display_name
+string agent_type
+string description
+string version
+string endpoint
+string status
+dict capabilities
+datetime last_heartbeat
+datetime created_at
+datetime updated_at
}
class AgentTask {
+UUID id
+UUID agent_id
+string task_type
+string status
+int priority
+dict input_data
+dict output_data
+string error_message
+UUID organization_id
+UUID project_id
+datetime scheduled_at
+datetime started_at
+datetime completed_at
+datetime created_at
}
class LifecycleProject {
+UUID id
+UUID organization_id
+string brand_name
+list brand_aliases
+int current_stage
+string status
+UUID created_by
+datetime created_at
+datetime updated_at
}
class ProjectStage {
+UUID id
+UUID project_id
+int stage_number
+string status
+datetime started_at
+datetime completed_at
+string notes
+dict metrics
}
class KnowledgeBase {
+UUID id
+UUID organization_id
+string name
+string type
+string description
+int document_count
+string status
+UUID created_by
+datetime created_at
+datetime updated_at
}
class KnowledgeDocument {
+UUID id
+UUID knowledge_base_id
+string title
+string source_type
+string source_url
+string content
+string content_hash
+int chunk_count
+string status
+string error_message
+dict extra_metadata
+datetime created_at
+datetime updated_at
}
class KnowledgeChunk {
+UUID id
+UUID document_id
+string content
+Vector embedding
+int chunk_index
+int token_count
+dict extra_metadata
+datetime created_at
}
User "1" --> "many" Query : "拥有"
User "1" --> "many" Subscription : "订阅"
User "1" --> "many" AgentTask : "创建"
Query "1" --> "many" CitationRecord : "产生"
Query "1" --> "many" QueryTask : "触发任务"
CitationRecord "many" --> "1" Query : "属于"
Subscription "many" --> "1" User : "属于"
AgentRegistry "1" --> "many" AgentTask : "执行"
AgentTask "many" --> "1" AgentRegistry : "属于"
LifecycleProject "1" --> "many" ProjectStage : "包含"
KnowledgeBase "1" --> "many" KnowledgeDocument : "包含"
KnowledgeDocument "1" --> "many" KnowledgeChunk : "包含"
```
**图表来源**
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
- [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/models/subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
- [backend/app/models/agent.py:12-206](file://backend/app/models/agent.py#L12-L206)
- [backend/app/models/lifecycle.py:12-92](file://backend/app/models/lifecycle.py#L12-L92)
- [backend/app/models/knowledge.py:22-213](file://backend/app/models/knowledge.py#L22-L213)
**章节来源**
- [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缓存热点统计数据，降低重复计算成本。
- 批量操作：任务创建采用批量插入，减少事务开销。
- 限流保护：多层级限流中间件防止恶意请求和滥用，保护系统稳定性。
- PDF生成：PDF导出使用FPDF库，支持中文字体加载，提供完整的品牌曝光度分析报告。
- 向量检索：知识库模块使用pgvector扩展进行高效相似性搜索，支持大规模文档向量化处理。
- 代理调度：Agent任务采用Redis队列进行异步处理，支持高并发任务分发与监控。
- 分析追踪：分析模块使用专门的追踪器和洞察生成器，优化大数据量的统计分析性能。
## 故障排除指南
- 认证相关
- 401 未授权：检查Authorization头是否正确携带Bearer token；确认JWT签名与过期时间有效。
- 401 凭据无效：检查用户名/密码是否正确；确认用户存在且被激活。
- 400 邮箱已注册：检查邮箱是否已被其他用户使用。
- 400 无效令牌：检查密码重置令牌是否正确且未过期。
- 查询管理
- 403 超出配额：检查用户计划与max_queries限制；清理或升级计划以增加配额。
- 404 未找到：确认query_id归属当前用户；检查路径参数是否正确。
- 引用数据
- 404 查询不可用：确认查询状态为active且配置了至少一个平台。
- 统计为空：当按查询ID过滤但无匹配记录时，返回零值统计。
- 报告导出
- 400 不支持的格式：确保format参数为csv或pdf。
- 404 查询不存在：确认query_id归属当前用户。
- 订阅管理
- 400 无效套餐：检查套餐ID是否存在于可用套餐列表中。
- 404 无订阅记录：确认当前用户是否有有效的订阅记录。
- 管理员功能
- 403 非管理员权限：确认当前用户具有管理员权限（is_admin=true）。
- 404 用户不存在：确认用户ID是否有效。
- 代理管理
- 404 Agent不存在：确认Agent名称是否正确。
- 404 任务不存在：确认任务ID格式和权限。
- 400 任务分发错误：检查Agent配置和可用性。
- 422 参数校验失败：检查请求体格式和字段约束。
- 分析监控
- 403 用户未关联组织：确认用户已加入有效组织。
- 404 发布记录不存在或无权限：检查发布ID和组织权限。
- 422 指标更新失败：检查数值范围和字段类型。
- 生命周期管理
- 404 用户未关联组织：确认用户已创建或加入组织。
- 404 项目不存在：检查项目ID和组织归属。
- 404 阶段不存在：检查阶段编号和项目归属。
- 知识库管理
- 400 用户未关联组织：确认用户已加入组织。
- 404 知识库不存在：检查知识库ID和组织权限。
- 404 文档不存在：检查文档ID和知识库归属。
- 400 URL内容获取失败：检查URL可访问性和内容格式。
- 限流保护
- 429 请求过于频繁：检查是否超过限流阈值，等待冷却时间后重试。
- 429 查询执行过于频繁：确认查询执行频率是否超过每小时10次限制。
**章节来源**
- [backend/app/api/auth.py:46-50](file://backend/app/api/auth.py#L46-L50)
- [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:25-29](file://backend/app/api/reports.py#L25-L29)
- [backend/app/api/subscriptions.py:53-57](file://backend/app/api/subscriptions.py#L53-L57)
- [backend/app/api/admin.py:22-25](file://backend/app/api/admin.py#L22-L25)
- [backend/app/api/agents.py:84-88](file://backend/app/api/agents.py#L84-L88)
- [backend/app/api/analytics.py:36-40](file://backend/app/api/analytics.py#L36-L40)
- [backend/app/api/lifecycle.py:146](file://backend/app/api/lifecycle.py#L146)
- [backend/app/api/knowledge.py:92-96](file://backend/app/api/knowledge.py#L92-L96)
- [backend/app/middleware/rate_limit.py:47-49](file://backend/app/middleware/rate_limit.py#L47-L49)
## 结论
GEO平台API采用清晰的模块化设计，围绕用户、查询、引用、报告、订阅、管理、代理、分析、生命周期和知识库十大领域构建RESTful接口。通过JWT认证与严格的资源所有权校验，保障了数据安全；通过统计分析与CSV/PDF导出，满足了业务洞察与合规需求；通过订阅管理、管理员功能、AI代理调度、内容分析追踪、项目生命周期管理和智能知识检索，提供了完整的商业运营支持；通过多层级限流中间件，确保了系统的稳定性和安全性。新增的四个核心API模块显著增强了平台的智能化水平，包括AI代理的自动化任务处理能力、深度的内容分析与优化建议、完整的项目生命周期管理以及强大的智能知识检索功能。建议在生产环境中进一步完善错误日志、监控指标与缓存策略，持续优化查询性能与用户体验。
Reference in New Issue View Git Blame Copy Permalink