feat: 支持饮水记录卡片

test-water-api.md

@@ -0,0 +1,135 @@
+# 喝水记录 API 修复测试文档
+
+## 修复内容总结
+
+### 1. 服务层修复 (services/waterRecords.ts)
+
+#### 接口路径修复
+- ✅ 更新喝水目标：`/water-goal` → `/water-records/goal/daily`
+- ✅ 获取统计数据：`/water-stats/today` → `/water-records/stats`
+- ✅ 获取指定日期统计：`/water-stats/${date}` → `/water-records/stats?date=${date}`
+
+#### 数据结构修复
+- ✅ 字段名称：`remark` → `note`
+- ✅ 枚举值：`'manual' | 'auto' | 'other'` → `'Manual' | 'Auto'`
+- ✅ 新增字段：`recordedAt` (记录时间)
+- ✅ 响应结构：处理标准 API 响应格式 `{ data: {...}, pagination: {...} }`
+
+#### 类型定义更新
+```typescript
+// 旧版本
+interface WaterRecord {
+  source: 'manual' | 'auto' | 'other';
+  remark?: string;
+}
+
+// 新版本
+interface WaterRecord {
+  source?: 'Manual' | 'Auto';
+  note?: string;
+  recordedAt: string;
+}
+```
+
+### 2. Redux Store 修复 (store/waterSlice.ts)
+
+#### Loading 状态完善
+- ✅ 新增：`create`, `update`, `delete` loading 状态
+
+#### 完成率计算修复
+- ✅ 统一使用百分比格式：`(totalAmount / dailyGoal) * 100`
+- ✅ 所有相关计算都已更新
+
+#### 日期字段处理
+- ✅ 优先使用 `recordedAt`，回退到 `createdAt`
+
+### 3. Hooks 修复 (hooks/useWaterData.ts)
+
+#### 函数签名更新
+```typescript
+// 旧版本
+addWaterRecord(amount: number, remark?: string)
+
+// 新版本  
+addWaterRecord(amount: number, note?: string, recordedAt?: string)
+```
+
+#### 完成率计算
+- ✅ 返回百分比格式而非小数
+
+### 4. 组件修复
+
+#### WaterIntakeCard.tsx
+- ✅ 日期字段：优先使用 `recordedAt`
+- ✅ 完成率显示：移除多余的 `* 100` 计算
+
+#### AddWaterModal.tsx
+- ✅ 字段名称：`remark` → `note`
+- ✅ 数据结构：添加 `source: 'Manual'`
+
+## 测试要点
+
+### 1. API 调用测试
+```javascript
+// 测试创建记录
+const createResult = await createWaterRecord({
+  amount: 250,
+  note: "测试记录",
+  source: "Manual",
+  recordedAt: "2023-12-01T10:00:00.000Z"
+});
+
+// 测试获取统计
+const stats = await getTodayWaterStats();
+console.log('完成率应该是百分比:', stats.completionRate); // 应该是 0-100 的数值
+
+// 测试更新目标
+const goalResult = await updateWaterGoal({ dailyWaterGoal: 2500 });
+```
+
+### 2. Redux 状态测试
+```javascript
+// 测试完成率计算
+// 假设总量 1500ml，目标 2000ml
+// 期望完成率：75 (百分比)
+const expectedRate = (1500 / 2000) * 100; // 75
+```
+
+### 3. 组件渲染测试
+- ✅ 完成率显示正确（不会超过 100%）
+- ✅ 图表数据使用正确的时间字段
+- ✅ 表单提交使用正确的字段名称
+
+## 兼容性说明
+
+### 向后兼容
+- ✅ 保留了 `createdAt` 字段的回退逻辑
+- ✅ 保留了单日期查询的兼容性处理
+- ✅ 保留了原有的选择器函数
+
+### 新功能支持
+- ✅ 支持自定义记录时间 (`recordedAt`)
+- ✅ 支持新的 API 响应格式
+- ✅ 支持百分比格式的完成率
+
+## 需要验证的功能
+
+1. **创建记录**：确保新记录包含正确的字段
+2. **更新记录**：确保更新时使用正确的字段名
+3. **删除记录**：确保删除后统计数据正确更新
+4. **目标设置**：确保目标更新后完成率重新计算
+5. **统计查询**：确保返回正确的百分比格式完成率
+6. **图表显示**：确保使用正确的时间字段进行分组
+
+## 潜在问题
+
+1. **时区处理**：`recordedAt` 字段的时区处理需要注意
+2. **数据迁移**：现有数据可能没有 `recordedAt` 字段
+3. **API 兼容性**：确保后端 API 已经更新到新版本
+
+## 建议测试流程
+
+1. 单元测试：测试各个函数的输入输出
+2. 集成测试：测试 Redux 状态管理
+3. 端到端测试：测试完整的用户操作流程
+4. API 测试：使用 Postman 或类似工具测试 API 接口