# 引用数据接口

<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)