ericwyuan/GarminHealthLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fd4106b0aa0103549155e2d1c337d9dba9d02d3
GarminHealthLab/README.md
ericwyuan c57c930949 feat(ai): AI 教练 —— 晨间简报、运动处方、趋势归因与 Copilot 
数值全部在服务端算好再交给模型，模型只做解读。让模型从 CSV 里自己推
z 分数，它算错的次数足以让简报引用图表反驳它的数字。

- services/insights.py：z 分数（28 天个人基线，且**排除当天**——用一个
  值参与算出来的均值去衡量它自己，会把真实离群点摊平）、13 个月趋势斜率
  （按序数日期最小二乘，手表放充电器上一周不会压缩 x 轴）、近 7 天活动量
  对比。
- services/coach.py：三套提示词 + 回复解析，每套都配一个规则引擎版本。
  网关一次生成要几分钟，上游被限流时给一个朴素的答案，好过给一张空卡片。
- services/ai.py：多轮 chat()、SSE stream()、complete()/stream_chat()，
  以及 extract_json()——上游是推理模型，可见输出以思维链开头，所以从末尾
  倒着找最后一个配平的 JSON（字符串感知，扛得住引号里的 } 和转义引号）。
- 接口 briefing / trend-insight / copilot(SSE)，缓存表 ai_insights。
- 前端：今日页晨报卡（后台生成 + 轮询升级）、全局 Copilot 浮窗、指标详情
  页归因面板。features.ai 打开。

实测（对着自建 ai-gateway）：晨报一次 273 秒，缓存命中 18 毫秒——所以简报
绝不能同步阻塞首屏。网关的流式通道比阻塞通道更不可靠：同一条提示词流式
139 秒后返回「所有模型均不可用」，阻塞则成功，因此 stream_chat() 在流式零
输出时对同一模型退回非流式重试。Copilot 实测 TTFB 9ms、全程 40 秒。

顺带修两处：refresh 原来只跳过缓存读、不删行，导致「重新生成」后的轮询读
到旧行、看到 cached 就停了，用户一直盯着他刚要求替换掉的那段字；基线零方差
时原来返回 z=0.0，把「和每一条观测都不同」标成「完全正常」，改为 z=null。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-01 13:57:35 +08:00

6.4 KiB
Raw Blame History

佳明健康数据分析平台 (Garmin Health Lab)

一个完整的健康数据分析平台，用于获取、分析和可视化你的佳明（Garmin）设备数据。

📊 主要功能

  • 数据同步: 通过 Garmin API 自动同步你的健康数据
  • 综合分析: 步数、心率、睡眠、运动、压力等多维度分析
  • 数据可视化: 交互式图表和仪表板展示健康数据趋势
  • 智能建议: 基于数据分析的个性化健康建议
  • 数据导出: 支持数据导出为 CSV/JSON 格式

🛠 技术栈

前端

  • React 18 + TypeScript
  • Recharts (数据可视化)
  • Tailwind CSS (样式)
  • Axios (API 请求)

后端

  • Python 3.10+ + Flask
  • Gunicorn（生产运行）
  • 可插拔数据层：SQLite（本地开发）/ MariaDB（生产，Oracle 云服务器本地 MariaDB 10.3，经 PyMySQL）
  • JWT 鉴权 + scrypt 密码哈希
  • garminconnect（可选，Garmin API 集成）

注：原 Node/TypeScript 后端保留在 server/（仅 service 逻辑骨架）； 当前可运行实现为 backend/ 下的 Python/Flask 单体服务。

📁 项目结构

GarminHealthLab/
├── client/                 # 前端应用 (React 18 + TypeScript)
│   └── src/services/api.ts # API 客户端（含 JWT 拦截器）
├── backend/                # 后端应用 (Python + Flask) —— 当前可运行实现
│   ├── app.py              # 应用工厂 / 路由装配
│   ├── wsgi.py             # Gunicorn 入口
│   ├── config.py           # 配置（读 .env）
│   ├── db.py               # 可插拔数据层 (SQLite / MariaDB)
│   ├── auth.py             # scrypt + JWT + require_auth
│   ├── services/           # 业务逻辑 (health / analysis / garmin)
│   ├── routes/             # 蓝图 (auth / garmin / health / analysis)
│   ├── tests/smoke.py      # 冒烟测试
│   ├── requirements.txt
│   └── .env.example
├── server/                 # 原 Node/TS 后端（仅 service 骨架，未接入路由）
├── docs/                   # 文档
├── package.json           # 工作空间根配置
└── README.md

