基于健康数据与电商库存的动态饮食引擎
核心特性 • 技术架构 • 部署状态 • 快速开始 • 项目结构 • 开发指南
💡 让个人与家庭的健康管理从「主观感性」走向「客观数据驱动」
Health Butler 是一个开源的家庭健康管理平台，通过 AI 营养规划、智能食谱生成和电商自动采购，帮助家庭建立可持续的健康管理习惯。项目采用 Cloudflare Pages + Neon PostgreSQL 的 Serverless 架构，实现完全免费部署。
| 环境 | 状态 | URL | 说明 |
|---|---|---|---|
| 生产环境 | ✅ 运行中 | hearthbulter.pages.dev | 主站点，自动从 main 分支部署 |
| 预览环境 | ✅ 可用 | *.hearthbulter.pages.dev |
每个 PR 自动生成预览链接 |
| 数据库 | ✅ 在线 | Neon Serverless PostgreSQL | 72 张数据表，0.5GB 免费配额 |
| CI/CD | ✅ 激活 | GitHub Actions | 7 个 Job 自动化流水线 |
Push to main → 代码质量检查 → TypeScript 类型检查 → 单元测试 → 构建检查 → 安全审计 → 自动部署
| Job | 说明 | 超时 |
|---|---|---|
quality-check |
ESLint + Prettier 格式检查 | 10min |
type-check |
TypeScript 类型检查 | 10min |
test |
Jest 单元测试 + 覆盖率报告 | 15min |
build |
Next.js 产物构建 | 20min |
cloudflare-build |
Cloudflare Pages 构建测试 | 25min |
security |
npm audit 安全审计 | 10min |
final-check |
最终状态汇总 | - |
- 多成员档案: 支持家庭成员独立健康档案（性别、年龄、身高、体重、健康目标）
- 健康目标设定: 减重/增肌/维持/疾病管理等个性化目标
- 过敏与禁忌: 食材过敏记录，智能避开不适宜食材
- 家庭邀请系统: 安全的邀请链接机制，家人协同管理健康
- 全面健康指标: 体重、体脂、血压、血糖、心率、睡眠等数据记录
- 体检报告 OCR: Tesseract.js 智能识别体检报告，自动提取关键指标
- 可穿戴设备同步: Apple HealthKit、华为健康 SDK 数据自动同步
- 健康评分系统: 基于多维度指标计算综合健康评分
- 异常检测: AI 智能识别健康数据异常波动
- USDA 数据对接: 5000+ 食物营养成分数据库
- 宏量营养素: 精确计算碳水、蛋白质、脂肪及热量
- 微量营养素: 维生素、矿物质摄入追踪
- 食物搜索: 智能搜索与自定义食物添加
- AI 食谱生成: 基于健康目标、库存食材、家庭偏好智能生成食谱
- 周期食谱计划: 支持 7 天/30 天食谱自动规划
- 食谱管理: 食谱收藏、评分、评论功能
- 膳食追踪: 每日餐饮记录，营养摄入实时追踪
- 智能替代: 根据库存自动推荐食材替代方案
- 一键生成清单: 根据食谱计划和库存自动生成购物清单
- SKU 智能匹配: 自动匹配电商平台商品编码
- 价格对比: 多平台价格比较，优选采购方案
- 预算管理: 购物预算设定与支出追踪
- 去重优化: 智能合并相同食材需求
- 食材库存追踪: 实时记录家庭食材库存
- 保质期提醒: 临期食材预警，减少浪费
- 消耗记录: 食材使用历史追踪
- 浪费日志: 记录食材浪费情况，优化采购决策
- 健康趋势分析: 可视化体重、体脂、营养摄入变化趋势
- 营养分析报告: 详细营养摄入报告，识别营养缺口
- 周报生成: 自动生成每周健康总结报告
- 成本分析: 食品采购成本分析与优化建议
- AI 健康顾问: 智能对话，解答健康与营养问题
- 个性化推荐: 基于健康数据与偏好智能推荐食谱和食材
- AI 食谱优化: 根据营养目标自动调整食谱配比
- 健康洞察: AI 分析健康数据，提供个性化改善建议
- 成就系统: 健康里程碑徽章，激励持续管理
- 排行榜: 家庭成员健康数据对比与排名
- 成果分享: 健康成就社交分享（可配置隐私）
- 社区互动: 健康心得分享与交流
- 多渠道通知: 应用内推送、邮件通知
- 个性化设置: 按类型、按时间精细化通知偏好
- 重要提醒: 食材过期、服药提醒、健康目标提醒
- Apple Health: iOS 设备健康数据无缝同步
- 华为健康: Android 设备健康数据集成
- 数据去重: 智能合并多源数据，避免重复记录
┌─────────────────────────────────────────────────────────────────────┐
│ 用户浏览器 / 移动设备 │
└─────────────────────────────────┬───────────────────────────────────┘
│ HTTPS (TLS 1.3)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Cloudflare 全球边缘网络 (300+ PoPs) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Cloudflare Pages (静态托管 + Functions) │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
│ │ │ Static Assets │ │ Edge Functions (API Routes) │ │ │
│ │ │ HTML/CSS/JS │ │ - 认证授权 │ │ │
│ │ │ 全球 CDN 缓存 │ │ - API 处理 │ │ │
│ │ │ 自动 Brotli │ │ - 边缘计算 │ │ │
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Neon Database │ │ Upstash Redis │ │ 第三方 API 服务 │
│ │ │ │ │ │
│ ┌──────────────┐ │ │ ┌──────────────┐ │ │ • OpenRouter AI │
│ │ PostgreSQL │ │ │ │ Session/Cache │ │ │ • USDA FoodData │
│ │ (72 张数据表) │ │ │ │ Rate Limit │ │ │ • Tesseract OCR │
│ │ Serverless │ │ │ └──────────────┘ │ │ • Clerk Auth │
│ │ 自动扩展 │ │ └──────────────────┘ │ • Instacart API │
│ └──────────────┘ │ └──────────────────┘
└──────────────────┘
|
|
| 服务 | 用途 | 环境变量 |
|---|---|---|
| OpenRouter | AI 服务（主要） | OPENROUTER_API_KEY |
| OpenAI | AI 服务（备用） | OPENAI_API_KEY |
| USDA FoodData Central | 营养数据库 | USDA_API_KEY |
| Instacart Connect | 美国市场电商集成 | INSTACART_CLIENT_ID/SECRET |
| Clerk | 用户认证 | CLERK_SECRET_KEY |
| Upstash Redis | 边缘缓存 | UPSTASH_REDIS_REST_URL/TOKEN |
| Sentry | 错误监控 | SENTRY_DSN |
| SMTP | 邮件发送 | SMTP_HOST/USER/PASS |
| 分类 | 文件数 | 核心服务 |
|---|---|---|
| AI 服务 | 11 | openai-client, health-analyzer, recipe-optimizer |
| 分析服务 | 4 | analytics-service, cache-stats-service |
| 预算服务 | 7 | budget-tracker, cost-analyzer, spending-report |
| 电商服务 | 12 | instacart-adapter, hema-adapter, ingredient-matcher |
| 通知服务 | 9 | email-service, notification-manager, template-engine |
| 推荐服务 | 6 | recipe-recommender, food-recommender |
| 社交服务 | 10 | achievement-service, leaderboard-service |
| 追踪服务 | 8 | health-tracker, meal-tracker, weight-tracker |
| 调度服务 | 6 | scheduler, smart-trigger, cron-jobs |
| 其他服务 | 44 | meal-planner, sku-matcher, report-generator 等 |
项目使用 72 张 PostgreSQL 数据表，按功能域组织：
| 功能域 | 表数量 | 核心表 |
|---|---|---|
| 用户和认证 | 5 | users, families, family_members, family_invitations, user_consents |
| 健康数据 | 15 | health_data, health_goals, health_reports, health_scores, health_anomalies |
| 营养和食谱 | 20 | foods, meals, meal_plans, meal_logs, recipes, daily_nutrition_targets |
| 购物和预算 | 11 | shopping_lists, shopping_items, budgets, price_histories, instacart_carts |
| 库存管理 | 4 | inventory_items, inventory_usages, waste_logs, orders |
| 协作和社区 | 12 | tasks, activities, community_posts, achievements, leaderboard_entries |
| 通知系统 | 4 | notifications, notification_preferences, notification_logs |
| AI 和分析 | 4 | ai_conversations, ai_advice, prompt_templates, smart_trigger_logs |
| 模块 | 状态 | 完成度 | 说明 |
|---|---|---|---|
| 🔐 认证授权 | 🟢 已完成 | 100% | NextAuth.js + JWT + OAuth (多提供商) |
| 👨👩👧👦 家庭档案管理 | 🟢 已完成 | 100% | 成员信息、健康目标、过敏史、邀请系统 |
| 📊 健康数据管理 | 🟢 已完成 | 100% | 体重/血压/血糖等指标 + 趋势可视化 |
| 🤖 AI 健康顾问 | 🟢 已完成 | 100% | 智能对话 + 营养建议 + 健康洞察 |
| 🍎 营养数据库 | 🟢 已完成 | 90% | USDA 食物数据对接 + 自定义食物管理 |
| 🍱 食谱规划引擎 | 🟢 已完成 | 85% | AI 生成 + 周期计划 + 收藏评分 |
| 🛒 购物清单生成 | 🟢 已完成 | 80% | 智能提取 + SKU 匹配 + 价格对比 |
| 📦 库存管理 | 🟢 已完成 | 80% | 库存追踪 + 保质期提醒 + 消耗记录 |
| 🔔 通知系统 | 🟢 已完成 | 90% | 多渠道推送 + 个性化偏好 |
| 📱 可穿戴设备同步 | 🟢 已完成 | 75% | Apple HealthKit + 华为健康 SDK |
| 📊 数据分析与报告 | 🟢 已完成 | 70% | 健康趋势 + 营养分析 + 周报生成 |
| 📄 体检报告 OCR | 🟢 已完成 | 70% | Tesseract.js 识别 + 指标提取 |
| 🛍️ 电商集成 | 🟡 进行中 | 60% | SKU 匹配 + 价格估算 + 电商服务 |
| 🏆 社交与激励 | 🟢 已完成 | 75% | 成就徽章 + 排行榜 + 成果分享 |
| 📈 推荐系统 | 🟢 已完成 | 70% | 个性化食谱 + 购物推荐 + 智能替代 |
| 📊 预算管理 | 🟢 已完成 | 70% | 预算设定 + 支出追踪 + 成本分析 |
图例: 🟢 已完成 (80-100%) | 🟡 进行中 (20-79%) | 🔴 未开始 (0-19%)
| 指标 | 数量 | 说明 |
|---|---|---|
| API 端点 | 198+ | 完整的后端 API 覆盖 |
| 服务模块 | 117+ | 核心业务逻辑服务 |
| 数据表 | 72 | PostgreSQL 数据库表 |
| Schema 代码 | 2522 行 | Prisma 数据模型定义 |
| React 组件 | 180+ | UI 组件 + 业务组件 |
| 代码模块 | 260+ | 工具函数与库模块 |
本项目采用完全免费的 Serverless 架构部署：
| 服务 | 免费额度 | 我们的用量 | 状态 |
|---|---|---|---|
| Cloudflare Pages | 无限请求 / 500 次构建/月 | ~50 次构建/月 | ✅ 免费 |
| Cloudflare Functions | 100,000 请求/天 | ~1,000 请求/天 | ✅ 免费 |
| Neon PostgreSQL | 0.5GB storage, 191h/月 | ~50MB | ✅ 免费 |
| Clerk Auth | 10,000 MAU | ~100 用户 | ✅ 免费 |
| GitHub Actions | 2,000 分钟/月 | ~200 分钟/月 | ✅ 免费 |
| Upstash Redis | 10,000 请求/天 | ~500 请求/天 | ✅ 免费 |
预计月成本: $0 (完全在免费额度内)
- Node.js 20.0+ LTS
- pnpm 8.0+ (推荐) 或 npm
- PostgreSQL 16+ (或使用 Neon)
# 1. 克隆仓库
git clone https://github.com/marovole/HearthBulter.git
cd HearthBulter
# 2. 安装依赖
pnpm install
# 3. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local，填入必要的配置
# 4. 生成 Prisma Client
pnpm db:generate
# 5. 启动开发服务器
pnpm dev访问 http://localhost:3000 查看应用。
📋 点击展开完整环境变量列表
# ========== 必需配置 ==========
# 数据库连接 (Neon Serverless PostgreSQL)
DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require
# Clerk 认证配置
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
# ========== 可选配置 ==========
# USDA 营养数据 API
USDA_API_KEY=your-usda-api-key
# Redis 缓存 (Upstash, 可选)
UPSTASH_REDIS_REST_URL=https://[ref].upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token
# Redis (可选，本地或自建)
REDIS_URL=redis://localhost:6379
# Web Push (可选)
NEXT_PUBLIC_VAPID_PUBLIC_KEY=your-vapid-public-key
# OAuth 登录 (通过 Clerk 配置)
# GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 在 Clerk Dashboard 配置
# AI 服务 (OpenAI / OpenRouter)
OPENAI_API_KEY=your-openai-api-key
OPENROUTER_API_KEY=your-openrouter-api-key
# 日志级别 (可选)
LOG_LEVEL=info
# 错误追踪 (Sentry)
SENTRY_DSN=your-sentry-dsnUpstash Redis 未配置时，缓存会降级为内存或跳过；如需自建 Redis，请配置 REDIS_URL。
HearthBulter/
├── .github/
│ └── workflows/ # GitHub Actions CI/CD
│ ├── ci.yml # 主 CI 流水线
│ └── code-review.yml # 代码审查
├── prisma/
│ ├── schema.prisma # 数据库 Schema (72 张表, 2522 行)
│ ├── seed.ts # 种子数据脚本
│ └── migrations/ # 数据库迁移
├── public/ # 静态资源
├── scripts/ # 构建和部署脚本 (100+ 脚本)
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── (auth)/ # 认证页面
│ │ ├── api/ # API Routes
│ │ ├── dashboard/ # 仪表盘
│ │ ├── health-data/ # 健康数据
│ │ ├── meal-planning/ # 餐饮规划
│ │ ├── onboarding/ # 用户引导
│ │ └── shopping-list/ # 购物清单
│ ├── components/ # React 组件 (180+ 组件)
│ │ ├── ui/ # shadcn/ui 基础组件
│ │ └── features/ # 业务功能组件
│ ├── hooks/ # 自定义 Hooks
│ ├── lib/ # 核心库 (260+ 模块)
│ │ ├── db/ # Prisma Client
│ │ ├── services/ # 业务逻辑服务 (117+ 文件)
│ │ └── utils/ # 工具函数
│ ├── schemas/ # Zod 验证 Schema
│ ├── services/ # 服务层
│ └── types/ # TypeScript 类型定义
├── supabase/ # Supabase 配置
├── tests/ # 测试文件
│ ├── unit/ # 单元测试
│ └── e2e/ # E2E 测试
├── functions/ # Cloudflare Functions
├── middleware.ts # Next.js 中间件
├── next.config.js # Next.js 配置
├── tailwind.config.ts # Tailwind 配置
├── wrangler.toml # Cloudflare Wrangler 配置
└── package.json # 项目依赖 (70+ 包)
# 开发
pnpm dev # 启动开发服务器
pnpm build # 构建生产版本
pnpm start # 启动生产服务器
# 代码质量
pnpm lint # ESLint 检查
pnpm lint:fix # ESLint 自动修复
pnpm format # Prettier 格式化
pnpm type-check # TypeScript 类型检查
# 测试
pnpm test # 运行单元测试
pnpm test:watch # Watch 模式
pnpm test:coverage # 生成覆盖率报告
pnpm test:e2e # E2E 测试
# 数据库
pnpm db:generate # 生成 Prisma Client
pnpm db:push # 推送 Schema 变更
pnpm db:migrate # 运行迁移
pnpm db:studio # 打开 Prisma Studio
# 部署
pnpm build:cloudflare # Cloudflare Pages 构建
pnpm deploy:cloudflare # 部署到 Cloudflare项目集成了自动化代码审查系统：
审查维度:
- 🔍 复杂度分析: 检测函数圈复杂度
- 🛡️ 类型安全: 检查 TypeScript 类型覆盖
- 🔒 安全扫描: SQL 注入、XSS 等漏洞检测
- 🎨 代码风格: 统一命名规范
- ⚡ 性能优化: 识别潜在性能问题
pnpm review # 运行代码审查
pnpm review:report # 生成审查报告遵循 Conventional Commits 规范：
feat: 添加新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式（不影响功能）
refactor: 重构（不是新功能也不是 bug 修复）
perf: 性能优化
test: 添加测试
chore: 构建过程或辅助工具变动
本项目采用 规范驱动开发 (Spec-Driven Development) 流程，所有重大变更通过 OpenSpec 提案管理。
| 提案 | 优先级 | 状态 | 预计工作量 |
|---|---|---|---|
| add-instacart-smart-ordering | P0 | 🟡 待实施 | 4 周 |
| cleanup-prisma-residue | P2 | 🟡 待处理 | 2-3 天 |
核心价值: AI 主动规划 → 一键购物
智能时机触发 → AI 生成周计划 → 邮件通知 → 用户对话调整 → 跳转 Instacart 下单
功能模块:
| 模块 | 描述 | 状态 |
|---|---|---|
| Instacart API 集成 | OAuth 授权、购物车 API、商品搜索 | 🔴 待开发 |
| 智能时机触发引擎 | 日历事件 + 消费周期 + 库存状态 + 行为习惯 | 🔴 待开发 |
| 周计划邮件通知 | 智能时机触发后发送周计划摘要 | 🔴 待开发 |
| 全局悬浮 AI 助手 | 任意页面可呼出的对话式计划调整 | 🔴 待开发 |
| 食材→商品匹配 | 菜谱食材映射到 Instacart 商品 | 🔴 待开发 |
技术决策:
- 单一平台深度集成 (Instacart Connect API)
- 跳转平台结算 (非应用内支付)
- MVP 先用样品数据验证流程
| 提案 | 完成日期 | 核心变更 |
|---|---|---|
| update-product-readiness | 2026-01-27 | 补齐预算分析、食谱收藏、报告导出等功能 |
| migrate-auth-data-to-clerk-convex | 2026-01-27 | 认证系统迁移到 Clerk + Convex |
| refactor-database-layer-to-supabase | 2026-01-18 | 数据库层从 Prisma 迁移到 Supabase |
| migrate-to-cloudflare-pages | 2025-11-10 | 从 Vercel 迁移到 Cloudflare Pages |
查看完整的 42 个已归档提案 了解项目架构演进路径。
关键里程碑：
- 2025-10-30: MVP 核心功能开发（家庭档案、健康数据、食谱规划等 20 个提案）
- 2025-11-02: 代码质量提升（自动化审查、测试覆盖率等 9 个提案）
- 2025-11-10: 部署平台迁移（Vercel → Cloudflare Pages）
- 2026-01-18: 数据库重构（Prisma → Supabase）
- 2026-01-27: 认证系统现代化（NextAuth → Clerk + Convex）
参考 OpenSpec 指南 了解如何创建和管理变更提案。
- 项目初始化 + 架构设计
- Cloudflare Pages + Neon 部署
- 用户认证 (邮箱 + Google + GitHub OAuth)
- 家庭档案管理 + 邀请系统
- 健康数据录入与可视化
- 营养数据库对接 (USDA)
- AI 食谱生成引擎
- 购物清单生成 + SKU 匹配
- 库存管理系统
- AI 健康顾问对话
- 体检报告 OCR 识别
- 可穿戴设备数据同步 (Apple HealthKit + 华为健康)
- 🇺🇸 美国市场智能购物 (Instacart 集成 + 智能时机触发)
- 电商 API 深度集成（山姆/盒马/叮咚买菜）
- 高级营养分析报告
- 家庭健康趋势预测
- 食谱分享社区
- 多人协作食谱编辑
- 医疗机构合作（体检中心 API）
- 商业化（订阅制 + 电商返佣）
- 智能家居设备集成
- 微信小程序
- 企业健康管理解决方案
- 营养师在线咨询服务
- 跨境电商食品采购
我们欢迎所有形式的贡献！
- Fork 本仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交变更 (
git commit -m 'feat: add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
- 🔍 所有 PR 必须通过 CI 检查
- 📝 核心功能需要编写单元测试（覆盖率 >80%）
- 📖 重要功能需要更新文档
- 💬 使用中文或英文提交 Issue
本项目采用 MIT License 开源协议。
Ronn Huang - GitHub
感谢以下开源项目和服务：
- Next.js - React 全栈框架
- Cloudflare Pages - 边缘部署平台
- Neon - Serverless PostgreSQL
- Clerk - 现代认证平台
- shadcn/ui - 精美的 UI 组件库
- Prisma - 下一代 ORM
- USDA FoodData Central - 营养数据 API
⭐ 如果这个项目对你有帮助，请给我们一个 Star！
Made with ❤️ in China