kitchen/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

## [0.92.1] - 2026-04-13

### 📁 目录结构重构 — 所有文件夹不超过8个文件

#### controllers/ (14→1+4子文件夹)
- `controllers/recipe/` — recipe_detail_controller, search_controller
- `controllers/home/` — home_controller, main_navigation_controller
- `controllers/tools/` — tools_controller, what_to_eat_controller, bedtime_reminder_controller
- `controllers/data/` — favorites, browse_history, cooking_note, shopping_list, meal_record, weekly_menu

#### models/ (11→4+2子文件夹)
- `models/user/` — user_goal_model, user_preference_model
- `models/data/` — browse_history, cooking_note, meal_record, shopping_item, weekly_menu

#### widgets/根目录 (11→4+2子文件夹)
- `widgets/common/` — adaptive_widgets, loading_indicator, responsive_grid, skeleton_widgets
- `widgets/recipe/` — recipe_card, recipe_image, nutrition_dashboard_card

#### pages/profile/ (11→5+2子文件夹)
- `pages/profile/data/` — cache_manage, data_center, stats_dashboard
- `pages/profile/social/` — chat, favorites, footprints

#### pages/tools/ (14→3+3子文件夹)
- `pages/tools/health/` — allergen_checker, allergen_report, bmi_calculator, meal_time_recommend
- `pages/tools/cooking/` — cooking_note, cooking_timer, serving_scaler, unit_converter
- `pages/tools/planning/` — meal_planner, weekly_menu_planner, eating_times

#### widgets/glass/ (10→7+1子文件夹)
- `widgets/glass/nav/` — glass_nav_bar, liquid_glass_nav_bar, home_app_bar

#### widgets/recipe_detail/ (20→1+4子文件夹)
- `widgets/recipe_detail/header/` — cover_image, title_section, author_card, meta_info_card, time_info
- `widgets/recipe_detail/content/` — ingredients_section, ingredient_details, steps_section, indices_card, picid_card
- `widgets/recipe_detail/interaction/` — action_bar, rating_dialog, statistics_bar, tags_section
- `widgets/recipe_detail/info/` — nutrition_section, ring_chart, allergen_warning, category_breadcrumb, similar_section

#### 代码质量
- ✅ flutter analyze 零错误通过
- 🔧 修复所有相对路径import（3个文件）

## [0.92.0] - 2026-04-13

### 🚀 21项功能批量实现 — 评分排行榜/过敏原报告/营养可视化/查重检测/运营大屏等

#### 新增功能
- 🏆 **评分排行榜** — HotPage新增sort=rate排序，HotRepository/HotController/HotPage三层联动
- 📋 **过敏原报告页面** — AllergenReportPage：选择过敏原→生成报告→安全/风险菜谱分类→替代建议
- 📊 **营养可视化环形图** — NutritionRingChart组件：蛋白质/脂肪/碳水/纤维占比环形图+热量达标进度条
- 🎯 **筛选步骤引导** — WhatToEatPage新增3步引导指示器（选分类→选口味→开转!）
- 🔄 **食材替代建议** — IngredientDetailPage新增30+食材替代映射，点击可跳转查看替代食材
- 🍽️ **相似菜品推荐** — RecipeSimilarSection组件：菜品详情页底部推荐同分类菜品
- 🍽️ **食材相关菜谱** — IngredientDetailPage底部显示含该食材的菜谱列表
- 💪 **健身餐推荐** — NutritionCenterPage新增减脂餐/增肌餐/生酮餐/碳水补充快捷入口
- ⚡ **营养中心快捷功能** — 营养目标/营养报告/购物清单快捷入口
- 🔍 **查重检测页面** — DuplicateCheckPage：输入菜谱名称→搜索相似→计算相似度→分级显示
- 📈 **运营数据大屏** — StatsDashboardPage：今日/本月/历史排行+浏览/点赞汇总统计
- 📈 **数据管理中心增强** — DataCenterPage新增运营数据大屏入口

#### 工具中心新增
- 📋 过敏原报告 — 工具中心健康分类新增入口
- 🔍 查重检测 — 工具中心数据分类新增入口
- 📊 运营数据大屏 — 工具中心数据分类新增入口

#### 路由注册
- `/allergen-report` — 过敏原报告页面
- `/duplicate-check` — 查重检测页面
- `/stats-dashboard` — 运营数据大屏页面