🚀 快速开始

前置要求

  • Node.js 18+
  • npm 或 yarn
  • Garmin Connect 账户

安装依赖

前端（React）：

npm install

后端（Python/Flask，建议在虚拟环境中安装）：

cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

配置环境变量

复制 backend/.env.example 为 backend/.env 并填入真实值（.env 已被 .gitignore 忽略，不会进入版本库）：

PORT=5000
DB_TYPE=sqlite                       # 本地开发用 sqlite；生产切 mariadb
DATABASE_PATH=./data/health.db
JWT_SECRET=your_jwt_secret_here      # 生产务必更换
CORS_ORIGIN=http://localhost:3000,http://localhost:5173

原 server/.env 的 Node 配置已弃用，请改用 backend/.env。

数据库：SQLite / MariaDB 可插拔

数据层通过 DB_TYPE 环境变量切换后端，业务代码无需改动：

  • SQLite（默认，本地开发）：零配置，由 DATABASE_PATH 指定文件位置。
  • MariaDB（生产）：运行于 Oracle 云服务器（129.146.26.249）本地的 MariaDB 10.3，专用账号 garmin 经 127.0.0.1:3306 连接（PyMySQL）。

生产使用独立库 garmin_health_lab（与 sentinel_home_ai 隔离）。完整配置见 backend/.env.example：

DB_TYPE=mariadb
MARIADB_HOST=127.0.0.1
MARIADB_PORT=3306
MARIADB_USER=garmin
MARIADB_PASSWORD=your_production_mariadb_password
MARIADB_DATABASE=garmin_health_lab

复制 backend/.env.example 为 backend/.env 并填入真实值；.env 已被 .gitignore 忽略，不会进入版本库。

启动开发服务器

后端（Flask，端口 5000）：

cd backend
source venv/bin/activate
python app.py
# 或生产方式：gunicorn wsgi:app -b 0.0.0.0:5000

前端（Vite/React，端口 3000 或 5173）：

npm run dev

冒烟测试

cd backend
python tests/smoke.py

📚 API 文档

认证

  • POST /api/auth/register - 用户注册（email, garminEmail, garminPassword）
  • POST /api/auth/login - 用户登录（email, password）
  • POST /api/auth/logout - 用户登出
  • POST /api/auth/refresh - 刷新 Token

Garmin 数据同步

  • POST /api/garmin/sync - 同步 Garmin 数据
  • GET /api/garmin/status - 获取同步状态

健康数据

  • GET /api/health/summary - 获取健康摘要
  • GET /api/health/steps - 获取步数数据
  • GET /api/health/heart-rate - 获取心率数据
  • GET /api/health/sleep - 获取睡眠数据
  • GET /api/health/activities - 获取运动数据

分析与建议

  • GET /api/analysis/trends - 获取数据趋势
  • GET /api/analysis/recommendations - 规则引擎健康建议
  • GET /api/analysis/models - 可用大模型及其配置状态
  • GET /api/analysis/ai-recommendations - 大模型健康建议（带缓存）

AI 教练

  • GET /api/analysis/briefing - 晨间简报 + 今日运动处方，附计算出的特征上下文
    • 立即返回。若没有匹配当前数据的模型答案，先返回规则版并带上 meta.pending，模型版本在后台生成，再次请求即可取到
    • ?date= 指定日期（默认最新有数据的一天）、?refresh=1 忽略缓存、 ?wait=1 阻塞等待模型（一次生成 2~5 分钟）
  • GET /api/analysis/trend-insight?metric=&startDate=&endDate= - 对选定区间内 单个指标的变化做归因分析（阻塞，未知指标返回 400 并附 supported 列表）
  • POST /api/analysis/copilot - 健康 Copilot 问答，SSE 流式返回
    • 请求体 {question, history?, date?, model?}
    • 事件序列 start → delta* → done，失败时为 error

AI 相关接口全部经由自建 ai-gateway（OpenAI 兼容，见 AI_GATEWAY_BASE_URL）。 该网关的主上游是大型推理模型，一次生成实测需 2~5 分钟，因此简报走后台生成 + 轮询，趋势归因与 Copilot 走显式触发；任一模型失败时降级为规则引擎， meta.source 会说明本次由谁作答。

🔐 安全说明

  • Garmin 账户密码使用加密存储
  • 所有 API 请求需要 JWT 认证
  • 敏感数据不在前端存储

📝 开发指南

详见 DEVELOPMENT.md

📄 许可证

MIT

Reference in New Issue View Git Blame Copy Permalink