c57c930949
数值全部在服务端算好再交给模型，模型只做解读。让模型从 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>
190 lines
6.4 KiB
Markdown
190 lines
6.4 KiB
Markdown
# 佳明健康数据分析平台 (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）：
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
后端（Python/Flask，建议在虚拟环境中安装）：
|
||
```bash
|
||
cd backend
|
||
python -m venv venv && source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
复制 `backend/.env.example` 为 `backend/.env` 并填入真实值（`.env` 已被
|
||
`.gitignore` 忽略，不会进入版本库）：
|
||
|
||
```env
|
||
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`：
|
||
|
||
```env
|
||
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）：
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
python app.py
|
||
# 或生产方式：gunicorn wsgi:app -b 0.0.0.0:5000
|
||
```
|
||
|
||
前端（Vite/React，端口 3000 或 5173）：
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
- 前端: http://localhost:3000
|
||
- 后端 API: http://localhost:5000/api
|
||
|
||
### 冒烟测试
|
||
|
||
```bash
|
||
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](./docs/DEVELOPMENT.md)
|
||
|
||
## 📄 许可证
|
||
|
||
MIT
|