目录
master
分支2
标签0
+ 疑修
Web IDE
云上
Initial commit: 全部覆盖仓库内容
22小时前1次提交
README.md

健康管理系统（Web 端 MVP）

一个面向「普通用户 / 健康管理师 / 医生」的 AI 辅助健康管理 Web 系统，包含完整的前后端可运行 MVP。

  • 前端：Next.js 15 + React 18 + TypeScript + Tailwind CSS + Recharts
  • 后端：FastAPI + SQLAlchemy + MySQL
  • AI 建议：统一调用外部 LLM + RAG 知识库接口，未配置真实模型时相关 AI 接口明确返回不可用

当前进度

截至 2026-05-28，项目处于 本地可运行 MVP / 前后端联调完成 阶段：

  • 已完成核心业务闭环：认证、健康档案、健康记录、Dashboard、饮食、运动、心理陪伴、AI 助手、远程问诊、提醒、设置。
  • 已提供本地演示数据、后端 pytest 主流程、前端 lint / TypeScript 检查、隔离目录生产构建、前后端冒烟验证脚本和 Playwright 浏览器级回归。
  • 已补充 Alembic 迁移、生产启动安全检查、WebSocket 信令、设备同步 Adapter、Google Fit OAuth 授权路由、通知 Provider 状态接口、AI/RAG 可替换接口基础。
  • 仍未进入完整生产上线态：真实设备厂商完整数据同步、双端 WebRTC 媒体协商、短信/公众号真实发送、TURN 服务部署、HTTPS、备份、性能压测和医学审核知识库仍需要外部服务或部署环境支撑。

比赛亮点

亮点 说明 可演示入口
AI 个性化健康管理 根据健康档案、记录和情绪数据调用外部 LLM 生成饮食、运动、睡眠、心理建议；未配置外部 LLM 时不使用模拟数据 /dashboard、/assistant
多维健康数据闭环 支持手动录入、CSV/Excel 导入、导出、演示设备同步和 Google Fit 授权入口 /records、/settings
运动动作本地演示 动作演示改为本地弹窗，展示动作要点、适用人群和注意事项，不再使用假链接 /exercise
远程问诊协作 普通用户发起咨询，医生账号查看并回复；WebRTC 信令与房间基础已接入 /consultation
心理陪伴与情绪趋势 情绪打卡、趋势图和陪伴式对话形成日常使用入口 /mental
生产边界透明 短信、OAuth、真实设备、邮件、TURN 未配置时明确展示状态，不伪造成功 /login、/records、/settings
交付文档完整 已补商业可行性、运营计划、测试报告、用户手册、管理员手册 docs/

评分标准对应说明

评分维度 项目对应能力 交付依据
创意与原创性 15% AI 健康建议、设备同步、远程问诊、心理陪伴、RAG 知识库接口 Dashboard、AI 助手、问诊、心理模块
用户体验设计 20% 响应式布局、搜索跳转、登录弹窗闭环、运动演示弹窗、无明显假按钮 前端页面与 Playwright e2e
技术实现 25% FastAPI + SQLAlchemy + Alembic、Next.js + TypeScript、JWT、2FA、导入导出、测试链路 backend/tests/、frontend/tests/
商业价值与可行性 20% 用户画像、市场痛点、竞品分析、商业模式、落地路径 docs/business-feasibility.md
上线运营能力 20% 上线步骤、推广策略、反馈机制、监控备份、版本计划、测试报告 docs/operation-plan.md、docs/test-report.md

如何演示给评委看

建议按 6-8 分钟节奏演示：

  1. 用 demo@health.cn / demo1234 登录，说明系统定位为 AI 健康管理 Web MVP。
  2. 在 健康总览 展示健康评分、趋势切换和 AI 建议。
  3. 在 健康记录 新增一条步数记录，展示文件导入、设备 Provider 状态和演示同步；说明真实厂商未配置时不会伪造成功。
  4. 在 饮食规划 生成今日菜单，展示过敏过滤和替代食材。
  5. 在 运动建议 生成运动计划，点击“动作演示”查看本地动作要点弹窗。
  6. 在 心理陪伴 完成一次情绪打卡，展示趋势与陪伴式建议。
  7. 在 远程问诊 发起咨询，再用 doctor@health.cn / doctor1234 登录查看医生回复流程。
  8. 在顶部搜索框输入“饮食 / 运动 / 问诊 / AI / 提醒”等关键词，展示模块跳转不是静态输入框。
  9. 打开 docs/business-feasibility.md、docs/operation-plan.md、docs/test-report.md，说明商业与运营交付已补齐。

