2c2e964199
新增完整的喝水记录管理功能，支持用户记录每日喝水情况、设置目标和查看统计信息。功能包括： - 创建、查询、更新和删除喝水记录 - 设置和管理每日喝水目标 - 获取今日喝水统计和完成率分析 - 支持分页查询和日期范围筛选 - 完整的数据验证和错误处理机制 该模块已从用户模块中独立出来，提供REST API接口，包含数据库迁移脚本和详细文档。
182 lines
4.9 KiB
Markdown
182 lines
4.9 KiB
Markdown
# 喝水记录模块 (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操作
|
||
- 支持喝水目标管理
|
||
- 支持统计分析功能 |