一、应用概述

1.1 应用简介

喝水助手（Water Reminder）是一款关注用户日常饮水健康的辅助工具。基于"每天8杯水"的健康理念，应用帮助用户设定每日饮水目标、记录每次饮水量、通过进度环直观展示饮水进度、定时提醒用户喝水，并生成饮水健康报告。该应用以HarmonyOS NEXT的ArkTS框架为基础，深入展示了定时提醒、进度可视化、数据记录、目标管理、健康分析和本地数据持久化等关键技术。

1.2 核心功能

1.3 应用架构

喝水助手应用采用分层架构：

1. UI表现层：今日饮水进度环、快捷记录按钮、饮水记录列表、统计图表、设置界面。
2. 业务逻辑层：饮水记录管理器、目标计算器、提醒管理器、健康分析引擎。
3. 数据持久层：使用Preferences API存储饮水记录和用户设置。

二、饮水管理

2.1 饮水数据模型

interface WaterRecord {
  id: string;
  date: string;           // YYYY-MM-DD
  time: string;           // HH:mm
  amount: number;         // 饮水量（ml）
  cupType: string;        // 杯子类型（大水杯/小水杯/自定义）
  note: string;           // 备注
  timestamp: number;      // 时间戳
}

interface WaterSettings {
  dailyGoal: number;          // 每日目标（ml）
  cupSize: number;            // 默认杯量（ml）
  reminderInterval: number;   // 提醒间隔（分钟）
  reminderStart: string;      // 提醒开始时间
  reminderEnd: string;        // 提醒结束时间
  enableSound: boolean;       // 提醒音效
  enableVibration: boolean;   // 震动提醒
  unit: 'ml' | 'oz';         // 单位
}

interface DailyWaterStats {
  date: string;
  totalAmount: number;
  goal: number;
  progress: number;       // 百分比
  records: WaterRecord[];
  cups: number;           // 杯数
  isGoalReached: boolean;
  averageInterval: number; // 平均饮水间隔（分钟）
  bestHour: number;        // 饮水最多的小时
}

class WaterDataManager {
  private records: WaterRecord[] = [];
  private settings: WaterSettings = {
    dailyGoal: 2000,
    cupSize: 250,
    reminderInterval: 60,
    reminderStart: '08:00',
    reminderEnd: '22:00',
    enableSound: true,
    enableVibration: true,
    unit: 'ml'
  };
  
  // 添加饮水记录
  addRecord(amount: number, cupType: string = 'default', note: string = ''): WaterRecord {
    const now = new Date();
    const record: WaterRecord = {
      id: Date.now().toString(),
      date: this.formatDate(now),
      time: this.formatTime(now),
      amount,
      cupType,
      note,
      timestamp: now.getTime()
    };
    this.records.push(record);
    return record;
  }
  
  // 获取今日统计
  getTodayStats(): DailyWaterStats {
    const today = this.formatDate(new Date());
    const todayRecords = this.records.filter(r => r.date === today);
    const totalAmount = todayRecords.reduce((sum, r) => sum + r.amount, 0);
    
    // 计算平均饮水间隔
    const sortedRecords = [...todayRecords].sort((a, b) => a.timestamp - b.timestamp);
    let totalInterval = 0;
    let intervalCount = 0;
    for (let i = 1; i < sortedRecords.length; i++) {
      const interval = (sortedRecords[i].timestamp - sortedRecords[i - 1].timestamp) / 60000;
      if (interval < 360) { // 忽略超过6小时的间隔
        totalInterval += interval;
        intervalCount++;
      }
    }
    
    // 计算饮水最多的小时
    const hourCounts: Record<number, number> = {};
    for (const r of todayRecords) {
      const hour = parseInt(r.time.split(':')[0]);
      hourCounts[hour] = (hourCounts[hour] || 0) + r.amount;
    }
    let bestHour = 0;
    let maxAmount = 0;
    for (const [hour, amount] of Object.entries(hourCounts)) {
      if (amount > maxAmount) {
        maxAmount = amount;
        bestHour = parseInt(hour);
      }
    }
    
    return {
      date: today,
      totalAmount,
      goal: this.settings.dailyGoal,
      progress: this.settings.dailyGoal > 0 ? Math.round(totalAmount / this.settings.dailyGoal * 100) : 0,
      records: todayRecords,
      cups: todayRecords.length,
      isGoalReached: totalAmount >= this.settings.dailyGoal,
      averageInterval: intervalCount > 0 ? Math.round(totalInterval / intervalCount) : 0,
      bestHour
    };
  }
  
