GarminHealthLab/docs/DEVELOPMENT.md

# 开发指南

## 环境设置

### 前置要求
- Node.js 18+
- npm 或 yarn
- Git
- Garmin Connect 账户

### 安装步骤

1. **克隆项目**
   ```bash
   cd ~/Desktop/Work
   git clone <repository-url> GarminHealthLab
   cd GarminHealthLab
   ```

2. **安装依赖**
   ```bash
   npm install
   ```

3. **配置环境变量**
   ```bash
   # 复制示例文件
   cp server/.env.example server/.env
   
   # 编辑 server/.env，填入你的 Garmin 凭证
   # GARMIN_CONNECT_USER=your_email@example.com
   # GARMIN_CONNECT_PASSWORD=your_password
   # JWT_SECRET=generate_a_random_string
   ```

4. **启动开发服务器**
   ```bash
   npm run dev
   ```
   
   - 前端: http://localhost:3000
   - 后端 API: http://localhost:5000/api

## 项目命令

```bash
# 开发模式（同时运行前后端）
npm run dev

# 仅运行后端服务器
npm run dev:server

# 仅运行前端应用
npm run dev:client

# 构建项目
npm run build

# 生产模式启动
npm start

# 类型检查
npm run typecheck
```

## 代码结构

### 后端 (server/)

```
server/
├── src/
│   ├── index.ts              # 入口文件
│   ├── routes/               # API 路由
│   │   ├── auth.ts
│   │   ├── garmin.ts
│   │   ├── health.ts
│   │   └── analysis.ts
│   ├── services/             # 业务逻辑服务
│   │   ├── AuthService.ts
│   │   ├── GarminService.ts
│   │   ├── HealthService.ts
│   │   └── AnalysisService.ts
│   ├── models/               # 数据模型
│   ├── middleware/           # 中间件
│   ├── utils/                # 工具函数
│   │   └── database.ts
│   └── types/                # TypeScript 类型定义
├── dist/                     # 编译输出
├── tsconfig.json
└── package.json
```

### 前端 (client/)

```
client/
├── src/
│   ├── index.tsx             # 入口文件
│   ├── App.tsx               # 主组件
│   ├── components/           # 可复用组件
│   ├── pages/                # 页面组件
│   │   ├── Dashboard.tsx
│   │   ├── DataSync.tsx
│   │   ├── Analysis.tsx
│   │   ├── Recommendations.tsx
│   │   └── Settings.tsx
│   ├── services/             # API 服务
│   │   └── api.ts
│   ├── types/                # TypeScript 类型定义
│   └── index.css             # 全局样式
├── public/                   # 静态资源
└── package.json
```

## 开发工作流

### 添加新的 API 端点

1. **创建路由处理器** (`server/src/routes/yourFeature.ts`)
   ```typescript
   import express from 'express';
   
   const router = express.Router();
   
   router.get('/endpoint', (req, res) => {
     // 业务逻辑
   });
   
   export default router;
   ```

2. **在主文件中注册路由** (`server/src/index.ts`)
   ```typescript
   import yourFeatureRoutes from './routes/yourFeature';
   app.use('/api/yourfeature', yourFeatureRoutes);
   ```

3. **创建 API 客户端方法** (`client/src/services/api.ts`)
   ```typescript
   getYourEndpoint() {
     return this.client.get('/yourfeature/endpoint');
   }
   ```

### 添加新页面

1. **创建页面组件** (`client/src/pages/YourPage.tsx`)
   ```typescript
   import React from 'react';
   
   function YourPage() {
     return <div>Page content</div>;
   }
   
   export default YourPage;
   ```

2. **在 App.tsx 中添加路由**
   ```typescript
   <Route path="/your-path" element={<YourPage />} />
   ```

### 数据库操作

使用数据库工具函数简化操作：

```typescript
import { runAsync, getAsync, allAsync } from '../utils/database';

// 插入数据
await runAsync('INSERT INTO table (col1, col2) VALUES (?, ?)', [val1, val2]);

// 查询单行
const row = await getAsync('SELECT * FROM table WHERE id = ?', [id]);

// 查询多行
const rows = await allAsync('SELECT * FROM table WHERE status = ?', ['active']);
```

## 调试

### 后端调试
```bash
# 启用详细日志
DEBUG=* npm run dev:server

# 使用 Node 调试器
node --inspect server/dist/index.js
```

### 前端调试
- 使用 React DevTools 浏览器扩展
- 使用浏览器开发者工具 (F12)
- 检查网络请求和响应

## 测试

### 测试后端 API

使用 curl 或 Postman：

```bash
# 获取健康摘要
curl http://localhost:5000/api/health/summary

# 触发 Garmin 同步
curl -X POST http://localhost:5000/api/garmin/sync

# 获取健康建议
curl http://localhost:5000/api/analysis/recommendations
```

## 常见问题

### 数据库连接失败
```bash
# 检查数据库文件
ls -la ./data/health.db

# 重置数据库
rm ./data/health.db
npm run dev
```

### 前端无法连接后端
- 检查 CORS 配置
- 确保后端运行在 5000 端口
- 检查防火墙设置

### Garmin 认证失败
- 验证 Garmin 邮箱和密码
- 检查网络连接
- 查看后端日志

## 性能优化建议

1. **数据库索引**
   - 在频繁查询的字段上添加索引
   - 定期分析查询性能

2. **缓存策略**
   - 实现 API 响应缓存
   - 使用浏览器缓存

3. **代码分割**
   - React 懒加载路由
   - 按需加载 JavaScript

## 代码规范

### TypeScript
- 使用严格模式
- 为所有函数参数添加类型
- 使用接口定义复杂对象

### CSS
- 使用 BEM 命名规范
- 响应式设计优先
- 避免内联样式

### 提交信息
```
feat: 添加新功能描述
fix: 修复 bug 描述
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
```

## 资源链接

- [Express.js 文档](https://expressjs.com/)
- [React 文档](https://react.dev/)
- [TypeScript 文档](https://www.typescriptlang.org/)
- [SQLite 文档](https://www.sqlite.org/)
- [Garmin API](https://developer.garmin.com/)