Smart Meal (智能饮食助手)

项目简介

Smart Meal 是一个面向普通健康饮食用户与家庭场景的智能饮食助手。

它要解决的不是“专业营养诊疗”问题，而是更日常的问题：

• 今天吃什么
• 怎么吃得更省心、更均衡
• 家里多人吃饭时，怎样给出更合理的菜品组合
• 用户想同时拿到菜谱、买菜清单和基础营养解释

项目当前处于：

需求澄清与文档完善阶段

当前优先稳定产品边界、核心规则、内容规范和数据定义，暂不进入完整架构与编码阶段。

首版核心价值

• 自动生成家常、可执行的一日三餐
• 支持按人数推荐多道菜组合
• 支持基础不吃食材过滤
• 提供菜谱、购物清单、食物库和营养知识库
• 提供简短推荐理由，帮助用户理解结果
• 以“全天营养均衡”为核心设计原则
• 支持 L1 离线查看最近内容

产品目标

本项目不追求：

• 医疗级营养建议
• 精确饮食控制
• 复杂个性化处方

本项目提供的是：

“简单、可执行、相对均衡”的日常饮食方案

核心模块

系统由以下模块组成：

1. Meal Plan：一日三餐推荐结果
2. Meal Item：推荐最小单位，也是营养与购物清单计算单位
3. Recipe：部分 meal item 的可选详情层
4. Shopping List：今日三餐对应的买菜清单
5. Food Library：食物视角的轻量营养内容
6. Nutrition Knowledge：营养素视角的轻量知识内容

核心设计原则

• 推荐最小单位是 meal item
• 并非所有 meal item 都有 recipe
• 营养策略以“全天均衡”为主，单餐只要求基础合理
• 多人用餐通过“多菜组合 + 克重调整”实现
• 早餐采用预定义组合
• 首版优先做简单、稳定、可落地的方案

当前确定的首版范围

请优先参考 docs/01_PRODUCT_SCOPE.md，当前已明确的重点包括：

• 每日三餐生成
• 每天最多刷新 3 次，且按“整天”刷新
• 支持 1~4 人用餐场景
• 一餐最多 4 个 meal items
• 支持基础不吃食材过滤
• 支持简短推荐理由
• 支持最近 7 天历史 day plan 浏览
• 今日购物清单
• 食物库首版 30~50 个高频食物
• 营养知识库首版 10~20 个高频营养素
• L1 离线支持

当前不做

以下功能不在首版范围：

• 单餐替换
• 锁定某道菜
• 一周营养总结
• 收藏 / 账号系统
• 小程序首发
• L2 离线生成
• 社区 / 评论 / UGC
• 医疗建议与疾病管理

文档阅读顺序

请按顺序阅读：

1. docs/00_PROJECT_OVERVIEW.md
2. docs/01_PRODUCT_SCOPE.md
3. docs/02_CORE_RULES.md
4. docs/03_GLOSSARY.md
5. docs/04_DATA_MODEL.md
6. docs/05_MEAL_ITEM_SPEC.md

文档优先级规则

当文档冲突时：

1. docs/15_DECISIONS.md
2. docs/02_CORE_RULES.md
3. 其他文档

项目结构

project/
├─ docs/
├─ data/
├─ backend/
├─ apps/
│  ├─ web/
│  └─ mobile/
└─ assets/

各目录职责：

• docs/：项目当前阶段最重要的事实来源，存放需求、规则、数据定义、内容规范和决策记录
• data/：存放录入模板、种子数据和映射数据
• backend/：后续后端接口、推荐逻辑、数据访问与聚合逻辑所在目录
• apps/web/：Web 端应用目录，后续承载首页、历史浏览、详情页等页面
• apps/mobile/：Mobile 端应用目录，后续复用同一套业务规则与接口
• assets/：图片、步骤图、提示词等非代码资源目录

Python 环境管理

项目当前统一使用 uv 管理 Python 环境与后续 Python 相关依赖。

当前约定：

• Python 版本固定为 3.12
• 根目录的 .venv/ 作为本地虚拟环境
• 使用 pyproject.toml 作为 Python 项目管理入口
• 不在项目中混用 pip、virtualenv 或手工创建的其他环境

常用命令：

uv sync
uv run python3 --version
uv add <package>
uv add --dev <package>

说明：

• 当前仓库还未进入完整后端开发阶段，因此依赖列表保持最小
• 后续凡是 Python 脚本、数据处理工具、后端服务，都应优先通过 uv 运行和管理