Files

Developer 8d27c67d3a api实现

2026-04-09 08:54:36 +08:00

16 KiB

Raw Blame History

🍳 Mom Kitchen API 集成开发计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将 Flutter App 从 mock 数据切换到真实后端 API，实现菜谱浏览、信息流推荐、用户互动、偏好设置等完整功能

Architecture: 采用 Repository 模式，API 层 → Repository 层 → Controller 层 → UI 层。现有 ApiService (Dio) 作为 HTTP 基础层，新建各业务 Repository 封装 API 调用，Controller 通过 Repository 获取数据驱动 UI

Tech Stack: Flutter + GetX + Dio + Dio Cache Interceptor + Connectivity Plus

API Base URL: http://eat.wktyl.com/api

一、API 接口清单

🔵 核心业务接口（App 必须集成）

#	文件	作用	关键操作	优先级
1	`api.php`	菜谱静态接口（只读）	`list` 列表、`detail` 详情、`full` 完整、`search` 搜索、`categories` 分类、`tags` 标签、`stats` 统计、`ingredients` 食材列表、`ingredient_detail` 食材详情、`query` 高级查询、`filter` 字段过滤	P1
2	`api_unified.php`	统一输出接口	`list`/`detail`/`search`/`hot`，支持 `type=recipe` 和 `type=ingredient`，字段格式对齐	P1
3	`api_action.php`	动态接口（写操作）	`like` 点赞/取消、`recommend` 推荐/取消（IP限制30次/天）、`view` 增加浏览量、`ip_status` IP状态	P1
4	`api_feed.php`	信息流接口	`recommend` 推荐流（热门+最新+随机混合）、`latest` 最新、`hot` 热门、`personal` 个性化（MDHW算法）、`prefetch` 预加载	P1
5	`api_preference.php`	用户偏好接口	`get` 获取偏好、`add_tag`/`remove_tag` 偏好标签、`add_category`/`remove_category` 偏好分类、`add_allergen`/`remove_allergen` 屏蔽过敏原、`allergens` 过敏原列表、`clear` 清除	P1

🟡 辅助功能接口（增强体验）

#	文件	作用	关键操作	优先级
6	`api_hot.php`	热门统计接口	`hot` 综合热门、`today` 今日热门、`month` 本月热门、`all` 累计热门，按浏览量/点赞/推荐排行	P2
7	`api_online.php`	在线人数统计	`heartbeat` 心跳（30秒轮询）、`stats` 在线统计、`platform` 平台分布、`page` 页面分布、`timeline` 时间线	P3

🔴 运维/调试接口（开发阶段使用）

#	文件	作用	关键操作	优先级
8	`api_request_stats.php`	请求量统计	`increment` 计数、`stats` 总计、`today` 今日、`api` 各接口、`hourly` 按小时	P4
9	`cache_manage.php`	缓存管理	`stats` 统计、`clean` 清理过期、`clear` 清除缓存	P4
10	`diagnose.php`	数据库诊断	HTML 页面，检查数据库连接/表结构/索引	P4

📄 文档文件

#	文件	作用
11	`doc/API_DOC.md`	API 总文档
12	`doc/API_STATIC.md`	静态接口文档
13	`doc/API_DYNAMIC.md`	动态接口文档
14	`doc/API_使用文档.md`	"今天吃什么"接口使用文档
15	`doc/RECOMMEND_ALGORITHM.md`	MDHW 推荐算法文档
16	`doc/WHAT_TO_EAT_DESIGN.md`	"今天吃什么"功能设计
17	`doc/WHAT_TO_EAT_PLAN.md`	"今天吃什么"开发计划
18	`doc/APP_GUIDE.md`	App 功能接入指南
19	`doc/RESPONSE_FORMAT.md`	响应格式说明
20	`doc/PERFORMANCE_REPORT.md`	性能报告

二、API 接口详细说明

2.1 api.php — 菜谱静态接口

地址： GET /api/api.php?act=xxx

操作	参数	说明
`list`	`page`, `limit`, `cate_id`, `tag_id`	菜谱列表（分页）
`detail`	`id`	菜谱详情
`full`	`id`	菜谱完整信息（含食材、营养）
`search`	`keyword`	搜索菜谱
`categories`	-	分类列表
`tags`	-	标签列表
`stats`	-	站点统计
`ingredients`	`page`, `limit`	食材列表
`ingredient_detail`	`id`	食材详情
`query`	多种筛选参数	高级查询
`filter`	`fields`	字段过滤

通用参数：