  // 获取周统计
  getWeeklyStats(): DailyWaterStats[] {
    const stats: DailyWaterStats[] = [];
    const today = new Date();
    for (let i = 6; i >= 0; i--) {
      const date = new Date(today);
      date.setDate(date.getDate() - i);
      const dateStr = this.formatDate(date);
      const dayRecords = this.records.filter(r => r.date === dateStr);
      const totalAmount = dayRecords.reduce((sum, r) => sum + r.amount, 0);
      
      stats.push({
        date: dateStr,
        totalAmount,
        goal: this.settings.dailyGoal,
        progress: this.settings.dailyGoal > 0 ? Math.round(totalAmount / this.settings.dailyGoal * 100) : 0,
        records: dayRecords,
        cups: dayRecords.length,
        isGoalReached: totalAmount >= this.settings.dailyGoal,
        averageInterval: 0,
        bestHour: 0
      });
    }
    return stats;
  }
  
  // 根据体重推荐饮水量（体重kg × 30ml）
  static calculateRecommendedGoal(weightKg: number): number {
    return Math.round(weightKg * 30 / 100) * 100; // 四舍五入到100ml
  }
  
  // 根据活动量调整推荐
  static calculateAdjustedGoal(weightKg: number, activityLevel: 'low' | 'medium' | 'high', temperature: 'normal' | 'hot'): number {
    const base = weightKg * 30;
    const activityMultiplier = { 'low': 1, 'medium': 1.2, 'high': 1.5 };
    const tempMultiplier = temperature === 'hot' ? 1.3 : 1;
    return Math.round(base * activityMultiplier[activityLevel] * tempMultiplier / 100) * 100;
  }
  
  private formatDate(date: Date): string {
    return `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}-${date.getDate().toString().padStart(2, '0')}`;
  }
  
  private formatTime(date: Date): string {
    return `${date.getHours().toString().padStart(2, '0')}:${date.getMinutes().toString().padStart(2, '0')}`;
  }
}

三、提醒系统

3.1 智能提醒管理器

class ReminderManager {
  private timerId: number | null = null;
  private isRunning: boolean = false;
  private settings: WaterSettings;
  private lastReminderTime: number = 0;
  
  constructor(settings: WaterSettings) {
    this.settings = settings;
  }
  
  start(): void {
    if (this.isRunning) return;
    this.isRunning = true;
    this.scheduleNextReminder();
  }
  
  stop(): void {
    if (this.timerId !== null) {
      clearTimeout(this.timerId);
      this.timerId = null;
    }
    this.isRunning = false;
  }
  
  private scheduleNextReminder(): void {
    const now = new Date();
    const startParts = this.settings.reminderStart.split(':').map(Number);
    const endParts = this.settings.reminderEnd.split(':').map(Number);
    
    const startMinutes = startParts[0] * 60 + startParts[1];
    const endMinutes = endParts[0] * 60 + endParts[1];
    const currentMinutes = now.getHours() * 60 + now.getMinutes();
    
    // 检查是否在提醒时间段内
    if (currentMinutes < startMinutes || currentMinutes >= endMinutes) {
      // 不在提醒时间段，计算下一次提醒开始时间
      const nextReminder = new Date(now);
      nextReminder.setHours(startParts[0], startParts[1], 0, 0);
      if (nextReminder <= now) {
        nextReminder.setDate(nextReminder.getDate() + 1);
      }
      const delay = nextReminder.getTime() - now.getTime();
      this.timerId = setTimeout(() => this.fireReminder(), delay);
      return;
    }
    
    // 在提醒时间段内，设置下一次提醒
    const interval = this.settings.reminderInterval * 60 * 1000;
    this.timerId = setTimeout(() => this.fireReminder(), interval);
  }
  
  private fireReminder(): void {
    // 发送通知
    this.sendNotification();
    this.lastReminderTime = Date.now();
    
    // 安排下一次
    this.scheduleNextReminder();
  }
  
  private async sendNotification(): Promise<void> {
    try {
      const notificationRequest = {
        content: {
          contentType: 0,
          text: '该喝水了！记得补充水分 💧',
          title: '💧 喝水提醒',
          additionalText: `今日进度: ${this.getTodayProgress()}%`
        },
        id: 1001,
        slotType: 0,
      };
      
      await notification.requestEnableNotification();
      await notification.publishNotification(notificationRequest);
    } catch (error) {
      console.error(`[Reminder] Failed to send notification: ${error}`);
    }
  }
  
  private getTodayProgress(): number {
    // 简单实现，实际应由外部传入
    return 50;
  }
  
