kitchen/docs/dev/LOCAL_FEATURES_PLAN.md

五、开发阶段

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

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

序号	任务	产出文件	状态
1.1	引入 hive_ce 依赖	pubspec.yaml	✅
1.2	实现 HiveService（初始化/注册适配器/打开Box）	lib/src/services/data/hive_service.dart	✅
1.3	创建 MealRecordModel + 手写 TypeAdapter	lib/src/models/meal_record_model.dart	✅
1.4	创建 ShoppingItemModel + 手写 TypeAdapter	lib/src/models/shopping_item_model.dart	✅
1.5	创建 UserGoalModel + 手写 TypeAdapter	lib/src/models/user_goal_model.dart	✅
1.6	创建 CookingNoteModel + 手写 TypeAdapter	lib/src/models/cooking_note_model.dart	✅
1.7	手写 TypeAdapter（替代 build_runner 代码生成）	各模型文件内嵌	✅
1.8	FavoritesController 持久化改造（迁移到 Hive Box）	lib/src/controllers/favorites_controller.dart	✅
1.9	AppService 初始化 HiveService	lib/src/services/core/app_service.dart	✅

阶段二：饮食日记（P1）

目标：记录每日饮食 + 自动计算营养

序号	任务	产出文件
2.1	MealRecordController	lib/src/controllers/meal_record_controller.dart
2.2	饮食日记页面（日历+列表）	lib/src/pages/nutrition/meal_diary_page.dart
2.3	添加饮食记录弹窗	lib/src/pages/nutrition/add_meal_sheet.dart
2.4	餐次选择器（早/午/晚/加餐）	lib/src/widgets/meal_type_selector.dart
2.5	营养自动计算（从 RecipeModel.nutrition 读取）	MealRecordController 内逻辑
2.6	发现页增加「营养中心」入口	discover_page.dart 修改

阶段三：热量追踪 + 营养分析（P1）

目标：可视化每日营养摄入 + 目标对比

序号	任务	产出文件
3.1	引入 fl_chart 依赖	pubspec.yaml
3.2	NutritionController	lib/src/controllers/nutrition_controller.dart
3.3	热量追踪页面（环形进度+三大营养素）	lib/src/pages/nutrition/calorie_tracker_page.dart
3.4	营养分析报告页面（周/月趋势图）	lib/src/pages/nutrition/nutrition_report_page.dart
3.5	用户目标设置页面	lib/src/pages/nutrition/goal_setting_page.dart
3.6	环形进度组件	lib/src/widgets/charts/calorie_ring.dart
3.7	折线趋势图组件	lib/src/widgets/charts/nutrition_line_chart.dart

阶段四：购物清单（P2）

目标：从菜谱食材自动生成购物清单

序号	任务	产出文件
4.1	ShoppingListController	lib/src/controllers/shopping_list_controller.dart
4.2	购物清单页面	lib/src/pages/shopping/shopping_list_page.dart
4.3	从菜谱添加食材到购物清单	首页卡片/菜谱详情页增加入口
4.4	食材分类展示	lib/src/widgets/shopping_category_group.dart
4.5	我的页面增加「购物清单」入口	profile_home.dart 修改

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

目标：烹饪计时器 + 用量换算 + 过敏原检测 + 烹饪笔记

序号	任务	产出文件
5.1	烹饪计时器页面	lib/src/pages/tools/cooking_timer_page.dart
5.2	用量换算工具页面	lib/src/pages/tools/unit_converter_page.dart
5.3	过敏原检测逻辑	lib/src/services/allergen_checker.dart
5.4	烹饪笔记功能	lib/src/controllers/cooking_note_controller.dart
5.5	用餐提醒（需 flutter_local_notifications）	lib/src/services/notification_service.dart
5.6	BMI 计算器	lib/src/pages/tools/bmi_calculator_page.dart
5.7	份量缩放工具	lib/src/pages/tools/serving_scaler_page.dart

---

六、页面导航规划

发现页
  └── 📊 营养中心
        ├── 🍽️ 饮食日记（日历视图 + 每日记录列表）
        │     └── ➕ 添加记录（底部弹窗：选餐次 + 选菜谱/手动输入）
        ├── 🔥 热量追踪（环形进度 + 三大营养素比例 + 目标线）
        └── 📊 分析报告（周/月趋势折线图 + 营养素饼图）

