kitchen/docs/dev/UNFINISHED_FEATURES.md

📋 未完成功能清单

文档创建: 2026-04-09
最后更新: 2026-04-11
数据来源 说明: 记录所有未完成的功能任务，跟踪开发进度
优先级说明: P1=核心功能 P2=重要功能 P3=增强功能
优先级值1-5: 5=最高优先级（多次提及自动提升）

---

📊 总体进度

阶段	总任务	已完成	未完成	完成率
三：热量追踪+营养分析	7	7	0	100% ✅
四：购物清单	5	5	0	100% ✅
十三：AI+规划高级功能	4	4	0	100% ✅
十四：接口能力挖掘	8	0	8	0% 🟢
十五：后端接口增强	6	0	6	0% 🔴
十六：用户体验优化+Bug 修复	7	7	0	100% ✅
十七：紧急Bug修复	14	14	0	100% ✅
十九：综合Bug修复+功能增强	18	18	0	100% ✅
二十：用户体验优化+交互增强	7	7	0	100% ✅
二十一：菜谱详情页功能增强	1	1	0	100% ✅
二十二：Picid功能Bug修复	2	2	0	100% ✅
合计	152	136	16	89%

---

五、开发阶段

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

目标：搭建 Hive 本地数据库 + 数据模型 + 持久化收藏

六、页面导航规划

发现页

## 八、开发优先级矩阵

| 功能 | 用户价值 | 技术难度 | 依赖关系 | 优先级 |
|------|---------|---------|---------|--------|
| Hive 本地数据库 | ⭐⭐⭐⭐⭐ | ⭐⭐ | 无 | P1-0 |
| 收藏持久化 | ⭐⭐⭐⭐ | ⭐ | 数据库 | P1-1 |
| 饮食日记 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 数据库 | P1-2 |
| 热量追踪 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 饮食日记 | P1-3 |
| 营养分析报告 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 饮食日记+fl_chart | P1-4 |
| 购物清单 | ⭐⭐⭐⭐ | ⭐⭐ | 数据库 | P2-1 |
| 烹饪计时器 | ⭐⭐⭐ | ⭐⭐ | 无 | P2-2 |
| 用量换算 | ⭐⭐⭐ | ⭐ | 无 | P2-3 |
| 过敏原检测 | ⭐⭐⭐ | ⭐⭐ | 偏好数据 | P2-4 |
| 烹饪笔记 | ⭐⭐ | ⭐⭐ | 数据库 | P3-1 |
| 用餐提醒 | ⭐⭐ | ⭐⭐⭐ | 本地通知 | P3-2 |
| BMI 计算器 | ⭐⭐ | ⭐ | 无 | P3-3 |
| 份量缩放 | ⭐⭐ | ⭐ | 无 | P3-4 |

---

## 九、验收标准


## 🟡 阶段五：增强功能（P2/P3）

**目标**：烹饪计时器 + 用量换算 + 过敏原检测 + 烹饪笔记 + 用餐提醒 + BMI + 份量缩放  
**前置依赖**：各功能独立，无强依赖  


---

## 🔵 阶段八：API v2.0.0 迁移 + Bug修复（P0/P1）

**目标**：迁移到 API v2.0.0 合并接口，修复用户反馈的8个严重Bug  


---

## 🔴 阶段九：架构修复+核心Bug（P0/P1）

**目标**：修复架构违规和核心功能缺失  
**发现时间**：2026-04-10（flutter analyze 全面扫描 + 项目分析）  


## 🟡 阶段十：代码质量提升（P1/P2）

---

## 🟢 阶段十一：烹饪模式+营养仪表盘（P1）

**目标**：实现核心增强功能，提升应用价值  
**前置依赖**：阶段九完成  

---

## 🟢 阶段十二：社交+通知增强（P2）

**目标**：增加社交分享和通知提醒功能  
**前置依赖**：阶段十一完成  
**关键阻塞**：12.1 需 `share_plus`，12.2 需 `flutter_local_notifications`

| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
|------|------|---------|--------|------|------|
| 12.1 | 📱 分享菜谱 | `lib/src/pages/home/recipe_detail_page.dart` | P2 | ✅ 已完成 | 分享按钮+生成菜谱文本+调用share_plus |
| 12.2 | 🔔 烹饪提醒通知 | `lib/src/services/notification_service.dart` | P2 | ❌ 未实现 | 定时提醒烹饪步骤，与计时器联动 |
| 12.3 | 🔍 搜索建议/热词 | `lib/src/controllers/search_controller.dart` | P2 | ✅ 已完成 | 从API获取热门标签，替代硬编码热词，保留fallback |
| 12.4 | 📸 拍照记录 | `lib/src/pages/tools/cooking_note_page.dart` | P3 | ❌ 未实现 | 烹饪笔记支持拍照上传，记录成品 |

### 功能详情

#### 12.1 分享菜谱
- **入口**：菜谱详情页 → 分享按钮
- **功能**：
  - 生成菜谱卡片图片（封面+标题+食材摘要）
  - 调用 iOS Share Sheet / Android 分享面板
  - 支持保存到相册
- **技术方案**：`screenshot` + `share_plus`

#### 12.2 烹饪提醒通知
- **入口**：烹饪模式 → 设置提醒
- **功能**：
  - 烹饪步骤到达时发送本地通知
  - 计时器完成时通知
  - 支持自定义提醒时间
- **技术方案**：`flutter_local_notifications`

