小妈厨房 API 文档

最后修改人	ai520
最后修改时间	2026-09-10 03:36:31
创建人	ai520
创建时间	2026-08-25 01:37:45

该文档由 ai520 创建于 2026-08-25 01:37:45 ， ai520 在 2026-09-10 03:36:31 修改了该文档。

[TOCM]

# 筛选与发现（api_filter / api_discover / api_what_to_eat）

> 多条件筛选、发现页瀑布流随机数据、"今天吃什么"智能选择

---

## 一、api_filter.php — 多条件筛选

### 接口总览

| act | 功能 |
|-----|------|
| index | 接口索引 |
| recipe_main_categories | 食谱大类（中国菜/脏腑调理等） |
| recipe_sub_categories | 食谱子类（按 parent_id） |
| ingredient_main_categories | 食材大类（含 ingredient_count） |
| ingredient_sub_categories | 食材子类 |
| taste_tags / cooking_tags | 口味/工艺标签 |
| meal_times | 用餐时段（含 count） |
| category_tags | 指定分类下的口味+工艺标签 |
| filter_recipes | **核心：多条件筛选菜谱** |
| filter_ingredients | 筛选食材 |
| ingredient_recipes | 食材对应菜品 |
| global_search | 全局搜索（菜谱+食材+标签） |

### 分类与标签获取

```
GET api_filter.php?act=recipe_main_categories
GET api_filter.php?act=recipe_sub_categories&parent_id=12
GET api_filter.php?act=ingredient_main_categories
GET api_filter.php?act=taste_tags&limit=20          # 口味标签
GET api_filter.php?act=cooking_tags&limit=20        # 工艺标签
GET api_filter.php?act=meal_times                   # 用餐时段
GET api_filter.php?act=category_tags&category_id=13 # 分类下标签联动
```

### filter_recipes — 多条件筛选菜谱（核心）

```
GET api_filter.php?act=filter_recipes&category_name=家常菜&meal_time=早餐&page=1
```

**基础参数**

| 参数 | 说明 |
|------|------|
| main_category / sub_category | 大类 ID / 子类 ID（多个逗号分隔） |
| category_name | 分类名称（与 ID 二选一，如"家常菜"） |
| taste_tag / cooking_tag | 口味/工艺标签 ID |
| taste_name / cooking_name | 口味/工艺名称（如"甜味"/"炒"） |
| meal_time | 用餐时段（早餐/中餐/晚餐/零食） |
| keyword | 搜索关键词 |
| page / limit | 分页，limit 最大 50 |

**高级筛选参数**

| 参数 | 示例 | 说明 |
|------|------|------|
| nutrition_name | `镁` | 按营养成分筛选 |
| nutrition_min / nutrition_max | `100` / `200` | 营养成分范围 |
| allergen | `豆` | 排除含该过敏原的菜品 |
| ingredient | `色拉酱` | 包含该食材的菜品 |
| author_id | `1` | 按作者筛选 |

**排除参数（exclude_*）**

| 参数 | 示例 |
|------|------|
| exclude_category / exclude_category_name | `42,43` / `凉菜` |
| exclude_taste / exclude_taste_name | `1,2` / `辣味` |
| exclude_cooking / exclude_cooking_name | `50,51` / `炸` |
| exclude_ingredient | `花生` |
| exclude_allergen | `虾` |
| exclude_author | `1,2` |
| exclude_meal_time | `早餐` |

**组合示例**

```
# 家常菜 + 早餐 + 含叶酸
GET api_filter.php?act=filter_recipes&category_name=家常菜&meal_time=早餐&nutrition_name=叶酸

# 家常菜中排除辣味和油炸
GET api_filter.php?act=filter_recipes&category_name=家常菜&exclude_taste_name=辣味&exclude_cooking_name=炸

# 高蛋白健身餐（蛋白质≥20g）
GET api_filter.php?act=filter_recipes&nutrition_name=蛋白质&nutrition_min=20
```

返回 `data.list[]` + `filters`（条件回显）+ `page/limit/total/has_more`。

### global_search — 全局搜索

```
GET api_filter.php?act=global_search&keyword=鸡蛋&type=all&limit=10
```

type: `all`(默认) / `recipes` / `ingredients` / `taste_tags` / `cooking_tags`。

返回 `data.result.{recipes[], ingredients[], taste_tags[], cooking_tags[]}`，适合首页搜索框与智能联想。

### 其余筛选端点