当前已完成 / 生产需配置

类别 当前已完成 生产需配置或后续补强
认证 邮箱登录、手机号验证码演示、JWT、双因素认证、OAuth 按钮状态 真实短信服务、第三方 OAuth Client ID / Secret、账号风控
健康管理 档案、记录、Dashboard、饮食、运动、心理、AI 建议 医学审核知识库、专家复核流程、更多异常流测试
设备同步 演示网关、手动网关、Google Fit OAuth 授权开始和 callback 路由、状态区分 Google Fit 真实密钥和授权测试、华为/小米/Apple 真实 Adapter
远程问诊 图文咨询、医生回复、WebRTC 房间和信令基础 TURN 服务、HTTPS、多网络音视频回归
通知提醒 站内提醒、浏览器通知授权、邮件/短信/公众号状态接口 SMTP、短信服务商、公众号模板消息
部署运维 Alembic、生产安全检查、部署指南、运营计划、测试报告 HTTPS、备份恢复演练、监控告警、压测、安全扫描

交付文档

文档 用途
商业价值与可行性分析 用户画像、市场痛点、竞品对比、商业模式、风险对策
上线运营计划 上线步骤、推广策略、用户反馈、监控备份、版本迭代
测试报告 测试范围、命令、覆盖模块、风险和待补测试
普通用户操作手册 用户端完整操作说明
管理员 / 运营 / 医生操作说明 角色操作、部署配置、故障处理和验收清单

目录结构

健康管理系统/
├── backend/                  FastAPI 服务
│   ├── app/
│   │   ├── api/              路由层（auth/profile/records/...）
│   │   ├── core/             安全工具 + 种子数据
│   │   ├── models/           SQLAlchemy 模型
│   │   ├── schemas/          Pydantic Schema
│   │   ├── services/         业务服务（AI/饮食/运动/仪表盘）
│   │   ├── config.py
│   │   ├── database.py
│   │   └── main.py           FastAPI 入口
│   ├── alembic/                 数据库迁移版本
│   ├── alembic.ini
│   ├── requirements.txt
│   └── .env.example
└── frontend/                 Next.js 前端
    ├── app/                  App Router 页面（12 个路由）
    ├── components/           UI 组件 + 布局 + 图表
    ├── lib/                  API 客户端 + 类型 + Auth
    ├── package.json
    ├── tailwind.config.ts
    └── .env.example

快速开始

1. 启动后端

需要 Python 3.10 及以上。

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1     # macOS/Linux 用 source .venv/bin/activate
pip install -r requirements.txt
copy .env.example .env           # macOS/Linux 用 cp
python -m uvicorn app.main:app --reload --port 8000

开发环境默认会在启动时执行 Alembic 迁移并写入演示数据。访问：

2. 启动前端

需要 Node.js 18.18+ 或 20+。

cd frontend
copy .env.example .env.local     # 默认指向 http://localhost:8000
npm install
npm run dev

打开浏览器访问 http://localhost:3000，使用演示账号登录。

3. 本地验证

# 后端主流程测试
cd backend
python -m pytest -q

# 前端静态检查
cd ..\frontend
npm run lint
npx tsc --noEmit --pretty false

# 当 dev server 正在运行时，用隔离目录构建，避免 .next 被占用
npm run build:verify

# 前后端都启动后，检查登录页、注册页、Dashboard 路由和核心 API
npm run smoke

# 首次运行 Playwright 前安装浏览器；前后端都启动后执行浏览器级回归
npx playwright install chromium
npm run test:e2e
# 如需观察浏览器界面
npm run test:e2e:headed

Playwright e2e 默认连接 http://127.0.0.1:3000 和 http://127.0.0.1:8000。如服务未启动，测试会在全局初始化阶段给出启动命令提示；可通过 E2E_FRONTEND_BASE_URL、E2E_API_BASE_URL、E2E_EMAIL、E2E_PASSWORD 覆盖默认地址和账号。

演示账号

角色 邮箱 密码
普通用户 demo@health.cn demo1234
医生（心血管） doctor@health.cn doctor1234
医生（营养） doctor2@health.cn doctor1234
营养师 / 教练 expert@health.cn expert1234

普通用户已带 7 天健康记录、情绪打卡、提醒，登录后可直接体验 Dashboard 与 AI 建议。新库种子数据中普通用户手机号为 13800000000；仅当后端设置 SMS_PROVIDER=demo 时，登录页手机号验证码会返回明确标记的演示验证码，不会发送真实短信。

