plates-server/docs/WATER_RECORDS.md

喝水记录功能

功能概述

新增了用户喝水记录功能，支持用户记录每日的喝水情况，设置喝水目标，并查看统计信息。

新增文件

模型文件

• 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

请求体：

{
  "amount": 250,
  "source": "manual",
  "remark": "早晨第一杯水"
}

2. 获取喝水记录列表

GET /users/water-records?limit=10&offset=0

3. 更新喝水记录

PUT /users/water-records/:id

请求体：

{
  "amount": 300,
  "remark": "修改后的备注"
}

4. 删除喝水记录

DELETE /users/water-records/:id

5. 更新喝水目标

PUT /users/water-goal

请求体：

{
  "dailyWaterGoal": 2000
}

6. 获取今日喝水统计

GET /users/water-stats/today

响应：

{
  "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. 运行数据库迁移脚本：

   mysql -u username -p database_name < sql-scripts/user-water-records-table.sql
   

2. 重启应用服务

3. 使用测试脚本验证功能：

   ./test-water-records.sh
   

注意事项

1. 喝水目标字段是可选的，可以为空
2. 喝水记录的来源默认为 'manual'
3. 喝水量的范围限制在 1-5000 毫升之间
4. 喝水目标的范围限制在 500-10000 毫升之间
5. 获取profile接口会返回用户的喝水目标
6. 喝水目标的更新集成在喝水接口中，避免用户服务文件过大