# 百度统计集成使用说明

## 概述

本项目已集成百度统计 API，可以实时获取文章的浏览量(PV)和访客量(UV)数据，并在页面中展示。

## 功能特性

- ✅ 实时获取百度统计数据
- ✅ 文章页面显示浏览量和访客量
- ✅ 统计数据管理页面
- ✅ 数据缓存机制（5分钟缓存）
- ✅ 自动刷新功能
- ✅ 数据导出功能
- ✅ 响应式设计

## 配置说明

### 1. 配置文件位置
```
src/config/analytics.ts
```

### 2. 主要配置项

```typescript
export const BAIDU_ANALYTICS_CONFIG = {
  // 访问令牌 - 需要定期更新
  accessToken: 'your_access_token_here',
  
  // 站点 ID
  siteId: 'your_site_id_here',
  
  // 百度统计站点代码
  siteCode: 'your_site_code_here',
  
  // 缓存配置
  cache: {
    expiry: 5 * 60 * 1000, // 5分钟缓存
  }
};
```

### 3. 环境变量配置（可选）

在 `.env` 文件中设置：
```env
VITE_BAIDU_ACCESS_TOKEN=your_access_token
VITE_BAIDU_SITE_ID=your_site_id
VITE_BAIDU_SITE_CODE=your_site_code
```

## 使用方法

### 1. 在文章页面显示统计数据

```tsx
import { ArticleStatsDisplay } from '@/components/blog/stats-display';

// 在文章组件中使用
<ArticleStatsDisplay 
  articleSlug="your-article-slug" 
  variant="inline" // 或 "card", "badge"
/>
```

### 2. 显示总体统计数据

```tsx
import { TotalStatsDisplay } from '@/components/blog/stats-display';

// 显示网站总体统计
<TotalStatsDisplay variant="card" />
```

### 3. 使用 Hook 获取数据

```tsx
import { useBaiduAnalytics, useArticleStats } from '@/hooks/use-baidu-analytics';

// 获取所有统计数据
const { articleStats, totalStats, loading, error } = useBaiduAnalytics();

// 获取单个文章统计
const { stats, loading, error } = useArticleStats('article-slug');
```

## 页面功能

### 1. 文章详情页
- 在文章元信息区域显示该文章的浏览量和访客量
- 数据来源：百度统计 API
- 自动匹配文章 URL

### 2. 统计管理页面 (`/analytics`)
- 查看所有文章的统计数据
- 支持时间范围筛选（今天、最近7天、最近30天、全部时间）
- 数据导出功能（CSV格式）
- 实时刷新功能

## API 接口说明

### 百度统计 API 端点
```
GET https://openapi.baidu.com/rest/2.0/tongji/report/getData
```

### 请求参数
- `access_token`: 访问令牌
- `site_id`: 站点ID
- `method`: visit/toppage/a（受访页面报告）
- `metrics`: pv_count,visitor_count（浏览量和访客数）
- `start_date`: 开始日期（可选）
- `end_date`: 结束日期（可选）

### 响应数据格式
```json
{
  "result": {
    "items": [
      [
        [{"name": "页面URL", "pageId": "页面ID"}],
        [浏览量, 访客数]
      ]
    ]
  }
}
```

## 数据匹配逻辑

系统通过以下方式匹配文章和统计数据：

1. **URL 匹配**: 检查页面 URL 是否包含 `/article/{articleSlug}`
2. **文章 slug 匹配**: 从 URL 中提取文章标识符
3. **模糊匹配**: 支持 URL 编码的中文标题匹配

## 缓存机制

- **缓存时间**: 5分钟
- **缓存策略**: 内存缓存，页面刷新后清空
- **自动刷新**: 可配置自动刷新间隔

## 错误处理

- API 请求失败时显示友好错误信息
- 网络错误时使用缓存数据
- 数据解析错误时返回空结果

## 性能优化

- 数据缓存减少 API 调用
- 懒加载统计组件
- 并行请求多个数据源
- 防抖处理频繁刷新

## 注意事项

1. **Access Token 更新**: 百度统计的 access_token 有有效期，需要定期更新
2. **API 限制**: 百度统计 API 有调用频率限制，建议合理使用缓存
3. **数据延迟**: 百度统计数据可能有1-2小时的延迟
4. **URL 匹配**: 确保文章 URL 格式与百度统计中的页面 URL 一致

## 故障排除

### 1. 数据不显示
- 检查 access_token 是否有效
- 确认 site_id 是否正确
- 查看浏览器控制台错误信息

### 2. 数据不匹配
- 检查文章 URL 格式
- 确认百度统计是否正确跟踪页面
- 查看 API 返回的页面列表

### 3. 性能问题
- 调整缓存时间
- 减少自动刷新频率
- 检查网络连接

## 更新日志

- **v1.0.0** (2025-09-23): 初始版本，支持基础统计功能
  - 百度统计 API 集成
  - 文章统计显示组件
  - 统计管理页面
  - 数据缓存和自动刷新