我的页面
  ├── 📋 购物清单（分类展示 + 勾选已购）
  ├── ⏱️ 烹饪计时器（多步骤倒计时）
  ├── 🔄 用量换算
  ├── 🎯 BMI 计算器
  └── ⚙️ 设置
        ├── 🎯 每日营养目标
        ├── 🔔 用餐提醒
        └── ⚠️ 过敏原管理

---

七、文件结构规划

lib/src/
├── models/
│   ├── meal_record_model.dart      # 饮食记录 + @HiveType
│   ├── shopping_item_model.dart    # 购物清单项 + @HiveType
│   ├── user_goal_model.dart        # 用户营养目标 + @HiveType
│   └── cooking_note_model.dart     # 烹饪笔记 + @HiveType
├── controllers/
│   ├── meal_record_controller.dart # 饮食记录控制器
│   ├── nutrition_controller.dart   # 营养分析控制器
│   ├── shopping_list_controller.dart # 购物清单控制器
│   └── cooking_note_controller.dart  # 烹饪笔记控制器
├── services/
│   └── data/
│       └── hive_service.dart       # Hive 初始化/Box 管理
├── pages/
│   ├── nutrition/
│   │   ├── nutrition_center_page.dart  # 营养中心主页
│   │   ├── meal_diary_page.dart        # 饮食日记
│   │   ├── add_meal_sheet.dart         # 添加记录弹窗
│   │   ├── calorie_tracker_page.dart   # 热量追踪
│   │   ├── nutrition_report_page.dart  # 营养报告
│   │   └── goal_setting_page.dart      # 目标设置
│   ├── shopping/
│   │   └── shopping_list_page.dart     # 购物清单
│   └── tools/
│       ├── cooking_timer_page.dart     # 烹饪计时器
│       ├── unit_converter_page.dart    # 用量换算
│       ├── bmi_calculator_page.dart    # BMI 计算器
│       └── serving_scaler_page.dart    # 份量缩放
└── widgets/
    ├── charts/
    │   ├── calorie_ring.dart           # 热量环形进度
    │   └── nutrition_line_chart.dart   # 营养趋势折线图
    ├── meal_type_selector.dart         # 餐次选择器
    └── shopping_category_group.dart    # 购物清单分类组

---

八、开发优先级矩阵

功能	用户价值	技术难度	依赖关系	优先级
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

---

九、验收标准

阶段一

• App 重启后收藏数据不丢失
• Hive Box 初始化成功，无报错
• TypeAdapter 注册正确，对象可序列化/反序列化
• HiveService 支持增删改查

阶段二

• 可按日期查看饮食记录
• 可添加/删除饮食记录
• 选择菜谱后自动填充营养数据
• 日历视图正确标记有记录的日期

阶段三

• 环形进度正确显示当日热量占比
• 三大营养素比例饼图正确
• 周/月趋势折线图可交互
• 可设置每日营养目标

阶段四

• 可从菜谱添加食材到购物清单
• 可勾选已购物品
• 食材按分类展示

---

十、技术决策记录

日期	决策	理由	替代方案
2026-04-09	选择 Hive CE 而非 sqflite	纯 Dart 零原生依赖，鸿蒙零风险；API 简单开发快；数据量小无需 SQL	sqflite（原生依赖，鸿蒙兼容风险）
2026-04-09	选择 hive_ce 而非原版 hive	社区版持续维护，支持 WASM，性能优于 v4	hive v2.2.3（3年未更新）
2026-04-09	选择 fl_chart 而非 charts_flutter	纯 Dart 无平台依赖，社区活跃	charts_flutter（已停维）
2026-04-09	营养数据冗余存储到 MealRecordModel	避免菜谱修改影响历史记录	联表查询（数据不一致风险）
2026-04-09	使用 ISO8601 日期格式	跨时区安全，排序方便	时间戳（可读性差）
2026-04-09	聚合查询用 Dart 代码实现	数据量极小（~2000条/年），Dart 过滤性能足够	SQL 聚合（需 sqflite，过度设计）