  // 智能调整提醒间隔
  static calculateSmartInterval(
    totalAmount: number,
    goal: number,
    currentTime: Date,
    wakeUpTime: string,
    bedTime: string
  ): number {
    const wakeParts = wakeUpTime.split(':').map(Number);
    const bedParts = bedTime.split(':').map(Number);
    const wakeMinutes = wakeParts[0] * 60 + wakeParts[1];
    const bedMinutes = bedParts[0] * 60 + bedParts[1];
    const awakeMinutes = bedMinutes - wakeMinutes;
    
    const remaining = goal - totalAmount;
    if (remaining <= 0) return 120; // 目标已达，每2小时提醒一次
    
    const remainingHours = awakeMinutes - (currentTime.getHours() * 60 + currentTime.getMinutes() - wakeMinutes);
    if (remainingHours <= 0) return 60;
    
    const intervalMinutes = Math.round(remainingHours * 60 / (remaining / 250));
    return Math.max(15, Math.min(120, intervalMinutes));
  }
}

四、UI交互设计

4.1 饮水进度环

@Component
struct WaterProgressRing {
  @Link progress: number;      // 0-100
  @Link currentAmount: number;
  @Link dailyGoal: number;
  @State showAnimation: boolean = false;
  
  build() {
    Column() {
      Stack() {
        // 背景环
        Circle()
          .width(200)
          .height(200)
          .fill('none')
          .stroke('#E3F2FD')
          .strokeWidth(16)
        
        // 前景环
        Circle()
          .width(200)
          .height(200)
          .fill('none')
          .stroke('#2196F3')
          .strokeWidth(16)
          .strokeDashOffset((1 - this.progress / 100) * 565.48)
          .rotate({ angle: -90 })
          .animation({ duration: 800, curve: Curve.EaseOut })
        
        // 中心信息
        Column() {
          Text('💧')
            .fontSize(36)
          Text(`${this.currentAmount}ml`)
            .fontSize(28)
            .fontWeight(FontWeight.Bold)
            .fontColor('#1565C0')
          Text(`/ ${this.dailyGoal}ml`)
            .fontSize(14)
            .fontColor('#666666')
          Text(`${this.progress}%`)
            .fontSize(14)
            .fontColor('#2196F3')
            .margin({ top: 4 })
        }
      }
      .width(200)
      .height(200)
      
      // 状态提示
      Text(this.getStatusText())
        .fontSize(14)
        .fontColor(this.getStatusColor())
        .margin({ top: 12 })
    }
  }
  
  private getStatusText(): string {
    if (this.progress >= 100) return '🎉 今日饮水目标已达成！';
    if (this.progress >= 75) return '👍 已喝了大半，继续保持！';
    if (this.progress >= 50) return '💪 已经喝完一半了！';
    if (this.progress >= 25) return '👌 不错的开始，继续加油！';
    if (this.progress > 0) return '💧 记得多喝水哦！';
    return '☀️ 开始今天的饮水计划吧！';
  }
  
  private getStatusColor(): string {
    if (this.progress >= 100) return '#4CAF50';
    if (this.progress >= 50) return '#FF9800';
    return '#2196F3';
  }
}

4.2 快捷记录按钮

@Component
struct QuickAddButtons {
  @Link cupSize: number;
  onAddWater: ((amount: number) => void) | null = null;
  
  build() {
    Row({ space: 12 }) {
      this.createQuickButton('🥤', `${this.cupSize}ml`, this.cupSize, '#E3F2FD')
      this.createQuickButton('🍶', `${this.cupSize * 2}ml`, this.cupSize * 2, '#BBDEFB')
      this.createQuickButton('🫗', `${this.cupSize * 3}ml`, this.cupSize * 3, '#90CAF9')
      this.createQuickButton('📏', '自定义', 0, '#E0E0E0')
    }
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
  
  @Builder
  private createQuickButton(emoji: string, label: string, amount: number, bgColor: string) {
    Column() {
      Text(emoji)
        .fontSize(28)
      Text(label)
        .fontSize(12)
        .fontColor('#333333')
        .margin({ top: 4 })
    }
    .padding(12)
    .backgroundColor(bgColor)
    .borderRadius(16)
    .onClick(() => {
      this.onAddWater?.(amount);
    })
  }
}

五、总结

5.1 核心技术要点

1. 饮水跟踪系统：精确记录每次饮水量，支持多种杯量和快速记录。
2. 进度环可视化：使用ArkTS Circle组件实现圆形进度环，动画过渡流畅。
3. 智能提醒系统：基于时间段和饮水进度的智能提醒，支持自定义提醒间隔。
4. 健康推荐算法：根据体重、活动量和气温计算个性化饮水目标。
5. 数据统计：日/周/月维度的饮水统计，趋势分析。
6. 通知集成：使用鸿蒙Notification API发送定时提醒通知。

5.2 扩展方向

1. 智能设备同步：连接智能水杯自动记录饮水量。
2. 天气联动：根据天气温湿度自动调整饮水目标。
3. 运动联动：记录运动后的额外水分补充需求。
4. 饮水健康报告：生成周/月饮水健康报告。
5. 社交挑战：与好友比拼饮水达标率。

5.3 核心代码量统计