目录树重构

2026-04-11 02:02:23 +08:00
parent 8c41df955c
commit ecaad58693
274 changed files with 11893 additions and 32447 deletions
--- a/docs/dev/ISSUES_TO_RESOLVE.md
+++ b/docs/dev/ISSUES_TO_RESOLVE.md
@@ -1,357 +0,0 @@
-# 待解决问题清单
-
-创建时间: 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. 添加测试覆盖
-
---
-
-*此文档将随着问题解决和新问题发现持续更新*
--- a/docs/dev/LOCAL_FEATURES_PLAN.md
+++ b/docs/dev/LOCAL_FEATURES_PLAN.md
@@ -1,191 +0,0 @@
-
-## 五、开发阶段
-
-### 阶段一：基础设施（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，过度设计） |
--- a/docs/dev/UNFINISHED_FEATURES.md
+++ b/docs/dev/UNFINISHED_FEATURES.md