_refresh=1 — 强制刷新缓存
_stale=1 — Stale 模式（高并发）
_format=json|gzip|msgpack — 响应格式

2.2 api_unified.php — 统一输出接口

地址： GET /api/api_unified.php?act=xxx&type=recipe|ingredient

操作	参数	说明
`list`	`type`, `page`, `limit`	统一列表
`detail`	`type`, `id`	统一详情
`search`	`type`, `keyword`	统一搜索
`hot`	`type`	统一热门

字段对齐： recipe 和 ingredient 输出格式统一，便于前端统一渲染

2.3 api_action.php — 动态接口

地址： GET /api/api_action.php?act=xxx

操作	参数	说明
`like`	`type=recipe\|ingredient`, `id`, `action=like\|unlike`	点赞/取消
`recommend`	`type`, `id`, `action=recommend\|unrecommend`, `score`(0-5)	推荐/取消（IP限制30次/天）
`view`	`type`, `id`, `count`(1-100)	增加浏览量
`ip_status`	-	获取IP推荐限制状态

IP限制： 每个 IP 每天可推荐 30 次，点赞无限制

2.4 api_feed.php — 信息流接口

地址： GET /api/api_feed.php?act=xxx

操作	参数	说明
`recommend`	`page`, `limit`	推荐流（热门+最新+随机混合）
`latest`	`page`, `limit`	最新发布
`hot`	`page`, `limit`	热门排行
`personal`	`user_id`, `page`, `limit`, `_debug=1`	个性化推荐（MDHW算法）
`prefetch`	`pages`, `user_id`	预加载多页

MDHW算法评分维度：

管理员权重：置顶分类 +50、推荐分类 +30
用户偏好：偏好分类 +25、偏好标签 +30/个、浏览历史 +5/次(上限20)
热门数据：浏览量 +1/100次(上限20)、点赞 +2/个(上限15)、推荐 +3/个(上限15)
时间衰减：1天内 +15、7天内 +10、30天内 +5

2.5 api_preference.php — 用户偏好接口

地址： GET /api/api_preference.php?act=xxx

操作	参数	说明
`get`	`user_id`	获取用户偏好
`set`	`user_id`, `preferred_tags`, `preferred_categories`, `blocked_allergens`	批量设置偏好
`add_tag`	`user_id`, `tag_id`	添加偏好标签
`remove_tag`	`user_id`, `tag_id`	移除偏好标签
`add_category`	`user_id`, `category_id`	添加偏好分类
`remove_category`	`user_id`, `category_id`	移除偏好分类
`add_allergen`	`user_id`, `allergen_type`	屏蔽过敏原
`remove_allergen`	`user_id`, `allergen_type`	取消屏蔽过敏原
`allergens`	-	获取过敏原类型列表
`clear`	`user_id`	清除所有偏好

过敏原类型： nuts(坚果)、seafood(海鲜)、dairy(乳制品)、eggs(蛋类)、grains(谷物)、beans(豆类)、meat(肉类)、fruits(水果)、vegetables(蔬菜)、mushrooms(菌类)、seasonings(调味品)、other(其他)

2.6 api_hot.php — 热门统计

地址： GET /api/api_hot.php?act=xxx

操作	说明
`hot`	综合热门排行
`today`	今日热门
`month`	本月热门
`all`	累计热门

支持按浏览量、点赞数、推荐数排行

2.7 api_online.php — 在线统计

地址： GET /api/api_online.php?act=xxx

操作	参数	说明
`heartbeat`	`user_id`, `platform`, `page`	心跳上报（30秒一次）
`stats`	-	在线人数统计
`platform`	-	平台分布
`page`	-	页面分布
`timeline`	-	时间线统计
`detail`	-	详细统计

三、开发阶段规划

阶段一：基础设施搭建（P1）✅ 已完成

目标： 配置 API 基础连接，创建数据模型和 Repository 层

任务清单：

1.1 修改 api_service.dart 的 baseUrl 为 http://eat.wktyl.com/api
1.2 创建 api_response.dart 通用响应模型（code/message/data/_query_time）
1.3 扩展 api_exception.dart 支持 429(限流) 错误码
1.4 创建 recipe_model.dart（对齐 api.php 返回字段：id/title/intro/category/tags/ingredients/nutrition/statistics）
1.5 创建 ingredient_model.dart（对齐 api_unified.php type=ingredient 返回字段）
1.6 创建 category_model.dart 和 tag_model.dart
1.7 创建 feed_item_model.dart（对齐 api_feed.php 返回字段）
1.8 创建 user_preference_model.dart（preferred_tags/preferred_categories/blocked_allergens）
1.9 创建 recipe_repository.dart（封装 api.php + api_unified.php 调用）
1.10 创建 feed_repository.dart（封装 api_feed.php 调用）
1.11 创建 action_repository.dart（封装 api_action.php 调用）
1.12 创建 preference_repository.dart（封装 api_preference.php 调用）

