Skip to content

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

🏸 菜篮盲盒系统 (Health Helper) - 用户使用手册

本手册详细说明了"菜篮盲盒 App"的各项功能模块、核心交互逻辑以及进阶使用技巧,帮助你(及任何使用者)快速掌握该系统。


👤 0. 个人信息与每日营养目标

页面顶部提供一张【个人信息】卡片,用于采集你的身体数据并实时估算每日能量与营养摄入目标,为后续科学配餐提供量化参考。

功能说明:

  • 信息录入:支持填写 性别(男/女切换)、年龄、身高 (cm)、体重 (kg)。所有数据静默持久化到本地,刷新或重进不丢失。
  • BMI 智能分级:依据 体重 / 身高² 实时计算 BMI,并按中国成人标准自动着色分级(偏瘦 / 正常 / 超重 / 肥胖)。
  • 每日热量估算:
    • 基础代谢 (BMR):采用国际通用的 Mifflin-St Jeor 方程,按性别分别计算。
    • 每日总消耗 (TDEE):在 BMR 基础上乘以活动系数,并与顶部【训练计划】的训练日/休息日状态联动——训练日按高活动量 (×1.725) 估算,休息日按轻活动量 (×1.375) 估算。
  • ✏️ 每日热量自定义:系统估算值仅作默认参考。点击"每日热量"卡片上的数值即可手动输入你的目标热量(回车或失焦保存,Esc 取消)。自定义生效后:
    • 卡片高亮为琥珀色描边并标注"· 自定义"。
    • 三大营养素会按你设定的热量重新换算(蛋白质按体重恒定,脂肪/碳水随热量浮动)。
    • 下方提供「恢复推荐值」一键还原为系统估算。
    • 自定义值持久化到本地,刷新不丢失。
  • 三大营养素目标:自动拆解每日建议的 碳水 / 蛋白质 / 脂肪 克数(蛋白质按运动员标准 1.8g/kg 体重,脂肪占总热量 25%,碳水补足剩余热量)。
  • 智能显隐:年龄、身高、体重任一未填写时,结果区自动隐藏并给出填写提示,填写完整后即时浮现。

📅 1. 核心功能:智能餐次转盘 (老虎机模块)

该模块为你提供一日三餐(早餐、午餐、晚餐)的饮食建议。它的核心是一套带有高度拟真物理"阻尼回落"感的老虎机转盘系统。

功能说明:

  • 一键随机抽签:点击主页面的 一键随机 按钮,三餐转盘将同时启动并在 3 秒内陆续停止,向你输出基于当前库存的随机有效菜谱。
  • 单餐独立重抽:如果对某一餐的随机结果不满意,直接点击该餐次所在的老虎机显示框,即可针对该单餐进行独立重抽。
  • 锁定心仪餐次 (锁定机制):老虎机右侧带有一个 🔓/🔒 锁扣图标。如果你对当前的午餐非常满意,可以点击锁扣将其锁定 (🔒)。此时再点击"一键随机",被锁定的餐次将不再变动。
  • 菜谱详情直达:老虎机停稳后,下方会展示该菜谱的关键配料明细。点击该区域可弹出详细的烹饪步骤和宏量营养素参考指标。
  • 空池物理拦截:当某个餐次的奖池中没有任何可抽取的菜谱时,系统会物理阻断转盘动画并弹出友好提示,防止出现空转盘的尴尬体验。

🛒 2. 库存控制:高级食材管理面板

转盘能抽出什么菜,完全取决于你在【食材管理】面板中的勾选状态。该模块采用了高度直觉化的"分类治之"交互架构。

2.1 状态与库存联动

  • 勾选入池:食材必须被勾选(渲染为高亮绿色),所有依赖该食材的预设菜谱才会被合法释放进入这顿餐次的老虎机奖池。
  • 批量操作:每个大类(如"蛋白质"、"碳水")右上角均附带轻量级的「全选」与「全不选」交互文字,让你能在采购日一次性补齐对应分类状态。