切换到 PostgreSQL

编辑 backend/.env：

DATABASE_URL=postgresql+psycopg2://用户名:密码@127.0.0.1:5432/health

并补装驱动：pip install psycopg2-binary。重启后端即可。

切换到 MySQL

编辑 backend/.env：

DATABASE_URL=mysql+pymysql://health_user:password@127.0.0.1:3306/health?charset=utf8mb4
SECRET_KEY=请替换为随机长密钥

执行 pip install -r requirements.txt 后重启后端。开发环境会自动执行 Alembic 迁移；生产环境请先手动执行 alembic upgrade head，再启动服务。

数据库迁移

后端已使用 Alembic 管理数据库结构。常用命令需在 backend/ 目录执行：

# 升级到最新结构
alembic upgrade head

# 查看当前数据库迁移版本
alembic current

# 查看迁移历史
alembic history

默认本地开发配置：

  • DB_AUTO_MIGRATE=true：启动后端时自动执行迁移。
  • DB_SEED_ENABLED=true：首次启动写入演示账号和演示数据。

生产部署要求：

  • APP_ENV=production
  • APP_DEBUG=false
  • DB_AUTO_MIGRATE=false
  • DB_SEED_ENABLED=false
  • 发布流程中显式执行 alembic upgrade head
  • 生产 SECRET_KEY 必须替换为 32 位以上随机值，CORS_ORIGINS 只能填写真实 HTTPS 前端域名。

完整生产部署流程见 生产部署加固指南，包含环境变量、MySQL 初始化、Alembic、前端构建、Nginx/HTTPS 和备份策略。

核心功能

模块 入口 说明
用户认证 /login、/register 邮箱注册、JWT 鉴权、角色字段预留
健康档案 /profile 身高、体重、过敏、目标，BMI 自动计算
健康记录 /records 体重 / 心率 / 血压 / 步数 / 运动 / 睡眠 / 饮食
数据导入导出 /records、/settings CSV/Excel 导入，CSV/Excel/PDF 导出，设备同步接口
数据可视化 /dashboard 健康评分、7/30/90 天趋势切换、AI 建议预览
饮食规划 /diet 日 / 周菜单，按过敏过滤，提供替代食材
运动建议 /exercise 按目标 + 强度生成动作清单
心理陪伴 /mental 情绪打卡、趋势图、外部 AI 陪伴聊天
AI 助手 /assistant 外部 LLM 问答 + 建议预览
远程问诊 /consultation 选择医生、留言、医生回复、患者档案摘要
提醒 /reminders 饮食 / 运动 / 药物 / 睡眠提醒
设置 /settings 账号信息、密码、双因素认证、通知授权、导出、退出登录

手动测试主流程

  1. 浏览器打开 http://localhost:3000/login，用 demo@health.cn / demo1234 登录。
  2. 进入 Dashboard，查看健康评分、近 7 日趋势与 AI 建议。点「刷新 AI 建议」会触发后端重新生成。
  3. 进入 健康档案，修改身高 / 体重 / 目标后保存，返回 Dashboard 看 BMI 与建议变化。
  4. 进入 健康记录，新增一条「步数 / 11000」记录，回 Dashboard 看到当日步数更新。
  5. 进入 饮食规划，点「生成今日菜单」获得包含目标热量、过敏过滤的菜单；点「生成本周菜单」展开 7 天。
  6. 进入 运动计划，选择目标 = 减脂、强度 = 高，生成计划查看动作。
  7. 进入 心理陪伴，做一次打卡（很棒），然后在底部对话框输入「最近压力大」查看回复。
  8. 进入 AI 助手，点击「我想减脂，应该怎么吃？」快捷提问。
  9. 进入 远程问诊，选择「李医生」发起咨询；用 doctor@health.cn / doctor1234 登录可看到收到的咨询并回复。
    • WebRTC 手测：分别用两个浏览器或一个普通窗口 + 一个无痕窗口登录用户和医生；用户点击「立即视频」，医生在同一问诊详情点击「加入视频」。双方浏览器授权摄像头/麦克风后，应显示本地小窗与远端视频。若未配置 WEBRTC_TURN_URLS，局域网或部分 NAT 可用，生产环境需配置 TURN。
  10. 进入 提醒，新增一条「19:00 运动提醒」，停用 / 启用 / 删除。

API 概览

后端统一以 /api 为前缀，主要路由：

