6b05d04773
- database.ts 改为按 DB_TYPE 切换 SQLite / MariaDB(mysql2)，sqlite3 按需动态导入 - index.ts 改为初始化数据库后再监听端口 - 新增 AuthService / HealthService / AnalysisService / GarminService - 新增 .gitignore、server/.env(忽略) 与 .env.example - README 增加数据库配置说明；package.json 增加 mysql2/@types
141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# 佳明健康数据分析平台 (Garmin Health Lab)
|
||
|
||
一个完整的健康数据分析平台，用于获取、分析和可视化你的佳明（Garmin）设备数据。
|
||
|
||
## 📊 主要功能
|
||
|
||
- **数据同步**: 通过 Garmin API 自动同步你的健康数据
|
||
- **综合分析**: 步数、心率、睡眠、运动、压力等多维度分析
|
||
- **数据可视化**: 交互式图表和仪表板展示健康数据趋势
|
||
- **智能建议**: 基于数据分析的个性化健康建议
|
||
- **数据导出**: 支持数据导出为 CSV/JSON 格式
|
||
|
||
## 🛠 技术栈
|
||
|
||
### 前端
|
||
- React 18 + TypeScript
|
||
- Recharts (数据可视化)
|
||
- Tailwind CSS (样式)
|
||
- Axios (API 请求)
|
||
|
||
### 后端
|
||
- Node.js + Express
|
||
- TypeScript
|
||
- SQLite3 (本地数据存储)
|
||
- garmin-connect (Garmin API 集成)
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
GarminHealthLab/
|
||
├── client/ # 前端应用
|
||
│ ├── src/
|
||
│ │ ├── components/ # React 组件
|
||
│ │ ├── pages/ # 页面
|
||
│ │ ├── services/ # API 服务
|
||
│ │ └── types/ # TypeScript 类型定义
|
||
│ └── package.json
|
||
├── server/ # 后端应用
|
||
│ ├── src/
|
||
│ │ ├── routes/ # API 路由
|
||
│ │ ├── services/ # 业务逻辑
|
||
│ │ ├── models/ # 数据模型
|
||
│ │ ├── middleware/ # 中间件
|
||
│ │ └── utils/ # 工具函数
|
||
│ └── package.json
|
||
├── docs/ # 文档
|
||
├── package.json # 工作空间根配置
|
||
└── README.md
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
- Node.js 18+
|
||
- npm 或 yarn
|
||
- Garmin Connect 账户
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
创建 `server/.env` 文件：
|
||
|
||
```env
|
||
PORT=5000
|
||
NODE_ENV=development
|
||
GARMIN_CONNECT_USER=your_garmin_email
|
||
GARMIN_CONNECT_PASSWORD=your_garmin_password
|
||
DATABASE_PATH=./data/health.db
|
||
JWT_SECRET=your_jwt_secret_here
|
||
CORS_ORIGIN=http://localhost:3000
|
||
```
|
||
|
||
### 数据库：SQLite / MariaDB 可插拔
|
||
|
||
数据层通过 `DB_TYPE` 环境变量切换后端，**业务代码无需改动**：
|
||
|
||
- **SQLite（默认，本地开发）**：零配置，由 `DATABASE_PATH` 指定文件位置。
|
||
- **MariaDB（生产，运行在 NAS 上）**：经 `mysql2` 连接，优先走 socket（`MARIADB_SOCKET`），也可用 `MARIADB_HOST` + `MARIADB_PORT`。
|
||
|
||
生产使用 NAS 上的独立库 `garmin_health_lab`（与 `sentinel_home_ai` 隔离）。完整配置见 `server/.env.example`：
|
||
|
||
```env
|
||
DB_TYPE=mariadb
|
||
MARIADB_SOCKET=/run/mysqld/mysqld10.sock
|
||
MARIADB_USER=root
|
||
MARIADB_PASSWORD=your_nas_mariadb_root_password
|
||
MARIADB_DATABASE=garmin_health_lab
|
||
```
|
||
|
||
> 复制 `server/.env.example` 为 `server/.env` 并填入真实值；`.env` 已被 `.gitignore` 忽略，不会进入版本库。
|
||
|
||
### 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
- 前端: http://localhost:3000
|
||
- 后端: http://localhost:5000
|
||
|
||
## 📚 API 文档
|
||
|
||
### 认证
|
||
- `POST /api/auth/login` - 用户登录
|
||
- `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` - 获取健康建议
|
||
|
||
## 🔐 安全说明
|
||
|
||
- Garmin 账户密码使用加密存储
|
||
- 所有 API 请求需要 JWT 认证
|
||
- 敏感数据不在前端存储
|
||
|
||
## 📝 开发指南
|
||
|
||
详见 [DEVELOPMENT.md](./docs/DEVELOPMENT.md)
|
||
|
||
## 📄 许可证
|
||
|
||
MIT
|