通用约定
Base URL：https://zhibo.zzhicong.eu.org。除「鉴权探针 / 管理类接口」外，读取接口均为公开。所有请求/响应均为 UTF-8 JSON。
| 鉴权方式 | 写操作与图片上传需带请求头 x-admin-token: <管理员口令>；口令错误返回 401 {"error":"unauthorized"} |
|---|---|
| 错误码 | 400 参数缺失/格式错误 · 401 未授权 · 404 不存在 · 405 方法不允许 · 413 图片过大（>4MB） · 500 服务器异常 |
| 幂等规则 | /api/ingest 与 /api/batch 按「日期 + source」先删后插：同日重复上传不会翻倍，整日覆盖 |
| 纠错引擎 | 入库接口自动应用错别字规则库（99 条，wrong 长度降序替换） |
公开读取接口
| 接口 | 说明 |
|---|---|
GET/api/version | 当前版本号 → {"version":"1.1"} |
GET/api/dates | 已归档日期列表（倒序）→ {"dates":["2026-10-09",…]} |
GET/api/messages?date=YYYY-MM-DD | 按日取消息（缺省取全部，上限 2000 条）；字段含 image_id（配图，可空） |
GET/api/messages/:id | 单条消息详情 |
GET/api/search?q=关键词 | 全文搜索（内容/发言人 LIKE，上限 500 条），返回 snippet 摘要 |
GET/api/image/:id | 图片二进制（带 cache-control，可直接放 <img src>） |
GET/api/rules | 错别字规则库全量 |
POST/api/preview | 解析+纠错预览（不入库）。body {"text":"…"} → {corrected, messages, applied}；applied 为命中的纠错清单（wrong/right/count） |
管理接口（需 x-admin-token）
| 接口 | 说明 |
|---|---|
GET/api/me | 鉴权探针 → 200 {"ok":true} / 401。后台用其判断登录态 |
POST/api/ingest | 粘贴整段群聊文本入库。body {"text":"李朋 2026-10-09 10:00 内容…"} → {inserted,dates} |
POST/api/batch | 结构化批量上传。body {"source?":"复盘群","items":[{date,time,sec,speaker,content,seq}]} → {inserted,dates,source} |
POST/api/messages | 新增单条消息。body {date,time?,sec?,speaker,content,image_id?,source?} → 201 {id,ok}（不整日覆盖，追加写入） |
PUT/api/messages/:id | 修改消息。body 可选 {content,speaker,msg_time,msg_sec,msg_date,image_id} → {ok} |
DEL/api/messages/:id | 删除单条消息 → {ok} |
POST/api/upload | 图片上传。body {"name?":"a.png","mime":"image/png","data":"<base64>"} → 201 {id,url:"/api/image/:id"}；单图 ≤4MB，mime 须 image/*（D1 base64 存储） |
DEL/api/image/:id | 删除图片 → {ok} |
POST/api/rerun-correct | 用当前规则重跑全部历史消息纠错 → {updated} |
POST/api/rules | 新增规则。body {wrong,right?,note?,category?} → 201 {id,…}（category：拼音/股票名/其他） |
PUT/api/rules/:id | 修改规则 → {ok} |
DEL/api/rules/:id | 删除规则 → {ok} |
调用示例（curl）
1) 批量上传（自动纠错、按日幂等）：
curl -X POST https://zhibo.zzhicong.eu.org/api/batch \
-H "Content-Type: application/json" \
-H "x-admin-token: YOUR_TOKEN" \
-d '{"items":[{"date":"2026-10-11","time":"10:30","sec":"00","speaker":"李朋","content":"pán面还行"}]}'
# → {"inserted":1,"dates":["2026-10-11"],"source":"复盘群"} （pán面 已自动纠正为 盘面）
2) 新增单条消息并配图：
# 先上传图片拿 url
curl -X POST https://zhibo.zzhicong.eu.org/api/upload \
-H "Content-Type: application/json" -H "x-admin-token: YOUR_TOKEN" \
-d '{"name":"k.png","mime":"image/png","data":"iVBORw0KGgo…"}'
# → {"id":7,"url":"/api/image/7"}
curl -X POST https://zhibo.zzhicong.eu.org/api/messages \
-H "Content-Type: application/json" -H "x-admin-token: YOUR_TOKEN" \
-d '{"date":"2026-10-11","time":"10:35","speaker":"廖峥","content":"看这张图","image_id":7}'
3) 修改 / 删除：
curl -X PUT https://zhibo.zzhicong.eu.org/api/messages/123 \
-H "Content-Type: application/json" -H "x-admin-token: YOUR_TOKEN" \
-d '{"content":"修正后的内容","image_id":7}'
curl -X DELETE https://zhibo.zzhicong.eu.org/api/messages/123 -H "x-admin-token: YOUR_TOKEN"
数据边界
图片以 base64 存于 D1（无 R2 依赖），单图上限 4MB，适合截图/轻量配图；消息集合查询上限 2000 条、搜索上限 500 条；/api/batch 与 /api/ingest 均为「整日覆盖」语义，追加单条请用 POST /api/messages。