小妈厨房 API 文档

最后修改人	ai520
最后修改时间	2026-09-10 03:36:34
创建人	ai520
创建时间	2026-09-06 00:13:22

该文档由 ai520 创建于 2026-09-06 00:13:22 ， ai520 在 2026-09-10 03:36:34 修改了该文档。

[TOCM]

# 投稿接口（contribute.php）

> 域文档：11 | 创建：2026-09-05 | 维护：ai520
> 部署路径：`https://eat.wktyl.com/api/contribute.php`（本地镜像 `docs/api/contribute.php`）

## 一、功能

菜谱投稿：**匿名可提交**（无需注册），图形验证码防滥用，写入待审队列 `zbp_contribute` 表。
后台 XMKAdmin「📮 投稿管理」进行 AI 一键标准化（fy.wyi.cc `/chat`，llama-3.3-70B）→ 人工核对 → 入库发布（写 `zbp_post` + `zbp_recipe` + `zbp_recipe_ingredient` 三表）。

预留给 App 快捷投稿：接口与网页共用，App 端集成时建议跳过网页验证码改为接口签名（预留 `contact` 之外新增 `app_key` 参数，方案见本文末尾）。

## 二、获取验证码

```http
GET /api/contribute.php?act=captcha
```

响应：

```json
{
  "code": 200,
  "data": {
    "captcha_id": "md5 随机串",
    "image": "data:image/png;base64,...",
    "expire": 600
  }
}
```

- 验证码 4 位（去易混字符），10 分钟有效，**一次性**（校验时即销毁，无论对错，防爆破）

## 三、提交投稿

```http
POST /api/contribute.php?act=submit
Content-Type: application/json   （或 multipart/form-data）

{
  "title":      "蒜蓉粉丝蒸扇贝",        // 必填，2-50 字
  "cate_name":  "家常菜",               // 选填，分类名（后台入库时可改）
  "intro":      "一句话简介",            // 选填，≤200 字
  "ingredients": "扇贝 6个\n粉丝 1把",    // 必填，每行一条，≤3000 字
  "steps":      "第一步\n第二步",        // 必填，每行一步，≤5000 字
  "tips":       "小贴士",               // 选填，≤1000 字
  "contact":    "微信号/邮箱",           // 选填，仅用于反馈
  "images":     "",                    // 选填，预留
  "captcha_id": "上一步返回的 id",
  "captcha":    "ABCD"                 // 用户输入，不区分大小写
}
```

成功响应：

```json
{ "code": 200, "msg": "投稿成功，审核通过后将展示在网站", "data": { "id": 2 } }
```

错误码：

| code | 场景 |
|---|---|
| 422 | 字段缺失/超长、验证码错误/过期 |
| 429 | 同 IP 60 秒内重复提交 / 当日超 3 条 |

## 四、限流与安全

- 同 IP：60s 提交间隔 + 3 条/天（文件计数 `api/cache/contribute/rate_*.json`）
- 验证码一次性销毁（错也销毁）
- 全字段 `strip_tags` + 截断 + 参数化转义入库；不写任何 HTML 到待审数据
- CORS：`Access-Control-Allow-Origin: *`（App/H5 直调）

## 五、后台处理流程（XMKAdmin「📮 投稿管理」）

1. 列表按状态筛选（🟡 待审 / 🟢 已入库 / 🔴 已拒绝）
2. 「🤖 AI 一键标准化」：原文 → `fy.wyi.cc/chat`（system 约束只输出 JSON）→ 解析为
   `{title, cate_name, process, taste, intro, ingredients[{name,amount,type}], steps[], tips}`
   存入 `ai_json` 字段；表单预填可人工修订后「保存标准稿」
3. 「✅ 入库并发布」：按标准稿（缺省回退原文）写三表 → 状态置 1 → 清站点缓存 →
   新菜谱立即可在「最新」信息流与详情页访问（无封面图不影响入库，仅不进推荐/热门流）
4. 「🚫 拒绝」（带原因）/「🗑 删除」

## 六、App 接入预留

App 投稿不需要图形验证码（有账号体系前可先用设备指纹/签名）：

- 方案 A（推荐，接入登录后）：投稿接口增加 `act=app_submit`，走 App 登录 token 鉴权，免验证码，限流放宽至 10 条/天
- 方案 B（临时）：沿用图形验证码，App 内嵌 WebView 完成首投

## 七、数据表

```sql
zbp_contribute (id, title, cate_name, intro, ingredients, steps, tips,
                images, contact, ip, status[0待审/1入库/2拒绝], ai_json,
                log_id, admin_note, created_at, reviewed_at)
```