#### 代码质量
- ✅ flutter analyze 零错误通过
- 🔧 修复nutrition_ring_chart num→double类型转换
- 🔧 修复stats_dashboard_page HotItem属性引用(recipeId→id, title→name)
- 🔧 移除allergen_report_page未使用的_isGenerating字段

## [0.91.21] - 2026-04-13

### 🐛 食材详情页闪退修复 + API能力分析文档更新

#### Bug修复
- 🐛 **setState() after dispose() 闪退** — 食材详情页异步操作完成后页面已销毁仍调用setState
  - `_loadIngredientFromArgs()` 添加 `mounted` 检查
  - `_loadIngredientByName()` 添加 `mounted` 检查
  - `_loadIngredients()` 3处 `setState` 全部添加 `mounted` 检查
  - 举一反三：扫描15个页面的 `await→setState` 模式，确认其他页面已有保护

#### 文档更新
- 📊 **API能力分析全面更新** — PAGE_STRUCTURE_ANALYSIS.md
  - 新增"已使用API接口一览"表（8个接口文件+9个Repository）
  - 新增"未使用API接口一览"表（18个未调用接口/参数/静态资源）
  - 🟢 已有API可直接开发：12项（新增筛选步骤引导、编码/模糊查询、食谱子分类）
  - 🟡 需组合API开发：10项（新增食材营养详情、食材替代建议、营养目标追踪、统一格式输出）
  - 🔴 需后端新开发API：13项（新增烹饪笔记同步、购物清单同步、每周菜单存储）
  - 新增"推荐开发路线图"三阶段规划

#### 代码修复
- 🍃 **CupertinoIcons.leaf不存在** — 替换为 `Icons.eco`（Material），添加 `material.dart` import
- 🧹 **移除不必要的 painting.dart import** — 替换为 `material.dart`

## [0.91.20] - 2026-04-13

### 🥬 食材详情本地缓存 + 缓存管理增强

#### 食材缓存
- 🥬 **IngredientModel.toJson** — 新增序列化方法，支持缓存存储
- 💾 **RecipeRepository.fetchIngredientDetail** — 添加缓存逻辑，优先读取本地缓存，7天有效期
- 🗑️ **缓存管理页面** — 新增食材详情缓存管理
  - 概览卡片：显示食材缓存数量
  - 操作按钮：清理食材详情缓存
  - 食材列表：显示已缓存食材，支持左滑删除、点击查看
  - 单项清理：`_clearSpecificIngredientCache`

## [0.91.19] - 2026-04-13

### 🎨 全局UI统一：圆角/颜色/毛玻璃/空状态/加载状态

#### 统一圆角
- 📐 **替换89处硬编码圆角** — `BorderRadius.circular(N)` → `DesignTokens.borderRadiusSm/Md/Lg/Xl/Full`
  - 映射规则：2-8→Sm, 10-16→Md, 18-20→Lg, 22-28→Xl, 25+→Full
  - 9个文件缺少 `design_tokens.dart` import，已自动添加

#### 统一颜色
- 🎨 **替换20处硬编码颜色** — `Color(0xFFFF3B30)` 等 → `DesignTokens.red/green/orange/purple/blue/teal/text2/text3`
  - 映射规则：FF3B30/F44336→red, 34C759/4CAF50→green, FFB800→gold, 9C27B0→purple, 3498DB→blue, 1ABC9C→teal, 8E8E93→text2
  - 修复 `const DesignTokens.red` → `DesignTokens.red`（静态字段不是构造函数）
  - 修复 `Colors.transparent` → `const Color(0x00000000)`（避免缺少 import）

#### 增强EmptyState
- 💎 **毛玻璃卡片包裹** — 新增 `useGlassCard` 参数（默认true）
- 🎯 **图标圆形背景** — 使用 `DesignTokens.dynamicPrimary` 主题色圆形背景
- 📏 **行高优化** — message 文本 `height: 1.5` 提升可读性

#### 增强LoadingIndicator
- 💎 **毛玻璃卡片包裹** — 新增 `useGlassCard` 参数
- 🎯 **主题色指示器** — 使用 `DesignTokens.dynamicPrimary` 替代 ThemeService 直接引用
- 📐 **centered参数** — 支持非居中场景（如列表底部加载更多）

## [0.91.18] - 2026-04-13

### 🎨 修复主题色切换全局不生效 + 统一动态主题色引用