```
GET api_filter.php?act=filter_ingredients&main_category=1001&keyword=鸡蛋&page=1
GET api_filter.php?act=ingredient_recipes&ingredient_id=1&page=1&limit=10
```

---

## 二、api_discover.php — 发现页随机数据

```
GET api_discover.php?total=30                                  # 自动分配比例
GET api_discover.php?recipe=8&ingredient=5&category=4&tag=6&nutrition=4&meal_time=3
GET api_discover.php?total=30&_refresh=1                       # 强制刷新去重记录
GET api_discover.php?total=8&exclude_recipe_ids=32674,32675    # 排除客户端已显示的菜品
```

**核心特性**

- **IP 去重**：同一客户端多次请求不返回重复数据（记录已返回 ID）
- **自动重置**：30 分钟后重置去重记录
- **客户端排除（2026-09-10 v1.3.0）**：`exclude_recipe_ids` 等参数把客户端已显示内容传给服务端 NOT IN 排除，与 IP 去重池取并集——根治 IP 池过期/耗尽重置后随机数据与已显示内容重叠（表现为"怎么刷新都是那几个"）
- **混合分类**：菜谱分类 60% + 食材分类 40%

**客户端排除参数（v1.3.0）**

| 参数 | 示例 | 说明 |
|------|------|------|
| exclude_recipe_ids | `32674,32675,33001` | 已显示菜品 log_ID，逗号分隔，上限 250 个 |
| exclude_ingredient_ids | `12,35` | 已显示食材 id，同上 |
| exclude_category_ids | `23,45` | 已显示分类 cate_ID，同上 |
| exclude_tag_ids | `101,102` | 已显示标签 tag_ID，同上 |
| exclude_nutrition_names | `蛋白质,脂肪` | 已显示营养名称，逗号分隔，上限 50 个 |

> 各类型排除独立生效；全部仅保留正整数/非空名称（服务端防注入清洗）。

**total 自动分配比例**：recipe 25% / ingredient 15% / category 15% / tag 20% / nutrition 15% / meal_time 10%

**返回结构**

| 字段 | 说明 |
|------|------|
| recipes[] | 随机菜品（id/title/cover/category/rating 摘要/views） |
| ingredients[] | 随机食材（id/name/category/allergen/intro 截取100字） |
| categories[] | 混合分类，含 `type`(recipe/ingredient)、`recipe_count`、`ingredient_count`、`count`、`parent_name`（可显示"中国菜 > 家常菜"） |
| tags[] | 标签（id/name/type(taste/cooking)/count 实际使用次数） |
| nutrition_types[] | 营养成分类型 |
| meal_times[] | 用餐时段 |
| meta.counts | 各类型实际数量 |

> 适用：首页/发现页瀑布流、下拉刷新加载。服务端耗时 ~1s（IP 去重+6 类随机查询），客户端建议配合本地缓存。

---

## 三、api_what_to_eat.php — 今天吃什么

| act | 功能 |
|-----|------|
| filter_steps | 获取可用筛选选项与菜谱数量（逐步筛选引导） |
| filter_apply | 应用筛选条件，返回随机菜谱（count=1 即"随机推荐一个"） |
| detail | 菜谱详情，**支持三种查询方式**（独有能力） |

### 筛选步骤

```
GET api_what_to_eat.php?act=filter_steps&category=13
```

### 应用筛选 / 随机推荐

```
GET api_what_to_eat.php?act=filter_apply&category=13&tag=2&count=5
GET api_what_to_eat.php?act=filter_apply&count=1          # 随机推荐一个
```

| 参数 | 说明 |
|------|------|
| category | 分类 ID，多个逗号分隔 |
| tag | 标签 ID，多个逗号分隔 |
| count | 返回数量，默认 5，最大 20 |

### 多方式查详情（独有能力）

```
GET api_what_to_eat.php?act=detail&id=32892            # 按 ID
GET api_what_to_eat.php?act=detail&code=CP032892       # 按菜谱编码（二维码/语音搜索场景）
GET api_what_to_eat.php?act=detail&title=鸡丁&fuzzy=1  # 按标题模糊匹配
```

> 设计背景（源自归档设计文档）：原始设计含 `act=random/smart/config` 与营养区间筛选（`nutrition=calories:200-500,protein:high`），实际实现收敛为 filter_steps/filter_apply/detail 三个端点，营养筛选由 `api_filter.php?act=filter_recipes` 的 nutrition_* 参数承担。