feat(water-records): 新增喝水记录功能模块
新增完整的喝水记录管理功能，支持用户记录每日喝水情况、设置目标和查看统计信息。功能包括： - 创建、查询、更新和删除喝水记录 - 设置和管理每日喝水目标 - 获取今日喝水统计和完成率分析 - 支持分页查询和日期范围筛选 - 完整的数据验证和错误处理机制 该模块已从用户模块中独立出来，提供REST API接口，包含数据库迁移脚本和详细文档。
This commit is contained in:
richarjiang
140
docs/WATER_RECORDS.md
Normal file
140
docs/WATER_RECORDS.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 喝水记录功能
|
||||
|
||||
## 功能概述
|
||||
|
||||
新增了用户喝水记录功能，支持用户记录每日的喝水情况，设置喝水目标，并查看统计信息。
|
||||
|
||||
## 新增文件
|
||||
|
||||
### 模型文件
|
||||
- `src/users/models/user-water-history.model.ts` - 喝水记录模型
|
||||
- 更新了 `src/users/models/user-profile.model.ts` - 添加了 `dailyWaterGoal` 字段
|
||||
|
||||
### DTO文件
|
||||
- `src/users/dto/water-record.dto.ts` - 喝水记录相关的DTO
|
||||
|
||||
### 服务文件
|
||||
- `src/users/services/water-record.service.ts` - 喝水记录服务
|
||||
|
||||
### 数据库脚本
|
||||
- `sql-scripts/user-water-records-table.sql` - 数据库迁移脚本
|
||||
|
||||
### 测试脚本
|
||||
- `test-water-records.sh` - API接口测试脚本
|
||||
|
||||
## API接口
|
||||
|
||||
### 1. 创建喝水记录
|
||||
```
|
||||
POST /users/water-records
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"amount": 250,
|
||||
"source": "manual",
|
||||
"remark": "早晨第一杯水"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取喝水记录列表
|
||||
```
|
||||
GET /users/water-records?limit=10&offset=0
|
||||
```
|
||||
|
||||
### 3. 更新喝水记录
|
||||
```
|
||||
PUT /users/water-records/:id
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"amount": 300,
|
||||
"remark": "修改后的备注"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 删除喝水记录
|
||||
```
|
||||
DELETE /users/water-records/:id
|
||||
```
|
||||
|
||||
### 5. 更新喝水目标
|
||||
```
|
||||
PUT /users/water-goal
|
||||
```
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"dailyWaterGoal": 2000
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 获取今日喝水统计
|
||||
```
|
||||
GET /users/water-stats/today
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"totalAmount": 1500,
|
||||
"recordCount": 6,
|
||||
"dailyGoal": 2000,
|
||||
"completionRate": 0.75
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 数据库表结构
|
||||
|
||||
### t_user_water_history (喝水记录表)
|
||||
- `id` - 主键，自增
|
||||
- `user_id` - 用户ID
|
||||
- `amount` - 喝水量（毫升）
|
||||
- `source` - 记录来源（manual/auto/other）
|
||||
- `remark` - 备注
|
||||
- `created_at` - 创建时间
|
||||
- `updated_at` - 更新时间
|
||||
|
||||
### t_user_profile (用户档案表 - 新增字段)
|
||||
- `daily_water_goal` - 每日喝水目标（毫升）
|
||||
|
||||
## 功能特点
|
||||
|
||||
1. **完整的CRUD操作** - 支持喝水记录的增删改查
|
||||
2. **目标设置** - 用户可以设置每日喝水目标
|
||||
3. **统计功能** - 提供今日喝水统计，包括总量、记录数、完成率等
|
||||
4. **数据验证** - 对输入数据进行严格验证
|
||||
5. **错误处理** - 完善的错误处理机制
|
||||
6. **日志记录** - 详细的操作日志
|
||||
7. **权限控制** - 所有接口都需要JWT认证
|
||||
|
||||
## 部署说明
|
||||
|
||||
1. 运行数据库迁移脚本：
|
||||
```bash
|
||||
mysql -u username -p database_name < sql-scripts/user-water-records-table.sql
|
||||
```
|
||||
|
||||
2. 重启应用服务
|
||||
|
||||
3. 使用测试脚本验证功能：
|
||||
```bash
|
||||
./test-water-records.sh
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 喝水目标字段是可选的，可以为空
|
||||
2. 喝水记录的来源默认为 'manual'
|
||||
3. 喝水量的范围限制在 1-5000 毫升之间
|
||||
4. 喝水目标的范围限制在 500-10000 毫升之间
|
||||
5. 获取profile接口会返回用户的喝水目标
|
||||
6. 喝水目标的更新集成在喝水接口中，避免用户服务文件过大
|
||||
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