# 心情打卡功能实现文档

## 功能概述

心情打卡功能允许用户记录每日的情绪状态，包括10种基本情绪类型，并可以添加强度评分和详细描述。该功能已完全集成到现有的健康数据统计页面中。

## 实现的功能

### 1. 核心功能
- ✅ 创建心情打卡记录
- ✅ 更新已有心情记录
- ✅ 删除心情记录（软删除）
- ✅ 查看每日心情记录
- ✅ 查看历史心情记录
- ✅ 心情统计分析

### 2. 心情类型
支持10种心情类型，每种都有对应的emoji和颜色：

| 心情类型 | 英文标识 | 中文标签 | Emoji | 颜色 |
|---------|---------|---------|-------|------|
| 开心 | happy | 开心 | 😊 | #4CAF50 |
| 心动 | excited | 心动 | 💓 | #E91E63 |
| 兴奋 | thrilled | 兴奋 | 🤩 | #FF9800 |
| 平静 | calm | 平静 | 😌 | #2196F3 |
| 焦虑 | anxious | 焦虑 | 😰 | #FF9800 |
| 难过 | sad | 难过 | 😢 | #2196F3 |
| 孤独 | lonely | 孤独 | 🥺 | #9C27B0 |
| 委屈 | wronged | 委屈 | 😔 | #607D8B |
| 生气 | angry | 生气 | 😡 | #F44336 |
| 心累 | tired | 心累 | 😴 | #9C27B0 |

### 3. 数据字段
- `moodType`: 心情类型（必填）
- `intensity`: 心情强度 1-10（必填，默认5）
- `description`: 心情描述（可选，最多200字符）
- `checkinDate`: 打卡日期（可选，默认当天）
- `metadata`: 扩展数据（可选）

## 文件结构

### 1. API服务层
```
services/moodCheckins.ts
```
- 定义心情类型和数据结构
- 提供完整的API调用方法
- 包含心情配置和工具函数

### 2. 组件层
```
components/MoodModal.tsx      # 心情打卡弹窗
components/MoodCard.tsx       # 心情卡片展示
components/MoodHistoryCard.tsx # 心情历史记录卡片
```

### 3. 页面层
```
app/(tabs)/statistics.tsx     # 主统计页面（集成心情卡片）
app/mood-statistics.tsx       # 心情统计详情页面
```

## API接口

### 创建心情打卡
```typescript
POST /api/mood-checkins
{
  "moodType": "happy",
  "intensity": 8,
  "description": "今天工作顺利，心情很好",
  "checkinDate": "2025-01-21"
}
```

### 获取每日心情
```typescript
GET /api/mood-checkins/daily?date=2025-01-21
```

### 获取心情历史
```typescript
GET /api/mood-checkins/history?startDate=2025-01-01&endDate=2025-01-31
```

### 获取心情统计
```typescript
GET /api/mood-checkins/statistics?startDate=2025-01-01&endDate=2025-01-31
```

## 使用方式

### 1. 在统计页面使用
心情卡片已集成到主统计页面中，用户可以选择日期查看对应的心情记录：

```typescript
// 加载指定日期的心情数据
const loadMoodData = async (targetDate?: Date) => {
  const dateString = dayjs(targetDate).format('YYYY-MM-DD');
  const checkins = await getDailyMoodCheckins(dateString);
  setCurrentMoodCheckin(checkins[0] || null);
};
```

### 2. 打开心情弹窗
点击心情卡片可以打开心情打卡弹窗：

```typescript
<MoodModal
  visible={moodModalVisible}
  onClose={() => setMoodModalVisible(false)}
  onSave={handleMoodSave}
  selectedDate={days[selectedIndex]?.date?.format('YYYY-MM-DD')}
/>
```

### 3. 查看心情统计
访问心情统计页面查看详细分析：

```typescript
// 加载最近30天的心情数据
const loadMoodData = async () => {
  const endDate = dayjs().format('YYYY-MM-DD');
  const startDate = dayjs().subtract(30, 'days').format('YYYY-MM-DD');
  
  const [historyData, statsData] = await Promise.all([
    getMoodCheckinsHistory({ startDate, endDate }),
    getMoodStatistics({ startDate, endDate })
  ]);
};
```

## 用户体验特性

### 1. 智能日期选择
- 支持选择任意日期进行心情打卡
- 自动加载选中日期的心情记录
- 如果已有记录，自动填充并支持更新

### 2. 直观的心情选择
- 使用emoji和颜色区分不同心情
- 支持心情强度1-10的滑动选择
- 可选的心情描述输入

### 3. 实时数据同步
- 保存后立即更新界面显示
- 支持离线缓存和网络同步
- 错误处理和重试机制

### 4. 统计分析
- 总打卡次数统计
- 平均心情强度计算
- 心情类型分布分析
- 最频繁心情识别

## 技术实现细节

### 1. 状态管理
使用React Hooks管理组件状态：
- `currentMoodCheckin`: 当前选中日期的情绪记录
- `isMoodLoading`: 加载状态
- `moodModalVisible`: 弹窗显示状态

### 2. 数据加载策略
- 页面聚焦时自动加载当前日期数据
- 日期切换时重新加载对应数据
- 支持并行加载多个数据源

### 3. 错误处理
- API调用失败时的友好提示
- 网络异常时的重试机制
- 数据加载失败时的降级显示

### 4. 性能优化
- 使用React.memo优化组件渲染
- 合理的数据缓存策略
- 避免不必要的API调用

## 扩展功能建议

1. **心情趋势图表**: 添加折线图显示心情变化趋势
2. **心情提醒**: 定时提醒用户进行心情打卡
3. **心情分享**: 允许用户分享心情状态到社交平台
4. **AI心情建议**: 基于心情状态提供改善建议
5. **数据导出**: 支持心情数据导出为CSV或PDF
6. **心情标签**: 支持自定义心情标签和分类
7. **心情日记**: 结合文字日记功能
8. **心情目标**: 设置心情改善目标并跟踪进度

## 注意事项

1. **数据隐私**: 心情数据属于敏感信息，需要严格的隐私保护
2. **用户体验**: 心情打卡应该是轻松愉快的体验，避免过于复杂的操作
3. **数据准确性**: 确保心情数据的准确性和一致性
4. **性能考虑**: 大量历史数据的加载和展示需要考虑性能优化
5. **兼容性**: 确保在不同设备和系统版本上的兼容性