# 喝水记录模块 (Water Records Module)

## 概述

喝水记录模块是一个独立的NestJS模块，用于管理用户的喝水记录和喝水目标。该模块已从用户模块中分离出来，以提高代码的可维护性和模块化程度。

## 模块结构

```
src/water-records/
├── water-records.controller.ts    # 控制器 - 处理HTTP请求
├── water-records.service.ts       # 服务 - 业务逻辑处理
├── water-records.module.ts        # 模块定义
├── models/
│   └── user-water-history.model.ts # 喝水记录数据模型
└── dto/
    └── water-record.dto.ts         # 数据传输对象
```

## API 接口

### 基础路径: `/water-records`

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| POST | `/` | 创建喝水记录 | JWT |
| GET | `/` | 获取喝水记录列表 | JWT |
| PUT | `/:id` | 更新喝水记录 | JWT |
| DELETE | `/:id` | 删除喝水记录 | JWT |
| PUT | `/goal/daily` | 更新每日喝水目标 | JWT |
| GET | `/stats/today` | 获取今日喝水统计 | JWT |

## 数据模型

### UserWaterHistory (喝水记录)

```typescript
{
  id: number;              // 记录ID
  userId: string;          // 用户ID
  amount: number;          // 喝水量（毫升）
  source: WaterRecordSource; // 记录来源
  note: string | null;     // 备注
  recordedAt: Date;        // 记录时间
  createdAt: Date;         // 创建时间
  updatedAt: Date;         // 更新时间
}
```

### WaterRecordSource (记录来源枚举)

- `manual` - 手动记录
- `auto` - 自动记录
- `other` - 其他来源

## 功能特性

### 1. 喝水记录管理
- ✅ 创建喝水记录
- ✅ 查询喝水记录（支持日期范围筛选和分页）
- ✅ 更新喝水记录
- ✅ 删除喝水记录

### 2. 喝水目标管理
- ✅ 设置每日喝水目标
- ✅ 在用户档案中返回喝水目标

### 3. 统计分析
- ✅ 今日喝水统计
- ✅ 完成率计算
- ✅ 记录数量统计

### 4. 数据验证
- ✅ 喝水量范围验证（1-5000ml）
- ✅ 喝水目标范围验证（500-10000ml）
- ✅ 输入数据格式验证

## 使用示例

### 创建喝水记录

```bash
curl -X POST "http://localhost:3000/water-records" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "amount": 250,
    "note": "早晨第一杯水",
    "recordedAt": "2023-12-01T08:00:00.000Z"
  }'
```

### 获取喝水记录列表

```bash
curl -X GET "http://localhost:3000/water-records?startDate=2023-12-01&endDate=2023-12-31&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 更新喝水目标

```bash
curl -X PUT "http://localhost:3000/water-records/goal/daily" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "dailyWaterGoal": 2500
  }'
```

### 获取今日统计

```bash
curl -X GET "http://localhost:3000/water-records/stats/today" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 数据库表结构

### t_user_water_history

```sql
CREATE TABLE t_user_water_history (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id VARCHAR(255) NOT NULL COMMENT '用户ID',
  amount INT NOT NULL COMMENT '喝水量（毫升）',
  source ENUM('manual', 'auto', 'other') NOT NULL DEFAULT 'manual' COMMENT '记录来源',
  note VARCHAR(255) NULL COMMENT '备注',
  recorded_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '记录时间',
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_user_id (user_id),
  INDEX idx_recorded_at (recorded_at)
);
```

## 模块依赖

- `@nestjs/common` - NestJS核心功能
- `@nestjs/sequelize` - Sequelize ORM集成
- `sequelize-typescript` - TypeScript装饰器支持
- `class-validator` - 数据验证
- `class-transformer` - 数据转换

## 与其他模块的关系

- **Users Module**: 依赖用户模块的UserProfile模型来管理喝水目标
- **Activity Logs Module**: 可选的活动日志记录
- **App Module**: 在主应用模块中注册

## 测试

运行测试脚本：

```bash
chmod +x test-water-records-module.sh
./test-water-records-module.sh
```

## 注意事项

1. **权限控制**: 所有接口都需要JWT认证
2. **数据验证**: 严格的输入验证确保数据质量
3. **错误处理**: 完善的错误处理和日志记录
4. **性能优化**: 支持分页查询，避免大量数据加载
5. **数据一致性**: 使用事务确保数据操作的一致性

## 迁移说明

该模块从原来的用户模块中分离出来，主要变化：

1. **路径变更**: 从 `/users/water-*` 变更为 `/water-records/*`
2. **模块独立**: 独立的控制器、服务和模块
3. **代码分离**: 减少了用户模块的复杂度
4. **维护性提升**: 更好的代码组织和维护性

## 版本历史

- **v1.0.0** - 初始版本，从用户模块分离
- 支持完整的CRUD操作
- 支持喝水目标管理
- 支持统计分析功能