# 统计 API 接口文档

## 概述

获取网站统计信息的 API 接口，返回分类数量、收录数量、热度统计等数据。

## 基础信息

- **接口地址**: `https://yy.vogov.cn/api/app/stats.php`
- **请求方式**: GET
- **返回格式**: JSON
- **字符编码**: UTF-8
- **支持跨域**: 是（`Access-Control-Allow-Origin: *`）

## 请求参数

无需任何参数，直接 GET 请求即可。

## 返回示例

```json
{
  "ok": true,
  "data": {
    "count_category": 3,
    "count_site": 15807,
    "count_apply": 14,
    "count_apply_reject": 3,
    "count_article": 2,
    "count_article_category": 4,
    "count_notice": 2,
    "count_link": 3,
    "count_tags": 131,
    "cumulative_hits": "16887",
    "cumulative_likes": "272",
    "top_hits_day": {
      "id": "7559",
      "name": "除却天边月，没人知。人有悲欢离合，月有阴晴圆缺，此事古难全。"
    },
    "top_hits_month": {
      "id": "461",
      "name": "人有悲欢离合，月有阴晴圆缺，此事古难全。"
    },
    "top_hits_total": {
      "id": "1",
      "name": "井鱼焉知身在渊，错把方寸作世间‌"
    },
    "top_like": {
      "id": "5876",
      "name": "世间无比酒，天下有名楼。"
    },
    "build_time": "2026-03-04"
  },
  "timestamp": 1774977191
}
```

## 返回字段说明

### 基础字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| ok | boolean | 请求是否成功 |
| data | object | 统计数据对象 |
| timestamp | int | 服务器时间戳 |

### data 对象字段

#### 数量统计

| 字段名 | 类型 | 说明 |
|--------|------|------|
| count_category | int | 已开设分类数量 |
| count_site | int | 已收录诗句数量 |
| count_apply | int | 审核中的申请数量 |
| count_apply_reject | int | 已拒绝的申请数量 |
| count_article | int | 文章数量 |
| count_article_category | int | 文章分类数量 |
| count_notice | int | 已发布公告数量 |
| count_link | int | 开发者人数 |
| count_tags | int | 分类标签数量 |

#### 热度统计

| 字段名 | 类型 | 说明 |
|--------|------|------|
| cumulative_hits | string | 累计热度次数 |
| cumulative_likes | string | 累计点赞数量 |

#### 热门内容

| 字段名 | 类型 | 说明 |
|--------|------|------|
| top_hits_day | object/null | 当天热门诗句 |
| top_hits_month | object/null | 本月热门诗句 |
| top_hits_total | object/null | 历史最热诗句 |
| top_like | object/null | 最高点赞诗句 |

#### 热门内容对象

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 诗句 ID |
| name | string | 诗句内容 |

#### 其他

| 字段名 | 类型 | 说明 |
|--------|------|------|
| build_time | string | 建站时间（格式：YYYY-MM-DD） |

## 错误返回

```json
{
  "ok": false,
  "error": "错误信息"
}
```

## 调用示例

### JavaScript (Fetch)

```javascript
fetch('https://yy.vogov.cn/api/app/stats.php')
  .then(response => response.json())
  .then(data => {
    if (data.ok) {
      console.log('已收录诗句：', data.data.count_site);
      console.log('当天热门：', data.data.top_hits_day.name);
    }
  })
  .catch(error => console.error('Error:', error));
```


### Flutter (Dart)

```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<StatsData?> getStats() async {
  final response = await http.get(
    Uri.parse('https://yy.vogov.cn/api/app/stats.php'),
  );
  
  if (response.statusCode == 200) {
    final data = json.decode(response.body);
    if (data['ok'] == true) {
      return StatsData.fromJson(data['data']);
    }
  }
  return null;
}

class StatsData {
  final int countSite;
  final String cumulativeHits;
  final TopContent? topHitsDay;
  
  StatsData({
    required this.countSite,
    required this.cumulativeHits,
    this.topHitsDay,
  });
  
  factory StatsData.fromJson(Map<String, dynamic> json) {
    return StatsData(
      countSite: json['count_site'],
      cumulativeHits: json['cumulative_hits'],
      topHitsDay: json['top_hits_day'] != null 
        ? TopContent.fromJson(json['top_hits_day']) 
        : null,
    );
  }
}

class TopContent {
  final String id;
  final String name;
  
  TopContent({required this.id, required this.name});
  
  factory TopContent.fromJson(Map<String, dynamic> json) {
    return TopContent(id: json['id'], name: json['name']);
  }
}
```

## 数据来源

数据来源于以下数据库表：

| 表名 | 说明 |
|------|------|
| pre_category | 分类表 |
| pre_site | 收录诗句表 |
| pre_apply | 申请收录表 |
| pre_article | 文章表 |
| pre_article_category | 文章分类表 |
| pre_notice | 公告表 |
| pre_link | 友情链接表 |

## 注意事项

1. **缓存建议**：统计数据变化频率较低，建议客户端缓存 5-10 分钟
2. **空值处理**：热门内容字段可能为 `null`，请做好空值判断
3. **跨域支持**：接口已配置 CORS，支持前端直接调用
4. **数据类型**：`cumulative_hits` 和 `cumulative_likes` 返回的是字符串类型

## 更新日志

- **v1.0.14** (2026-03-30): 新增统计 API 接口