smartplate 1.0.0__py3-none-any.whl

smartplate/advice_engine.py

@@ -0,0 +1,460 @@
+"""
+advice_engine.py - 个性化建议生成模块
+基于《中国居民膳食指南 2022》的膳食参考摄入量（DRI）规则引擎
+支持用户画像参数：性别、年龄、体重、活动水平、健康目标
+"""
+
+from typing import Any
+
+# ============================================================
+# 膳食参考摄入量（DRI）基准值
+# 数据来源：《中国居民膳食营养素参考摄入量（2023版）》
+# ============================================================
+
+# 基础能量需求（kcal/天），按性别和年龄段
+# 轻体力活动水平
+ENERGY_RDA = {
+    "male": {
+        (18, 50): 2250,
+        (50, 65): 2100,
+        (65, 80): 1950,
+    },
+    "female": {
+        (18, 50): 1800,
+        (50, 65): 1750,
+        (65, 80): 1600,
+    },
+}
+
+# 活动水平系数（乘在基础能量上）
+ACTIVITY_FACTOR = {
+    "sedentary": 0.95,
+    "light": 1.0,
+    "moderate": 1.15,
+    "active": 1.3,
+}
+
+# 宏量营养素推荐供能比
+MACRO_RATIO = {
+    "carbs": (0.50, 0.65),   # 碳水供能比 50%-65%
+    "protein": (0.10, 0.15), # 蛋白质供能比 10%-15%
+    "fat": (0.20, 0.30),     # 脂肪供能比 20%-30%
+}
+
+# 每克宏量营养素的热量
+KCAL_PER_GRAM = {"carbs": 4, "protein": 4, "fat": 9}
+
+# 微量元素每日推荐摄入量（18-50岁成人）
+MICRO_RDA = {
+    "calcium_mg": 800,
+    "iron_mg": (12, 20),       # (男, 女)
+    "zinc_mg": (12.5, 7.5),
+    "magnesium_mg": 330,
+    "potassium_mg": 2000,
+    "fiber_g": 25,
+}
+
+# 特殊人群的调整系数
+GOAL_ADJUSTMENTS: dict[str, dict[str, Any]] = {
+    "diabetes": {
+        "carbs_max_per_meal": 60,      # 每餐碳水上限(g)
+        "gi_limit": 55,                 # GI 上限
+        "gl_max_per_meal": 40,          # 每餐血糖负荷(GL)上限
+        "fiber_target_per_meal": 8,     # 每餐膳食纤维目标(g)
+        "prefer_low_gi": True,
+        "description": "糖尿病/血糖控制",
+    },
+    "weight_loss": {
+        "calorie_deficit": 0.75,        # 热量系数（75%日常需求）
+        "protein_min_per_meal": 25,     # 每餐蛋白质下限(g)
+        "fat_max_per_meal": 20,         # 每餐脂肪上限(g)
+        "description": "减脂/体重控制",
+    },
+    "muscle_gain": {
+        "calorie_surplus": 1.1,         # 热量系数（110%日常需求）
+        "protein_min_per_meal": 30,     # 每餐蛋白质下限(g)
+        "carbs_min_per_meal": 60,       # 每餐碳水下限(g)
+        "description": "增肌/力量训练",
+    },
+    "general": {
+        "description": "日常健康饮食",
+    },
+}
+
+# 建议知识库（按营养素和状态组织）
+ADVICE_KNOWLEDGE = {
+    "carbs_high": "碳水化合物偏高，建议适当减少主食份量，或选择低GI替代品（如糙米代替白米、全麦面包代替白面包）。",
+    "carbs_low": "碳水化合物摄入偏少，运动后可适量补充复合碳水（如红薯、燕麦）。",
+    "protein_high": "蛋白质充足，有利于肌肉合成和饱腹感维持。",
+    "protein_low": "蛋白质偏低，建议增加瘦肉、鱼虾、蛋类、豆制品的摄入。",
+    "fat_high": "脂肪摄入偏高，建议选择清淡烹饪方式（蒸、煮、炖），减少油炸和高脂食材。",
+    "fat_low": "脂肪摄入偏低，适量摄入优质脂肪（坚果、橄榄油、鱼油）有益健康。",
+    "calories_high": "此餐热量偏高，注意控制份量，多吃蔬菜增加饱腹感。",
+    "calories_low": "此餐热量偏低，可适量增加主食或蛋白质食物。",
+    "fiber_low": "膳食纤维不足，建议增加蔬菜、全谷物、豆类的摄入。",
+    "fiber_high": "膳食纤维充足，有助于肠道健康和血糖稳定。",
+    "gl_high": "本餐血糖负荷(GL)偏高，即使单种食物GI不高，大量碳水化合物仍会显著升高血糖。建议减少主食份量或分餐食用。",
+    "gl_moderate": "本餐血糖负荷(GL)中等，注意搭配蛋白质和蔬菜一起食用以减缓血糖上升速度。",
+    "gl_low": "本餐血糖负荷(GL)较低，对血糖影响较小。",
+}
+
+
+# ============================================================
+# 用户画像
+# ============================================================
+def get_user_rda(gender: str = "male", age: int = 30, activity: str = "light",
+                 goal: str = "general") -> dict:
+    """
+    根据用户画像计算个性化每日推荐摄入量
+    :param gender: 'male' 或 'female'
+    :param age: 年龄
+    :param activity: 'sedentary' / 'light' / 'moderate' / 'active'
+    :param goal: 'general' / 'diabetes' / 'weight_loss' / 'muscle_gain'
+    :return: 每日推荐摄入量字典
+    """
+    # 基础能量
+    base_energy = 2000
+    for (lo, hi), val in ENERGY_RDA.get(gender, ENERGY_RDA["male"]).items():
+        if lo <= age < hi:
+            base_energy = val
+            break
+
+    # 活动水平调整
+    act_factor = ACTIVITY_FACTOR.get(activity, 1.0)
+    daily_energy = base_energy * act_factor
+
+    # 目标调整
+    goal_config: dict[str, Any] = GOAL_ADJUSTMENTS.get(goal, GOAL_ADJUSTMENTS["general"])
+    if "calorie_deficit" in goal_config:
+        daily_energy *= goal_config["calorie_deficit"]
+    elif "calorie_surplus" in goal_config:
+        daily_energy *= goal_config["calorie_surplus"]
+
+    # 宏量营养素
+    carbs_kcal = daily_energy * (MACRO_RATIO["carbs"][0] + MACRO_RATIO["carbs"][1]) / 2
+    protein_kcal = daily_energy * (MACRO_RATIO["protein"][0] + MACRO_RATIO["protein"][1]) / 2
+    fat_kcal = daily_energy * (MACRO_RATIO["fat"][0] + MACRO_RATIO["fat"][1]) / 2
+
+    daily_carbs = carbs_kcal / KCAL_PER_GRAM["carbs"]
+    daily_protein = protein_kcal / KCAL_PER_GRAM["protein"]
+    daily_fat = fat_kcal / KCAL_PER_GRAM["fat"]
+
+    return {
+        "daily_energy_kcal": round(daily_energy),
+        "daily_carbs_g": round(daily_carbs, 1),
+        "daily_protein_g": round(daily_protein, 1),
+        "daily_fat_g": round(daily_fat, 1),
+        "daily_fiber_g": MICRO_RDA["fiber_g"],
+        "goal": goal,
+        "goal_description": goal_config.get("description", ""),
+        "goal_config": goal_config,
+    }
+
+
+def per_meal_rda(rda: dict, meals_per_day: int = 3) -> dict:
+    """将每日 RDA 转换为每餐目标"""
+    return {
+        "energy_kcal": round(rda["daily_energy_kcal"] / meals_per_day),
+        "carbs_g": round(rda["daily_carbs_g"] / meals_per_day, 1),
+        "protein_g": round(rda["daily_protein_g"] / meals_per_day, 1),
+        "fat_g": round(rda["daily_fat_g"] / meals_per_day, 1),
+        "fiber_g": round(rda["daily_fiber_g"] / meals_per_day, 1),
+    }
+
+
+# ============================================================
+# 营养分析
+# ============================================================
+def analyze_nutrition(totals: dict, per_meal_targets: dict,
+                      goal_config: dict) -> list[dict]:
+    """
+    将本餐营养数据与每餐目标对比，输出每个指标的分析
+    :return: 分析结果列表，每项包含 {nutrient, label, value, target, status, percentage, message}
+    """
+    results = []
+
+    # 碳水
+    carbs = totals.get("carbs_g", 0)
+    target_carbs = per_meal_targets.get("carbs_g", 80)
+    # 控糖目标单独限制
+    if "carbs_max_per_meal" in goal_config:
+        target_carbs = min(target_carbs, goal_config["carbs_max_per_meal"])
+
+    carbs_ratio = carbs / max(target_carbs, 1) * 100
+    if carbs_ratio > 130:
+        status, msg_key = "high", "carbs_high"
+    elif carbs_ratio < 50:
+        status, msg_key = "low", "carbs_low"
+    else:
+        status, msg_key = "normal", ""
+
+    results.append({
+        "nutrient": "carbohydrate",
+        "label": "碳水化合物",
+        "value": round(carbs, 1),
+        "unit": "g",
+        "target": round(target_carbs, 1),
+        "status": status,
+        "percentage": round(carbs_ratio),
+        "message": ADVICE_KNOWLEDGE.get(msg_key, ""),
+    })
+
+    # 蛋白质
+    protein = totals.get("protein_g", 0)
+    target_protein = per_meal_targets.get("protein_g", 25)
+    if "protein_min_per_meal" in goal_config:
+        target_protein = max(target_protein, goal_config["protein_min_per_meal"])
+
+    protein_ratio = protein / max(target_protein, 1) * 100
+    if protein_ratio > 150:
+        status, msg_key = "high", "protein_high"
+    elif protein_ratio < 60:
+        status, msg_key = "low", "protein_low"
+    else:
+        status, msg_key = "normal", ""
+
+    results.append({
+        "nutrient": "protein",
+        "label": "蛋白质",
+        "value": round(protein, 1),
+        "unit": "g",
+        "target": round(target_protein, 1),
+        "status": status,
+        "percentage": round(protein_ratio),
+        "message": ADVICE_KNOWLEDGE.get(msg_key, ""),
+    })
+
+    # 脂肪
+    fat = totals.get("fat_g", 0)
+    target_fat = per_meal_targets.get("fat_g", 18)
+    if "fat_max_per_meal" in goal_config:
+        target_fat = goal_config["fat_max_per_meal"]
+
+    fat_ratio = fat / max(target_fat, 1) * 100
+    if fat_ratio > 150:
+        status, msg_key = "high", "fat_high"
+    elif fat_ratio < 30:
+        status, msg_key = "low", "fat_low"
+    else:
+        status, msg_key = "normal", ""
+
+    results.append({
+        "nutrient": "fat",
+        "label": "脂肪",
+        "value": round(fat, 1),
+        "unit": "g",
+        "target": round(target_fat, 1),
+        "status": status,
+        "percentage": round(fat_ratio),
+        "message": ADVICE_KNOWLEDGE.get(msg_key, ""),
+    })
+
+    # 热量
+    calories = totals.get("calories", 0)
+    target_calories = per_meal_targets.get("energy_kcal", 600)
+
+    cal_ratio = calories / max(target_calories, 1) * 100
+    if cal_ratio > 130:
+        status, msg_key = "high", "calories_high"
+    elif cal_ratio < 50:
+        status, msg_key = "low", "calories_low"
+    else:
+        status, msg_key = "normal", ""
+
+    results.append({
+        "nutrient": "calories",
+        "label": "热量",
+        "value": round(calories),
+        "unit": "kcal",
+        "target": round(target_calories),
+        "status": status,
+        "percentage": round(cal_ratio),
+        "message": ADVICE_KNOWLEDGE.get(msg_key, ""),
+    })
+
+    # 膳食纤维
+    fiber = totals.get("fiber_g", 0)
+    target_fiber = per_meal_targets.get("fiber_g", 8)
+    if "fiber_target_per_meal" in goal_config:
+        target_fiber = goal_config["fiber_target_per_meal"]
+
+    fiber_ratio = fiber / max(target_fiber, 1) * 100
+    if fiber_ratio > 80:
+        status, msg_key = "normal", "fiber_high"
+    else:
+        status, msg_key = "low", "fiber_low"
+
+    results.append({
+        "nutrient": "fiber",
+        "label": "膳食纤维",
+        "value": round(fiber, 1),
+        "unit": "g",
+        "target": round(target_fiber, 1),
+        "status": status,
+        "percentage": round(fiber_ratio),
+        "message": ADVICE_KNOWLEDGE.get(msg_key, ""),
+    })
+
+    # 血糖负荷（GL = GI × 碳水克数 / 100，仅控糖模式展示）
+    if "gl_max_per_meal" in goal_config:
+        gl = totals.get("glycemic_load", 0)
+        # 如果 totals 没有预计算 GL，用平均 GI 估算
+        if gl == 0 and carbs > 0:
+            avg_gi = totals.get("avg_gi", 50)
+            gl = avg_gi * carbs / 100.0
+        target_gl = goal_config["gl_max_per_meal"]
+        gl_ratio = gl / max(target_gl, 1) * 100
+        if gl_ratio > 130:
+            gl_status, gl_key = "high", "gl_high"
+        elif gl_ratio > 80:
+            gl_status, gl_key = "normal", "gl_moderate"
+        else:
+            gl_status, gl_key = "normal", "gl_low"
+
+        results.append({
+            "nutrient": "glycemic_load",
+            "label": "血糖负荷(GL)",
+            "value": round(gl, 1),
+            "unit": "",
+            "target": round(target_gl, 1),
+            "status": gl_status,
+            "percentage": round(gl_ratio),
+            "message": ADVICE_KNOWLEDGE.get(gl_key, ""),
+        })
+
+    return results
+
+
+# ============================================================
+# 建议生成（主入口）
+# ============================================================
+def _generate_pairing_advice(totals: dict, goal: str, goal_config: dict) -> list[str]:
+    """基于食物搭配原理生成针对性建议"""
+    tips = []
+    protein = totals.get("protein_g", 0)
+    fiber = totals.get("fiber_g", 0)
+    gl = totals.get("glycemic_load", 0)
+
+    if goal == "diabetes":
+        # 食物搭配协同效应分析
+        gl_limit = goal_config.get("gl_max_per_meal", 40)
+        if gl > gl_limit:
+            if protein >= 20 and fiber >= 5:
+                tips.append("💡 蛋白质+纤维组合可降低本餐的血糖冲击，实测餐后血糖峰值可比纯碳水饮食低30-50%。")
+            if fiber < 5:
+                tips.append("💡 搭配建议：增加一份绿叶蔬菜（如西兰花、菠菜），纤维可与碳水结合减缓吸收。")
+            if protein < 15:
+                tips.append("💡 搭配建议：增加一份瘦肉/鱼虾/豆腐，蛋白质可延缓胃排空速度。")
+
+        # 低GI替代建议
+        avg_gi = totals.get("avg_gi", 0)
+        if avg_gi > goal_config.get("gi_limit", 55):
+            tips.append("💡 主食替换：尝试用糙米饭(GI≈55)替代白米饭(GI≈73)，或用全麦面包替代白面包，可降低升糖速度。")
+
+        # 好组合表扬
+        if 0 < gl <= gl_limit and fiber >= 5 and protein >= 15:
+            tips.append("✅ 本餐搭配合理：碳水、蛋白质、纤维均衡，有利于血糖平稳。")
+
+    return tips
+
+
+def generate_advice(totals: dict, user_type: str,
+                    gender: str = "male", age: int = 30,
+                    activity: str = "light") -> dict:
+    """
+    生成个性化饮食建议
+    :param totals: 总营养数据字典
+    :param user_type: 'general' / 'diabetes' / 'weight_loss' / 'muscle_gain'
+    :param gender: 'male' / 'female'
+    :param age: 年龄
+    :param activity: 'sedentary' / 'light' / 'moderate' / 'active'
+    :return: 包含建议文本和分析详情的字典
+    """
+    # 向后兼容：旧的 user_type 映射
+    goal_map = {
+        "diabetes": "diabetes",
+        "fitness": "muscle_gain",
+        "general": "general",
+    }
+    goal = goal_map.get(user_type, user_type)
+
+    # 获取用户 RDA
+    rda = get_user_rda(gender, age, activity, goal)
+    meal_targets = per_meal_rda(rda)
+    goal_config = rda["goal_config"]
+
+    # 逐项分析
+    analysis = analyze_nutrition(totals, meal_targets, goal_config)
+
+    # 生成文本建议
+    lines = [f"【{rda['goal_description']}】本餐分析（目标 {meal_targets['energy_kcal']} kcal/餐）"]
+
+    warnings = []
+    goods = []
+    for a in analysis:
+        if a["status"] == "high":
+            warnings.append(f"⚠️ {a['label']}: {a['value']}{a['unit']} / 目标 {a['target']}{a['unit']} ({a['percentage']}%)")
+        elif a["status"] == "low":
+            warnings.append(f"↓ {a['label']}: {a['value']}{a['unit']} / 目标 {a['target']}{a['unit']} ({a['percentage']}%)")
+        else:
+            goods.append(f"✓ {a['label']}: {a['value']}{a['unit']}（达标）")
+
+    if goods:
+        lines.extend(goods)
+    if warnings:
+        lines.append("")
+        lines.extend(warnings)
+
+    # 针对性建议
+    specific_advice = []
+    for a in analysis:
+        if a["message"]:
+            specific_advice.append(f"💡 {a['message']}")
+
+    # 动态食物搭配建议（基于实际营养构成）
+    pairing_advice = _generate_pairing_advice(totals, goal, goal_config)
+    if pairing_advice:
+        specific_advice.extend(pairing_advice)
+
+    if goal == "diabetes":
+        # 动态进餐顺序建议
+        carbs_val = totals.get("carbs_g", 0)
+        protein_val = totals.get("protein_g", 0)
+        fiber_val = totals.get("fiber_g", 0)
+        fat_val = totals.get("fat_g", 0)
+
+        if carbs_val > goal_config.get("carbs_max_per_meal", 60):
+            if protein_val >= 15 and fiber_val >= 4:
+                specific_advice.append("💡 本餐碳水较高但蛋白质和纤维充足：先吃蔬菜→再吃蛋白质→最后吃主食，可降低餐后血糖峰值30-40%。")
+            elif fiber_val >= 4:
+                specific_advice.append("💡 先吃蔬菜摄入膳食纤维，再吃主食，纤维可延缓糖分吸收、平稳血糖。")
+            elif protein_val >= 15:
+                specific_advice.append("💡 先吃蛋白质食物，再吃主食。蛋白质可延缓胃排空，减缓血糖上升速度。")
+            else:
+                specific_advice.append("💡 本餐碳水偏高且缺乏蛋白质和纤维配合，建议增加蔬菜和瘦肉来搭配主食，降低血糖冲击。")
+        elif fiber_val >= 5:
+            specific_advice.append("💡 本餐膳食纤维充足，搭配碳水一起食用可有效延缓血糖上升。")
+        if fat_val > 20:
+            specific_advice.append("💡 高脂肪会延迟但延长血糖升高，控糖人群应注意脂肪总摄入量。")
+    elif goal == "weight_loss":
+        specific_advice.append("💡 减脂建议：细嚼慢咽，每餐不少于20分钟，增加饱腹感。")
+    elif goal == "muscle_gain":
+        specific_advice.append("💡 增肌建议：训练后30分钟内补充蛋白质+碳水，促进肌肉合成。")
+
+    if specific_advice:
+        lines.append("")
+        lines.extend(specific_advice)
+
+    return {
+        "advice_text": "\n".join(lines),
+        "user_profile": {
+            "gender": gender,
+            "age": age,
+            "activity": activity,
+            "goal": goal,
+            "goal_description": rda["goal_description"],
+        },
+        "daily_rda": rda,
+        "per_meal_targets": meal_targets,
+        "analysis": analysis,
+    }