# 诗词API接口文档

## 概述

本文档描述了诗词应用的所有API接口，包括诗词推荐、搜索、点赞、统计等功能。

**基础URL**: `https://yy.vogov.cn/api/`

---

## 1. 诗词推荐接口 (`/pms.php`)

### 接口说明
提供诗词随机推荐、获取指定站点信息及点赞功能，支持朝代、标签多条件筛选。

**请求方式**: GET / POST 均可

**重要**: 只要接口成功返回 `data` 字段，即会自动增加该站点的浏览次数（日、月、总）。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|
| `lid` | int | 否 | 点赞ID。传入时直接对该站点执行点赞/取消点赞，返回更新后的信息，并增加浏览次数统计。此时忽略其他所有参数。 |
| `id` | int | 否 | 站点ID。返回该站点的完整信息（不点赞），可与 `like` 组合实现同时点赞。 |
| `like` | 标志 | 否 | 无值参数。若存在，则对本次请求返回的站点（通过 `id` 指定或随机推荐）执行点赞/取消点赞。可与 `id`、`dyn`、`tag` 组合。 |
| `dyn` | string | 否 | 朝代，多个用英文逗号分隔，例如 `宋代,唐代`。条件为"或"，即满足任一朝代。 |
| `tag` | string | 否 | 标签，多个用英文逗号分隔，例如 `友情,柳树`。条件为"或"，即满足任一标签。 |

### 优先级说明
- `lid` > `id` > 随机推荐。若同时提供 `lid` 和 `like`，`like` 无效（以 `lid` 为准）。
- 若不提供任何参数，则从全站随机返回一条。
- 若同时提供 `dyn` 和 `tag`，则取交集（必须同时满足朝代和标签条件）。

### 返回格式

始终返回 JSON 格式，包含以下字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | 状态码：0 成功，非0 失败 |
| `msg` | string | 提示信息（如"点赞成功"、"取消点赞"等） |
| `data` | object | 站点完整信息 |

### data 对象字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 站点ID |
| `name` | string | 诗词名称/诗句 |
| `alias` | string | 朝代 |
| `keywords` | string | 标签（多个用逗号分隔） |
| `introduce` | string | 译文/介绍 |
| `drtime` | string | 原文 |
| `like` | int | 点赞数 |
| `url` | string | 诗人和<标题> |
| `tui` | int | 是否推荐（1是0否） |
| `star` | int | 星级 |
| `hits_total` | int | 总浏览数 |
| `hits_month` | int | 月浏览数 |
| `hits_day` | int | 日浏览数 |
| `date` | string | 最后统计日期（Y-m-d） |
| `datem` | string | 最后统计月份（Y-m） |
| `time` | string | 收录时间 |
| `create_time` | string | 创建时间 |
| `update_time` | string | 更新时间 |
| …… | | 其他数据库字段均返回 |

### 示例请求

#### 1. 随机推荐（无参数）
```
GET /pms.php
```

#### 2. 随机推荐并点赞
```
GET /pms.php?like
```

#### 3. 获取指定站点信息（id=5）
```
GET /pms.php?id=5
```

#### 4. 获取指定站点信息并点赞（id=5 且 like）
```
GET /pms.php?id=5&like
```

#### 5. 按朝代筛选（宋代或唐代）并随机推荐
```
GET /pms.php?dyn=宋代,唐代
```

#### 6. 按朝代筛选并点赞（like 标志）
```
GET /pms.php?like&dyn=宋代
```

#### 7. 按标签筛选（友情）并点赞
```
GET /pms.php?like&tag=友情
```

#### 8. 同时筛选（朝代=宋代 且 标签=友情）并点赞
```
GET /pms.php?like&dyn=宋代&tag=友情
```

#### 9. 直接点赞指定站点（lid=5）
```
POST /pms.php?lid=5
```

### 返回示例
```json
{
    "code": 0,
    "msg": "点赞成功",
    "data": {
        "id": 15572,
        "name": "良将不怯死以苟免，烈士不毁节以求生",
        "alias": "暂无朝代",
        "keywords": "三国志",
        "introduce": "优秀的将领不会畏惧死亡而苟且偷生，忠烈之士不会毁坏名节而求得生存。",
        "drtime": "(赏析)此句强调了人的尊严和信仰是不能被牺牲和放弃...",
        "like": 1,
        "tui": 0,
        "star": 4,
        "hits_total": 156,
        "hits_month": 12,
        "hits_day": 3,
        "date": "2026-03-21",
        "datem": "2026-03",
        "create_time": "2026-03-13 06:38:24",
        "update_time": "2026-03-13 21:03:58"
    }
}
```

### 注意事项

1. **浏览次数统计**：只要接口成功返回 data，该站点的日、月、总浏览次数均会 +1。
2. **朝代对应**：数据库字段 alias，标签对应 keywords（支持模糊匹配）。
3. **多个值分隔**：用英文逗号分隔，不要混用中文逗号。
4. **点赞/取消点赞**：基于 IP 进行限制，同一 IP 对同一站点切换状态。
5. **like 是无值参数**：只需在 URL 中包含 &like 或 ?like 即可，无需赋值。
6. **频率限制**：每个 IP 每秒最多请求 2 次，超出将返回 `{"code":429, "msg":"请求过于频繁，请稍后再试"}`。
7. **接口未做严格的频率限制**，但建议合理调用。

---

## 2. 搜索接口 (`/searchs.php`)