#### 12.3 搜索建议/热词
- **入口**：搜索页搜索栏
- **功能**：
  - 空搜索框时展示热门搜索词
  - 输入时自动补全建议
  - 热门搜索词从 API 获取
- **技术方案**：`RecipeRepository.fetchTags()` 获取热词



## 🔵 阶段十三：AI+规划高级功能（P3）

**目标**：实现智能化和规划类高级功能  
**前置依赖**：阶段十二完成  
**关键阻塞**：13.1 需 AI API，13.2 需日历组件

| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
|------|------|---------|--------|------|------|
| 13.1 | AI 菜谱推荐 | `lib/src/services/recommendation_service.dart` | P3 | ✅ 已实现 | 基于口味偏好+浏览历史，智能推荐菜谱 |
| 13.2 | 每周菜单规划 | `lib/src/pages/tools/weekly_menu_planner_page.dart` | P3 | ✅ 已实现 | 日历视图规划一周饮食，自动生成购物清单 |
| 13.3 | 食材用量换算增强 | `lib/src/pages/tools/serving_scaler_page.dart` | P3 | ✅ 已实现 | 添加单位换算Tab(重量/容量/计数)+常用换算表 |
| 13.4 | 就寝提醒 | `lib/src/pages/profile/bedtime_reminder_page.dart` | P3 | ✅ 已实现 | 根据饮食时间推荐健康作息 |

### 功能详情

#### 13.1 AI 菜谱推荐
- **入口**：首页"为你推荐"Tab
- **功能**：
  - 基于用户口味偏好（PreferenceController）
  - 基于浏览历史（FootprintsPage 数据）
  - 基于收藏记录（FavoritesController）
  - 推荐相似菜谱
- **技术方案**：调用后端推荐 API 或本地协同过滤算法

#### 13.2 每周菜单规划
- **入口**：工具页 → "📅 每周菜单"
- **功能**：
  - 日历视图选择日期
  - 每日早/中/晚三餐分配菜谱
  - 自动汇总生成购物清单
  - 支持拖拽调整
- **技术方案**：自定义日历组件 + Hive 持久化

#### 13.3 食材用量换算增强
- **入口**：工具页 → 份量缩放
- **功能**：
  - 支持克/千克/磅/盎司互转
  - 支持毫升/升/杯/汤匙互转
  - 常用食材密度表
- **技术方案**：扩展 `serving_scaler_page.dart`，添加单位换算 Tab

#### 13.4 就寝提醒
- **入口**：设置 → 健康提醒
- **功能**：
  - 根据晚餐时间推荐就寝时间
  - 睡前不宜进食提醒
  - 与营养追踪联动
- **技术方案**：`flutter_local_notifications` + 健康算法

### 验收标准
- [x] "为你推荐"展示个性化推荐菜谱
- [x] 每周菜单可规划三餐并生成购物清单
- [x] 份量缩放支持多种单位换算
- [x] 就寝提醒根据饮食时间智能推荐

---

## 🟢 阶段十四：接口能力挖掘（P1/P2）

**目标**：利用已有API接口能力，实现App端未开发的功能  

## 🔴 阶段十六：用户体验优化+Bug修复（P0/P1）


### 技术要点

- **数据文件**：`http://eat.wktyl.com/api/assets/eating_times.json`（34种时段）
- **功能**：
  - 🌅 早餐推荐（7-10点）
  - 🍱 午餐推荐（11-14点）
  - 🌙 晚餐推荐（17-20点）
  - 📅 每日菜单规划（早中晚餐）

#### 14.2 营养分析增强
- **接口支持**：`api.php?act=full&id=xxx` 返回 `nutrition` 字段
- **数据文件**：`http://eat.wktyl.com/api/assets/nutrition_types.json`（31种营养成分）
- **功能**：
  - 📊 营养成分详情展示（维生素/矿物质/宏量营养素）
  - 🎯 每日营养目标追踪
  - 🏋️ 健身餐推荐（高蛋白/低碳水）
  - 📈 营养趋势分析图表

#### 14.3 过敏原警示增强
- **接口支持**：`api.php?act=full&id=xxx` 返回 `allergens` 字段
- **数据文件**：`http://eat.wktyl.com/api/assets/gmy.json`（585种过敏原数据）
- **功能**：
  - ⚠️ 菜谱详情页过敏原警示
  - 🚫 自动过滤含过敏原菜谱
  - 🔄 食材替代建议
  - 📋 过敏原报告生成

#### 14.4 点赞/推荐系统
- **接口支持**：
  - `api_action.php?act=like&type=recipe&id=1&action=like/unlike`
  - `api_action.php?act=recommend&type=recipe&id=1&score=5`
- **功能**：
  - 👍 点赞/取消点赞
  - ⭐ 五星评分
  - 📊 用户评价统计
  - 🏆 推荐排行榜

#### 14.5 社交分享
- **接口支持**：`api_what_to_eat.php?act=detail&code=CP032892`（code字段生成分享链接）
- **功能**：
  - 🔗 分享链接生成（`https://eat.wktyl.com/recipe/CP032892`）
  - 📱 二维码海报
  - 📊 热度标签展示（🔥爆款/📈热门/❤️受欢迎）
  - 👥 社交平台分享



## 🔴 阶段十五：后端接口增强（P1/P2）

**目标**：新增后端接口，实现高级功能  
**前置依赖**：后端开发配合  
**关键阻塞**：需要后端新增接口  
**优先级说明**：🔴 红色表示需要后端支持

