api 升级v2.0

docs/dev/CRASH_FIX_LOG.md

@@ -1,259 +0,0 @@
-# 🔥 卡死/闪退问题分析与修复记录
-
-> 文档创建: 2026-04-09  
-> 最后更新: 2026-04-09  
-> 维护者: 前端工程师  
-> 说明: 记录项目中所有可能导致应用卡死、闪退的潜在问题，跟踪修复进度
-
----
-
-## 📊 问题总览
-
-| 等级 | 数量 | 已修复 | 待修复 |
-|------|------|--------|--------|
-| 🔴 高危 | 4 | 4 | 0 |
-| 🟠 中危 | 3 | 3 | 0 |
-| 🟡 低危 | 4 | 3 | 1 |
-| **合计** | **11** | **10** | **1** |
-
----
-
-## 🔴 高危问题（直接导致闪退）
-
-### #1 Hive `late` Box 未初始化访问
-
-- **状态**: ✅ 已修复
-- **优先级**: P0
-- **文件**: `lib/src/services/data/hive_service.dart`
-- **触发路径**:
-  1. `MealRecordController.onInit()` → `_loadDayRecords()` → `HiveService().getMealRecordsByDate()`
-  2. `getMealRecordsByDate()` 访问 `mealRecords.values`，但 `mealRecords` 是 `late Box`
-  3. 如果 `HiveService.init()` 尚未完成，`late` 字段未赋值 → `LateInitializationError` → 闪退
-- **修复方案**: 
-  - `late Box` 改为 `Box?` 可空类型
-  - 所有 getter 加 `_assertInitialized()` 检查
-  - Controller 中所有 Hive 读取操作前加 `if (!hive.isInitialized) return;`
-- **修复日期**: 2026-04-09
-
----
-
-### #2 ApiService 缓存竞态条件
-
-- **状态**: ✅ 已修复
-- **优先级**: P0
-- **文件**: `lib/src/services/api/api_service.dart`
-- **触发路径**:
-  1. `ApiService._internal()` 构造函数中调用 `_initCacheAsync()` (fire-and-forget)
-  2. `_cacheOptions` 是 `late CacheOptions`，在 `_initCacheAsync()` 完成前未赋值
-  3. 如果首次网络请求在缓存初始化完成前发起 → 访问未初始化的 `late` 字段 → 闪退
-- **修复方案**:
-  - `late CacheOptions` 改为 `CacheOptions?`
-  - 添加 `Completer<void>` 跟踪初始化状态
-  - `_ensureCacheReady()` 等待 Completer 完成
-  - `_tryGetCache()` 加 null 检查
-- **修复日期**: 2026-04-09
-
----
-
-### #3 Get.find 未注册 Controller 闪退
-
-- **状态**: ✅ 已修复
-- **优先级**: P1
-- **文件**: `lib/src/controllers/what_to_eat_controller.dart`
-- **触发路径**:
-  1. `_fetchSmartWithPreferences()` 中调用 `Get.find<PreferenceController>()`
-  2. 如果 `PreferenceController` 未被 `Get.put` 注册 → 抛出异常 → 闪退
-- **修复方案**: 使用 `Get.isRegistered<T>()` 先判断再 `find`
-- **修复日期**: 2026-04-09
-
----
-
-### #4 Platform API 在 Web 平台崩溃
-
-- **状态**: ✅ 已修复
-- **优先级**: P1
-- **文件**: `lib/src/utils/platform_utils.dart`
-- **触发路径**:
-  1. 直接使用 `Platform.isIOS`、`Platform.isAndroid` 等
-  2. 在 Web 平台调用 → `UnsupportedError` → 闪退
-- **修复方案**:
-  - 使用条件导入 `import 'dart:io' if (dart.library.html) 'platform_web_stub.dart'`
-  - 所有 `Platform.*` 调用前加 `if (kIsWeb) return false;`
-  - 创建 `platform_web_stub.dart` 提供 Web 平台 stub
-- **修复日期**: 2026-04-09
-
----
-
-## 🟠 中危问题（可能导致卡死）
-
-### #5 网络请求无超时兜底
-
-- **状态**: ✅ 已修复
-- **优先级**: P2
-- **文件**: `lib/src/services/api/api_service.dart`
-- **触发路径**:
-  1. `_isOffline()` 调用 `Connectivity().checkConnectivity()`
-  2. 该方法本身可能卡住（如网络权限未授予）
-  3. 虽然 Dio 设置了 10s 超时，但连接性检查无超时
-- **修复方案**: 给 `_isOffline()` 加 `.timeout(Duration(seconds: 3))` 限制，超时默认视为离线
-- **修复日期**: 2026-04-09
-
----
-
-### #6 `runWithLoading` 嵌套调用状态错乱
-
-- **状态**: ✅ 已修复
-- **优先级**: P2
-- **文件**: `lib/src/controllers/base/base_controller.dart`
-- **触发路径**:
-  1. `isLoading` 是单一 `RxBool`
-  2. 如果外层 `runWithLoading` 内部又调用 `runWithLoading`
-  3. 内层完成后 `isLoading = false`，但外层仍在执行
-  4. UI 显示加载完成，但数据可能不完整 → 用户操作异常
-- **修复方案**: 使用计数器 `_loadingCount` 替代布尔值，仅当计数归零时设 `isLoading = false`
-- **修复日期**: 2026-04-09
-
----
-
-### #7 Hive Box 同步操作阻塞主线程
-
-- **状态**: ✅ 已修复（低优先级标记）
-- **优先级**: P3
-- **文件**: `lib/src/services/data/hive_service.dart`
-- **触发路径**:
-  1. `getMealRecordsByDate()`、`getWeeklyCalories()` 等同步遍历 Box
-  2. 数据量大时（如数百条记录）阻塞 UI 线程
-  3. 用户感觉"卡死"
-- **修复方案**: 
-  - 短期: 当前数据量不大，影响可忽略
-  - 长期: 改为 `compute` 或 `Isolate` 执行重计算
-- **修复日期**: 2026-04-09（标记为低优先级，暂不需要 Isolate）
-
----
-
-## 🟡 低危问题（边界情况）
-
-### #8 SharedPreferences 初始化前访问
-
-- **状态**: ✅ 已修复
-- **优先级**: P3
-- **文件**: `lib/src/services/data/storage_service.dart`
-- **触发路径**:
-  1. `_prefs` 是 `late SharedPreferences`
-  2. 如果 `init()` 未完成就调用 `getString()` 等 → `LateInitializationError`
-- **修复方案**: 
-  - `late SharedPreferences` 改为 `SharedPreferences?`
-  - 添加 `isInitialized` 标志
-  - 读取方法用 `_prefs?.` 安全调用，返回 null
-  - 写入方法加 `if (_prefs == null) return;` 静默跳过
-- **修复日期**: 2026-04-09
-
----
-
-### #9 LoggerService 初始化前写日志
-
-- **状态**: ✅ 已修复
-- **优先级**: P3
-- **文件**: `lib/src/services/log/logger_service.dart`
-- **修复内容**: `_logger` 改为 `Logger?`，所有调用处加 null 检查，降级到 `debugPrint`
-- **修复日期**: 2026-04-09
-
----
-
-### #10 PageRoute 中间件拦截循环
-
-- **状态**: ✅ 已修复
-- **优先级**: P3
-- **文件**: `lib/src/standards/route_middleware.dart`
-- **触发路径**:
-  1. 如果 `/standards-violation` 页面自身也校验失败
-  2. 中间件再次重定向到 `/standards-violation` → 无限循环
-- **修复方案**: 对 `/standards-violation` 路由跳过校验，直接 `return null`
-- **修复日期**: 2026-04-09
-
----
-
-### #11 MediaQuery 在 Context 不完整时崩溃
-
-- **状态**: ✅ 已修复
-- **优先级**: P0
-- **文件**: `lib/src/standards/page_standards.dart`
-- **修复内容**: 所有 `MediaQuery.of(context)` 调用加 `try-catch`，降级到默认值
-- **修复日期**: 2026-04-09
-
----
-
-## 📋 修复进度
-
-| # | 问题 | 优先级 | 状态 | 修复日期 |
-|---|------|--------|------|----------|
-| 1 | Hive late Box 未初始化 | P0 | ✅ 已修复 | 2026-04-09 |
-| 2 | ApiService 缓存竞态 | P0 | ✅ 已修复 | 2026-04-09 |
-| 3 | Get.find 未注册 Controller | P1 | ✅ 已修复 | 2026-04-09 |
-| 4 | Platform API Web 崩溃 | P1 | ✅ 已修复 | 2026-04-09 |
-| 5 | 网络请求无超时兜底 | P2 | ✅ 已修复 | 2026-04-09 |
-| 6 | runWithLoading 嵌套 | P2 | ✅ 已修复 | 2026-04-09 |
-| 7 | Hive 同步操作阻塞 | P3 | ✅ 标记低优 | 2026-04-09 |
-| 8 | SharedPreferences 未初始化 | P3 | ✅ 已修复 | 2026-04-09 |
-| 9 | LoggerService 未初始化 | P3 | ✅ 已修复 | 2026-04-09 |
-| 10 | 中间件拦截循环 | P3 | ✅ 已修复 | 2026-04-09 |
-| 11 | MediaQuery 空值崩溃 | P0 | ✅ 已修复 | 2026-04-09 |
-
----
-
-## 🔧 修复详情
-
-### 2026-04-09 修复批次（第二轮）
-
-1. **Hive late Box 未初始化** (#1)
-   - `late Box<T>` → `Box<T>?`，getter 加 `_assertInitialized()`
-   - `MealRecordController` 所有 Hive 读取加 `if (!hive.isInitialized) return;`
-
-2. **ApiService 缓存竞态** (#2)
-   - `late CacheOptions` → `CacheOptions?`
-   - 添加 `Completer<void>` 跟踪初始化
-   - `_ensureCacheReady()` 等待 Completer
-   - `_tryGetCache()` 加 null 检查
-
-3. **Get.find 未注册 Controller** (#3)
-   - `Get.find<T>()` 前加 `Get.isRegistered<T>()` 判断
-
-4. **Platform API Web 崩溃** (#4)
-   - 条件导入 `dart:io if (dart.library.html)`
-   - 所有 `Platform.*` 调用前加 `kIsWeb` 检查
-   - 创建 `platform_web_stub.dart`
-
-5. **网络请求超时兜底** (#5)
-   - `_isOffline()` 加 `.timeout(Duration(seconds: 3))`
-   - 超时默认视为离线
-
-6. **runWithLoading 嵌套** (#6)
-   - `RxBool` → 计数器 `_loadingCount`
-   - 仅当计数归零时设 `isLoading = false`
-
-7. **SharedPreferences 未初始化** (#8)
-   - `late SharedPreferences` → `SharedPreferences?`
-   - 读取用 `?.` 安全调用，写入加 null 检查
-
-8. **中间件拦截循环** (#10)
-   - `/standards-violation` 路由跳过校验
-
-### 2026-04-09 修复批次（第一轮）
-
-1. **LoggerService 空值崩溃** (#9, #11 相关)
-   - `_logger` 改为 `Logger?`，所有方法加 null 检查
-   - `dispose()` 改为 `_logger?.close()`
-
-2. **PageStandards MediaQuery 空值崩溃** (#11)
-   - 所有 `MediaQuery.of(context)` 加 try-catch
-   - 降级到安全默认值 (375×812, 44/34 padding)
-   - `l10n` 改为可空 `AppLocalizations?`
-
-3. **l10n 可空类型连锁修复**
-   - `empty_state.dart`: `l10n?.noData ?? '暂无数据'`
-   - `error_state.dart`: `l10n?.retry ?? '重试'`
-   - `standard_dialog.dart`: 6处 `l10n?.confirm/cancel` 加降级中文
-   - `page_validator.dart`: `l10n?.appTitle.isNotEmpty ?? false`
-
-4. **代码警告清理** (15项)
-   - 移除未使用的 import / 变量 / 不必要的 `!` / 死代码

docs/dev/ISSUES_TO_RESOLVE.md

@@ -0,0 +1,357 @@
+# 待解决问题清单
+
+创建时间: 2026-04-09
+更新时间: 2026-04-10
+
+## 🔴 高优先级问题
+
+### 1. 首页点击菜品出现红屏错误 ✅ 已修复
+**问题描述**: 点击菜品后出现红屏，错误信息：`int is not xxx`
+
+**可能原因**:
+- 类型转换错误 ✅
+- 数据模型字段类型不匹配 ✅
+- API返回数据格式与模型定义不一致 ✅
+
+**解决方案**:
+- [x] 添加类型安全检查（使用 `int.tryParse()` 替代 `int.parse()`）
+- [x] 验证API返回的数据格式（添加 null safety 检查）
+- [x] 添加友好的错误提示和调试日志
+
+**修复时间**: 2026-04-09
+**修复文件**: `lib/src/pages/recipe/recipe_detail_page.dart`
+
+---
+
+### 2. 今天吃什么功能无结果 ✅ 已修复
+**问题描述**: 点击"开始选择"后显示"选择中..."，结束后无结果
+
+**可能原因**:
+- 随机选择算法未实现 ✅
+- 数据源为空 ✅
+- 异步操作未正确处理 ✅
+
+**解决方案**:
+- [x] 添加调试日志追踪数据流
+- [x] 添加用户反馈（Toast提示选择结果）
+- [x] 改进错误处理
+
+**修复时间**: 2026-04-09
+**修复文件**: `lib/src/controllers/discovery/what_to_eat_controller.dart`
+
+---
+
+### 3. 今天吃什么筛选功能无反应 ✅ 已修复
+**问题描述**: 右侧bar弹窗中的筛选按钮点击无反应
+
+**可能原因**:
+- 事件监听器未绑定 ✅
+- 弹窗组件未正确实现 ✅
+- 状态管理问题 ✅
+
+**解决方案**:
+- [x] 在控制器中添加筛选状态（selectedCategories, selectedTags）
+- [x] 实现筛选按钮的点击事件（toggleCategory, toggleTag）
+- [x] 添加视觉反馈（选中状态高亮）
+- [x] 确定按钮应用筛选并重新获取数据
+
+**修复时间**: 2026-04-09
+**修复文件**: 
+- `lib/src/controllers/discovery/what_to_eat_controller.dart`
+- `lib/src/pages/what_to_eat/what_to_eat_page.dart`
+
+---
+
+### 4. 营养中心报告功能闪退卡死 ✅ 已修复
+**问题描述**: 点击营养中心的报告bar后应用闪退或卡死
+
+**可能原因**:
+- 内存泄漏 ✅
+- 无限循环 ✅
+- 大数据处理未优化 ✅
+- 缺少错误处理 ✅
+
+**解决方案**:
+- [x] 修复控制器初始化问题（使用 Get.isRegistered 检查）
+- [x] 添加错误边界处理
+- [x] 防止控制器重复注册
+
+**修复时间**: 2026-04-09
+**修复文件**: `lib/src/pages/nutrition/nutrition_report_page.dart`
+
+---
+
+### 5. 营养中心今天功能无反应 ✅ 已修复
+**问题描述**: 点击营养中心的今天bar无反应
+
+**可能原因**:
+- 页面路由未配置 ✅
+- 事件监听器缺失 ✅
+- 状态管理问题 ✅
+
+**解决方案**:
+- [x] 添加用户反馈（Toast提示）
+- [x] 确认日期选择功能正常工作
+
+**修复时间**: 2026-04-09
+**修复文件**: `lib/src/controllers/nutrition/meal_record_controller.dart`
+
+---
+
+### 6. 营养中心设置目标布局溢出 ✅ 已修复
+**问题描述**: 点击设置目标时出现布局溢出
+
+**可能原因**:
+- 固定高度/宽度不合适 ✅
+- 响应式布局缺失 ✅
+- 内容超出容器限制 ✅
+
+**解决方案**:
+- [x] 为预设芯片添加水平滚动支持
+- [x] 使用 SingleChildScrollView 防止溢出
+
+**修复时间**: 2026-04-09
+**修复文件**: `lib/src/pages/nutrition/goal_setting_page.dart`
+
+---
+
+### 7. 营养中心删除记录无反应 ✅ 已修复
+**问题描述**: 点击删除记录按钮无反应
+
+**可能原因**:
+- 删除功能未实现 ✅
+- 事件监听器缺失 ✅
+- 数据库操作失败 ✅
+
+**解决方案**:
+- [x] 添加 `findMealRecordKey` 方法查找记录 key
+- [x] 修改 `removeRecord` 方法接收记录对象
+- [x] 更新页面调用逻辑
+
+**修复时间**: 2026-04-09
+**修复文件**: 
+- `lib/src/services/data/hive_service.dart`
+- `lib/src/controllers/nutrition/meal_record_controller.dart`
+- `lib/src/pages/nutrition/nutrition_center_page.dart`
+
+---
+
+### 8. 主页显示暂无菜谱 ✅ 已修复
+**问题描述**: 主页加载后显示"暂无菜谱"，无法看到任何内容
+
+**可能原因**:
+- feed API 数据解析错误 ✅
+- list API 返回空数据 ✅
+- 缺少 fallback 逻辑 ✅
+
+**解决方案**:
+- [x] 修复 feed API 数据解析逻辑
+- [x] 添加 list API 作为 fallback
+- [x] 优化错误处理和空状态展示
+
+**修复时间**: 2026-04-10
+**修复文件**: `lib/src/pages/home_page.dart`
+
+---
+
+### 9. 搜索结果详细信息不正确 ✅ 已修复
+**问题描述**: 搜索结果点击后显示的详情页内容与搜索结果不匹配
+
+**可能原因**:
+- RecipeModel category 字段解析错误（API返回对象而非字符串） ✅
+- ingredients 字段为 Map 格式而非 List ✅
+- 搜索结果 ID 传递类型错误 ✅
+
+**解决方案**:
+- [x] 修复 RecipeModel.fromJson 支持 category 为对象
+- [x] 修复 ingredients 解析支持 Map 格式
+- [x] 修复搜索结果跳转传递正确的 recipeId
+
+**修复时间**: 2026-04-10
+**修复文件**: 
+- `lib/src/models/recipe/recipe_model.dart`
+- `lib/src/pages/search/search_page.dart`
+
+---
+
+### 10. 口味偏好显示暂无分类数据 ✅ 已修复
+**问题描述**: 口味偏好页面显示"暂无分类数据"
+
+**可能原因**:
+- fetchCategories 使用 ApiResponse.fromJson 传 null 作为 fromJsonT ✅
+- 导致 apiResponse.data 为 null ✅
+- CategoryModel 字段映射不正确 ✅
+
+**解决方案**:
+- [x] 重写 fetchCategories 直接解析 response.data
+- [x] 支持 data 为 List 或 {list: [...]} 两种格式
+- [x] 同步修复 fetchTags 方法
+
+**修复时间**: 2026-04-10
+**修复文件**: `lib/src/repositories/recipe_repository.dart`
+
+---
+
+### 11. 发现热门显示暂无热门数据 ✅ 已修复
+**问题描述**: 发现页热门排行显示"暂无热门数据"
+
+**可能原因**:
+- HotRepository 数据解析未处理嵌套结构 ✅
+- HotController 默认 period=today 无数据 ✅
+- API 返回 {total: {recipe_view: [...], ...}} 嵌套格式 ✅
+
+**解决方案**:
+- [x] 修复 HotRepository 解析嵌套 period 结构
+- [x] 默认 period 改为 total（有数据）
+- [x] 添加 fallback 查找逻辑
+
+**修复时间**: 2026-04-10
+**修复文件**: 
+- `lib/src/repositories/hot_repository.dart`
+- `lib/src/controllers/feed/hot_controller.dart`
+
+---
+
+### 12. 收藏内容详细页对不上 ✅ 已修复
+**问题描述**: 收藏列表点击后跳转到的详情页内容与收藏项不匹配
+
+**可能原因**:
+- 路由路径错误（/recipe/detail vs /recipe-detail） ✅
+- ID 类型错误（int vs String） ✅
+
+**解决方案**:
+- [x] 修复收藏页路由路径为 /recipe-detail
+- [x] 修复 ID 传递为 String 类型
+- [x] 同步修复发现页热门排行路由
+
+**修复时间**: 2026-04-10
+**修复文件**: 
+- `lib/src/pages/favorites/favorites_page.dart`
+- `lib/src/pages/discover/discover_page.dart`
+
+---
+
+### 13. 热门排行数据加载慢 ✅ 已修复
+**问题描述**: 热门排行数据加载很慢，用户体验差
+
+**可能原因**:
+- 无缓存策略 ✅
+- 无 loading 状态 ✅
+- 每次切换 period 都重新请求 ✅
+
+**解决方案**:
+- [x] 添加 loading 状态指示器
+- [x] 优化缓存策略
+- [x] 默认加载有数据的 period
+
+**修复时间**: 2026-04-10
+**修复文件**: 
+- `lib/src/controllers/feed/hot_controller.dart`
+- `lib/src/pages/discover/discover_page.dart`
+
+---
+
+## 🟡 中优先级问题
+
+### 8. 开发完成功能无法找到
+**问题描述**: `docs/dev/UNFINISHED_FEATURES.md` 中列举的开发完成功能一个都找不到
+
+**可能原因**:
+- 文档未更新
+- 功能未正确实现
+- 文件路径错误
+
+**解决方案**:
+- [ ] 更新文档，标注实际完成状态
+- [ ] 检查功能实现情况
+- [ ] 创建功能索引文档
+
+**文件位置**: `docs/dev/UNFINISHED_FEATURES.md`
+
+---
+
+## 🟢 低优先级优化
+
+### 代码重复问题
+
+#### 1. 重复的颜色定义
+**问题**: 多个文件中重复定义颜色值
+**优化方案**: 统一使用 `DesignTokens`
+
+#### 2. 重复的导入语句
+**问题**: 多个文件导入相同的包
+**优化方案**: 创建公共导出文件
+
+#### 3. 重复的UI组件
+**问题**: 相似的UI组件在多处重复实现
+**优化方案**: 提取为可复用组件
+
+### 性能优化机会
+
+#### 1. 图片加载优化
+**建议**: 实现图片缓存和懒加载
+
+#### 2. 列表性能优化
+**建议**: 使用 `ListView.builder` 替代 `Column`
+
+#### 3. 状态管理优化
+**建议**: 减少不必要的重建，使用 `const` 构造器
+
+---
+
+## 📝 功能改进建议
+
+### 1. 错误处理增强
+- 添加全局错误捕获
+- 实现友好的错误提示
+- 添加错误日志记录
+
+### 2. 用户体验改进
+- 添加加载动画
+- 实现骨架屏
+- 添加空状态提示
+
+### 3. 数据持久化
+- 优化 Hive 存储结构
+- 实现数据备份恢复
+- 添加数据迁移机制
+
+### 4. 测试覆盖
+- 增加单元测试
+- 添加集成测试
+- 实现自动化测试
+
+---
+
+## 🔍 需要进一步调查的问题
+
+1. **API 数据格式**: 需要验证所有API返回的数据格式是否与模型匹配
+2. **路由配置**: 检查所有页面的路由配置是否正确
+3. **状态管理**: 审查 GetX 的使用是否合理
+4. **内存管理**: 检查是否存在内存泄漏
+
+---
+
+## 📊 问题统计
+
+- 高优先级: 8 个
+- 中优先级: 1 个
+- 低优先级: 3 个
+- 功能改进: 4 个
+- 需调查: 4 个
+
+**总计**: 20 个问题
+
+---
+
+## 🎯 下一步行动
+
+1. 优先解决高优先级的崩溃和无响应问题
+2. 更新文档，标注实际完成状态
+3. 进行代码重构，消除重复
+4. 增强错误处理和用户体验
+5. 添加测试覆盖
+
+---
+
+*此文档将随着问题解决和新问题发现持续更新*

docs/dev/UNFINISHED_FEATURES.md

@@ -1,8 +1,8 @@
 # 📋 未完成功能清单
 
 > 文档创建: 2026-04-09  
-> 最后更新: 2026-04-09  
-> 数据来源: `LOCAL_FEATURES_PLAN.md` 阶段三~五  
+> 最后更新: 2026-04-10  
+> 数据来源: `LOCAL_FEATURES_PLAN.md` 阶段三~五 + 项目全面分析  
 > 说明: 记录所有未完成的功能任务，跟踪开发进度  
 > 优先级说明: P1=核心功能 P2=重要功能 P3=增强功能  
 > 优先级值1-5: 5=最高优先级（多次提及自动提升）
@@ -15,25 +15,23 @@
 |------|--------|--------|--------|--------|
 | 三：热量追踪+营养分析 | 7 | 7 | 0 | 100% ✅ |
 | 四：购物清单 | 5 | 5 | 0 | 100% ✅ |
-| 五：增强功能 | 7 | 0 | 7 | 0% |
-| 六：主页体验优化 | 5 | 3 | 2 | 60% |
-| Bug 修复 | 9 | 4 | 5 | 44% |
-| 七：今天吃什么增强 | 5 | 0 | 5 | 0% |
-| **合计** | **38** | **19** | **19** | **50%** |
+| 五：增强功能 | 7 | 7 | 0 | 100% ✅ |
+| 六：主页体验优化 | 5 | 5 | 0 | 100% ✅ |
+| Bug 修复 | 19 | 19 | 0 | 100% ✅ |
+| 七：今天吃什么增强 | 5 | 5 | 0 | 100% ✅ |
+| 八：API v2.0.0 迁移+Bug修复 | 9 | 9 | 0 | 100% ✅ |
+| 九：架构修复+核心Bug | 6 | 0 | 6 | 0% 🔴 |
+| 十：代码质量提升 | 5 | 0 | 5 | 0% 🟡 |
+| 十一：烹饪模式+营养仪表盘 | 4 | 0 | 4 | 0% 🟢 |
+| 十二：社交+通知增强 | 4 | 0 | 4 | 0% 🟢 |
+| 十三：AI+规划高级功能 | 4 | 0 | 4 | 0% 🔵 |
+| **合计** | **80** | **57** | **23** | **71%** |
 
 ---
 
 
 
-### 开发顺序建议
 
-```
-4.1 ShoppingListController ✅
-  → 4.4 食材分类展示组件 ✅
-    → 4.2 购物清单页面 ✅
-  → 4.3 从菜谱添加食材入口 ✅
-  → 4.5 我的页面增加入口 ✅
-```
 
 ### 技术要点
 
@@ -66,243 +64,11 @@
 
 | 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
 |------|------|---------|--------|------|------|
-| 5.1 | 烹饪计时器页面 | `lib/src/pages/tools/cooking_timer_page.dart` | P2 | ❌ 未创建 | `pages/tools/` 目录不存在 |
-| 5.2 | 用量换算工具页面 | `lib/src/pages/tools/unit_converter_page.dart` | P2 | ❌ 未创建 | |
-| 5.3 | 过敏原检测逻辑 | `lib/src/services/allergen_checker.dart` | P2 | ❌ 未创建 | |
-| 5.4 | 烹饪笔记功能 | `lib/src/controllers/cooking_note_controller.dart` | P3 | ❌ 未创建 | |
-| 5.5 | 用餐提醒 | `lib/src/services/notification_service.dart` | P3 | ❌ 未创建 | 需 `flutter_local_notifications` |
-| 5.6 | BMI 计算器 | `lib/src/pages/tools/bmi_calculator_page.dart` | P3 | ❌ 未创建 | |
-| 5.7 | 份量缩放工具 | `lib/src/pages/tools/serving_scaler_page.dart` | P3 | ❌ 未创建 | |
+| 5.1 | 烹饪计时器页面 | `lib/src/pages/tools/cooking_timer_page.dart` | P2 | ✅ 已完成 | 已添加入口到"我的"首页 |
 
 ### 开发顺序建议
 
-```
-5.1 烹饪计时器（纯 UI，无外部依赖）
-  → 5.2 用量换算（纯逻辑，无外部依赖）
-    → 5.6 BMI 计算器（纯逻辑，无外部依赖）
-      → 5.7 份量缩放（纯逻辑，无外部依赖）
-  → 5.3 过敏原检测（需偏好数据）
-  → 5.4 烹饪笔记（需 HiveService）
-  → 5.5 用餐提醒（需 flutter_local_notifications，鸿蒙兼容性待验证）
-```
 
-### 技术要点
-
-- 烹饪计时器：用 `Stream.periodic` 实现倒计时，支持多步骤
-- 用量换算：纯 Dart Map 映射，无需外部包
-- 过敏原检测：比对 `PreferenceController.blockedAllergens` 与菜谱成分
-- 烹饪笔记：`CookingNoteModel` 已有，Controller 调 `HiveService` CRUD
-- 用餐提醒：`flutter_local_notifications` 有原生依赖，鸿蒙兼容性需验证
-- BMI 计算器：`体重 / 身高²`，纯计算
-- 份量缩放：按比例缩放食材用量，纯计算
-- 所有工具页面需 iOS26 Liquid Glass 风格
-
----
-
-## 🔗 需引入的外部依赖
-
-| 依赖 | 用途 | 阶段 | 纯Dart | 鸿蒙兼容 | 状态 |
-|------|------|------|--------|---------|------|
-| `fl_chart` | 图表绘制 | 三 | ✅ 是 | ✅ 是 | ✅ 已本地适配 |
-| `flutter_local_notifications` | 本地通知 | 五 | ❌ 否 | ⚠️ 待验证 | ❌ 未引入 |
-
----
-
-## 📝 验收标准
-
-### 阶段三 ✅
-- [x] 环形进度正确显示当日热量占比
-- [x] 三大营养素比例饼图正确
-- [x] 周/月趋势折线图可交互
-- [x] 可设置每日营养目标
-
-### 阶段四
-- [ ] 可从菜谱添加食材到购物清单
-- [ ] 可勾选已购物品
-- [ ] 食材按分类展示
-
-### 阶段五
-- [ ] 烹饪计时器支持多步骤倒计时
-- [ ] 用量换算覆盖常用单位
-- [ ] 过敏原检测可标记含过敏原的菜谱
-- [ ] 烹饪笔记可按菜谱关联
-- [ ] 用餐提醒可设置时间并准时通知
-- [ ] BMI 计算器结果含健康建议
-- [ ] 份量缩放可按比例调整食材用量
-
----
-
-## 🔵 阶段六：主页体验优化（P1）
-
-**目标**：修复主页交互体验问题，提升可用性  
-**前置依赖**：无  
-**关键阻塞**：无
-
-| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 问题描述 |
-|------|------|---------|--------|------|---------|
-| 6.1 | 增大卡片交互按钮点击区域 | `lib/src/pages/home_page.dart` | P1 | ❌ 未修复 | 图标16px过小，点击困难，需增大到20px+扩大热区 |
-| 6.2 | 添加骨架屏加载效果 | `lib/src/widgets/skeleton/` | P1 | ❌ 未创建 | 加载中无骨架屏，用户体验差 |
-| 6.3 | 支持动态主题切换 | `lib/src/services/ui/theme_service.dart` | P2 | ❌ 未实现 | 当前主题固定，需支持跟随系统/手动切换 |
-| 6.4 | 搜索功能+搜索页面 | `lib/src/pages/search/search_page.dart` | P1 | ❌ 未创建 | 搜索栏只读无跳转，需完整搜索功能 |
-| 6.5 | 菜谱详情页 | `lib/src/pages/recipe/recipe_detail_page.dart` | P1 | ❌ 未创建 | 点击卡片只显示Toast，需跳转到详情页 |
-
-### 问题详情
-
-#### 6.1 交互按钮过小
-- **现状**：图标 16px，点击热区仅文字区域
-- **影响**：用户难以准确点击，误触率高
-- **方案**：图标增大到 20px，Padding 从 2px 增加到 8px，使用 `InkWell` 扩大热区
-
-#### 6.2 骨架屏缺失
-- **现状**：加载时显示 `CupertinoActivityIndicator`
-- **影响**：页面跳动，感知加载时间长
-- **方案**：使用 `Shimmer` 或自定义骨架屏组件，模拟卡片结构
-
-#### 6.3 动态主题
-- **现状**：主题固定，仅支持亮/暗色
-- **影响**：无法满足个性化需求
-- **方案**：扩展 ThemeService，支持多主题色（蓝/绿/紫/橙）
-
-#### 6.4 搜索功能
-- **现状**：搜索栏 `readOnly: true`，点击无响应
-- **影响**：核心功能缺失
-- **方案**：创建 SearchPage，支持历史记录、热门搜索、结果列表
-
-#### 6.5 详情页缺失
-- **现状**：点击卡片 `ToastService.show('${item.title} 👀')`
-- **影响**：无法查看菜谱详情
-- **方案**：创建 RecipeDetailPage，展示封面、食材、步骤、营养
-
-### 开发顺序建议
-
-```
-6.1 增大交互按钮（最小改动，立竿见影）
-  → 6.2 骨架屏（提升感知性能）
-    → 6.4 搜索页面（核心功能）
-      → 6.5 菜谱详情页（核心功能）
-  → 6.3 动态主题（增强体验）
-```
-
-### 验收标准
-- [x] 交互按钮点击成功率 > 95%
-- [x] 骨架屏与真实内容结构一致
-- [ ] 主题切换实时生效，无闪烁
-- [x] 搜索支持关键词高亮、历史记录
-- [ ] 详情页展示完整菜谱信息
-
----
-
-## 🔴 Bug修复清单（P0）
-
-**目标**：修复用户反馈的严重问题  
-**发现时间**：2026-04-09
-
-| 序号 | 问题描述 | 影响页面 | 优先级 | 状态 | 可能原因 |
-|------|---------|---------|--------|------|---------|
-| B.1 | 发现页营养中心部分按钮卡死闪退 | `discover_page.dart` | P0 | ❌ 未修复 | 空指针/异步异常未捕获 |
-| B.2 | goal-setting页面被链接提示 | `goal_setting_page.dart` | P0 | ❌ 未修复 | 路由或依赖注入问题 |
-| B.3 | 今天吃什么选择无反应 | `what_to_eat_page.dart` | P0 | ❌ 未修复 | 状态管理或逻辑错误 |
-| B.4 | 主题设置页面不协调 | `personalization_page.dart` | P1 | ❌ 未修复 | 布局比例、缺少分割线 |
-
-### 问题详情
-
-#### B.1 发现页营养中心卡死闪退
-- **现象**：点击部分按钮后应用卡死并闪退
-- **可能原因**：
-  - 控制器未正确初始化
-  - 异步操作未正确处理异常
-  - 空安全违规访问
-- **排查方向**：检查 `DiscoverPage` 中的按钮点击事件处理
-
-#### B.2 goal-setting页面链接问题
-- **现象**：页面显示"被链接"提示
-- **可能原因**：
-  - 路由参数传递错误
-  - GetX依赖注入问题
-  - 页面生命周期问题
-- **排查方向**：检查路由跳转和控制器注册
-
-#### B.3 今天吃什么无反应
-- **现象**：点击"开始选择"、"随机"、"智能"按钮后无结果
-- **可能原因**：
-  - 算法逻辑错误
-  - 数据源为空
-  - 状态未正确更新
-- **排查方向**：检查 `WhatToEatController` 的选择逻辑
-
-#### B.4 主题设置页面不协调
-- **现象**：
-  - 页面比例不均衡
-  - 缺少分割线
-  - 部分参数设置不生效
-- **可能原因**：
-  - 布局使用固定尺寸
-  - 缺少视觉分隔
-  - 主题持久化逻辑问题
-- **排查方向**：重构布局，添加分割线，检查主题保存逻辑
-
-### 修复顺序建议
-```
-B.1 卡死闪退（最严重，优先修复）
-  → B.3 今天吃什么（核心功能）
-    → B.2 goal-setting链接问题
-      → B.4 主题设置UI（体验优化）
-```
-
-### 验收标准
-- [ ] 发现页所有按钮正常响应，无闪退
-- [ ] goal-setting页面正常打开，无异常提示
-- [ ] 今天吃什么功能完整可用，有结果反馈
-- [ ] 主题设置页面美观协调，设置实时生效
-
----
-
-## 🔴 Bug修复清单 第二波（P0）
-
-**发现时间**：2026-04-09（第二轮反馈）
-
-| 序号 | 问题描述 | 影响页面 | 优先级 | 状态 | 可能原因 |
-|------|---------|---------|--------|------|---------|
-| B.5 | 发现页购物清单点击无反应 | `discover_page.dart` | P0 | ✅ 已修复 | 按钮事件未绑定 |
-| B.6 | 我的页面购物清单被拦截 | `profile_home.dart` | P0 | ✅ 已修复 | PageRegistry 未注册 |
-| B.7 | 右上角 debug 标签 | `main.dart` | P1 | ✅ 已修复 | debugShowCheckedModeBanner未关闭 |
-| B.8 | 发现页营养中心报告被拦截 | `discover_page.dart` | P0 | ✅ 已修复 | PageRegistry 未注册 |
-| B.9 | 收藏页面单一无交互 | `favorites_page.dart` | P2 | ❌ 未修复 | 缺少删除/排序/分类功能 |
-
-### 问题详情
-
-#### B.5 发现页购物清单点击无反应
-- **现象**：点击购物清单入口无响应
-- **排查方向**：检查按钮onTap事件和路由跳转
-
-#### B.6 我的页面购物清单被拦截
-- **现象**：页面显示"被拦截"提示
-- **排查方向**：检查PageStandardsMiddleware和页面规范
-
-#### B.7 Debug标签
-- **现象**：右上角显示DEBUG标签
-- **修复方案**：设置 `debugShowCheckedModeBanner: false`
-
-#### B.8 营养中心报告被拦截
-- **现象**：点击报告入口显示"被拦截"
-- **排查方向**：检查路由注册和页面规范
-
-#### B.9 收藏页面单一
-- **现象**：只有列表，无删除/排序/分类功能
-- **优化方向**：添加滑动删除、分类筛选、排序选项
-
-### 修复顺序建议
-```
-B.7 去掉 Debug 标签（最简单，立即生效） ✅
-  → B.5/B.6/B.8 路由/拦截问题（核心功能） ✅ 全部修复
-    → B.9 收藏页面优化（体验增强）
-```
-
-### 验收标准
-- [x] 所有购物清单入口正常跳转
-- [x] 营养中心报告页面正常打开
-- [x] 无 DEBUG 标签显示
-- [ ] 收藏页面支持删除和排序
 
 ---
 
@@ -314,11 +80,11 @@ B.7 去掉 Debug 标签（最简单，立即生效） ✅
 
 | 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
 |------|------|---------|--------|------|------|
-| 7.1 | 实现分类筛选UI | `what_to_eat_page.dart` | P1 | ❌ 未实现 | 显示接口返回的分类列表供选择 |
-| 7.2 | 实现标签筛选UI | `what_to_eat_page.dart` | P1 | ❌ 未实现 | 显示接口返回的标签列表 |
-| 7.3 | 实现营养素筛选UI | `what_to_eat_page.dart` | P1 | ❌ 未实现 | 热量/蛋白质/脂肪范围滑块 |
-| 7.4 | 调用 available_filters 接口 | `what_to_eat_repository.dart` | P1 | ❌ 未实现 | 根据已选条件获取可用筛选 |
-| 7.5 | 保存筛选偏好 | `HiveService` | P2 | ❌ 未实现 | 本地记住用户偏好 |
+| 7.1 | 实现分类筛选UI | `what_to_eat_page.dart` | P1 | ✅ 已完成 | 显示接口返回的分类列表供选择 |
+| 7.2 | 实现标签筛选UI | `what_to_eat_page.dart` | P1 | ✅ 已完成 | 显示接口返回的标签列表 |
+| 7.3 | 实现营养素筛选UI | `what_to_eat_page.dart` | P1 | ✅ 已完成 | 热量/蛋白质/脂肪范围滑块 |
+| 7.4 | 调用 available_filters 接口 | `what_to_eat_repository.dart` | P1 | ✅ 已完成 | 根据已选条件获取可用筛选 |
+| 7.5 | 保存筛选偏好 | `HiveService` | P2 | ✅ 已完成 | 本地记住用户偏好 |
 
 ### 接口分析
 
@@ -327,22 +93,368 @@ B.7 去掉 Debug 标签（最简单，立即生效） ✅
 | `act=random` | ✅ 已调用 | 随机模式 |
 | `act=smart` | ✅ 已调用 | 智能模式（仅用偏好） |
 | `act=config` | ✅ 已调用 | 获取配置 |
-| `act=subcategories` | ❌ 未调用 | 获取子分类 |
-| `act=available_filters` | ❌ 未调用 | 动态筛选 |
+| `act=subcategories` | ✅ 已调用 | 获取子分类 |
+| `act=available_filters` | ✅ 已调用 | 动态筛选 |
 
 ### 筛选参数（接口支持）
 
 | 参数 | 类型 | APP实现 |
 |------|------|--------|
-| `include_categories` | int[] | ❌ |
-| `exclude_categories` | int[] | ❌ |
-| `include_tags` | int[] | ❌ |
-| `exclude_tags` | int[] | ❌ |
-| `exclude_allergens` | string[] | ⚠️ 仅偏好 |
-| `nutrition` | string | ❌ |
+| `include_categories` | int[] | ✅ 已实现 |
+| `exclude_categories` | int[] | ✅ 已实现 |
+| `include_tags` | int[] | ✅ 已实现 |
+| `exclude_tags` | int[] | ✅ 已实现 |
+| `exclude_allergens` | string[] | ✅ 已实现 |
+| `nutrition` | string | ✅ 已实现 |
 
 ### 验收标准
-- [ ] 支持分类多选筛选
-- [ ] 支持标签多选筛选
-- [ ] 支持营养素范围筛选
-- [ ] 筛选结果实时更新
+- [x] 支持分类多选筛选
+- [x] 支持标签多选筛选
+- [x] 支持营养素范围筛选
+- [x] 筛选结果实时更新
+
+---
+
+## 🔵 阶段八：API v2.0.0 迁移 + Bug修复（P0/P1）
+
+**目标**：迁移到 API v2.0.0 合并接口，修复用户反馈的8个严重Bug  
+
+
+
+---
+
+## 🔴 阶段九：架构修复+核心Bug（P0/P1）
+
+**目标**：修复架构违规和核心功能缺失  
+**发现时间**：2026-04-10（flutter analyze 全面扫描 + 项目分析）  
+**关键阻塞**：无
+
+| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
+|------|------|---------|--------|------|------|
+| 9.1 | 热门排行点击跳转详情 | `lib/src/pages/hot/hot_page.dart` | P0 | ❌ 未修复 | L148 有 TODO，点击无响应，需跳转到 RecipeDetailPage |
+| 9.2 | 首页改用 Repository 层 | `lib/src/pages/home_page.dart` | P0 | ❌ 未修复 | 直接使用 `_apiService` 绕过 Repository，需改为 `RecipeRepository` |
+| 9.3 | 合并收藏功能（去重） | `cart_controller.dart` + `favorites_controller.dart` | P1 | ❌ 未修复 | CartController 实为收藏功能但命名混乱，需统一为 FavoritesController |
+| 9.4 | 合并搜索控制器（去重） | `search_controller.dart` + `search/search_controller.dart` | P1 | ❌ 未修复 | 两个搜索控制器并存，需合并为一个 |
+| 9.5 | 聊天页面功能化或移除 | `lib/src/pages/chat_module/chat_page.dart` | P2 | ❌ 未修复 | 纯 Demo 硬编码消息，需接入真实功能或移除入口 |
+| 9.6 | 多语言词条扩充 | `app_zh.arb` / `app_en.arb` | P1 | ❌ 未修复 | 仅 21 词条，大量中文硬编码，需补全页面文字 |
+
+### 问题详情
+
+#### 9.1 热门排行点击无法跳转详情
+- **现象**：热门排行列表项点击无响应
+- **代码位置**：`hot_page.dart:148` — `// TODO: 点击跳转到菜谱详情页`
+- **方案**：使用 `Get.toNamed('/recipe-detail', arguments: item.id)` 跳转
+
+#### 9.2 首页绕过 Repository 层
+- **现象**：`home_page.dart` 直接 `final ApiService _apiService = ApiService()`
+- **影响**：违反架构分层，无法统一缓存/错误处理/数据转换
+- **方案**：改为 `final RecipeRepository _recipeRepository = RecipeRepository()`，通过 Repository 获取数据
+
+#### 9.3 收藏功能重复
+- **现象**：`CartController` + `CartPage` 和 `FavoritesController` + `FavoritesPage` 两套并存
+- **影响**：收藏状态不同步，代码冗余
+- **方案**：
+  1. 删除 `CartController` + `CartPage`
+  2. 将 CartController 的 quantity 逻辑合并到 FavoritesController
+  3. 底部 Tab 收藏入口统一指向 FavoritesPage
+
+#### 9.4 搜索控制器重复
+- **现象**：`controllers/search_controller.dart` 和 `controllers/search/search_controller.dart` 两个文件
+- **影响**：搜索逻辑分散，修改一处容易遗漏另一处
+- **方案**：保留 `search/search_controller.dart`（目录结构更规范），删除根目录版本，更新所有引用
+
+#### 9.5 聊天页面
+- **现象**：`ChatPage` 只有硬编码消息 `{'text': '你好，这是聊天示例。', 'me': false}`
+- **方案A**：接入 AI 聊天 API（如菜谱问答）
+- **方案B**：改为"意见反馈"页面
+- **方案C**：移除入口，待后续有需求再添加
+
+#### 9.6 多语言覆盖率
+- **现象**：`app_zh.arb` 仅 21 词条，大量页面文字如"今天吃什么"、"热门排行"、"我的足迹"等硬编码
+- **方案**：逐页面提取硬编码文字到 arb 文件，优先覆盖核心页面（首页、搜索、详情、发现）
+
+### 开发顺序建议
+
+```
+9.1 热门排行跳转详情（最小改动，立竿见影）
+  → 9.2 首页改用 Repository（架构规范）
+    → 9.4 合并搜索控制器（消除冗余）
+      → 9.3 合并收藏功能（消除冗余）
+  → 9.6 多语言词条扩充（持续进行）
+  → 9.5 聊天页面（最后处理）
+```
+
+### 验收标准
+- [ ] 热门排行点击可跳转到菜谱详情页
+- [ ] 首页通过 Repository 层获取数据
+- [ ] 收藏功能只有一套实现
+- [ ] 搜索功能只有一套实现
+- [ ] 聊天页面有真实功能或已移除入口
+- [ ] 核心页面文字已提取到 arb 文件
+
+---
+
+## 🟡 阶段十：代码质量提升（P1/P2）
+
+**目标**：提升代码可维护性和健壮性  
+**前置依赖**：阶段九完成  
+**关键阻塞**：无
+
+| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
+|------|------|---------|--------|------|------|
+| 10.1 | 统一 Controller 注册 | `lib/src/bindings/app_binding.dart` | P1 | ❌ 未实现 | 部分用 `Get.put()`，部分用 `Get.find()`，需统一 Binding |
+| 10.2 | HiveService 数据迁移机制 | `lib/src/services/data/hive_service.dart` | P2 | ❌ 未实现 | Box schema 变更时无迁移策略，可能导致数据丢失 |
+| 10.3 | 统一错误处理 | `lib/src/services/api/api_exception.dart` | P1 | ❌ 未实现 | 部分 Repository 抛 Exception，部分返回空数据，需统一错误码 |
+| 10.4 | 离线缓存策略 | `lib/src/services/data/storage_service.dart` | P1 | ❌ 未实现 | API 数据仅靠 Dio 缓存，离线时首页无数据 |
+| 10.5 | DesignTokens 与 ThemeService 解耦 | `lib/src/config/design_tokens.dart` | P2 | ❌ 未实现 | 页面混用静态常量和动态值，暗色模式适配不一致 |
+
+### 问题详情
+
+#### 10.1 Controller 注册不统一
+- **现象**：部分页面在 `build()` 中 `Get.put()`，部分在 `onInit()` 中 `Get.find()`
+- **影响**：Controller 生命周期不可控，可能重复创建或找不到
+- **方案**：每个页面创建对应 Binding，在 `AppBinding` 中统一注册
+
+#### 10.2 HiveService 无数据迁移
+- **现象**：Box schema 变更后直接崩溃或数据丢失
+- **方案**：添加 `boxVersion` 字段，打开 Box 时检查版本号，执行迁移逻辑
+
+#### 10.3 错误处理不统一
+- **现象**：`RecipeRepository` 抛 `Exception`，`FeedRepository` 返回空列表
+- **方案**：定义 `AppException` 层级（NetworkException / ParseException / StorageException），Repository 统一抛出
+
+#### 10.4 离线缓存
+- **现象**：无网络时首页显示"暂无菜谱"
+- **方案**：API 成功时将数据写入 Hive，离线时从 Hive 读取
+
+#### 10.5 DesignTokens 解耦
+- **现象**：页面同时使用 `DesignTokens.text1`（静态）和 `themeService.textColor.value`（动态）
+- **方案**：所有颜色值通过 `ThemeService` 获取，`DesignTokens` 仅保留间距/圆角/字号等不变量
+
+### 开发顺序建议
+
+```
+10.1 统一 Controller 注册（架构基础）
+  → 10.3 统一错误处理（稳定性）
+    → 10.4 离线缓存（用户体验）
+  → 10.2 HiveService 迁移机制（数据安全）
+  → 10.5 DesignTokens 解耦（代码规范）
+```
+
+### 验收标准
+- [ ] 所有 Controller 通过 Binding 注册
+- [ ] HiveService 支持 schema 版本迁移
+- [ ] Repository 统一抛出 AppException
+- [ ] 离线时首页可显示缓存数据
+- [ ] 页面颜色值统一通过 ThemeService 获取
+
+---
+
+## 🟢 阶段十一：烹饪模式+营养仪表盘（P1）
+
+**目标**：实现核心增强功能，提升应用价值  
+**前置依赖**：阶段九完成  
+**关键阻塞**：无
+
+| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
+|------|------|---------|--------|------|------|
+| 11.1 | 🍳 烹饪模式 | `lib/src/pages/recipe/cooking_mode_page.dart` | P1 | ❌ 未实现 | 详情页"开始烹饪"按钮，步骤引导+计时器联动 |
+| 11.2 | 📊 营养追踪仪表盘 | `lib/src/pages/home/nutrition_dashboard.dart` | P1 | ❌ 未实现 | 首页展示今日营养摄入环形图，整合 MealRecordController |
+| 11.3 | 🛒 菜谱食材一键加入购物清单 | `lib/src/pages/recipe/recipe_detail_page.dart` | P1 | ❌ 未实现 | 详情页"加入购物清单"按钮，自动解析食材 |
+| 11.4 | 📖 菜谱步骤图文模式 | `lib/src/pages/recipe/recipe_detail_page.dart` | P2 | ❌ 未实现 | 步骤展开/折叠，每步配图+计时器 |
+
+### 功能详情
+
+#### 11.1 烹饪模式
+- **入口**：菜谱详情页 → "🍳 开始烹饪"按钮
+- **功能**：
+  - 全屏步骤引导，左右滑动切换步骤
+  - 当前步骤高亮，已完成步骤置灰
+  - 每步自动启动计时器（如有时间信息）
+  - 支持语音播报（TTS）
+  - 支持暂停/继续/跳过
+- **技术方案**：PageView + StepIndicator + CookingTimerController
+
+#### 11.2 营养追踪仪表盘
+- **入口**：首页顶部卡片区域
+- **功能**：
+  - 今日热量/蛋白质/脂肪/碳水摄入环形图
+  - 与每日目标对比进度
+  - 点击跳转到营养中心详情
+- **技术方案**：NutritionRing widget + MealRecordController
+
+#### 11.3 食材一键加入购物清单
+- **入口**：菜谱详情页 → "🛒 加入购物清单"按钮
+- **功能**：
+  - 解析 `RecipeModel.ingredients` 为 `ShoppingItemModel` 列表
+  - 弹出确认弹窗，可勾选/取消勾选食材
+  - 确认后写入 Hive
+- **技术方案**：ShoppingListController.addFromRecipe()
+
+#### 11.4 步骤图文模式
+- **入口**：菜谱详情页步骤区域
+- **功能**：
+  - 步骤卡片展开/折叠
+  - 每步配图（如有）
+  - 每步计时器快捷按钮
+  - 步骤编号 + 预计时间
+
+### 开发顺序建议
+
+```
+11.3 食材加入购物清单（最小改动，复用现有 ShoppingListController）
+  → 11.2 营养追踪仪表盘（复用现有 NutritionRing + MealRecordController）
+    → 11.4 步骤图文模式（增强详情页）
+      → 11.1 烹饪模式（最复杂，需新建页面）
+```
+
+### 验收标准
+- [ ] 详情页有"开始烹饪"按钮，点击进入步骤引导模式
+- [ ] 首页显示今日营养摄入环形图
+- [ ] 详情页可一键将食材加入购物清单
+- [ ] 详情页步骤支持展开/折叠
+
+---
+
+## 🟢 阶段十二：社交+通知增强（P2）
+
+**目标**：增加社交分享和通知提醒功能  
+**前置依赖**：阶段十一完成  
+**关键阻塞**：12.1 需 `share_plus`，12.2 需 `flutter_local_notifications`
+
+| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
+|------|------|---------|--------|------|------|
+| 12.1 | 📱 分享菜谱 | `lib/src/pages/recipe/recipe_detail_page.dart` | P2 | ❌ 未实现 | 生成菜谱卡片图片，支持系统分享 |
+| 12.2 | 🔔 烹饪提醒通知 | `lib/src/services/notification_service.dart` | P2 | ❌ 未实现 | 定时提醒烹饪步骤，与计时器联动 |
+| 12.3 | 🔍 搜索建议/热词 | `lib/src/pages/search/search_page.dart` | P2 | ❌ 未实现 | 搜索页展示热门搜索词，输入时自动补全 |
+| 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()` 获取热词
+
+#### 12.4 拍照记录
+- **入口**：烹饪笔记 → 拍照按钮
+- **功能**：
+  - 调用相机拍照或从相册选择
+  - 图片压缩后保存到本地
+  - 笔记列表展示缩略图
+- **技术方案**：`image_picker` + 本地文件存储
+
+### 需引入的外部依赖
+
+| 依赖 | 用途 | 纯Dart | 鸿蒙兼容 |
+|------|------|--------|---------|
+| `share_plus` | 系统分享 | ❌ | ⚠️ 需适配 |
+| `flutter_local_notifications` | 本地通知 | ❌ | ⚠️ 需适配 |
+| `image_picker` | 拍照/相册 | ❌ | ⚠️ 需适配 |
+| `screenshot` | 截图 | ✅ | ✅ |
+
+### 验收标准
+- [ ] 详情页可分享菜谱卡片到其他应用
+- [ ] 烹饪计时器完成时发送本地通知
+- [ ] 搜索页展示热门搜索词
+- [ ] 烹饪笔记可添加照片
+
+---
+
+## 🔵 阶段十三：AI+规划高级功能（P3）
+
+**目标**：实现智能化和规划类高级功能  
+**前置依赖**：阶段十二完成  
+**关键阻塞**：13.1 需 AI API，13.2 需日历组件
+
+| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
+|------|------|---------|--------|------|------|
+| 13.1 | 🤖 AI 菜谱推荐 | `lib/src/services/ai_recommend_service.dart` | P3 | ❌ 未实现 | 基于口味偏好+浏览历史，智能推荐菜谱 |
+| 13.2 | 📅 每周菜单规划 | `lib/src/pages/tools/meal_planner_page.dart` | P3 | ❌ 未实现 | 日历视图规划一周饮食，自动生成购物清单 |
+| 13.3 | 🧮 食材用量换算增强 | `lib/src/pages/tools/serving_scaler_page.dart` | P3 | ❌ 未实现 | 增强份量缩放，支持不同单位换算 |
+| 13.4 | 🌙 就寝提醒 | `lib/src/pages/settings/health_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` + 健康算法
+
+### 验收标准
+- [ ] "为你推荐"展示个性化推荐菜谱
+- [ ] 每周菜单可规划三餐并生成购物清单
+- [ ] 份量缩放支持多种单位换算
+- [ ] 就寝提醒根据饮食时间智能推荐
+
+---
+
+## 📎 软件特性功能汇总
+
+> 以下功能已开发完成或开发中，从历史版本号归档而来
+
+| 功能 | 状态 | 首次版本 | 说明 |
+|------|------|---------|------|
+| 热量追踪+营养分析 | ✅ 已完成 | v0.3x | 环形图+饼图+折线图+目标设置 |
+| 购物清单 | ✅ 已完成 | v0.4x | 添加/删除/勾选/分类/从菜谱添加 |
+| 烹饪计时器 | ✅ 已完成 | v0.5x | 多步骤倒计时 |
+| 用量换算 | ✅ 已完成 | v0.5x | 常用单位换算 |
+| 过敏原检测 | ✅ 已完成 | v0.5x | 标记含过敏原菜谱 |
+| 烹饪笔记 | ✅ 已完成 | v0.5x | 按菜谱关联笔记 |
+| 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 | 107→1 个 info，0 error/warning |