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

590 lines
24 KiB
Markdown
Raw Permalink 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.

# 引用数据接口
<cite>
**本文档引用的文件**
- [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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“引用数据查询与分析”场景，提供完整的API文档与实现解析。内容覆盖：
- 引用数据查询接口：支持按查询任务、平台、时间范围过滤，分页与排序
- 统计分析功能：总查询数、引用数、引用率、平均位置、按平台统计、近30天趋势
- 上下文提取机制：品牌识别、竞争品牌识别、置信度评分
- 趋势分析与平台对比：通过统计接口与前端图表组件展示
- 报告导出：CSV导出能力
- 数据过滤、排序与分页参数说明
- 前端接口调用与可视化使用指南
## 项目结构
后端采用FastAPI + SQLAlchemy异步ORM，前端Next.js + Recharts，核心模块如下：
- API层：路由定义与参数校验
- 服务层：业务逻辑与数据库查询
- 模型层：SQLAlchemy ORM映射
- 工作器：AI平台适配器与引用检测引擎
- 前端：API封装、图表组件与平台映射
```mermaid
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
```
**图表来源**
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
**章节来源**
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
## 核心组件
- 引用查询接口：支持按query_id、platform、start_date、end_date过滤，分页skip/limit，按时间倒序
- 统计分析接口：总查询数、总引用数、引用率、平均位置、按平台统计、近30天趋势
- 即时查询触发：向队列提交查询任务
- 报告导出：CSV导出引用记录
- 品牌识别与上下文提取：精确/别名/模糊匹配，置信度评分，上下文片段与段落位置，竞争品牌识别
**章节来源**
- [backend/app/api/citations.py:25-78](file://backend/app/api/citations.py#L25-L78)
- [backend/app/schemas/citation.py:1-50](file://backend/app/schemas/citation.py#L1-L50)
- [backend/app/services/citation.py:24-269](file://backend/app/services/citation.py#L24-L269)
- [backend/app/workers/citation_engine.py:19-309](file://backend/app/workers/citation_engine.py#L19-L309)
## 架构总览
后端通过API路由接收请求，经服务层进行权限校验与数据聚合，模型层负责数据库访问；引用检测由工作器引擎驱动，调用各平台适配器获取AI响应，再进行品牌匹配与竞争品牌识别。
```mermaid
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/状态
```
**图表来源**
- [backend/app/api/citations.py:25-78](file://backend/app/api/citations.py#L25-L78)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/base.py:10-17](file://backend/app/workers/platforms/base.py#L10-L17)
## 详细组件分析
### 引用查询接口
- 路径与方法
- 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时，会额外校验该查询是否属于当前用户
```mermaid
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"]
```
**图表来源**
- [backend/app/api/citations.py:25-46](file://backend/app/api/citations.py#L25-L46)
- [backend/app/services/citation.py:24-73](file://backend/app/services/citation.py#L24-L73)
**章节来源**
- [backend/app/api/citations.py:25-46](file://backend/app/api/citations.py#L25-L46)
- [backend/app/services/citation.py:24-73](file://backend/app/services/citation.py#L24-L73)
### 引用统计分析接口
- 路径与方法
- 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时，会校验查询归属
```mermaid
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["返回统计结果"]
```
**图表来源**
- [backend/app/api/citations.py:49-56](file://backend/app/api/citations.py#L49-L56)
- [backend/app/services/citation.py:76-201](file://backend/app/services/citation.py#L76-L201)
**章节来源**
- [backend/app/api/citations.py:49-56](file://backend/app/api/citations.py#L49-L56)
- [backend/app/schemas/citation.py:25-44](file://backend/app/schemas/citation.py#L25-L44)
- [backend/app/services/citation.py:76-201](file://backend/app/services/citation.py#L76-L201)
### 即时查询触发接口
- 路径与方法
- POST /api/v1/citations/{query_id}/run-now
- 行为
- 校验查询归属与状态(必须为active)
- 为配置的每个平台创建一个QueryTask(状态pending)
- 返回任务ID与状态
- 错误处理
- 查询不存在或不属于当前用户：404
- 查询状态非active：404
- 无平台配置：404
```mermaid
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 + 任务信息
```
**图表来源**
- [backend/app/api/citations.py:59-78](file://backend/app/api/citations.py#L59-L78)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
- [backend/app/workers/citation_engine.py:268-289](file://backend/app/workers/citation_engine.py#L268-L289)
**章节来源**
- [backend/app/api/citations.py:59-78](file://backend/app/api/citations.py#L59-L78)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
### 报告导出接口
- 路径与方法
- GET /api/v1/reports/export/csv
- 查询参数
- query_id: UUID，必填
- format: 字符串，当前仅支持csv
- 响应
- Content-Type: text/csv
- Content-Disposition: 附件下载
- 内容: CSV表格（日期、平台、是否引用、引用位置、引用文本、竞争品牌）
**章节来源**
- [backend/app/api/reports.py:16-47](file://backend/app/api/reports.py#L16-L47)
- [backend/app/services/citation.py:237-269](file://backend/app/services/citation.py#L237-L269)
### 查询管理接口（用于关联引用数据）
- 路径与方法
- 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等
**章节来源**
- [backend/app/api/queries.py:15-86](file://backend/app/api/queries.py#L15-L86)
- [backend/app/schemas/query.py:11-94](file://backend/app/schemas/query.py#L11-L94)
- [backend/app/services/query.py:12-130](file://backend/app/services/query.py#L12-L130)
### 数据模型与关系
- 引用记录模型
- 关键字段：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
```mermaid
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 : "拥有"
```
**图表来源**
- [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.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)
### 引用检测与上下文提取机制
- 品牌匹配器
- 支持精确匹配、别名匹配、模糊匹配
- 输出：cited、confidence、match_type、position、citation_text
- 置信度：精确=1.0，别名=0.9，模糊按相似度取值
- 竞争品牌检测
- 基于预定义行业品牌集合，排除目标品牌后返回其他品牌列表
- 上下文提取
- 按段落定位品牌首次出现位置（1-based）
- 提取不超过200字符的上下文片段
- 引擎流程
- 为每个平台创建/获取QueryTask，更新状态为running
- 调用平台适配器获取原始响应
- 使用BrandMatcher进行检测，CompetitorDetector提取竞争品牌
- 写入CitationRecord，更新Query的时间字段
```mermaid
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
```
**图表来源**
- [backend/app/workers/citation_engine.py:19-309](file://backend/app/workers/citation_engine.py#L19-L309)
- [backend/app/workers/platforms/base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)
- [backend/app/workers/platforms/kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [backend/app/workers/platforms/wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)
**章节来源**
- [backend/app/workers/citation_engine.py:19-309](file://backend/app/workers/citation_engine.py#L19-L309)
### 前端接口调用与可视化
- API封装
- 提供查询列表、统计、报告导出等方法
- 自动附加Authorization头
- 趋势图组件
- 接收trend数组，按周展示引用次数
- 平台柱状图组件
- 接收by_platform统计，按平台引用率展示
- 平台映射
- 将平台枚举转换为中文标签
**章节来源**
- [frontend/lib/api.ts:23-57](file://frontend/lib/api.ts#L23-L57)
- [frontend/components/charts/trend-chart.tsx:13-59](file://frontend/components/charts/trend-chart.tsx#L13-L59)
- [frontend/components/charts/platform-chart.tsx:15-67](file://frontend/components/charts/platform-chart.tsx#L15-L67)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
## 依赖分析
- API层依赖服务层与认证依赖注入
- 服务层依赖模型层与数据库会话
- 引擎依赖平台适配器，适配器继承抽象基类
- 前端依赖后端API与图表库
```mermaid
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
```
**图表来源**
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
**章节来源**
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
## 性能考虑
- 分页与索引
- 引用记录表对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、时间范围）
- 查询尚未产生任何引用记录
**章节来源**
- [backend/app/api/reports.py:23-27](file://backend/app/api/reports.py#L23-L27)
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/workers/platforms/kimi.py:21-32](file://backend/app/workers/platforms/kimi.py#L21-L32)
- [backend/app/workers/platforms/wenxin.py:21-32](file://backend/app/workers/platforms/wenxin.py#L21-L32)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
## 结论
本系统提供了完整的引用数据查询、统计与导出能力，并内置品牌识别与竞争品牌检测机制。通过清晰的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}
**章节来源**
- [backend/app/api/citations.py:25-78](file://backend/app/api/citations.py#L25-L78)
- [backend/app/api/reports.py:16-47](file://backend/app/api/reports.py#L16-L47)
- [backend/app/api/queries.py:15-86](file://backend/app/api/queries.py#L15-L86)
### 数据过滤、排序与分页参数
- 过滤
- query_id：按所属查询任务过滤
- platform：按平台过滤
- start_date/end_date：按时间范围过滤
- 排序
- 默认按 queried_at 降序
- 分页
- skip：>=0
- limit：>=1且<=100
**章节来源**
- [backend/app/api/citations.py:25-46](file://backend/app/api/citations.py#L25-L46)
- [backend/app/services/citation.py:24-73](file://backend/app/services/citation.py#L24-L73)
### 品牌识别与置信度评分
- 匹配类型与置信度
- 精确匹配：1.0
- 别名匹配：0.9
- 模糊匹配：按相似度取值（>0.4视为匹配）
- 输出字段
- cited、confidence、match_type、position、citation_text、competitor_brands
**章节来源**
- [backend/app/workers/citation_engine.py:26-120](file://backend/app/workers/citation_engine.py#L26-L120)
### 平台对比与趋势分析
- 平台对比
- by_platform包含各平台queries、citations、rate、avg_position
- 前端使用柱状图组件展示引用率
- 趋势分析
- trend为近30天按周统计的citations
- 前端使用折线图组件展示
**章节来源**
- [backend/app/schemas/citation.py:25-44](file://backend/app/schemas/citation.py#L25-L44)
- [frontend/components/charts/platform-chart.tsx:34-67](file://frontend/components/charts/platform-chart.tsx#L34-L67)
- [frontend/components/charts/trend-chart.tsx:22-59](file://frontend/components/charts/trend-chart.tsx#L22-L59)
Reference in New Issue View Git Blame Copy Permalink