# 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代理的自动化任务处理能力、深度的内容分析与优化建议、完整的项目生命周期管理以及强大的智能知识检索功能。建议在生产环境中进一步完善错误日志、监控指标与缓存策略，持续优化查询性能与用户体验。