# 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/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) ## 更新摘要 **所做更改** - 新增代理管理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["应用入口
backend/app/main.py"] --> B["认证路由
backend/app/api/auth.py"] A --> C["查询路由
backend/app/api/queries.py"] A --> D["引用数据路由
backend/app/api/citations.py"] A --> E["报告路由
backend/app/api/reports.py"] A --> F["订阅管理路由
backend/app/api/subscriptions.py"] A --> G["管理员路由
backend/app/api/admin.py"] A --> H["代理管理路由
backend/app/api/agents.py"] A --> I["分析监控路由
backend/app/api/analytics.py"] A --> J["生命周期管理路由
backend/app/api/lifecycle.py"] A --> K["知识库路由
backend/app/api/knowledge.py"] A --> L["依赖注入与认证中间件
backend/app/api/deps.py"] A --> M["限流中间件
backend/app/middleware/rate_limit.py"] A --> N["配置中心
backend/app/config.py"] A --> O["数据库模型
backend/app/models/*.py"] A --> P["业务服务层
backend/app/services/*.py"] A --> Q["数据传输对象
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["前端应用
localhost:3000"] ENDUSER["终端用户"] end subgraph "后端服务" AUTH["认证模块
/api/v1/auth"] QUERIES["查询模块
/api/v1/queries"] CITATIONS["引用数据模块
/api/v1/citations"] REPORTS["报告模块
/api/v1/reports"] SUBSCRIPTIONS["订阅管理模块
/api/v1/subscriptions"] ADMIN["管理员模块
/api/v1/admin"] AGENTS["代理管理模块
/api/v1/agents"] ANALYTICS["分析监控模块
/api/v1/analytics"] LIFECYCLE["生命周期管理模块
/api/v1/lifecycle"] KNOWLEDGE["知识库模块
/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代理的自动化任务处理能力、深度的内容分析与优化建议、完整的项目生命周期管理以及强大的智能知识检索功能。建议在生产环境中进一步完善错误日志、监控指标与缓存策略，持续优化查询性能与用户体验。