feat(water-records): 新增喝水记录功能模块
新增完整的喝水记录管理功能，支持用户记录每日喝水情况、设置目标和查看统计信息。功能包括： - 创建、查询、更新和删除喝水记录 - 设置和管理每日喝水目标 - 获取今日喝水统计和完成率分析 - 支持分页查询和日期范围筛选 - 完整的数据验证和错误处理机制 该模块已从用户模块中独立出来，提供REST API接口，包含数据库迁移脚本和详细文档。
This commit is contained in:
richarjiang
182
docs/WATER_RECORDS_MODULE.md
Normal file
182
docs/WATER_RECORDS_MODULE.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 喝水记录模块 (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操作
|
||||
- 支持喝水目标管理
|
||||
- 支持统计分析功能
|
||||
Reference in New Issue
Block a user