GET 请求（curl）
curl "http://127.0.0.1:8000/api/v1/pokemon?page=1&page_size=20&q=001"
API 调用说明文档
当前服务状态正常，返回结构统一为 {"code":0,"message":"ok","data":{},"meta":{}}。
服务器资源真贵请勿滥用
Base URL: http://127.0.0.1:8000/api/v1
Content-Type: application/json
接口版本: v1
管理后台: /admin
调用方式说明
POST 请求（curl）
curl -X POST "http://127.0.0.1:8000/api/v1/guestbook/messages" \
-H "Content-Type: application/json" \
-d '{"name":"张三","email":"demo@example.com","message":"你好"}'
前端 fetch
const res = await fetch(`${API_BASE}/pokemon?page=1&page_size=20`);
const json = await res.json();
if (json.code !== 0) throw new Error(json.message);
console.log(json.data, json.meta);
API 列表（含入参 / 返回）
| Method | 接口 | 说明 | 入参 | 返回 data |
|---|---|---|---|---|
| GET | /api/v1/health | 服务健康检查 | - | { service, timestamp } |
| GET | /api/v1/meta | 服务元信息 | - | { service, version, import_summary, bundle, sprite_base_url, updated_at } |
| GET | /api/v1/meta/version | 版本探测 | - | { version, updated_at } |
| GET | /api/v1/site/config | 网站标题/SEO/底部/二维码 | - | { site_title, seo_description, seo_keywords, footer_description, qrcode_* } |
| GET | /api/v1/site/legal | 用户协议/隐私政策/免责声明/关于我们 | - | { user_agreement, privacy_policy, disclaimer, about_us } |
| GET | /api/v1/bundle/full | Bundle 元信息 | - | { version, file, url, size, sha256, generated_at, gzip } |
| GET | /api/v1/bundle/full/data | Bundle 全量数据（二进制） | - | application/octet-stream（X-Pokopia-Payload-Encoding=gzip-json-v1，解压后为 { version, generated_at, sprites, data, counts }） |
| GET | /api/v1/sprites/sheets | Sprite 图集信息 | - | { base_url, sheets } |
| GET | /api/v1/pokemon | 宝可梦列表 | q?,type?,speciality?,habitat?,is_event?,page?,page_size? | Pokemon[] + { page, page_size, total } |
| GET | /api/v1/pokemon/{uid} | 宝可梦详情 | uid | Pokemon |
| GET | /api/v1/habitats | 栖息地列表 | q?,is_event?,page?,page_size? | Habitat[] + { page, page_size, total } |
| GET | /api/v1/habitats/{code} | 栖息地详情 | code | Habitat |
| GET | /api/v1/items | 道具列表 | q?,has_icon?,page?,page_size? | Item[] + { page, page_size, total } |
| GET | /api/v1/items/{hash} | 道具详情 | hash | Item |
| GET | /api/v1/locations | 地点列表 | q? | Location[] + { total } |
| GET | /api/v1/events | 活动列表 | q?,page?,page_size? | Event[] + { page, page_size, total } |
| GET | /api/v1/events/{id} | 活动详情 | id | Event |
| GET | /api/v1/search | 全局搜索 | q(必填),limit? | [{ type, id, title, subtitle, sprite }] + { total, limit } |
| GET | /api/v1/guestbook/messages | 留言列表（仅已审核通过） | page?,page_size? | Message[] + { page, page_size, total } |
| POST | /api/v1/guestbook/messages | 提交留言 | name,email,message | { id, status, submitted_at } |
留言提交限制：同一邮箱 1 分钟最多提交 2 条；超限返回 code=429001。行为风控命中返回 code=429002（临时封禁）。留言状态统一为 pending/approved/rejected，列表接口仅返回 status=approved 的留言。
响应示例
{
"code": 0,
"message": "ok",
"data": [],
"meta": {
"page": 1,
"page_size": 20,
"total": 123
}
}