POST /api/auth/register
POST /api/auth/login
POST /api/auth/login/phone-code
POST /api/auth/sms/send-code
POST /api/auth/sms/verify
GET  /api/auth/me
PUT  /api/auth/password
POST /api/auth/2fa/setup
POST /api/auth/2fa/enable
POST /api/auth/2fa/disable
GET  /api/auth/oauth/providers

GET  /api/profile
PUT  /api/profile

GET  /api/records?record_type=&start=&end=
POST /api/records
POST /api/records/import
GET  /api/records/device-providers
POST /api/records/device-providers/{provider}/authorize
GET  /api/records/device-providers/{provider}/callback
POST /api/records/sync-device
GET  /api/records/export?format=csv|xlsx|pdf
PUT  /api/records/{id}
DELETE /api/records/{id}

GET  /api/dashboard/summary

GET  /api/recommendations?refresh=true
POST /api/assistant/chat
POST /api/assistant/agent
GET  /api/assistant/status
GET  /api/assistant/knowledge/search?q=

GET  /api/diet/plans
POST /api/diet/generate

GET  /api/exercise/plans
POST /api/exercise/generate

GET  /api/mental/emotions
POST /api/mental/emotions

GET  /api/consultations
POST /api/consultations
GET  /api/consultations/{id}
PUT  /api/consultations/{id}
GET  /api/consultations/{id}/profile        # 医生角色查看患者档案
POST /api/consultations/{id}/room           # 创建 WebRTC 问诊房间
WS   /api/consultations/{id}/ws             # WebSocket 信令：join/offer/answer/ice/chat/leave
GET  /api/consultations/{id}/signals
POST /api/consultations/{id}/signals
GET  /api/consultations/doctors

GET  /api/reminders
POST /api/reminders
GET  /api/reminders/due
GET  /api/reminders/notification-channels
POST /api/reminders/test-email
PUT  /api/reminders/{id}
DELETE /api/reminders/{id}

完整 OpenAPI 在 http://localhost:8000/docs。

未完成项与后续建议

MVP 阶段已补齐基础能力，仍需外部服务密钥或生产基础设施支撑的项目：

  • 真实手环厂商同步：已提供 Adapter 接口、演示 Adapter、Google Fit OAuth 授权路由与华为/小米/Apple 配置占位；真实数据拉取仍需开放平台密钥、用户授权和厂商 API 回归测试。
  • 真实视频 / 语音通话：已提供 WebRTC 房间、WebSocket 信令与前端 RTCPeerConnection 协商；生产环境仍需部署 TURN 服务并做多网络浏览器回归。
  • 邮件提醒：已实现 SMTP 配置检测、测试发送和通知通道状态接口；需要在 .env 中填写 SMTP 配置。
  • OAuth 第三方登录：已支持 GitHub/Google OAuth 流程；需要配置对应 Client ID / Secret。
  • RAG 知识库：已抽象本地知识库接口，并预留向量数据库配置；向量数据库未实现时不会伪装向量检索成功。
  • 手机号登录 / 短信提醒 / 公众号通知：短信与公众号已有 Provider 状态占位；真实发送仍需要短信服务商、公众号授权与对应回调配置。
  • 部署加固：已补 Alembic 迁移与生产启动安全检查；仍需结合实际部署补 HTTPS、备份、密钥管理、日志脱敏与压测报告。
  • 自动化测试扩展：后端已有 pytest 主流程，前端已有 lint、TypeScript、隔离构建、smoke 和 Playwright 核心路径回归；后续可继续补充异常流、下载内容校验和医生端双浏览器 WebRTC 场景。

设计取舍

  • 默认 MySQL：更接近真实部署环境；模型层用 SQLAlchemy 2.x，便于后续迁移。
  • AI 调用：聊天、健康建议、饮食规划和运动计划均走真实外部模型；未配置 AI_API_KEY 时返回明确错误，不生成模拟 AI 结果。
  • 字段命名清晰 + created_at/updated_at 一致：模型层有 TimestampMixin 复用。
  • 权限：JWT + 角色字段，api/deps.py 提供 require_roles 装饰，方便后续扩展专业 / 医生 / 管理员权限。
关于

康悦健康是一套前后端分离的 AI 智慧健康管理 Web 系统，支持健康档案、体征记录、饮食规划、运动建议、心理陪伴、AI 助手、远程问诊、健康提醒和账号设置等核心流程，面向普通用户、健康管理师和医生提供日常健康管理辅助。

web应用开发
README.md
213.7 MB
MIT-advertising
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号