| 序号 | 任务 | 建议接口 | 优先级 | 状态 | 说明 |
|------|------|---------|--------|------|------|
| 15.1 | 👤 用户注册登录 | `api_user.php?act=register/login` | P1 | ❌ 未实现 | 用户账号体系 |
| 15.2 | 💾 收藏云端同步 | `api_favorite.php?act=add/remove/list` | P1 | ❌ 未实现 | 收藏数据云端存储 |
| 15.3 | 💬 评论系统 | `api_comment.php?act=list/add/delete` | P2 | ❌ 未实现 | 菜谱评论功能 |
| 15.4 | 🔔 消息推送 | `api_message.php?act=list/read` | P2 | ❌ 未实现 | 站内信+推送通知 |
| 15.5 | 📜 浏览历史同步 | `api_history.php?act=add/list` | P2 | ❌ 未实现 | 浏览历史云端存储 |
| 15.6 | 📝 菜谱上传 | `api_recipe.php?act=add/edit/delete` | P2 | ❌ 未实现 | 用户菜谱上传/编辑 |

- **功能**：
  - 💬 发表评论
  - 👍 评论点赞
  - 📝 评论回复
  - 🔔 评论通知

#### 15.4 消息推送
- **现状**：❌ 无推送接口
- **建议接口**：
 
- **功能**：
  - 📬 站内信
  - 🔔 推送通知
  - 📢 系统公告
  - 💬 评论提醒