#### 核心Bug修复
- 🎨 **主题色切换全局不生效** — 根因：UI组件使用 `DesignTokens.primary`（静态常量）而非 `DesignTokens.dynamicPrimary`（动态读取ThemeService）
  - 批量替换 `isDark ? DarkDesignTokens.primary : DesignTokens.primary` → `DesignTokens.dynamicPrimary`（34个文件）
  - 批量替换 `DesignTokens.primary` → `DesignTokens.dynamicPrimary`（33个文件，排除design_tokens.dart定义和theme_service.dart默认值）
  - 修复 `DarkDesignTokens.dynamicPrimary` 误替换为 `DesignTokens.dynamicPrimary`（5个文件）
  - 修复 `const` 上下文错误：移除包含 `dynamicPrimary` 的 `const` 构造函数关键字
  - 修复默认参数值错误：`AppProgressBar.color` 和 `NutritionLineChart.lineColor` 改为可空+初始化列表

#### 影响范围
- 全部59个dart文件中的439处 `DesignTokens.primary` / `DarkDesignTokens.primary` 引用
- 主题色切换现在能即时生效于所有页面

## [0.91.17] - 2026-04-13

### 📝 文档更新：页面结构分析 + 视图文件引用

#### 核心变更
- 📊 **新增页面结构分析文档** — `docs/dev/PAGE_STRUCTURE_ANALYSIS.md`（新建）
  - 全局导航图：MainTabView → 首页/发现/工具/我的 四大Tab
  - 12个页面详细结构图（文本符号可视化）
  - 每个页面跳转关系表（触发元素/跳转方式/目标页面/路由/传参）
  - 美观问题分析（严重度分级：🟡高/🟡中/🟢低）
  - 功能缺失清单（优先级P1-P3）
  - 全局美观/功能问题汇总

- 📄 **页面视图文件引用** — `docs/dev/PAGE_STRUCTURE_ANALYSIS.md`
  - 为每个页面添加"📄 页面视图文件"章节
  - 仅展示前2个关联视图文件（主页面+核心组件/控制器）
  - 涵盖：首页/发现/搜索/高级搜索/菜品详情/工具中心/我的/食材详情/分类浏览/标签列表/热门排行/今天吃什么

- 📋 **压缩未完成功能清单** — `docs/dev/UNFINISHED_FEATURES.md`
  - 从~600行压缩至~130行
  - 聚焦未完成任务，已完成阶段仅保留汇总

## [0.91.16] - 2026-04-13

### ✨ 搜索功能修复 + 高级搜索 + 食材详情返回首页

#### 核心变更
- 🔍 **修复搜索功能** — `lib/src/controllers/search_controller.dart`
  - 切换到 `api_filter.php?act=global_search` 接口，解决搜索无结果问题
  - 新增4类搜索结果：recipeResults/ingredientResults/tasteTagResults/cookingTagResults
  - 新增 SearchIngredientResult 模型解析食材搜索结果
  - 新增 `totalResultCount`/`hasAnyResult`/`_autoSelectTab` 便捷方法
  - 新增 `searchByFilter()` 支持高级筛选搜索

- 📑 **搜索结果分Tab展示** — `lib/src/pages/home/search_page.dart`
  - 搜索结果动态Tab：📖 菜谱 / 🥬 食材 / 👅 口味 / 🍳 工艺
  - 每个Tab显示结果数量徽章
  - 自动选择有结果的Tab
  - 导航栏增加高级搜索入口（⚙️ slider_horizontal_3图标）
  - 食材结果卡片显示分类名和菜谱数量
  - 口味/工艺标签结果使用2列网格布局

- ⚙️ **新增高级搜索页面** — `lib/src/pages/home/advanced_search_page.dart`（新建）
  - 4个筛选维度：📂 菜谱分类 / 👅 口味标签 / 🍳 工艺标签 / 🕐 用餐时段
  - 支持多条件组合筛选
  - 支持重置筛选条件
  - 底部搜索按钮调用 searchByFilter() 执行筛选

- 🔌 **Repository新增接口** — `lib/src/repositories/recipe_repository.dart`
  - `fetchMainCategories()`: 获取菜谱大类列表（调用 recipe_main_categories 接口）

- 🛤️ **新增路由** — `lib/src/config/app_routes.dart`
  - 新增 `advancedSearch` 路由（/advanced-search）

- 🏠 **食材详情返回首页** — `lib/src/pages/tools/ingredient_detail_page.dart`
  - 底部按钮从"返回列表"改为"返回首页"
  - 使用 `Get.until((route) => route.isFirst)` 返回根路由

- 📦 **CategoryModel增强** — `lib/src/models/recipe/category_model.dart`
  - fromJson 支持 `recipe_count` 字段映射到 count