阶段二：核心数据接入（P1）✅ 已完成

目标： 将首页从 mock 数据切换到真实 API

任务清单：

2.1 改造 HomeController：注入 RecipeRepository，loadProducts() 改为调用 api.php?act=list
2.2 改造分类数据：调用 api.php?act=categories 获取真实分类列表
2.3 改造搜索功能：调用 api.php?act=search&keyword=xxx
2.4 改造 HomeCardCarousel：使用 RecipeModel 替代 ProductModel
2.5 改造 ProductCard 组件：适配 RecipeModel 字段（name→title, description→intro, price→statistics）
2.6 改造 CartController + CartPage：从购物车改为收藏夹，使用 RecipeModel
2.7 改造 HomeProductsTab + HomeRecommendedTab：使用 RecipeModel + filteredRecipes
2.8 验证：flutter analyze 无 error

阶段三：信息流 + 推荐系统（P1）✅ 已完成

目标： 接入信息流接口，实现推荐/最新/热门/个性化四种流

任务清单：

3.1 创建 FeedController：管理信息流状态（当前流类型、分页、加载更多）
3.2 实现推荐流：调用 api_feed.php?act=recommend
3.3 实现最新流：调用 api_feed.php?act=latest
3.4 实现热门流：调用 api_feed.php?act=hot
3.5 实现个性化推荐：调用 api_feed.php?act=personal&user_id=xxx
3.6 改造首页 Tab 栏：全部→推荐流，推荐→个性化流，新增最新/热门
3.7 添加下拉刷新 + 上拉加载更多
3.8 验证：信息流正常加载和切换

阶段四：互动功能（P1）✅ 已完成

目标： 实现点赞、推荐、浏览量上报

任务清单：

4.1 创建 ActionController：管理互动状态
4.2 实现点赞：调用 api_action.php?act=like，UI 同步点赞数
4.3 实现推荐：调用 api_action.php?act=recommend，处理 429 限流
4.4 实现浏览量上报：进入详情页时调用 api_action.php?act=view
4.5 IP 状态检查：调用 api_action.php?act=ip_status，显示剩余推荐次数
4.6 验证：互动功能正常，数据同步

阶段五：用户偏好系统（P1）✅ 已完成

目标： 实现偏好分类/标签选择和过敏原屏蔽

任务清单：

5.1 创建 PreferenceController：管理用户偏好状态
5.2 实现偏好分类管理：add_category / remove_category
5.3 实现偏好标签管理：add_tag / remove_tag
5.4 实现过敏原屏蔽：add_allergen / remove_allergen
5.5 获取过敏原类型列表：api_preference.php?act=allergens
5.6 新建偏好设置页面（iOS 风格）：分类选择、标签选择、过敏原开关
5.7 偏好与个性化推荐联动：设置偏好后影响 api_feed.php?act=personal 结果
5.8 验证：偏好设置生效，推荐结果变化

阶段六："今天吃什么"功能（P2）✅ 已完成

目标： 实现随机选择和智能推荐功能

参考文档： doc/WHAT_TO_EAT_DESIGN.md

任务清单：

6.1 创建 WhatToEatController：管理选择状态
6.2 实现随机选择：调用 api_what_to_eat.php?act=random（返回5个候选）
6.3 实现智能推荐：调用 api_what_to_eat.php?act=smart + 筛选参数
6.4 获取配置选项：调用 api_what_to_eat.php?act=config
6.5 实现子分类获取：act=subcategories&parent_id=xx
6.6 实现动态筛选：act=available_filters
6.7 新建"今天吃什么"页面（iOS 风格转盘动画）
6.8 实现转盘动画：快(2s)/中(5s)/慢(8s)/跳过(0s)
6.9 实现结果卡片：封面+简介+食材+营养摘要
6.10 验证：随机和智能推荐正常工作

阶段七：热门排行 + 在线统计（P3）✅ 已完成

目标： 实现热门排行和在线人数统计

任务清单：

