# 📋 未完成功能清单

> 文档创建: 2026-04-09  
> 最后更新: 2026-04-10  
> 数据来源: `LOCAL_FEATURES_PLAN.md` 阶段三~五 + 项目全面分析  
> 说明: 记录所有未完成的功能任务，跟踪开发进度  
> 优先级说明: P1=核心功能 P2=重要功能 P3=增强功能  
> 优先级值1-5: 5=最高优先级（多次提及自动提升）

---

## 📊 总体进度

| 阶段 | 总任务 | 已完成 | 未完成 | 完成率 |
|------|--------|--------|--------|--------|
| 三：热量追踪+营养分析 | 7 | 7 | 0 | 100% ✅ |
| 四：购物清单 | 5 | 5 | 0 | 100% ✅ |
| 五：增强功能 | 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%** |

---





### 技术要点

- `ShoppingItemModel` 已有 `category` 字段，分类展示直接用 `groupby`
- 勾选已购用 `isChecked` 字段，写入 Hive 持久化
- 从菜谱添加需解析 `RecipeModel.ingredients`，转为 `ShoppingItemModel` 列表
- 购物清单页面需 iOS26 Liquid Glass 风格

### 已完成文件清单

| 文件路径 | 说明 |
|---------|------|
| `lib/src/controllers/shopping/shopping_list_controller.dart` | 购物清单控制器 |
| `lib/src/pages/shopping/shopping_list_page.dart` | 购物清单页面 |
| `lib/src/models/shopping/shopping_item_model.dart` | 购物清单模型（已存在） |

### 路由

| 路由路径 | 页面 |
|---------|------|
| `/shopping-list` | 购物清单页面 |

---

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

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

| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
|------|------|---------|--------|------|------|
| 5.1 | 烹饪计时器页面 | `lib/src/pages/tools/cooking_timer_page.dart` | P2 | ✅ 已完成 | 已添加入口到"我的"首页 |

### 开发顺序建议



---

## 🟡 阶段七：今天吃什么增强（P1）

**目标**：实现接口支持的动态筛选功能  
**前置依赖**：接口已支持（`api_what_to_eat.php` v1.24.0）  
**分析结论**：接口已完整支持随机/智能/分类/标签/营养素筛选，APP端未调用

| 序号 | 任务 | 产出文件 | 优先级 | 状态 | 说明 |
|------|------|---------|--------|------|------|
| 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 | ✅ 已完成 | 本地记住用户偏好 |

### 接口分析

| 端点 | APP调用 | 说明 |
|------|---------|------|
| `act=random` | ✅ 已调用 | 随机模式 |
| `act=smart` | ✅ 已调用 | 智能模式（仅用偏好） |
| `act=config` | ✅ 已调用 | 获取配置 |
| `act=subcategories` | ✅ 已调用 | 获取子分类 |
| `act=available_filters` | ✅ 已调用 | 动态筛选 |

### 筛选参数（接口支持）

| 参数 | 类型 | APP实现 |
|------|------|--------|
| `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 |