## [0.91.15] - 2026-04-13

### ✨ 发现页推荐Tab新增口味/工艺筛选 + 分类导航修复

#### 核心变更
- 👅 **推荐Tab新增口味筛选** — `lib/src/pages/discover/discover_page.dart`
  - GlassSegmentedControl 从2段扩展为4段：📖 菜谱 / 🥬 食材 / 👅 口味 / 🍳 工艺
  - 口味Tab显示口味标签网格（3列），点击跳转 TagRecipeListPage
  - 工艺Tab显示工艺标签网格（3列），点击跳转 TagRecipeListPage

- 🏷️ **标签网格UI** — `lib/src/pages/discover/discover_page.dart`
  - 新增 `_buildTagGrid` 方法，3列紧凑布局，圆角卡片+边框
  - 空状态显示🏷️图标+"暂无标签数据"
  - 点击标签传递 tagName/tagId/tagType 到 TagRecipeListPage

- 📂 **分类网格重构** — `lib/src/pages/discover/discover_page.dart`
  - 提取 `_buildCategoryGrid` 方法，与标签网格分离
  - 提取 `_buildRecommendContent` 方法，根据tab索引切换内容

- 🔌 **Repository新增筛选接口** — `lib/src/repositories/recipe_repository.dart`
  - `fetchTasteTags()`: 获取口味标签列表
  - `fetchCookingTags()`: 获取工艺标签列表
  - `filterRecipesByTag()`: 按口味/工艺/分类筛选菜谱

- 🐛 **分类导航修复** — `lib/src/pages/discover/category_browse_page.dart`
  - 修复点击菜谱/食材分类闪退问题（BOTTOM OVERFLOWED）
  - 使用 CustomScrollView + SliverList 替代 Column + Expanded

## [0.91.14] - 2026-04-13

### ✨ 菜品详情页功能完善 — 评分显示 + 交互跳转

#### 核心变更
- ⭐ **新增 RecipeRating 模型** — `lib/src/models/recipe/recipe_model.dart`
  - 对齐 API v2.8.0 rating 字段：score/nums/display/status/level/star
  - 支持评分状态判断（none/few/normal/sufficient/abnormal）
  - 支持评分等级判断（优秀/推荐/一般/较差/不推荐）
  - 提供 `displayText`/`hasRating` 等便捷属性

- 📊 **更新 RecipeStatistics 模型** — `lib/src/models/recipe/recipe_model.dart`
  - 新增 `rateNums`/`rateScore` 字段，替代旧的 `recommends`/`recommendScore`
  - 新增 `rating` (RecipeRating?) 字段
  - 旧字段标记为 `@Deprecated`，保持向后兼容
  - fromJson 兼容 `rate_nums`/`recommends`/`recommend_count` 多种API字段名

- 📈 **重构 RecipeStatisticsBar** — `lib/src/widgets/recipe_detail/recipe_statistics_bar.dart`
  - 评分列从"⭐推荐"改为星级+评分文本+等级标签
  - 5星评级显示（CupertinoIcons.star_fill/star）
  - 评分等级彩色标签（🌟金色优秀/⭐蓝色推荐/✨灰色一般/⚠️红色较差）
  - 无评分时显示灰色星星+"暂无评分"

- 🖼️ **更新 RecipeCoverImage** — `lib/src/widgets/recipe_detail/recipe_cover_image.dart`
  - 封面图叠加层新增评分徽章（⭐ 4.5）
  - 有评分时显示评分徽章，无评分时显示热度标签
  - 评分等级对应不同徽章颜色

- 🏷️ **标签点击跳转** — `lib/src/widgets/recipe_detail/recipe_tags_section.dart`
  - 点击标签跳转到 TagRecipeListPage
  - 标签添加 chevron_right 图标提示可点击

- 📂 **分类面包屑点击跳转** — `lib/src/widgets/recipe_detail/recipe_category_breadcrumb.dart`
  - 非末级分类可点击跳转到 CategoryBrowsePage
  - 末级分类高亮不可点击
  - 面包屑项添加 chevron_right 图标提示可点击

- 🔄 **RecipeDetailPage 传递 rating** — `lib/src/pages/home/recipe_detail_page.dart`
  - RecipeCoverImage 和 RecipeStatisticsBar 接收 rating 参数

#### 文档更新
- 📋 更新 `docs/dev/UNFINISHED_FEATURES.md` 新增阶段二十九：菜品详情页功能完善

> 📌 已移除更早版本记录(0.91.13及之前)，功能已归档至软件特性清单。