基于用户画像的食谱推荐系统

1. 项目简介

这是一个基于 Flask + SQLite + 规则引擎 + 轻量机器学习的食谱推荐系统，面向课程设计/演示场景。
系统核心思路：

• 采集用户问卷与活动数据（步数、活动分钟）
• 构建用户特征向量并进行用户画像聚类
• 基于规则过滤和打分，再结合随机森林回归模型进行排序
• 输出可解释的推荐结果（规则命中原因 + 模型融合说明）

项目目标是提供一个可运行、可展示、可扩展的端到端闭环，而不是工业级推荐系统。

---

2. 技术栈

• 语言：Python 3.12.x
• Web 框架：Flask 3.x
• ORM：Flask-SQLAlchemy 3.x
• 登录认证：Flask-Login
• 数值计算：NumPy
• 机器学习：scikit-learn（KMeans、RandomForestRegressor）
• 前端：Jinja2 模板 + Bootstrap + ECharts
• 数据库：SQLite（默认 diet_recommend.db）
• 测试：pytest

依赖定义见 requirements.txt。

---

3. 项目目录结构

diet-recommend-system/
├── app.py                 # 应用入口
├── config.py              # 配置（密钥、数据库 URI、端口等）
├── requirements.txt
├── 项目说明.md
├── 测试说明.md
├── app/
│   ├── __init__.py        # 应用工厂
│   ├── cli.py             # Flask CLI（init-db、seed-data、evaluate 等）
│   ├── extensions.py      # db、login_manager
│   ├── models.py          # ORM 模型
│   ├── tag_labels.py      # 食谱标签中英文映射
│   ├── seed_recipes_data.py   # 演示食谱种子数据
│   ├── blueprints/
│   │   ├── auth.py        # 注册 / 登录 / 登出
│   │   └── main.py        # 工作台、问卷、推荐、活动等页面路由
│   └── services/
│       ├── preprocessing.py      # 问卷清洗、用户特征向量
│       ├── profile_builder.py      # 聚类、画像标签、同步写库
│       ├── recipe_engine.py        # 规则打分、混合推荐
│       ├── ml_train.py             # 随机森林训练与 ranker 模型文件
│       ├── evaluation.py           # 离线 Hit@K、NDCG
│       └── association_mining.py   # 标签共现（支持度）
├── templates/             # Jinja2 页面模板
├── static/                # 静态资源（CSS 等）
├── tests/                 # pytest
├── mac/                   # macOS 辅助脚本（部署与启动见项目内部署手册）
├── instance/              # 运行时目录（如 ranker.pkl，勿提交敏感内容）
└── diet_recommend.db      # SQLite 数据库（本地运行时生成）

---

4. 功能模块说明

4.1 用户与认证

• 注册、登录、登出
• 登录后可填写问卷、记录活动、查看画像、生成推荐
• 已修复登录 next 参数开放重定向风险（只允许站内路径）

4.2 问卷与活动数据

问卷字段包括：

• 年龄段、性别、身高体重
• 目标（减脂/维持/增重/增肌/健康）
• 活动水平、饮食风格
• 过敏项、不喜食材
• 每日餐次、热量目标

活动字段包括：

• 日期、步数、活动分钟、备注

系统会将活动数据融合进用户向量末 3 维（最近 14 天）：

• 平均步数归一化
• 平均活动分钟归一化
• 记录覆盖度

4.3 用户画像（聚类 + 标签）

• 从所有有问卷的用户构建特征向量
• 使用 KMeans 聚类（样本太少时做稳健处理）
• 生成中文标签文本（目标、风格、过敏、活动特征）
• 将结果写入 UserProfile

注意：单用户时不会强行聚类，会走单用户兜底逻辑，避免 n_clusters > n_samples 异常。

4.4 推荐引擎

推荐流程分为两层：

1. 规则层（硬约束 + 基线分）
   • 过敏标签命中直接剔除
   • 不喜食材与食材名称子串匹配命中直接剔除
   • 根据目标、饮食风格、脂肪控制、单餐热量匹配增加得分
2. 模型层（可选）
   • 将用户向量与食谱特征拼接
   • 随机森林预测分与规则分融合（0.55 / 0.45）
   • 模型不可用或维度不匹配时自动回退为规则排序

输出包含可解释说明（命中规则和融合详情）。

4.5 数据挖掘展示

• insights 页面提供食谱标签共现统计（支持度）
• 用于展示“关联规则挖掘”模块的可视化结果

---

5. 数据模型说明

主要模型（app/models.py）：

• User：用户账号、密码哈希、问卷 JSON、特征向量 JSON
• UserActivity：活动日志
• UserProfile：画像簇编号、标签、标签 JSON
• Recipe：食谱基础数据（食材/营养/步骤/标签）
• RecipeGeneration：推荐生成记录与明细

时间字段已采用时区感知时间（UTC）写法，避免 datetime.utcnow() 的弃用问题。

---

6. 推荐与画像的数据流（端到端）

1. 用户注册并登录
2. 提交问卷 -> 清洗/标准化 -> 保存问卷 JSON
3. 构建用户特征向量（问卷 15 维 + 活动 3 维）
4. 同步所有用户画像（聚类 + 标签）
5. 用户发起推荐
6. 规则过滤与打分，必要时叠加模型预测
7. 返回 TopN 结果并写入推荐日志

---

7. 特征工程与准确性策略

当前用户特征总维度为 18 维：

• 问卷特征：15 维
• 活动特征：3 维

已做关键优化：序数与连续特征统一归一化到 [0,1] 量级，降低距离模型（KMeans）被高量纲字段主导的风险，提升画像稳定性与可解释性。

---

8. CLI 命令说明

通过 flask 命令可执行：

• flask init-db：建表
• flask seed-data：导入演示用户/食谱/活动并训练模型
• flask rebuild-profiles：重建用户画像
• flask rebuild-model：重训排序模型
• flask evaluate：离线评估 Hit@K、NDCG
• flask replace-recipes：清空并重导食谱后重训模型

---

9. 已知限制

• 离线评估使用“弱标签”（由规则分派生），不能等价真实用户反馈
• 关联规则模块当前仅支持支持度统计，未扩展置信度/提升度
• 推荐模型使用规则分做监督信号，属于“弱监督近似学习”

单元测试与运行方式见 测试说明.md。

---

10. 快速排障

• 启动后无法登录演示账号：
  • 删除 diet_recommend.db 与 .data_seeded 后按部署手册重新初始化并导入数据
• 页面提示模型不可用：
  • 执行 flask rebuild-model
• 画像结果异常：
  • 执行 flask rebuild-profiles
• 修改特征工程后建议：
  • 重新 seed-data 或 rebuild-model，避免旧模型参数不一致

---

11. 许可与用途

本项目用于教学与课程设计演示。