#### 15.5 浏览历史同步
- **现状**：⚠️ 仅本地存储
- **建议接口**：
  ```text
  POST api_history.php?act=add
  { "user_id": "xxx", "recipe_id": 123 }

  GET api_history.php?act=list&user_id=xxx&page=1

• 功能：
  • ☁️ 浏览历史云端存储
  • 🔄 多设备同步
  • 📊 浏览统计
  • 🧹 历史清理

15.6 菜谱上传

• 现状：❌ 无上传接口
• 建议接口：

• 功能：
  • 📝 用户菜谱上传
  • ✏️ 菜谱编辑
  • 🗑️ 菜谱删除
  • 📊 菜谱审核

开发优先级

优先级	功能	说明
P1	用户注册登录	核心功能，其他功能依赖用户体系
P1	收藏云端同步	用户数据安全，多设备同步
P2	评论系统	增加互动，提升活跃度
P2	消息推送	用户触达，提升留存
P2	浏览历史同步	用户体验，多设备同步
P2	菜谱上传	UGC内容，丰富平台

验收标准

• 用户可注册/登录
• 收藏数据云端同步
• 菜谱可评论
• 收到系统通知
• 浏览历史云端同步
• 用户可上传菜谱

---

📎 软件特性功能汇总

以下功能已开发完成或开发中，从历史版本号归档而来 2026-04-11 重新审核：修正不实标记，区分"已完成""部分完成""未完成"

功能	状态	首次版本	说明
热量追踪+营养分析	⚠️ 部分完成	v0.3x	环形图+柱状图+目标设置 ✅；饼图+折线图 ❌
购物清单	✅ 已完成	v0.4x	添加/删除/勾选/分类 ✅；从菜谱添加 ✅（菜谱详情页"购物"按钮）
烹饪计时器	✅ 已完成	v0.5x	多步骤倒计时
用量换算	✅ 已完成	v0.5x	常用单位换算
过敏原检测	✅ 已完成	v0.5x	标记含过敏原菜谱 ✅；AllergenChecker完整实现
烹饪笔记	✅ 已完成	v0.5x	按菜谱关联笔记 ✅；CookingNotePage完整实现
BMI 计算器	✅ 已完成	v0.5x	含健康建议
份量缩放	✅ 已完成	v0.5x	按比例调整 ✅；支持从菜谱导入 ✅（菜谱详情页"缩放"按钮）
主页体验优化	✅ 已完成	v0.6x	骨架屏+动画+搜索+详情页
今天吃什么增强	✅ 已完成	v0.7x	分类/标签/过敏原三维筛选
API v2.0.0 迁移	✅ 已完成	v0.8x	合并接口+8个Bug修复
动态主题	✅ 已完成	v0.6x	多主题色+暗色模式+卡片滑动方向
Liquid Glass 风格	✅ 已完成	v0.6x	底栏+搜索栏+分段控件+卡片
收藏管理	✅ 已完成	v0.8x	编辑/排序/分类/跳转详情
静态分析清理	✅ 已完成	v0.52	1071 个 info，0 error/warning
工具中心	✅ 已完成	v0.9x	工具入口Bar+分类筛选+使用频率统计
过敏原检查工具	✅ 已完成	v0.9x	食材过敏原查询与分类浏览（API数据源）
用餐时段推荐	✅ 已完成	v0.9x	根据时间推荐早中晚餐菜谱
每周菜单规划	✅ 已完成	v0.88x	一周三餐UI ✅；数据持久化 ✅（Hive）；从菜谱添加 ✅
食材详情查询	✅ 已完成	v0.9x	食材列表+搜索 ✅；营养信息+选购指南+存储提示 ✅
统一Controller Binding	✅ 已完成	v0.63	AppBinding全局管理+移除重复注册
AI菜谱推荐	✅ 已完成	v0.88x	基于用户偏好+浏览历史+收藏记录的智能推荐 ✅
就寝提醒	✅ 已完成	v0.88x	智能推荐就寝时间+睡前进食提醒 ✅

---

🛠️ 工具中心开发记录

2026-04-10 开发完成

已实现工具列表

工具名称	路由	是否联网	完成度	说明
⏱️ 烹饪计时器	/tools/timer	❌ 离线	✅ 完整	多步骤倒计时
📏 用量换算	/tools/converter	❌ 离线	✅ 完整	常用单位换算
🧮 BMI 计算器	/tools/bmi	❌ 离线	✅ 完整	含健康建议
⚖️ 份量缩放	/tools/scaler	❌ 离线	⚠️ 部分	按比例调整 ✅；食材硬编码，不支持从菜谱导入 ❌
🥜 过敏原检查	/tools/allergen	✅ 联网	✅ 完整	食材过敏原查询
🍽️ 用餐时段推荐	/tools/meal-time	✅ 联网	✅ 完整	根据时间推荐菜谱
📅 每周菜单规划	/tools/planner	❌ 离线	⚠️ 部分	UI ✅；数据不持久化 ❌；从收藏添加 ❌
🥕 食材详情查询	/tools/ingredient	✅ 联网	⚠️ 部分	列表+搜索 ✅；营养详情+选购指南 ❌
📊 营养中心	/tools/nutrition	✅ 联网	⚠️ 部分	环形图+目标 ✅；饼图+折线图 ❌
📈 热门统计	/tools/stats	✅ 联网	✅ 完整	热门菜谱排行

技术实现

1. 工具数据模型 (tool_item_model.dart)

   • ToolItem: 工具项数据结构
   • ToolCategory: 工具分类枚举
   • ToolRegistry: 工具注册表

2. 工具控制器 (tools_controller.dart)

   • 工具列表管理
   • 使用频率统计（SharedPreferences）
   • 搜索与分类过滤
   • 常用工具推荐

3. 工具中心页面 (tools_center_page.dart)

   • 搜索栏
   • 分类标签筛选
   • 工具网格布局（一行两个）
   • 联网状态指示器（绿点/红点）

4. 收藏页工具入口Bar

   • 显示常用工具快捷入口
   • 更多工具入口按钮
   • 使用频率排序

文件清单

lib/src/
├── models/tools/
│   └── tool_item_model.dart          # 工具数据模型
├── controllers/tools/
│   └── tools_controller.dart         # 工具控制器
└── pages/tools/
    ├── tools_center_page.dart        # 工具中心页面
    ├── allergen_checker_page.dart    # 过敏原检查
    ├── meal_time_recommend_page.dart # 用餐时段推荐
    ├── meal_planner_page.dart        # 每周菜单规划
    └── ingredient_detail_page.dart   # 食材详情查询

---

🔴 阶段十七：紧急Bug修复（P0/P1）

目标：修复用户反馈的多个严重问题，提升应用稳定性
发现时间：2026-04-11（用户反馈）
关键阻塞：无
优先级：P0=最高优先级（影响用户使用的严重问题）

序号	任务	产出文件	优先级	状态	说明
17.1	🔍 搜索详情卡死修复	lib/src/pages/search/search_page.dart	P0	✅ 已完成	使用Get.toNamed命名路由跳转
17.2	❤️ 收藏页更多按钮GetX报错	lib/src/pages/favorites/favorites_page.dart	P0	✅ 已完成	使用命名路由跳转工具中心
17.3	🌙 夜间模式字体颜色优化	lib/src/config/design_tokens.dart	P1	✅ 已完成	调整DarkDesignTokens文字颜色值
17.4	📊 营养中心报告GetX报错	lib/src/bindings/feature_binding.dart	P1	✅ 已完成	Controller改为permanent注册
17.5	🎲 今天吃什么筛选优化	lib/src/pages/what_to_eat/what_to_eat_page.dart	P1	✅ 已完成	修复筛选逻辑和随机选择
17.6	🏠 首页加载骨架屏优化	lib/src/pages/home_page.dart	P1	✅ 已完成	添加骨架屏组件和超时保护
17.7	📋 购物清单UI优化	lib/src/pages/shopping/shopping_list_page.dart	P2	✅ 已完成	增大图标尺寸，优化布局
17.8	⚙️ 主题设置iOS风格重构	lib/src/pages/settings/personalization_page.dart	P2	✅ 已完成	重构为iOS设计风格
17.9	🏷️ 口味偏好数据修复	lib/src/pages/settings/preference_page.dart	P1	✅ 已完成	添加错误处理和默认数据
17.10	👁️ 菜谱详情浏览量统计	lib/src/pages/recipe/recipe_detail_page.dart	P1	✅ 已完成	增加浏览量并显示
17.11	🔥 热门排行今日数据修复	lib/src/pages/hot/hot_page.dart	P1	✅ 已完成	修复API参数传递
17.12	🍽️ 用餐时段推荐卡死修复	lib/src/pages/tools/meal_time_recommend_page.dart	P0	✅ 已完成	添加超时处理和默认数据
17.13	🛠️ 工具中心跳转分裂修复	lib/src/controllers/tools/tools_controller.dart	P0	✅ 已完成	使用Get.toNamed命名路由
17.14	📝 文档更新	docs/dev/UNFINISHED_FEATURES.md	P2	✅ 已完成	记录修复内容

问题详情

17.1 搜索详情卡死

• 现象：搜索结果点击详情后应用卡死闪退
• 原因：使用Get.to()直接跳转Widget，未正确注册Binding
• 方案：改用Get.toNamed('/recipe-detail', arguments: recipeId)

17.2 收藏页更多按钮报错

• 现象：点击"更多"按钮后GetX报错
• 原因：直接跳转ToolsCenterPage未通过路由系统
• 方案：使用Get.toNamed('/tools')

17.3 夜间模式字体颜色

• 现象：夜间模式大部分字体灰色看不清
• 原因：DarkDesignTokens文字颜色值过暗
• 方案：调整text2为#EBEBF5，text3为#8E8E93

17.4 营养中心报告报错

• 现象：点击报告按钮GetX报错
• 原因：MealRecordController未正确注册
• 方案：在FeatureBinding中使用permanent: true注册

17.5 今天吃什么筛选

• 现象：分类筛选不支持动态筛选，随机选择无结果
• 原因：筛选逻辑未正确触发，空结果无提示
• 方案：优化筛选触发机制，添加空结果Toast提示

17.6 首页加载优化

• 现象：加载时间超过8秒，无骨架屏
• 原因：无超时保护，无骨架屏组件
• 方案：添加12秒超时保护，创建SkeletonLoader组件

17.7 购物清单UI

• 现象：图标太小，列表分裂，容易误触
• 原因：图标尺寸过小，间距不合理
• 方案：增大图标尺寸，优化布局间距

17.8 主题设置风格

• 现象：不符合iOS设计风格
• 原因：使用Material风格组件
• 方案：重构为Cupertino风格，符合iOS设计规范

17.9 口味偏好数据

• 现象：显示"暂无分类数据"
• 原因：API返回数据未正确处理
• 方案：添加错误处理和默认数据展示

17.10 菜谱浏览量

• 现象：详情页无浏览量显示
• 原因：未调用浏览量统计接口
• 方案：加载时调用viewnums接口，显示浏览次数

17.11 热门排行今日数据

• 现象：无今日数据
• 原因：API参数传递错误
• 方案：修复period参数为'today'

17.12 用餐时段推荐卡死

• 现象：页面卡死黑屏
• 原因：网络请求无超时处理，无错误状态
• 方案：添加8秒超时，添加默认用餐时段数据

17.13 工具中心跳转分裂

• 现象：跳转页面出现分裂感，左边工具中心右边目标页面
• 原因：路由跳转方式问题
• 方案：统一使用Get.toNamed命名路由

验收标准

• 搜索结果点击详情正常跳转
• 收藏页更多按钮正常跳转
• 夜间模式字体清晰可见
• 营养中心报告按钮正常跳转
• 今天吃什么支持动态筛选
• 首页加载有骨架屏
• 购物清单图标易于点击
• 主题设置符合iOS风格
• 口味偏好正常显示数据
• 菜谱详情显示浏览量
• 热门排行显示今日数据
• 用餐时段推荐正常加载
• 工具中心跳转无分裂感

---

<EFBFBD> 阶段十八：浑水摸鱼功能补全（P1/P2）— ✅ 已完成

目标：修复标记为"已完成"但实际未完成或仅部分完成的功能
发现时间：2026-04-11（代码审核）
完成时间：2026-04-11
关键阻塞：无
优先级：P1=影响用户功能完整性

问题清单

序号	任务	产出文件	优先级	状态	说明
18.1	📝 烹饪笔记页面	lib/src/pages/tools/cooking_note_page.dart	P1	✅ 已完成	创建完整页面，支持按菜谱关联、增删改查
18.2	🥜 过敏原检测实现	lib/src/services/allergen_checker.dart	P1	✅ 已完成	接入用户偏好设置，实现关键词匹配检测逻辑
18.3	⚖️ 份量缩放-从菜谱导入	lib/src/pages/tools/serving_scaler_page.dart	P2	✅ 已完成	支持从菜谱详情页跳转时携带食材数据
18.4	📅 菜单规划-数据持久化	lib/src/pages/tools/meal_planner_page.dart	P1	✅ 已完成	接入SharedPreferences持久化，按周保存/加载
18.5	📅 菜单规划-从收藏添加	lib/src/pages/tools/meal_planner_page.dart	P2	✅ 已完成	实现收藏列表选择弹窗，从FavoritesController获取数据
18.6	🛒 购物清单-从菜谱添加入口	lib/src/pages/profile/shopping_list_page.dart	P1	✅ 已完成	菜谱详情页已有"购物"按钮，调用addItemsFromRecipe
18.7	🥕 食材详情-营养信息	lib/src/pages/tools/ingredient_detail_page.dart	P2	✅ 已完成	创建60+食材营养数据库，展示热量/蛋白质/脂肪/碳水/纤维+关键营养素+时令+选购技巧+储存方法
18.8	📊 营养中心-饼图+折线图	lib/src/pages/profile/nutrition/nutrition_report_page.dart	P2	✅ 已完成	新增MealTypePieChart餐次分布饼图，现有折线图+营养素饼图+餐次饼图完整

实施记录

第一批（P1 — 核心功能缺失）

1. 18.1 烹饪笔记页面 — 创建CookingNotePage，支持添加/编辑/删除笔记，从菜谱详情页跳转
2. 18.2 过敏原检测实现 — AllergenChecker接入PreferenceController，11类过敏原关键词匹配
3. 18.4 菜单规划持久化 — 使用StorageService+SharedPreferences按周保存/加载，自动清理过期数据
4. 18.6 购物清单从菜谱添加 — 已确认recipe_detail_page.dart中已有_addToShoppingList方法

第二批（P2 — 功能增强） 5. 18.3 份量缩放从菜谱导入 — ServingScalerPage支持ingredients+defaultServings参数，路由传递数据 6. 18.5 菜单规划从收藏添加 — _addFromFavorites方法，CupertinoActionSheet选择收藏菜谱 7. 18.7 食材详情营养信息 — 创建IngredientNutritionDb（60+食材），页面展示营养概览/占比/关键营养素/时令/选购/储存 8. 18.8 营养中心饼图+折线图 — 新增MealTypePieChart组件（早/午/晚/加餐热量分布），集成到营养报告页

新增文件

• lib/src/services/data/ingredient_nutrition_db.dart — 食材营养数据库（60+种常见食材）

验收标准

• 烹饪笔记：可从菜谱详情进入，支持添加/编辑/删除笔记
• 过敏原检测：用户设置过敏原后，菜谱详情页显示过敏原警告
• 菜单规划：退出后重新打开数据不丢失
• 购物清单：菜谱详情页可一键添加食材到购物清单
• 份量缩放：支持从菜谱详情页导入真实食材列表
• 菜单规划：可从收藏列表选择菜谱添加到规划
• 食材详情：显示营养成分数据和选购建议
• 营养报告：包含饼图（营养素占比+餐次分布）和折线图（热量趋势）

---

🔴 阶段十九：综合Bug修复+功能增强（P0/P1/P2）— 🔄 进行中

目标：修复用户反馈的多个问题，增强现有功能
开始时间：2026-04-11
关键阻塞：无
优先级：P0=崩溃 P1=功能缺陷 P2=体验优化

问题清单

序号	任务	产出文件	优先级	状态	说明
19.1	🛠️ 发现页更多按钮卡死	lib/src/pages/tools/tools_center_page.dart	P0	✅ 已完成	添加ToolsController安全检查，防止未注册时崩溃
19.2	⏱️ 烹饪计时器常用预设	lib/src/pages/tools/cooking_timer_page.dart	P1	✅ 已完成	添加18种常用烹饪步骤快捷添加（煮鸡蛋/煮面条/炖汤等）
19.3	📋 菜谱详情显示全部数据	lib/src/pages/home/recipe_detail_page.dart	P1	✅ 已完成	显示浏览量/营养成分/分类/标签/过敏原/时间等全部字段，笔记icon横向滚动
19.4	🏷️ 口味偏好分类+标签修复	lib/src/models/user_preference_model.dart	P1	✅ 已完成	修复PreferenceCategory id字符串解析+children子分类+标签显示
19.5	🔥 热门排行数据修复	lib/src/repositories/hot_repository.dart	P1	✅ 已完成	添加fallback机制，period无数据时回退total
19.6	🛒 购物清单按钮增大	lib/src/pages/profile/shopping_list_page.dart	P2	✅ 已完成	勾选/删除按钮增大至44x44点击区域，icon增大至22
19.7	🔄 我的页面左右滑动	lib/src/pages/profile/profile_page.dart	P2	✅ 已完成	使用PageView替代条件渲染，支持手势滑动+SegmentedControl联动
19.8	📝 笔记保存后不显示	lib/src/pages/tools/cooking_note_page.dart	P1	✅ 已完成	修复异步保存未await+添加Obx响应式刷新
19.9	🌙 深色模式跟随系统	lib/src/services/ui/theme_service.dart	P1	✅ 已完成	添加DarkModeSource枚举，支持system/manual模式，监听系统亮度变化
19.10	📝 字体大小全局生效	lib/main.dart	P1	✅ 已完成	通过GetCupertinoApp.builder设置全局textScaleFactor
19.11	📱 底部Tab栏高度+安全区	lib/src/widgets/glass/glass_nav_bar.dart	P1	✅ 已完成	高度64→68，添加底部安全区域padding
19.12	🧊 白色区域遮住底部	lib/src/widgets/navigation_widgets.dart	P0	✅ 已完成	移除SafeArea(bottom:false)，GlassNavBar自行处理安全区域
19.13	📂 推荐分类层级导航	lib/src/pages/discover/category_browse_page.dart	P1	✅ 已完成	大类→小类→菜谱列表→详情，新建CategoryBrowsePage
19.14	🎲 今天吃什么GetX报错	lib/src/pages/discover/what_to_eat_page.dart	P0	✅ 已完成	控制器注册+加载优化+分类扁平化
19.15	🔍 搜索显示相似结果	lib/src/pages/home/search_page.dart	P2	✅ 已完成	无结果时提取关键词模糊搜索，显示相似推荐列表
19.16	⚙️ 设置功能全局生效	lib/src/widgets/navigation_widgets.dart	P1	🔄 进行中	底部栏样式已全局生效，动画/对话框等仍需逐项接入
19.17	📖 用餐时段推荐页	lib/src/pages/tools/eating_times_page.dart	P2	✅ 已完成	基于eating_times.json创建5类时段浏览+菜谱列表
19.18	🌐 网络请求优化	lib/src/services/api/api_service.dart	P1	✅ 已完成	增强日志+重试机制+统一离线检查+缓存解析修复

实施记录

19.1 发现页更多按钮卡死

• 问题：点击收藏页"更多"按钮跳转工具中心时，ToolsController未注册导致崩溃
• 方案：添加Get.isRegistered检查，未注册时显示友好错误页面和返回按钮

19.2 烹饪计时器常用预设

• 问题：添加步骤时需要手动输入名称和时长
• 方案：添加18种常用烹饪预设（煮鸡蛋10min、煮面条8min、炖汤45min等），点击自动填充

19.3 菜谱详情显示全部数据

• 问题：详情页只显示部分数据，笔记icon溢出屏幕
• 方案：添加statistics/tags/meta/categorizedIngredients/allergens等全部字段显示，笔记按钮改为横向滚动

19.4 口味偏好分类+标签修复

• 问题：API返回id为字符串但模型解析为int导致null，children未解析
• 方案：PreferenceCategory添加动态类型解析(_parseInt)，添加children字段和子分类显示

19.8 笔记保存后不显示

• 问题：addNote是异步方法但未await，setState在数据保存前执行
• 方案：await addNote后再setState，使用Obx包裹_buildBody实现响应式刷新

19.9 深色模式跟随系统

• 问题：深色模式只能手动切换，不支持跟随系统
• 方案：添加DarkModeSource枚举(system/manual)，main.dart添加WidgetsBindingObserver监听系统亮度变化

19.10 字体大小全局生效

• 问题：字体大小设置只在个性化设置页面可见
• 方案：通过GetCupertinoApp.builder包裹MediaQuery，设置全局textScaleFactor

19.12 白色区域遮住底部

• 问题：SafeArea(bottom:false)导致底部导航栏下方出现白色区域
• 方案：移除外层SafeArea，GlassNavBar自行通过MediaQuery.padding.bottom处理安全区域

19.13 推荐分类层级导航

• 问题：推荐Tab显示假数据
• 方案：创建CategoryBrowsePage，实现大类→小类→菜谱列表三级导航，CategoryModel添加children字段

待解决问题

• 设置功能全局生效：底部栏样式已接入，动画/对话框/消息气泡/卡片方向等仍需逐项接入各页面
• API扩展功能：参考API文档扩展更多接口能力（阶段十四/十五）

19.14 今天吃什么GetX报错

• 问题：页面跳转时控制器未注册，分类数据加载慢
• 方案：WhatToEatController在AppBinding注册，分类扁平化处理（食材1413子类限制20个），添加12秒超时

19.15 搜索显示相似结果

• 问题：搜索无结果时直接显示空白
• 方案：SearchController添加_searchSimilar方法，提取关键词子串+常见食材后缀进行模糊搜索，空结果视图显示相似推荐列表

19.17 用餐时段推荐页

• 问题：设置页需要基于eating_times.json扩展新功能
• 方案：创建EatingTimesPage，从API获取5类时段数据(standard/combined/frequency/method/other)，点击时段搜索菜谱，EatingTimeRecipesPage显示结果

19.18 网络请求优化

• 问题：ApiService日志拦截器无输出、无重试机制、post/put/delete重复代码
• 方案：增强日志拦截器(debugPrint请求/响应/错误)、添加_executeWithRetry(最多2次重试)、统一_executeWithOfflineCheck、修复_tryGetCache缓存数据jsonDecode

验收标准

• 发现页更多按钮正常跳转工具中心
• 烹饪计时器支持常用预设快速添加
• 菜谱详情显示全部API数据
• 口味偏好分类和标签正确解析
• 热门排行有fallback机制
• 购物清单按钮易于点击
• 我的页面支持左右滑动切换
• 笔记保存后立即显示
• 深色模式支持跟随系统
• 字体大小全局生效
• 底部Tab栏适配安全区域
• 白色区域不再遮住底部
• 推荐分类支持层级导航
• 今天吃什么正常加载
• 搜索无结果时显示相似推荐
• 用餐时段推荐页可浏览
• 网络请求有日志和重试

---

🟢 阶段二十：用户体验优化+交互增强（P0/P1/P2）— ✅ 已完成

目标：修复关键Bug，优化用户体验，增强交互功能
完成时间：2026-04-11
关键阻塞：无
优先级：P0=崩溃/闪退 P1=功能缺陷 P2=体验优化

问题清单

序号	任务	产出文件	优先级	状态	说明
20.1	🐛 笔记按钮闪退修复	cooking_note_page.dart	P0	✅ 已完成	安全Controller初始化，防止空指针异常
20.2	🚀 详情页骨架屏加载	recipe_detail_page.dart	P1	✅ 已完成	骨架屏+8秒超时保护+重试按钮
20.3	🔍 发现页推荐导航优化	discover_page.dart + category_browse_page.dart	P1	✅ 已完成	智能路由：子分类/直接菜谱列表/分类浏览
20.4	🖼️ 图片Invalid image data错误	recipe_image.dart	P0	✅ 已完成	图片格式验证（魔数检测）+自动Fallback
20.5	⚠️ 工具中心GetX警告+溢出	tools_center_page.dart	P1	✅ 已完成	StatefulWidget重构+动态padding计算
20.6	👆 发现页左右滑动功能	discover_page.dart	P2	✅ 已完成	Dismissible组件+快速操作菜单
20.7	🍽️ 用餐时段图片加载	meal_time_recommend_page.dart	P1	✅ 已完成	引入RecipeImage组件显示封面图

实施记录

20.1 笔记按钮闪退修复

• 问题：菜谱详情页点击"笔记"按钮导致应用卡死/闪退
• 根因：Controller未安全初始化，空指针异常
• 方案：
  • 实现安全的Controller获取模式（带错误状态）
  • 添加_controllerError标志位防止重复异常
  • 初始化时try-catch包裹，失败时显示友好提示
  • 所有Controller调用使用getter安全访问

20.2 详情页骨架屏加载

• 问题：菜谱详情页加载超过5秒，用户体验差
• 方案：
  • 实现完整骨架屏（封面图250px + 标题描述 + 统计数据4列 + 内容区域）
  • 8秒超时检测，超时后显示提示和重试按钮
  • ActionController/FavoritesController安全获取，所有操作添加try-catch

20.3 发现页推荐导航优化

• 问题1：点击推荐下的"菜谱"分类进入后不显示子类
• 问题2：点击"食材"分类显示"暂无菜谱"
• 方案：
  • 分类点击智能路由：有子分类→子类浏览 / 有菜谱数→直接加载 / 都没有→分类浏览
  • 新增loadRecipesDirectly参数支持直接加载模式
  • CategoryBrowsePage支持三种显示模式

20.4 图片Invalid image data错误

• 问题：多个页面显示"Exception: Invalid image data"
• 根因：API返回的非图片数据被当作图片解析
• 方案：
  • 新增_isValidImageData()方法验证图片格式
  • 支持JPEG/PNG/GIF/WebP/BMP格式检测（文件头魔数判断）
  • 无效数据自动触发Fallback链，尝试下一个URL
  • errorBuilder回调中增加自动重试机制

20.5 工具中心GetX警告+布局溢出

• 问题1：工具中心显示"use of a GetX has been detected"警告
• 问题2：底部溢出54像素
• 方案：
  • 重构为StatefulWidget，安全初始化Controller
  • GridView使用childAspectRatio: 0.85替代固定高度
  • padding动态计算底部安全区域

20.6 发现页左右滑动功能

• 新功能：热门列表支持左右滑动操作
• 交互设计：
  • 右滑（绿色背景）：查看详情
  • 左滑（蓝色背景）：快速操作菜单（收藏/查看详情/分享）
• 技术实现：Dismissible组件 + CupertinoActionSheet

20.7 用餐时段图片加载优化

• 问题：用餐时段页面显示图片错误
• 方案：引入RecipeImage组件显示菜谱封面图，自动享受Fallback链+错误处理

验收标准

• 笔记按钮点击正常，不闪退
• 详情页3秒内显示骨架屏，8秒内加载完成或显示重试
• 发现页推荐分类导航正确
• 图片加载失败时自动Fallback，不显示错误信息
• 工具中心无GetX警告，无布局溢出
• 发现页热门列表支持左右滑动
• 用餐时段页面正常显示菜谱封面图

---

🟢 阶段二十一：菜谱详情页功能增强（P2）— ✅ 已完成

目标：增强菜谱详情页功能，方便开发者调试和用户查看图片信息
完成时间：2026-04-11
关键阻塞：无
优先级：P2=功能增强

问题清单

序号	任务	产出文件	优先级	状态	说明
21.1	🖼️ Picid显示和复制功能	recipe_detail_page.dart	P2	✅ 已完成	在作者卡片下方显示图片信息卡片

实施记录

21.1 Picid显示和复制功能

• 需求：在菜谱详情页用户名称下方显示图片信息和Picid
• 功能实现：
  • 新增图片信息卡片，显示在作者卡片下方
  • 显示Picid编号（可选中复制）
  • 显示图片链接（可选中复制）
  • 点击卡片一键复制Picid到剪贴板
  • 复制成功后显示Toast提示
• UI设计：
  • 卡片式设计，带主题色边框
  • 右上角显示"点击复制"提示标签
  • Picid使用等宽字体（monospace）高亮显示
  • 图片链接支持多行显示
• 技术细节：
  • 导入 flutter/services.dart 使用 Clipboard
  • 使用 SelectableText 支持文本选中
  • 无Picid时显示"无"，但仍显示图片链接

验收标准

• 菜谱详情页显示图片信息卡片
• Picid可选中复制
• 图片链接可选中复制
• 点击卡片一键复制Picid
• 复制成功显示Toast提示

---

🟢 阶段二十二：Picid功能Bug修复（P0）— ✅ 已完成

目标：修复Picid显示为0和点击复制卡死闪退的问题
完成时间：2026-04-11
关键阻塞：无
优先级：P0=崩溃/闪退

问题清单

序号	任务	产出文件	优先级	状态	说明
22.1	🐛 Picid显示为0	recipe_detail_page.dart	P0	✅ 已完成	添加有效性检查，无效时显示"无"
22.2	🐛 点击复制卡死闪退	recipe_detail_page.dart	P0	✅ 已完成	安全Toast显示+异常捕获

实施记录

22.1 Picid显示为0的问题

• 问题：所有菜谱的Picid都显示为0
• 根因：API返回的pic_id字段可能不存在或为null，_parseInt返回默认值0
• 方案：
  • 添加有效性检查：hasValidPicId = picId != null && picId > 0
  • 无效Picid时显示"无"，不显示0
  • 无有效Picid时图片链接显示"暂无图片链接"
  • 添加调试日志输出picId实际值

22.2 点击复制卡死闪退

• 问题：点击Picid卡片复制时应用卡死闪退
• 根因：ToastService.show可能因ThemeService未注册而崩溃
• 方案：
  • 新增 _showCopyToast() 方法安全显示Toast
  • 添加mounted检查防止Widget已销毁
  • Clipboard.setData包裹try-catch防止异常
  • 失败时显示友好提示而非崩溃

验收标准

• Picid为0或null时显示"无"
• 点击复制不卡死不闪退
• 复制成功显示Toast提示
• 复制失败显示友好提示