ui细节优化
This commit is contained in:
Developer
216
lib/services/document/统计API文档.md
Normal file
216
lib/services/document/统计API文档.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 统计 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 接口
|
||||
|
||||
Reference in New Issue
Block a user