**Flutter 客户端**：`lib/utils/http/poetry_api.dart` 中 `PoetryApi.searchPoetry` 已对接本接口；全站搜索 UI 为 `lib/views/active/active_search_page.dart`。

### 接口说明
提供诗词内容搜索功能，支持模糊搜索和精确搜索，多关键字搜索，以及自定义搜索字段。

**请求方式**: GET / POST 均可

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|
| `q` | string | 否 | 搜索关键词 |
| `field` | string | 否 | 搜索字段：name(标题), keywords(标签), introduce(译文) |
| `page` | int | 否 | 页码，默认1 |
| `limit` | int | 否 | 每页数量，默认20 |

### 返回格式

```json
{
    "code": 0,
    "msg": "搜索成功",
    "data": {
        "total": 156,
        "page": 1,
        "limit": 20,
        "list": [
            {
                "id": 123,
                "name": "诗词标题",
                "alias": "唐代",
                "keywords": "友情,离别",
                "introduce": "译文内容...",
                "like": 25,
                "hits_total": 1024
            }
        ]
    }
}
```

### 示例请求

#### 1. 基础搜索
```
GET /searchs.php?q=李白
```

#### 2. 按标题搜索
```
GET /searchs.php?q=李白&field=name
```

#### 3. 分页搜索
```
GET /searchs.php?q=爱情&page=2&limit=10
```

---

## 3. 朝代列表接口 (`/dyn.php`)

### 接口说明
获取所有可用的朝代列表。

**请求方式**: GET

### 返回格式

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 8,
        "dynasties": [
            "先秦",
            "汉代",
            "唐代",
            "宋代",
            "元代",
            "明代",
            "清代",
            "暂无朝代"
        ]
    }
}
```

---

## 4. 排行榜接口 (`/apilist.php`)

### 接口说明
获取诗词排行榜信息，包括点赞排行、浏览排行等。

**请求方式**: GET

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|
| `type` | string | 否 | 排行类型：like(点赞), hits(浏览) |
| `period` | string | 否 | 时间周期：day(日), month(月), total(总) |
| `limit` | int | 否 | 返回数量，默认10 |

### 返回格式

```json
{
    "code": 0,
    "msg": "success", 
    "data": {
        "top_like": [
            {"id": 123, "name": "诗词标题", "like": 156}
        ],
        "top_hits_day": [
            {"id": 456, "name": "诗词标题", "hits_day": 89}
        ],
        "top_hits_month": [
            {"id": 789, "name": "诗词标题", "hits_month": 456}
        ],
        "top_hits_total": [
            {"id": 101, "name": "诗词标题", "hits_total": 2341}
        ]
    }
}
```

---

## 5. 网站统计接口 (`/stat.php`)

### 接口说明
获取网站整体统计信息。

**请求方式**: GET

### 返回格式

```json
{
    "code": 0,
    "msg": "网站统计",
    "data": {
        "build_time": "2026-03-13 06:38:24",
        "category": 25,
        "site": 1568,
        "apply": 45,
        "apply_reject": 12,
        "article": 89,
        "article_category": 8,
        "notice": 6,
        "link": 23,
        "top_hits_day": [
            {"id": 123, "name": "诗词标题", "hits_day": 156}
        ],
        "top_hits_month": [
            {"id": 456, "name": "诗词标题", "hits_month": 892}
        ],
        "top_hits_total": [
            {"id": 789, "name": "诗词标题", "hits_total": 3456}
        ],
        "top_like": [
            {"id": 101, "name": "诗词标题", "like": 234}
        ]
    }
}
```

---

## 通用说明

### 错误码

| 错误码 | 说明 |
|------|------|
| 0 | 成功 |
| -1 | 数据不存在或参数错误 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |

### 通用响应格式

所有接口都遵循统一的响应格式：

```json
{
    "code": 0,           // 状态码
    "msg": "success",     // 提示信息
    "data": {}            // 具体数据，成功时返回
}
```

### 开发建议

1. **错误处理**：检查 `code` 字段，非0时处理错误信息
2. **频率控制**：避免短时间内大量请求，建议每秒不超过2次
3. **缓存策略**：对于不常变化的数据（如朝代列表），建议本地缓存
4. **分页处理**：搜索接口支持分页，合理设置每页数量
5. **字段验证**：传入参数前进行基本验证

---

## Flutter客户端使用示例

### 使用HttpClient

```dart
import 'package:your_app/utils/http/http_client.dart';
import 'package:your_app/utils/http/poetry_api.dart';

// 获取随机诗词
try {
  final response = await PoetryApi.getRandomPoetry();
  print('诗词标题: ${response.data?.name}');
  print('朝代: ${response.data?.alias}');
} catch (e) {
  print('获取失败: $e');
}

// 按朝代获取
final response = await PoetryApi.getRandomPoetry(dynasty: '唐代');

// 搜索诗词
final searchResponse = await PoetryApi.searchPoetry('李白');

// 点赞
if (poetryData?.id != null) {
  await PoetryApi.toggleLike(poetryData!.id);
}
```

### 网络权限配置

确保在 `AndroidManifest.xml` 和 `module.json5` 中配置了网络权限：

**Android**:
```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

**鸿蒙**:
```json
"requestPermissions": [
  {"name": "ohos.permission.INTERNET"},
  {"name": "ohos.permission.GET_NETWORK_INFO"}
]
```

---

*最后更新时间: 2026-03-21*
*API版本: v1.0*