2.2 🔍 全局搜索 (实时检索)

  • 搜索栏:面板顶部固定悬浮一个带 🔍 图标的搜索框,Placeholder 为 搜索食材...。
  • 实时防抖过滤:输入关键词后,系统在 300ms 防抖延迟后自动触发实时匹配。下方视图从原本的"分类折叠"瞬间切换为扁平化的**"搜索结果平铺列表"**,每个结果条目的右侧附带轻量分类角标(如 [蛋白质])。
  • 即时勾选同步:你可以直接在搜索结果中勾选/取消勾选食材,底层 selectedIngredients 与分类视图中的状态完全打通、实时同步。
  • 清空恢复:点击搜索框右侧的 ✕ 按钮清空输入后,列表瞬间恢复为原有的分类折叠视图。

2.3 自定义食材录入 (+)

  • 极简添加:点击对应分类名称右侧的 + 虚线框,即可呼出行内输入。
  • 自动归类:在此处输入的自定义食材,不仅会自动继承当前分类标签(绝不乱序),还会立刻勾选入库并进入系统奖池环境。

2.4 深度删除模式 (-) 与"软删除"

  • 进入删除模式:点击分类栏右上角的 - 虚线框,该分类将立刻进入红色警戒删除模式。此时你可以自由勾选想彻底踢出视野的食材,点击「确认」执行销毁。
  • 官方数据软删除安全阀:为保证引擎不出错,对于带有关联菜谱的"系统内置食材",系统会聪慧地执行"软隐藏"(仅做标记,不在界面展示)。不破坏整体菜谱的完整性。
  • 极客复活机制 (Name Sniffing):如果你后悔删除了某项官方预设食材(例如"鸡胸肉"),只需通过上述的 + 号重新手动输入"鸡胸肉",系统在匹配同名后,会智能解冻该官方数据并原地"复活",连带恢复关联的所有隐藏食谱。

📖 3. 菜谱管理面板

该模块将系统预设的 25+ 道官方菜谱与你自建的菜谱统一管理,并引入了「客观可用」与「主观意愿」的双层状态解耦机制。

3.1 状态解耦:可用 vs 选中

  • 客观可用 (isAvailable):当该菜谱所需的全部食材均已在食材面板中勾选时,卡片自动变为高亮态(无灰度遮罩),表示"你能做这道菜"。
  • 主观选中 (isSelected):卡片上的 ★/☆ 标志代表你的"心愿单"状态。★ 表示你主动希望这道菜进入转盘奖池。食材满足 ≠ 自动选中,两个状态完全独立,保障用户拥有完全的自主选择权。

3.2 🔍 全局搜索 (实时检索)

  • 搜索栏:面板顶部固定悬浮搜索框,Placeholder 为 搜索你想吃的菜...。
  • 实时防抖过滤:输入关键词(如"鸡")后,300ms 防抖自动触发,下方从分类折叠视图切换为跨分类的菜谱卡片平铺墙,每张卡片底部附带分类角标(如 [丰盛正餐])。
  • 即时交互同步:在搜索结果中点击可用菜谱直接 toggle ★/☆ 选中状态,点击灰色(不可用)菜谱则弹出"查缺补漏 Bottom Sheet"。

3.3 战术标签系统 (多维多选)

  • 多标签体系:每道菜谱可同时隶属于多个战术标签池(如 练前餐、练后餐、日常餐),数据字段 mealTag 为数组类型。
  • 智能分池逻辑:转盘根据当日训练状态自动判定餐次标签(如午餐 → 练后餐),然后使用 mealTag.includes(tag) 从全局扁平菜谱池中过滤匹配项。由于大量菜谱同时具备 [练后餐, 日常餐] 双重标签,奖池利用率得到极大提升。

3.4 转盘奖池的两级优先级

  • 第一优先级(主观):如果你在当前餐次手动 ★ 选中了菜谱,转盘奖池仅抓取这些选中项。
  • 第二优先级(智能降级):如果你没有手动选中任何该餐次的菜谱,系统自动降级为"全部客观可用菜谱"。

