plates-server/docs/WATER_RECORDS_MODULE.md

喝水记录模块 (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 (喝水记录)

{
  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）
• ✅ 输入数据格式验证

使用示例

创建喝水记录

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"
  }'

获取喝水记录列表

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"

更新喝水目标

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

获取今日统计

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

数据库表结构

t_user_water_history

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: 在主应用模块中注册

测试

运行测试脚本：

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操作
• 支持喝水目标管理
• 支持统计分析功能