7.1 创建 HotController：管理排行时间段切换
7.2 实现今日/本月/累计排行：调用 api_hot.php?act=today|month|total
7.3 新建热门排行页面（iOS 风格）：排行榜、奖牌、时间段切换
7.4 创建 OnlineController：管理心跳和在线数据
7.5 实现心跳上报：调用 api_online.php?act=heartbeat（30秒间隔）
7.6 实现在线统计：调用 api_online.php?act=stats
7.7 验证：排行和在线统计正常

阶段八：缓存优化 + 离线支持（P3）✅ 已完成

目标： 优化网络性能，支持离线浏览

任务清单：

8.1 升级缓存存储：MemCacheStore → FileCacheStore（持久化文件缓存）
8.2 缓存策略优化：CachePolicy.request + 离线时自动读取缓存
8.3 离线支持：ConnectivityService 监听网络状态变化
8.4 离线横幅：OfflineBanner 组件，网络断开时显示提示
8.5 网络恢复提示：自动弹出 SnackBar 通知
8.6 GET 请求支持 forceRefresh 参数强制刷新

四、依赖关系图

阶段一（基础设施）
  ↓
阶段二（核心数据）→ 阶段三（信息流+推荐）
  ↓                      ↓
阶段四（互动功能）    阶段五（用户偏好）
  ↓                      ↓
阶段六（今天吃什么）←──────┘
  ↓
阶段七（热门+在线）
  ↓
阶段八（缓存优化）

五、API 通用参数说明

参数	类型	说明	默认值
`_refresh`	int	强制刷新缓存（1=刷新）	0
`_stale`	int	Stale 模式，允许返回过期缓存	0
`_format`	string	响应格式：json/gzip/msgpack	json
`_debug`	int	调试模式（仅 api_feed.php）	0
`_pretty`	int	格式化 JSON 输出	0

六、API 响应通用结构

{
  "code": 200,
  "message": "success",
  "data": { ... },
  "_query_time": "15ms",
  "_cached": true,
  "_cache_age": 120
}

错误码：

错误码	说明
200	成功
400	参数错误
404	未找到数据
429	请求过于频繁（IP推荐限制）
500	服务器错误

七、现有项目改造对照表

现有文件	当前状态	改造方向
`api_service.dart`	baseUrl = `https://api.example.com`	→ `http://eat.wktyl.com/api`
`home_controller.dart`	`ProductModel.mock()` 6条硬编码	→ `RecipeRepository.fetchList()`
`product_model.dart`	name/price/description/imageUrl/emoji	→ `RecipeModel` 对齐 API 字段
`cart_controller.dart`	`addToCart` 仅本地操作	→ 增加 `view` 上报
`home_card_carousel.dart`	使用 `ProductModel`	→ 使用 `RecipeModel`
`product_card.dart`	显示 name/price/+按钮	→ 显示 title/statistics/❤️/⭐/+按钮

八、版本规划

版本	阶段	说明
v0.17.0	阶段一	基础设施：baseUrl + 模型 + Repository
v0.18.0	阶段二	核心数据接入：首页真实数据
v0.19.0	阶段三	信息流 + 推荐系统
v0.20.0	阶段四	互动功能：点赞/推荐/浏览
v0.21.0	阶段五	用户偏好系统
v0.22.0	阶段六	"今天吃什么"功能
v0.23.0	阶段七	热门排行 + 在线统计
v0.24.0	阶段八	缓存优化 + 离线支持

16 KiB Raw Blame History Unescape Escape

🍳 Mom Kitchen API 集成开发计划

一、API 接口清单

🔵 核心业务接口（App 必须集成）

🟡 辅助功能接口（增强体验）

🔴 运维/调试接口（开发阶段使用）

📄 文档文件

二、API 接口详细说明

2.1 api.php — 菜谱静态接口

2.2 api_unified.php — 统一输出接口

2.3 api_action.php — 动态接口

2.4 api_feed.php — 信息流接口

2.5 api_preference.php — 用户偏好接口

2.6 api_hot.php — 热门统计

2.7 api_online.php — 在线统计

三、开发阶段规划

阶段一：基础设施搭建（P1）✅ 已完成

阶段二：核心数据接入（P1）✅ 已完成

阶段三：信息流 + 推荐系统（P1）✅ 已完成

阶段四：互动功能（P1）✅ 已完成

阶段五：用户偏好系统（P1）✅ 已完成

阶段六："今天吃什么"功能（P2）✅ 已完成

阶段七：热门排行 + 在线统计（P3）✅ 已完成

阶段八：缓存优化 + 离线支持（P3）✅ 已完成

四、依赖关系图

五、API 通用参数说明

六、API 响应通用结构

七、现有项目改造对照表

八、版本规划

16 KiB

Raw Blame History