3.5 查缺补漏 Bottom Sheet

  • 逐个补充:点击灰色(不可用)菜谱卡片,弹出 Bottom Sheet 展示所有缺失食材。你可以逐个点击 + 食材名 将其快捷加入库存。
  • ⚡ 一键补齐缺料:点击 Bottom Sheet 右上角的绿色 ⚡ 一键补齐缺料 按钮,系统在一个事务中连续执行:① 批量注入所有缺失食材 → ② 自动将该菜谱加入心愿单 (★) → ③ 自动关闭弹窗。操作完成后,该菜谱瞬间变亮且被选中,转盘奖池立即收录。

3.6 新建自定义菜谱 (+)

  • 点击分类标题栏右侧的 + 触发新建菜谱弹窗。
  • 战术标签多选 (Pill Toggles):弹窗中的战术标签已从单选框升级为药丸式多选控件。点击 练前餐、练后餐、日常餐 标签可自由组合,系统会智能合并所有选中标签对应的适用餐段(如选中 练后餐 + 日常餐 → 自动覆盖早/午/晚三餐)。
  • 关联食材搜索:通过输入框实时搜索系统食材库,将所需食材关联至菜谱。

3.7 批量管理

  • 全选/全不选:每个分类标题栏提供「全选」(一键加入心愿单)和「全不选」(一键移出心愿单)操作。
  • 删除模式 (-):进入删除模式后可批量标记要移除的菜谱。

📱 4. 部署与环境说明

本应用程序属于现代化 PWA (Progressive Web App) 单页应用,所有数据依托于设备的本地持久层运作。

离线与极客体验

当你通过 Vercel 或手机自带的「添加到主屏幕」在手机端创建快捷方式后:

  • 具有防跳出、沉浸式状态栏体验。
  • 支持断网运作——应用核心计算、动画引擎均跑在本地缓存中无网络调控请求,即便是在网络信号极差的羽毛球场地下室或更衣室,照样能够零延迟运行。

🔧 常见排错与重置

由于应用具有高强度的无缝静默状态持久化(保存你的操作习惯不断联),如果你的数据发生错乱想要全面洗牌重来:

  1. 打开浏览器的开发者工具 (Desktop: F12)。
  2. 进入 Application -> Local Storage 选项卡,清空对应 LocalHost 或域名下的键值对;或者利用清空缓存重新载入。所有预设数据与黑名单池将恢复"出厂设置"。

🚀 5. 开发者部署指南 (For Developers)

如果你想在自己的机器上运行、进行二次开发,或是将其公共部署以便团队/他人使用,请遵循以下基于 Vue 3 + Vite 的标准工作流:

5.1 环境要求

  • Node.js: 请确保本地已安装 Node.js (推荐 v18.0.0 或最新长期支持版 LTS)。
  • Git: 用于版本控制和同步代码。

5.2 本地安装与启动

  1. 克隆代码库到本地

    git clone https://github.com/WAYKEN-TSE/health_helper.git
    cd health_helper
  2. 安装核心依赖项

    npm install
  3. 启动带热更新 (HMR) 的本地开发服务器

    npm run dev

    小贴士:控制台会输出一个 Local 地址 (如 http://localhost:5173) 供你在浏览器内开发。若需在手机上预览测试,在同一 Wi-Fi 下可强制输入 npm run dev -- --host 获取局域网 IP 并访问。

5.3 终态打包与公共部署

本应用完全作为离线友好的纯前端架构设计,绝不依赖任何传统后端数据库系统。你可以将其无缝"白嫖"托管到各大免费静态网站服务中:

  1. 生成高度压缩的静态资源目录

    npm run build

    执行完毕后,所有可用代码会被编译至工程下的 dist/ 文件夹中。你需要部署的仅仅是这一个文件夹里的产物。

  2. 主流云端一键托管方案推荐

    • Netlify (最简命令流):直接在控制台敲击 npx netlify-cli deploy --prod,授权登录并指向 dist 目录,2 分钟内即上线。
    • Vercel (最配 GitHub 行动):在 Vercel 官网关联你的 GitHub 仓库根目录,框架预设选择 Vite,每次你 git push 给主分支时,它都会自动化帮你走完 Build 并推送发布。
    • GitHub Pages:你可以通过 GitHub Actions 编写简单脚本将 dist 推至 gh-pages 分支做到站内免费分发。并且此举对于推广和 PWA 的直接挂载最为方便。

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages