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

24 KiB
Raw Permalink Blame History

引用数据接口

**本文档引用的文件** - [backend/app/api/citations.py](file://backend/app/api/citations.py) - [backend/app/api/queries.py](file://backend/app/api/queries.py) - [backend/app/api/reports.py](file://backend/app/api/reports.py) - [backend/app/schemas/citation.py](file://backend/app/schemas/citation.py) - [backend/app/schemas/query.py](file://backend/app/schemas/query.py) - [backend/app/services/citation.py](file://backend/app/services/citation.py) - [backend/app/services/query.py](file://backend/app/services/query.py) - [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py) - [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py) - [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py) - [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx) - [frontend/components/charts/platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx) - [frontend/lib/platforms.ts](file://frontend/lib/platforms.ts)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向“引用数据查询与分析”场景，提供完整的API文档与实现解析。内容覆盖：

  • 引用数据查询接口：支持按查询任务、平台、时间范围过滤，分页与排序
  • 统计分析功能：总查询数、引用数、引用率、平均位置、按平台统计、近30天趋势
  • 上下文提取机制：品牌识别、竞争品牌识别、置信度评分
  • 趋势分析与平台对比：通过统计接口与前端图表组件展示
  • 报告导出：CSV导出能力
  • 数据过滤、排序与分页参数说明
  • 前端接口调用与可视化使用指南

项目结构

后端采用FastAPI + SQLAlchemy异步ORM，前端Next.js + Recharts，核心模块如下：

  • API层：路由定义与参数校验
  • 服务层：业务逻辑与数据库查询
  • 模型层：SQLAlchemy ORM映射
  • 工作器：AI平台适配器与引用检测引擎
  • 前端：API封装、图表组件与平台映射
graph TB
subgraph "前端"
FE_API["前端API封装<br/>lib/api.ts"]
FE_Trend["趋势图组件<br/>charts/trend-chart.tsx"]
FE_Platform["平台柱状图组件<br/>charts/platform-chart.tsx"]
FE_PlatformMap["平台映射<br/>lib/platforms.ts"]
end
subgraph "后端"
API_Cit["引用API<br/>app/api/citations.py"]
API_Query["查询API<br/>app/api/queries.py"]
API_Report["报告API<br/>app/api/reports.py"]
Svc_Cit["引用服务<br/>app/services/citation.py"]
Svc_Query["查询服务<br/>app/services/query.py"]
Model_Cit["引用记录模型<br/>app/models/citation_record.py"]
Model_Query["查询模型<br/>app/models/query.py"]
Engine["引用检测引擎<br/>app/workers/citation_engine.py"]
Plat_Base["平台适配器基类<br/>app/workers/platforms/base.py"]
Plat_Kimi["Kimi适配器<br/>app/workers/platforms/kimi.py"]
Plat_Wenxin["文心一言适配器<br/>app/workers/platforms/wenxin.py"]
end
FE_API --> API_Cit
FE_API --> API_Query
FE_API --> API_Report
FE_Trend --> FE_API
FE_Platform --> FE_API
FE_PlatformMap --> FE_Platform
API_Cit --> Svc_Cit
API_Query --> Svc_Query
API_Report --> Svc_Cit
Svc_Cit --> Model_Cit
Svc_Query --> Model_Query
Engine --> Plat_Base
Engine --> Plat_Kimi
Engine --> Plat_Wenxin

图表来源

章节来源

核心组件

  • 引用查询接口：支持按query_id、platform、start_date、end_date过滤，分页skip/limit，按时间倒序
  • 统计分析接口：总查询数、总引用数、引用率、平均位置、按平台统计、近30天趋势
  • 即时查询触发：向队列提交查询任务
  • 报告导出：CSV导出引用记录
  • 品牌识别与上下文提取：精确/别名/模糊匹配，置信度评分，上下文片段与段落位置，竞争品牌识别

章节来源

架构总览

后端通过API路由接收请求，经服务层进行权限校验与数据聚合，模型层负责数据库访问；引用检测由工作器引擎驱动，调用各平台适配器获取AI响应，再进行品牌匹配与竞争品牌识别。

sequenceDiagram
participant Client as "客户端"
participant API as "引用API"
participant Service as "引用服务"
participant DB as "数据库"
participant Engine as "引用检测引擎"
participant Adapter as "平台适配器"
Client->>API : GET /api/v1/citations
API->>Service : get_citations(...)
Service->>DB : 查询引用记录(带过滤+分页)
DB-->>Service : 记录列表与总数
Service-->>API : {items,total}
API-->>Client : JSON响应
Client->>API : POST /api/v1/citations/{query_id}/run-now
API->>Service : trigger_query_now(...)
Service->>Engine : 执行查询与检测
Engine->>Adapter : 平台查询(keyword)
Adapter-->>Engine : 原始响应文本
Engine-->>Service : 引用检测结果
Service-->>API : 任务信息
API-->>Client : 任务ID/状态

图表来源

详细组件分析

引用查询接口

  • 路径与方法
    • GET /api/v1/citations
  • 查询参数
    • query_id: UUID，可选，按所属查询任务过滤
    • platform: 字符串，可选，按平台过滤
    • start_date: 日期时间，可选，起始时间
    • end_date: 日期时间，可选，结束时间
    • skip: 整数，>=0，默认0
    • limit: 整数，>=1且<=100，默认20
  • 排序规则：按 queried_at 降序
  • 响应体
    • items: 引用记录数组
    • total: 符合条件的总记录数
  • 权限与安全
    • 仅返回当前用户拥有的查询所对应的引用记录
    • 当提供query_id时，会额外校验该查询是否属于当前用户
flowchart TD
Start(["进入 list_citations"]) --> Build["构建基础条件: 用户ID过滤"]
Build --> CheckQueryID{"是否提供 query_id?"}
CheckQueryID --> |是| Verify["校验查询归属(用户ID)"]
Verify --> |不存在| ReturnEmpty["返回空结果与total=0"]
Verify --> |存在| AddFilter["追加 query_id 过滤"]
CheckQueryID --> |否| AddPlatform["追加 platform 过滤(可选)"]
AddFilter --> AddPlatform
AddPlatform --> AddTime["追加 start_date/end_date 过滤(可选)"]
AddTime --> QueryDB["查询+分页+排序"]
QueryDB --> Count["统计总数"]
Count --> Return["返回 items 与 total"]

图表来源

章节来源

引用统计分析接口

  • 路径与方法
    • GET /api/v1/citations/stats
  • 查询参数
    • query_id: UUID，可选，限定到特定查询任务
  • 响应体字段
    • total_queries: 总查询数
    • total_citations: 总引用数
    • citation_rate: 引用率 = total_citations / total_queries
    • avg_position: 平均位置（仅对有位置的引用计算）
    • by_platform: 各平台统计，含 queries、citations、rate、avg_position
    • trend: 近30天按周统计的引用数列表
  • 权限与安全
    • 当提供query_id时，会校验查询归属
flowchart TD
Start(["进入 get_citation_stats"]) --> Verify{"是否提供 query_id?"}
Verify --> |是| CheckOwner["校验查询归属"]
CheckOwner --> |不存在| Empty["返回全零统计"]
CheckOwner --> |存在| SetBase["设置基础条件(用户ID+query_id)"]
Verify --> |否| SetBase
SetBase --> Totals["统计 total_queries/total_citations"]
Totals --> AvgPos["计算 avg_position(仅cited且有位置)"]
AvgPos --> ByPlatform["按平台 group 统计"]
ByPlatform --> Trend["近30天按周统计"]
Trend --> Return["返回统计结果"]

图表来源

章节来源

即时查询触发接口

  • 路径与方法
    • POST /api/v1/citations/{query_id}/run-now
  • 行为
    • 校验查询归属与状态(必须为active)
    • 为配置的每个平台创建一个QueryTask(状态pending)
    • 返回任务ID与状态
  • 错误处理
    • 查询不存在或不属于当前用户：404
    • 查询状态非active：404
    • 无平台配置：404
sequenceDiagram
participant Client as "客户端"
participant API as "引用API"
participant Service as "引用服务"
participant DB as "数据库"
participant Engine as "引用检测引擎"
Client->>API : POST /citations/{query_id}/run-now
API->>Service : trigger_query_now(user_id, query_id)
Service->>DB : 校验查询归属与状态
DB-->>Service : 查询对象
Service->>Engine : 为每个平台创建QueryTask
Engine-->>Service : 返回首个任务
Service-->>API : 任务ID/状态
API-->>Client : 202 Accepted + 任务信息

图表来源

章节来源

报告导出接口

  • 路径与方法
    • GET /api/v1/reports/export/csv
  • 查询参数
    • query_id: UUID，必填
    • format: 字符串，当前仅支持csv
  • 响应
    • Content-Type: text/csv
    • Content-Disposition: 附件下载
    • 内容: CSV表格（日期、平台、是否引用、引用位置、引用文本、竞争品牌）

章节来源

查询管理接口（用于关联引用数据）

  • 路径与方法
    • GET /api/v1/queries
    • POST /api/v1/queries
    • GET /api/v1/queries/{query_id}
    • PUT /api/v1/queries/{query_id}
    • DELETE /api/v1/queries/{query_id}
  • 分页参数
    • skip: >=0，默认0
    • limit: >=1且<=100，默认20
  • 响应体
    • 查询列表/详情，包含keyword、target_brand、brand_aliases、platforms、frequency、status等

章节来源

数据模型与关系

  • 引用记录模型
    • 关键字段：query_id、platform、cited、citation_position、citation_text、competitor_brands、raw_response、queried_at
    • 索引：query_id、queried_at、platform
  • 查询模型
    • 关键字段：user_id、keyword、target_brand、brand_aliases、platforms、frequency、status、last_queried_at、next_query_at、created_at、updated_at
    • 索引：user_id、status、next_query_at
erDiagram
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
datetime last_queried_at
datetime next_query_at
datetime created_at
datetime updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
boolean cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
datetime queried_at
}
QUERIES ||--o{ CITATION_RECORDS : "拥有"

图表来源

章节来源

引用检测与上下文提取机制

  • 品牌匹配器
    • 支持精确匹配、别名匹配、模糊匹配
    • 输出：cited、confidence、match_type、position、citation_text
    • 置信度：精确=1.0，别名=0.9，模糊按相似度取值
  • 竞争品牌检测
    • 基于预定义行业品牌集合，排除目标品牌后返回其他品牌列表
  • 上下文提取
    • 按段落定位品牌首次出现位置（1-based）
    • 提取不超过200字符的上下文片段
  • 引擎流程
    • 为每个平台创建/获取QueryTask，更新状态为running
    • 调用平台适配器获取原始响应
    • 使用BrandMatcher进行检测，CompetitorDetector提取竞争品牌
    • 写入CitationRecord，更新Query的时间字段
classDiagram
class BrandMatcher {
+match(text) dict
-_extract_candidates(text) list
-_extract_position_and_context(text, keyword) tuple
}
class CompetitorDetector {
+detect(text, target_brand) list
}
class CitationEngine {
+execute_query(query, db) list
+execute_single_platform(keyword, platform, target_brand, brand_aliases) dict
-_get_or_create_task(db, query_id, platform) QueryTask
-_calculate_next_query_at(frequency) datetime
}
class BasePlatformAdapter {
<<abstract>>
+query(keyword) str
+close()
}
class KimiAdapter {
+query(keyword) str
+close()
}
class WenxinAdapter {
+query(keyword) str
+close()
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
CitationEngine --> BasePlatformAdapter : "依赖"
KimiAdapter --|> BasePlatformAdapter
WenxinAdapter --|> BasePlatformAdapter

图表来源

章节来源

前端接口调用与可视化

  • API封装
    • 提供查询列表、统计、报告导出等方法
    • 自动附加Authorization头
  • 趋势图组件
    • 接收trend数组，按周展示引用次数
  • 平台柱状图组件
    • 接收by_platform统计，按平台引用率展示
  • 平台映射
    • 将平台枚举转换为中文标签

章节来源

依赖分析

  • API层依赖服务层与认证依赖注入
  • 服务层依赖模型层与数据库会话
  • 引擎依赖平台适配器，适配器继承抽象基类
  • 前端依赖后端API与图表库
graph LR
API_Cit["citations.py"] --> Svc_Cit["services/citation.py"]
API_Query["queries.py"] --> Svc_Query["services/query.py"]
API_Report["reports.py"] --> Svc_Cit
Svc_Cit --> Model_Cit["models/citation_record.py"]
Svc_Query --> Model_Query["models/query.py"]
Svc_Cit --> Engine["workers/citation_engine.py"]
Engine --> Plat_Base["platforms/base.py"]
Engine --> Plat_Kimi["platforms/kimi.py"]
Engine --> Plat_Wenxin["platforms/wenxin.py"]
FE_API["frontend/lib/api.ts"] --> API_Cit
FE_API --> API_Query
FE_API --> API_Report
FE_Trend["trend-chart.tsx"] --> FE_API
FE_Platform["platform-chart.tsx"] --> FE_API

图表来源

章节来源

性能考虑

  • 分页与索引
    • 引用记录表对query_id、queried_at、platform建立索引，提升过滤与排序效率
    • 查询接口默认limit=20，最大100，避免一次性返回过多数据
  • 统计查询
    • 使用SQL聚合函数与分组，减少Python侧计算量
    • 趋势按周聚合，降低前端渲染压力
  • 并发与重试
    • 平台适配器对查询过程进行最多3次重试与指数退避，提高稳定性
  • 引擎批处理
    • 触发即时查询时为每个平台创建任务，便于后续并发执行

[本节为通用建议，无需具体文件分析]

故障排查指南

  • 404 Not Found
    • 查询不存在或不属于当前用户（统计与导出均会校验归属）
    • 即时查询时查询状态非active或未配置平台
  • 400 Bad Request
    • 报告导出format非csv
  • 403 Forbidden
    • 创建查询超过用户最大配额限制
  • 平台适配器错误
    • Playwright浏览器未安装或启动失败
    • 页面交互超时，检查网络与平台可用性
  • 结果为空
    • 过滤条件过于严格（如query_id、platform、时间范围）
    • 查询尚未产生任何引用记录

章节来源

结论

本系统提供了完整的引用数据查询、统计与导出能力，并内置品牌识别与竞争品牌检测机制。通过清晰的API设计、完善的权限校验与数据模型，以及前后端协同的可视化组件，能够满足日常的品牌监测与竞品分析需求。建议在生产环境中关注平台适配器的稳定性与数据库索引策略，以进一步提升性能与可靠性。

[本节为总结性内容，无需具体文件分析]

附录

API端点一览

  • 引用查询
    • GET /api/v1/citations
    • 参数：query_id、platform、start_date、end_date、skip、limit
    • 响应：items、total
  • 引用统计
    • GET /api/v1/citations/stats
    • 参数：query_id
    • 响应：总览与分项统计
  • 即时查询
    • POST /api/v1/citations/{query_id}/run-now
    • 响应：task_id、status、message
  • 报告导出
    • GET /api/v1/reports/export/csv
    • 参数：query_id、format(csv)
    • 响应：CSV流
  • 查询管理
    • GET /api/v1/queries
    • POST /api/v1/queries
    • GET /api/v1/queries/{query_id}
    • PUT /api/v1/queries/{query_id}
    • DELETE /api/v1/queries/{query_id}

章节来源

数据过滤、排序与分页参数

  • 过滤
    • query_id：按所属查询任务过滤
    • platform：按平台过滤
    • start_date/end_date：按时间范围过滤
  • 排序
    • 默认按 queried_at 降序
  • 分页
    • skip：>=0
    • limit：>=1且<=100

章节来源

品牌识别与置信度评分

  • 匹配类型与置信度
    • 精确匹配：1.0
    • 别名匹配：0.9
    • 模糊匹配：按相似度取值（>0.4视为匹配）
  • 输出字段
    • cited、confidence、match_type、position、citation_text、competitor_brands

章节来源

平台对比与趋势分析

  • 平台对比
    • by_platform包含各平台queries、citations、rate、avg_position
    • 前端使用柱状图组件展示引用率
  • 趋势分析
    • trend为近30天按周统计的citations
    • 前端使用折线图组件展示

章节来源