api实现

2026-04-09 08:54:36 +08:00
parent 2eaf317705
commit 8d27c67d3a
319 changed files with 70169 additions and 4677 deletions
--- a/docs/api/doc/API_DOC.md
+++ b/docs/api/doc/API_DOC.md
@@ -0,0 +1,441 @@
+# 🍳 菜谱API接口文档
+
+> 版本: v1.7.0  
+> 更新日期: 2025-04-08  
+> 基础地址: `http://eat.wktyl.com/api/`
+
+---
+
+## 📚 文档索引
+
+| 文档 | 说明 | 文件 |
+|-----|------|------|
+| [📖 静态接口文档](API_STATIC.md) | 只读接口：列表、详情、搜索、统计、查询 | api.php |
+| [📖 动态接口文档](API_DYNAMIC.md) | 写操作：点赞、推荐、浏览量 | api_action.php |
+| [📖 今天吃什么接口](#-今天吃什么接口-api_what_to_eatphp) | 智能推荐、随机选择、筛选过滤 | api_what_to_eat.php |
+
+---
+
+## 📋 快速导航
+
+### 静态接口 (api.php)
+
+| 接口 | 说明 | 示例 |
+|-----|------|------|
+| list | 菜谱列表 | `?act=list&page=1` |
+| detail | 菜谱详情 | `?act=detail&id=1` |
+| ingredients | 食材列表 | `?act=ingredients` |
+| ingredient_detail | 食材详情 | `?act=ingredient_detail&id=1` |
+| search | 搜索 | `?act=search&keyword=鸡蛋` |
+| categories | 分类列表 | `?act=categories` |
+| tags | 标签列表 | `?act=tags` |
+| stats | 统计数据 | `?act=stats` |
+| query | 高级查询 | `?act=query&module=recipe&field=log_Title&value=鸡蛋&operator=like` |
+| filter | 字段筛选 | `?act=filter&module=recipe&field=log_CateID` |
+
+### 全面统计 (stats_full.php)
+
+| 参数 | 说明 | 示例 |
+|-----|------|------|
+| layer=basic | 基础统计 | `stats_full.php` |
+| layer=hot | 热门统计 | `stats_full.php?layer=hot` |
+| layer=detail | 详细统计 | `stats_full.php?layer=detail` |
+| module=recipe | 菜谱统计 | `stats_full.php?module=recipe` |
+
+### 动态接口 (api_action.php)
+
+| 接口 | 说明 | 示例 |
+|-----|------|------|
+| like | 点赞/取消点赞 | `?act=like&type=recipe&id=1&action=like` |
+| recommend | 推荐/取消推荐 | `?act=recommend&type=recipe&id=1&action=recommend&score=5` |
+| view | 增加浏览量 | `?act=view&type=recipe&id=1` |
+
+### 今天吃什么接口 (api_what_to_eat.php)
+
+| 接口 | 说明 | 示例 |
+|-----|------|------|
+| random | 随机选择 | `?act=random` |
+| smart | 智能推荐 | `?act=smart&include_categories=12,13` |
+| config | 获取配置 | `?act=config` |
+| subcategories | 获取子分类 | `?act=subcategories&parent_id=12` |
+| like | 点赞 | `?act=like&id=1` |
+| recommend | 推荐 | `?act=recommend&id=1` |
+| view | 增加浏览量 | `?act=view&id=1` |
+
+---
+
+## 🎲 今天吃什么接口 (api_what_to_eat.php)
+
+### 基础信息
+
+- **文件**: `api_what_to_eat.php`
+- **功能**: 智能推荐菜谱、随机选择、筛选过滤
+- **版本**: v1.0.0
+
+### 接口列表
+
+#### 1. 获取配置 (config)
+
+获取筛选所需的配置选项，包括分类、标签、过敏原等。
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=config
+```
+
+**返回**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "categories": [
+      {
+        "id": 12,
+        "name": "中国菜",
+        "count": 100,
+        "parent_id": 11,
+        "parent_name": "菜谱"
+      }
+    ],
+    "tags": {
+      "taste": [
+        {"id": 1, "name": "咸鲜味"},
+        {"id": 2, "name": "原本味"}
+      ],
+      "craft": [
+        {"id": 48, "name": "煮"},
+        {"id": 50, "name": "炒"}
+      ]
+    },
+    "allergen_types": [
+      {"type": "seafood", "name": "海鲜", "icon": "🦐"},
+      {"type": "nuts", "name": "坚果", "icon": "🥜"}
+    ]
+  }
+}
+```
+
+#### 2. 随机选择 (random)
+
+随机返回一个菜谱。
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=random
+```
+
+**返回**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "candidates": [...],
+    "candidates_count": 1,
+    "best_match_count": 1
+  }
+}
+```
+
+#### 3. 智能推荐 (smart)
+
+根据筛选条件返回5个候选菜谱。
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=smart
+```
+
+**参数**
+
+| 参数 | 类型 | 说明 |
+|-----|------|------|
+| exclude_allergens | string | 排除的过敏原，逗号分隔 |
+| exclude_categories | string | 排除的分类ID，逗号分隔 |
+| exclude_tags | string | 排除的标签ID，逗号分隔 |
+| include_categories | string | 包含的分类ID，逗号分隔 |
+| include_tags | string | 包含的标签ID，逗号分隔 |
+
+**示例**
+
+```
+# 筛选中国菜，排除海鲜过敏原
+GET /api/api_what_to_eat.php?act=smart&include_categories=12&exclude_allergens=seafood
+
+# 筛选咸鲜口味，炒菜工艺
+GET /api/api_what_to_eat.php?act=smart&include_tags=1,50
+```
+
+**返回**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "candidates": [
+      {
+        "id": 123,
+        "title": "红烧肉",
+        "cover": "http://...",
+        "intro": "经典家常菜...",
+        "category": {"id": 12, "name": "中国菜"},
+        "tags": [{"id": 1, "name": "咸鲜味"}],
+        "ingredients": {
+          "main": [
+            {
+              "name": "五花肉",
+              "amount": "500克",
+              "detail": {
+                "id": 1,
+                "alias": ["三层肉"],
+                "suitable_crowd": ["一般人群"],
+                "unsuitable_crowd": ["湿热痰滞者"],
+                "intro": "五花肉即猪腹部的肉...",
+                "efficacy": "补肾养血，滋阴润燥...",
+                "allergen_type": [],
+                "category_names": ["畜肉类"]
+              }
+            }
+          ],
+          "auxiliary": [...],
+          "seasoning": [...]
+        },
+        "nutrition": {
+          "calories": "500kcal",
+          "protein": "25g",
+          "fat": "30g",
+          "all": [
+            {"name": "能量", "value": 500, "unit": "千卡"}
+          ]
+        },
+        "statistics": {
+          "view_count": 1000,
+          "like_count": 50,
+          "recommend_count": 20
+        }
+      }
+    ],
+    "candidates_count": 100,
+    "best_match_count": 20,
+    "total_shown": 5
+  }
+}
+```
+
+#### 4. 获取子分类 (subcategories)
+
+获取指定分类的子分类列表（随机返回20个）。
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=subcategories&parent_id=12
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|-----|------|------|------|
+| parent_id | int | 是 | 父分类ID |
+
+**返回**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "parent_id": 12,
+    "subcategories": [
+      {"id": 13, "name": "粤菜", "count": 50},
+      {"id": 14, "name": "鲁菜", "count": 30}
+    ],
+    "total": 20
+  }
+}
+```
+
+#### 5. 点赞 (like)
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=like&id=123
+```
+
+#### 6. 推荐 (recommend)
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=recommend&id=123
+```
+
+#### 7. 增加浏览量 (view)
+
+**请求**
+
+```
+GET /api/api_what_to_eat.php?act=view&id=123
+```
+
+---
+
+## 📱 App集成建议
+
+### 1. 接口调用流程
+
+```
+App启动 → 获取统计数据(stats_full.php?layer=hot) → 展示首页
+       → 获取菜谱列表(list) → 展示列表页
+       → 点击菜谱 → 获取详情(detail) + 增加浏览量(view)
+       → 用户点赞 → 调用点赞接口(like)
+```
+
+### 2. 缓存策略
+
+- 菜谱列表: 缓存3分钟
+- 菜谱详情: 缓存5分钟
+- 食材列表: 缓存5分钟
+- 分类/标签: 缓存10分钟
+- 统计数据: 缓存1分钟
+
+### 3. 图片处理
+
+- 封面图片建议使用CDN加速
+- 支持WebP格式减少流量
+- 列表页使用缩略图
+
+### 4. 错误处理
+
+- 网络超时: 提示用户检查网络
+- 404错误: 显示"内容不存在"
+- 400错误: 检查参数是否正确
+
+---
+
+## 🔧 高级查询示例
+
+### 精确查询
+
+```
+# 查询分类ID为11的菜谱
+GET /api/api.php?act=query&module=recipe&field=log_CateID&value=11
+```
+
+### 模糊查询
+
+```
+# 查询标题包含"鸡蛋"的菜谱
+GET /api/api.php?act=query&module=recipe&field=log_Title&value=鸡蛋&operator=like
+```
+
+### 按需输出字段
+
+```
+# 只返回id和标题
+GET /api/api.php?act=query&module=ingredient&field=name&value=番茄&operator=like&fields=ingredient_id,name
+```
+
+### 排序
+
+```
+# 按浏览量降序
+GET /api/api.php?act=query&module=recipe&field=log_Status&value=0&order=log_ViewNums&sort=desc
+```
+
+---
+
+## 📊 数据模型
+
+### Recipe (菜谱)
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| id | int | 菜谱ID |
+| title | string | 标题 |
+| content | string | 内容(HTML) |
+| intro | string | 简介 |
+| category_id | int | 分类ID |
+| category_name | string | 分类名称 |
+| tags | array | 标签列表 |
+| view_count | int | 浏览量 |
+| comment_count | int | 评论数 |
+| ingredients | array | 食材列表 |
+| cover | string | 封面图片URL |
+
+### Ingredient (食材)
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| id | int | 食材ID (范围: 1-1392) |
+| name | string | 名称 |
+| alias | array | 别名列表 |
+| view_count | int | 浏览量 |
+| like_count | int | 点赞数 |
+| recommend_count | int | 推荐数 |
+| related_recipes | array | 相关菜谱 |
+| allergen | array | 过敏源列表 (可选) |
+| allergen_type | array | 过敏源类型 (可选) |
+
+**过敏源类型说明**:
+
+| 类型 | 说明 |
+|-----|------|
+| 坚果类 | 核桃、杏仁、腰果、榛子、松子、开心果、栗子、花生 |
+| 海鲜类 | 鱼、虾、蟹、贝类、海参等 |
+| 乳制品 | 牛奶、奶粉、奶酪、奶油、酸奶、黄油等 |
+| 蛋类 | 鸡蛋、鸭蛋、鹅蛋、鸽蛋、鹌鹑蛋 |
+| 谷物类 | 小麦、面粉、面包、面条等 |
+| 豆类 | 黄豆、绿豆、红豆、蚕豆、豌豆等 |
+| 肉类 | 猪、牛、羊、鸡、鸭、鹅等 |
+| 水果类 | 桃、芒果、菠萝、草莓、猕猴桃等 |
+| 蔬菜类 | 芹菜、茄子、韭菜、香菜、姜、蒜等 |
+| 菌类 | 香菇、金针菇、木耳、银耳等 |
+
+---
+
+## 📝 更新日志
+
+### v1.6.0 (2025-04-08)
+- 🚀 性能优化 - JOIN查询、Gzip压缩、数据库索引
+- 📦 输出压缩 - 减少传输数据量
+- ⏱️ 缓存时间延长 - 提升缓存命中率
+- 🗂️ 数据库索引 - 11个关键索引加速查询
+
+### v1.5.0 (2025-04-08)
+- 🥜 新增过敏原字段 - allergen、allergen_type
+- 📊 过敏原分类 - 12种过敏源类型标识
+- 🔍 高级查询支持过敏原字段
+
+### v1.4.0 (2025-04-08)
+- 🔍 新增高级查询接口 - 精确查询和模糊查询
+- 📋 新增字段筛选接口 - 获取字段所有值
+- 📊 按需输出字段 - 只返回需要的字段
+- 📚 文档分离 - 静态接口和动态接口独立文档
+
+### v1.3.0 (2025-04-08)
+- 📊 全面统计接口 - 支持分层、模块化统计
+- 🔥 热门统计 - 热门菜谱、热门食材、排行榜
+- ⏰ 时间维度统计 - 今日、本月、累计数据
+
+### v1.2.0 (2025-04-08)
+- 🚀 新增文件缓存系统
+- ⚡ 静态接口支持缓存
+- 🧹 自动清理过期缓存
+
+### v1.1.0 (2025-04-08)
+- 🔀 API分离为静态接口和动态接口
+- 👍 新增点赞/取消点赞接口
+- ⭐ 新增推荐/取消推荐接口
+- 👁️ 新增浏览量增加接口
+
+### v1.0.0
+- 🎉 初始版本发布