feat: 实现日历提醒完整功能（操作执行、通知服务重构、归档）

- 新增 ReminderActionExecutor 处理取消/稍后提醒操作 - 新增 ReminderOutboxStore 本地存储待处理操作 - 重构 LocalNotificationService 支持聚合提醒和交互操作 - 新增 event_color_resolver 工具类统一颜色解析 - 新增 CalendarService.archiveEvent 归档方法 - 增强 ModelTracking 支持缓存命中、推理token和成本追踪 - 添加 qwen3.5-35b-a3b 模型配置 - 更新 AndroidManifest 全屏intent权限 - 补充相关单元测试和文档
2026-03-18 19:12:47 +08:00
parent 257cb0f5d5
commit 00f37d7e19
35 changed files with 2676 additions and 244 deletions
@@ -1,6 +1,7 @@
 import 'package:dio/dio.dart';
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 import 'package:get_it/get_it.dart';
+import 'package:shared_preferences/shared_preferences.dart';
 import '../api/api_client.dart';
 import '../api/i_api_client.dart';
 import '../storage/token_storage.dart';
@@ -13,6 +14,8 @@ import '../../features/auth/presentation/bloc/auth_bloc.dart';
 import '../../features/auth/presentation/bloc/auth_event.dart';
 import '../../features/calendar/data/calendar_api.dart';
 import '../../features/calendar/data/services/calendar_service.dart';
+import '../../features/calendar/reminders/reminder_action_executor.dart';
+import '../../features/calendar/reminders/reminder_outbox_store.dart';
 import '../../features/calendar/ui/calendar_state_manager.dart';
 import '../../features/friends/data/friends_api.dart';
 import '../../features/messages/data/inbox_api.dart';
@@ -49,6 +52,9 @@ Future<void> configureDependencies() async {
  final authApi = AuthApi(apiClient);
  sl.registerSingleton<AuthApi>(authApi);

+  final sharedPreferences = await SharedPreferences.getInstance();
+  sl.registerSingleton<SharedPreferences>(sharedPreferences);
+
  final usersApi = UsersApi(apiClient);
  sl.registerSingleton<UsersApi>(usersApi);

@@ -58,8 +64,18 @@ Future<void> configureDependencies() async {
  final calendarService = CalendarService(apiClient: apiClient);
  sl.registerSingleton<CalendarService>(calendarService);

+  final reminderOutboxStore = ReminderOutboxStore(sharedPreferences);
+  sl.registerSingleton<ReminderOutboxStore>(reminderOutboxStore);
+
  sl.registerSingleton<LocalNotificationService>(LocalNotificationService());

+  final reminderActionExecutor = ReminderActionExecutor(
+    calendarService: calendarService,
+    notificationService: sl<LocalNotificationService>(),
+    outboxStore: reminderOutboxStore,
+  );
+  sl.registerSingleton<ReminderActionExecutor>(reminderActionExecutor);
+
  final friendsApi = FriendsApi(apiClient);
  sl.registerSingleton<FriendsApi>(friendsApi);

@@ -1,26 +1,40 @@
-import 'package:flutter_local_notifications/flutter_local_notifications.dart';
+import 'dart:convert';
+
 import 'package:flutter/foundation.dart';
+import 'package:flutter_local_notifications/flutter_local_notifications.dart';
 import 'package:timezone/data/latest.dart' as tz_data;
 import 'package:timezone/timezone.dart' as tz;

 import '../../features/calendar/data/models/schedule_item_model.dart';
+import '../../features/calendar/reminders/models/reminder_action.dart';
+import '../../features/calendar/reminders/models/reminder_payload.dart';
+import '../../features/calendar/reminders/reminder_overlap_policy.dart';

-class NotificationScheduleException implements Exception {
-  final String message;
-
-  NotificationScheduleException(this.message);
-
-  @override
-  String toString() => message;
-}
+typedef ReminderNotificationActionHandler =
+    Future<void> Function({
+      required ReminderAction action,
+      required ReminderPayload payload,
+    });

 class LocalNotificationService {
-  final FlutterLocalNotificationsPlugin _plugin;
-  bool _initialized = false;
-  bool _exactAlarmPermissionRequested = false;
+  static const String _iosCategoryId = 'calendar_reminder_actions_v1';
+  static const String _actionCancel = 'cancel';
+  static const String _actionSnooze = 'snooze_10m';

-  LocalNotificationService({FlutterLocalNotificationsPlugin? plugin})
-    : _plugin = plugin ?? FlutterLocalNotificationsPlugin();
+  final FlutterLocalNotificationsPlugin _plugin;
+  final ReminderOverlapPolicy _overlapPolicy;
+  bool _initialized = false;
+  ReminderNotificationActionHandler? _actionHandler;
+
+  LocalNotificationService({
+    FlutterLocalNotificationsPlugin? plugin,
+    ReminderOverlapPolicy? overlapPolicy,
+  }) : _plugin = plugin ?? FlutterLocalNotificationsPlugin(),
+       _overlapPolicy = overlapPolicy ?? const ReminderOverlapPolicy();
+
+  void bindActionHandler(ReminderNotificationActionHandler handler) {
+    _actionHandler = handler;
+  }

  Future<void> initialize() async {
    if (_initialized) {
@@ -29,20 +43,40 @@ class LocalNotificationService {
    tz_data.initializeTimeZones();

    const android = AndroidInitializationSettings('@mipmap/ic_launcher');
-    const ios = DarwinInitializationSettings(
+    final ios = DarwinInitializationSettings(
      requestAlertPermission: false,
      requestBadgePermission: false,
      requestSoundPermission: false,
+      notificationCategories: [
+        DarwinNotificationCategory(
+          _iosCategoryId,
+          actions: <DarwinNotificationAction>[
+            DarwinNotificationAction.plain(_actionCancel, '取消'),
+            DarwinNotificationAction.plain(
+              _actionSnooze,
+              '稍后提醒',
+              options: <DarwinNotificationActionOption>{
+                DarwinNotificationActionOption.foreground,
+              },
+            ),
+          ],
+        ),
+      ],
    );
-    const settings = InitializationSettings(android: android, iOS: ios);
+    final settings = InitializationSettings(android: android, iOS: ios);

-    await _plugin.initialize(settings);
+    await _plugin.initialize(
+      settings,
+      onDidReceiveNotificationResponse: _onNotificationResponse,
+    );

    final androidImpl = _plugin
        .resolvePlatformSpecificImplementation<
          AndroidFlutterLocalNotificationsPlugin
        >();
    await androidImpl?.requestNotificationsPermission();
+    await androidImpl?.requestExactAlarmsPermission();
+    await androidImpl?.requestFullScreenIntentPermission();

    final iosImpl = _plugin
        .resolvePlatformSpecificImplementation<
@@ -55,115 +89,46 @@ class LocalNotificationService {

  Future<void> upsertEventReminder(ScheduleItemModel event) async {
    await initialize();
-
-    final reminderMinutes = event.metadata?.reminderMinutes;
-    if (reminderMinutes == null) {
+    if (event.status != ScheduleStatus.active ||
+        event.metadata?.reminderMinutes == null) {
      await cancelEventReminder(event.id);
      return;
    }

-    final fireAt = event.startAt.subtract(Duration(minutes: reminderMinutes));
-    if (!fireAt.isAfter(DateTime.now())) {
+    final now = DateTime.now();
+    final fireAt = _overlapPolicy.resolveFirstFireAt(event, now: now);
+    if (fireAt == null) {
      await cancelEventReminder(event.id);
      return;
    }

-    final notificationId = _notificationIdForEvent(event.id);
-    final scheduledAt = tz.TZDateTime.from(fireAt, tz.local);
-    final androidImpl = _plugin
-        .resolvePlatformSpecificImplementation<
-          AndroidFlutterLocalNotificationsPlugin
-        >();
+    await cancelEventReminder(event.id);
+    await _scheduleRemindersFrom(event: event, firstFireAt: fireAt);
+  }

-    var androidScheduleMode = AndroidScheduleMode.exactAllowWhileIdle;
-    if (defaultTargetPlatform == TargetPlatform.android &&
-        androidImpl != null) {
-      var notificationsEnabled =
-          await androidImpl.areNotificationsEnabled() ?? false;
-      if (!notificationsEnabled) {
-        await androidImpl.requestNotificationsPermission();
-        notificationsEnabled =
-            await androidImpl.areNotificationsEnabled() ?? false;
-      }
-      if (!notificationsEnabled) {
-        throw NotificationScheduleException('系统通知权限未开启，无法创建提醒');
-      }
-
-      try {
-        var canScheduleExact =
-            await androidImpl.canScheduleExactNotifications() ?? false;
-        if (!canScheduleExact && !_exactAlarmPermissionRequested) {
-          _exactAlarmPermissionRequested = true;
-          await androidImpl.requestExactAlarmsPermission();
-          canScheduleExact =
-              await androidImpl.canScheduleExactNotifications() ?? false;
-        }
-        if (!canScheduleExact) {
-          androidScheduleMode = AndroidScheduleMode.inexactAllowWhileIdle;
-        }
-      } catch (_) {
-        androidScheduleMode = AndroidScheduleMode.inexactAllowWhileIdle;
-      }
-    }
-
-    final details = NotificationDetails(
-      android: AndroidNotificationDetails(
-        'calendar_reminder_channel',
-        '日历提醒',
-        channelDescription: '日历事件提醒通知',
-        importance: Importance.max,
-        priority: Priority.high,
-        enableVibration: true,
-      ),
-      iOS: const DarwinNotificationDetails(
-        presentAlert: true,
-        presentSound: true,
-        presentBadge: true,
-      ),
-    );
-
-    try {
-      await _plugin.zonedSchedule(
-        notificationId,
-        event.title,
-        _buildReminderBody(event, reminderMinutes),
-        scheduledAt,
-        details,
-        androidScheduleMode: androidScheduleMode,
-        uiLocalNotificationDateInterpretation:
-            UILocalNotificationDateInterpretation.absoluteTime,
-      );
-
-      final pending = await _plugin.pendingNotificationRequests();
-      final scheduled = pending.any((item) => item.id == notificationId);
-      if (!scheduled) {
-        throw NotificationScheduleException('提醒未被系统接受，请检查系统通知和电池优化设置');
-      }
-    } catch (error) {
-      if (error is NotificationScheduleException) {
-        rethrow;
-      }
-      await _plugin.zonedSchedule(
-        notificationId,
-        event.title,
-        _buildReminderBody(event, reminderMinutes),
-        scheduledAt,
-        details,
-        androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
-        uiLocalNotificationDateInterpretation:
-            UILocalNotificationDateInterpretation.absoluteTime,
-      );
-
-      final pending = await _plugin.pendingNotificationRequests();
-      final scheduled = pending.any((item) => item.id == notificationId);
-      if (!scheduled) {
-        throw NotificationScheduleException('提醒创建失败，请检查系统设置后重试');
-      }
-    }
+  Future<void> scheduleReminderAt(
+    ScheduleItemModel event,
+    DateTime fireAt,
+  ) async {
+    await initialize();
+    await cancelEventReminder(event.id);
+    await _scheduleRemindersFrom(event: event, firstFireAt: fireAt);
  }

  Future<void> cancelEventReminder(String eventId) async {
    await initialize();
+    final pending = await _plugin.pendingNotificationRequests();
+    for (final request in pending) {
+      final payload = _decodePayload(request.payload);
+      if (payload == null) {
+        continue;
+      }
+      if (payload.eventId == eventId ||
+          payload.aggregateIds.contains(eventId)) {
+        await _plugin.cancel(request.id);
+      }
+    }
+
    await _plugin.cancel(_notificationIdForEvent(eventId));
  }

@@ -171,8 +136,15 @@ class LocalNotificationService {
    Iterable<ScheduleItemModel> events,
  ) async {
    await initialize();
-    for (final event in events) {
-      await upsertEventReminder(event);
+
+    final now = DateTime.now();
+    final groups = _overlapPolicy.groupByMinute(events, now: now);
+    for (final group in groups) {
+      if (group.isAggregate) {
+        await _scheduleAggregateReminder(group.events, group.fireAt);
+        continue;
+      }
+      await upsertEventReminder(group.events.first);
    }
  }

@@ -180,10 +152,243 @@ class LocalNotificationService {
    return eventId.hashCode & 0x7fffffff;
  }

-  String _buildReminderBody(ScheduleItemModel event, int reminderMinutes) {
-    if (reminderMinutes == 0) {
-      return '日程现在开始：${event.title}';
+  int _notificationIdForEventCycle(
+    String eventId,
+    DateTime fireAt,
+    ReminderPayloadMode mode,
+  ) {
+    final cycleMinute =
+        fireAt.millisecondsSinceEpoch ~/
+        const Duration(minutes: 1).inMilliseconds;
+    return '$eventId|$cycleMinute|${mode.value}'.hashCode & 0x7fffffff;
+  }
+
+  Future<AndroidScheduleMode> _resolveAndroidScheduleMode() async {
+    if (defaultTargetPlatform != TargetPlatform.android) {
+      return AndroidScheduleMode.exactAllowWhileIdle;
+    }
+
+    final androidImpl = _plugin
+        .resolvePlatformSpecificImplementation<
+          AndroidFlutterLocalNotificationsPlugin
+        >();
+    if (androidImpl == null) {
+      return AndroidScheduleMode.exactAllowWhileIdle;
+    }
+
+    final canScheduleExact =
+        await androidImpl.canScheduleExactNotifications() ?? false;
+    return canScheduleExact
+        ? AndroidScheduleMode.exactAllowWhileIdle
+        : AndroidScheduleMode.inexactAllowWhileIdle;
+  }
+
+  NotificationDetails _buildNotificationDetails() {
+    return NotificationDetails(
+      android: AndroidNotificationDetails(
+        'calendar_alarm_channel_v2',
+        '日程闹钟提醒',
+        channelDescription: '日程到点闹钟式提醒通知',
+        importance: Importance.max,
+        priority: Priority.max,
+        category: AndroidNotificationCategory.alarm,
+        audioAttributesUsage: AudioAttributesUsage.alarm,
+        fullScreenIntent: true,
+        playSound: true,
+        enableVibration: true,
+        vibrationPattern: Int64List.fromList([0, 1000, 500, 1200]),
+        timeoutAfter: 30000,
+        autoCancel: true,
+        actions: <AndroidNotificationAction>[
+          AndroidNotificationAction(_actionCancel, '取消'),
+          AndroidNotificationAction(
+            _actionSnooze,
+            '稍后提醒',
+            showsUserInterface: true,
+          ),
+        ],
+      ),
+      iOS: const DarwinNotificationDetails(
+        presentAlert: true,
+        presentSound: true,
+        presentBadge: true,
+        categoryIdentifier: _iosCategoryId,
+      ),
+    );
+  }
+
+  Future<void> _scheduleSingleReminder({
+    required ScheduleItemModel event,
+    required DateTime fireAt,
+  }) async {
+    final notificationId = _notificationIdForEventCycle(
+      event.id,
+      fireAt,
+      ReminderPayloadMode.single,
+    );
+    final payload = ReminderPayload(
+      eventId: event.id,
+      title: event.title,
+      startAt: event.startAt,
+      endAt: event.endAt,
+      timezone: event.timezone,
+      location: event.metadata?.location,
+      notes: event.metadata?.notes,
+      color: event.metadata?.color,
+      mode: ReminderPayloadMode.single,
+      version: 1,
+    );
+
+    final details = _buildNotificationDetails();
+    final scheduledAt = tz.TZDateTime.from(fireAt, tz.local);
+    final mode = await _resolveAndroidScheduleMode();
+
+    try {
+      await _plugin.zonedSchedule(
+        notificationId,
+        event.title,
+        _buildReminderBody(event, event.metadata?.reminderMinutes ?? 0),
+        scheduledAt,
+        details,
+        payload: jsonEncode(payload.toJson()),
+        androidScheduleMode: mode,
+        uiLocalNotificationDateInterpretation:
+            UILocalNotificationDateInterpretation.absoluteTime,
+      );
+    } catch (_) {
+      await _plugin.zonedSchedule(
+        notificationId,
+        event.title,
+        _buildReminderBody(event, event.metadata?.reminderMinutes ?? 0),
+        scheduledAt,
+        details,
+        payload: jsonEncode(payload.toJson()),
+        androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
+        uiLocalNotificationDateInterpretation:
+            UILocalNotificationDateInterpretation.absoluteTime,
+      );
+    }
+  }
+
+  Future<void> _scheduleRemindersFrom({
+    required ScheduleItemModel event,
+    required DateTime firstFireAt,
+  }) async {
+    final endAt = event.endAt;
+    var cursor = firstFireAt;
+    if (endAt == null) {
+      await _scheduleSingleReminder(event: event, fireAt: cursor);
+      return;
+    }
+
+    while (cursor.isBefore(endAt)) {
+      await _scheduleSingleReminder(event: event, fireAt: cursor);
+      cursor = cursor.add(const Duration(minutes: 10));
+    }
+  }
+
+  Future<void> _scheduleAggregateReminder(
+    List<ScheduleItemModel> events,
+    DateTime fireAt,
+  ) async {
+    if (events.isEmpty) {
+      return;
+    }
+
+    final first = events.first;
+    final aggregateIds = events.map((event) => event.id).toList();
+    for (final id in aggregateIds) {
+      await cancelEventReminder(id);
+    }
+
+    final payload = ReminderPayload(
+      eventId: first.id,
+      title: '你有${events.length}个日程提醒',
+      startAt: first.startAt,
+      endAt: first.endAt,
+      timezone: first.timezone,
+      mode: ReminderPayloadMode.aggregate,
+      aggregateIds: aggregateIds,
+      version: 1,
+    );
+
+    final details = _buildNotificationDetails();
+    final scheduledAt = tz.TZDateTime.from(fireAt, tz.local);
+    final mode = await _resolveAndroidScheduleMode();
+    final preview = events.take(3).map((item) => item.title).join('、');
+
+    await _plugin.zonedSchedule(
+      _notificationIdForEventCycle(
+        first.id,
+        fireAt,
+        ReminderPayloadMode.aggregate,
+      ),
+      '你有${events.length}个日程提醒',
+      preview,
+      scheduledAt,
+      details,
+      payload: jsonEncode(payload.toJson()),
+      androidScheduleMode: mode,
+      uiLocalNotificationDateInterpretation:
+          UILocalNotificationDateInterpretation.absoluteTime,
+    );
+  }
+
+  ReminderPayload? _decodePayload(String? raw) {
+    if (raw == null || raw.isEmpty) {
+      return null;
+    }
+    try {
+      final json = Map<String, dynamic>.from(jsonDecode(raw) as Map);
+      return ReminderPayload.fromJson(json);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  String _buildReminderBody(ScheduleItemModel event, int reminderMinutes) {
+    final when = reminderMinutes == 0
+        ? '日程现在开始'
+        : '日程即将开始（提前$reminderMinutes分钟）';
+    final location = event.metadata?.location;
+    final notes = event.metadata?.notes;
+    final buffer = StringBuffer(when);
+    if (location != null && location.isNotEmpty) {
+      buffer.write('\n地点：$location');
+    }
+    if (notes != null && notes.isNotEmpty) {
+      buffer.write(
+        '\n备注：${notes.length > 30 ? '${notes.substring(0, 30)}...' : notes}',
+      );
+    }
+    return buffer.toString();
+  }
+
+  Future<void> _onNotificationResponse(NotificationResponse response) async {
+    final payloadRaw = response.payload;
+    if (payloadRaw == null || payloadRaw.isEmpty) {
+      return;
+    }
+    final handler = _actionHandler;
+    if (handler == null) {
+      return;
+    }
+
+    try {
+      final payload = ReminderPayload.fromJson(
+        Map<String, dynamic>.from(jsonDecode(payloadRaw) as Map),
+      );
+      final actionId = response.actionId;
+      if (actionId == _actionCancel) {
+        await handler(action: ReminderAction.cancel, payload: payload);
+        return;
+      }
+      if (actionId == _actionSnooze) {
+        await handler(action: ReminderAction.snooze10m, payload: payload);
+      }
+    } catch (_) {
+      debugPrint('failed to handle reminder notification response');
+      return;
    }
-    return '日程即将开始（提前$reminderMinutes分钟）：${event.title}';
  }
 }
@@ -1,16 +1,20 @@
 import '../../features/auth/presentation/bloc/auth_state.dart';
 import '../../features/calendar/data/services/calendar_service.dart';
+import '../../features/calendar/reminders/reminder_action_executor.dart';
 import '../notifications/local_notification_service.dart';

 class AuthSessionBootstrapper {
  AuthSessionBootstrapper({
    required CalendarService calendarService,
    required LocalNotificationService notificationService,
+    required ReminderActionExecutor reminderActionExecutor,
  }) : _calendarService = calendarService,
-       _notificationService = notificationService;
+       _notificationService = notificationService,
+       _reminderActionExecutor = reminderActionExecutor;

  final CalendarService _calendarService;
  final LocalNotificationService _notificationService;
+  final ReminderActionExecutor _reminderActionExecutor;

  String? _syncedUserId;

@@ -24,13 +28,15 @@ class AuthSessionBootstrapper {
      return;
    }

-    _syncedUserId = state.user.id;
-
    try {
+      await _reminderActionExecutor.replayPendingActions();
+
      final now = DateTime.now();
+      final start = now.subtract(const Duration(days: 90));
      final end = now.add(const Duration(days: 90));
-      final events = await _calendarService.getEventsForRange(now, end);
+      final events = await _calendarService.getEventsForRange(start, end);
      await _notificationService.rebuildUpcomingReminders(events);
+      _syncedUserId = state.user.id;
    } catch (_) {
      // ignore reminder bootstrap failures
    }
@@ -44,6 +44,14 @@ class CalendarService {
    return _api.update(event);
  }

+  Future<ScheduleItemModel?> archiveEvent(String id) async {
+    final event = await getEventById(id);
+    if (event == null) {
+      return null;
+    }
+    return updateEvent(event.copyWith(status: ScheduleStatus.archived));
+  }
+
  Future<void> deleteEvent(String id) async {
    await _api.delete(id);
  }
@@ -0,0 +1,17 @@
+enum ReminderAction {
+  cancel('cancel'),
+  snooze10m('snooze_10m'),
+  timeout30s('timeout_30s'),
+  autoArchive('auto_archive');
+
+  const ReminderAction(this.value);
+
+  final String value;
+
+  static ReminderAction fromValue(String raw) {
+    return ReminderAction.values.firstWhere(
+      (item) => item.value == raw,
+      orElse: () => ReminderAction.timeout30s,
+    );
+  }
+}
@@ -0,0 +1,174 @@
+class ReminderPayload {
+  final String eventId;
+  final String title;
+  final DateTime startAt;
+  final DateTime? endAt;
+  final String timezone;
+  final String? location;
+  final String? notes;
+  final String? color;
+  final ReminderPayloadMode mode;
+  final List<String> aggregateIds;
+  final int version;
+
+  const ReminderPayload({
+    required this.eventId,
+    required this.title,
+    required this.startAt,
+    required this.timezone,
+    this.endAt,
+    this.location,
+    this.notes,
+    this.color,
+    this.mode = ReminderPayloadMode.single,
+    this.aggregateIds = const [],
+    this.version = 1,
+  });
+
+  ReminderPayload copyWith({
+    String? eventId,
+    String? title,
+    DateTime? startAt,
+    DateTime? endAt,
+    String? timezone,
+    String? location,
+    String? notes,
+    String? color,
+    ReminderPayloadMode? mode,
+    List<String>? aggregateIds,
+    int? version,
+  }) {
+    return ReminderPayload(
+      eventId: eventId ?? this.eventId,
+      title: title ?? this.title,
+      startAt: startAt ?? this.startAt,
+      endAt: endAt ?? this.endAt,
+      timezone: timezone ?? this.timezone,
+      location: location ?? this.location,
+      notes: notes ?? this.notes,
+      color: color ?? this.color,
+      mode: mode ?? this.mode,
+      aggregateIds: aggregateIds ?? this.aggregateIds,
+      version: version ?? this.version,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'eventId': eventId,
+      'title': title,
+      'startAt': startAt.toIso8601String(),
+      'endAt': endAt?.toIso8601String(),
+      'timezone': timezone,
+      'location': location,
+      'notes': notes,
+      'color': color,
+      'mode': mode.value,
+      'aggregateIds': aggregateIds,
+      'version': version,
+    };
+  }
+
+  factory ReminderPayload.fromJson(Map<String, dynamic> json) {
+    final eventId = (json['eventId'] as String?) ?? '';
+    if (eventId.isEmpty) {
+      throw const FormatException('eventId is required');
+    }
+
+    final startAtRaw = json['startAt'] as String?;
+    if (startAtRaw == null || startAtRaw.isEmpty) {
+      throw const FormatException('startAt is required');
+    }
+    final parsedStartAt = DateTime.parse(startAtRaw);
+
+    final mode = ReminderPayloadMode.fromValue(
+      (json['mode'] as String?) ?? 'single',
+    );
+    final aggregateIds = (json['aggregateIds'] as List<dynamic>? ?? const [])
+        .map((item) => item.toString())
+        .toList();
+    if (mode == ReminderPayloadMode.aggregate && aggregateIds.length < 2) {
+      throw const FormatException('aggregateIds must contain at least 2 items');
+    }
+
+    return ReminderPayload(
+      eventId: eventId,
+      title: (json['title'] as String?) ?? '',
+      startAt: parsedStartAt,
+      endAt: json['endAt'] != null
+          ? DateTime.parse(json['endAt'] as String)
+          : null,
+      timezone: (json['timezone'] as String?) ?? 'UTC',
+      location: json['location'] as String?,
+      notes: json['notes'] as String?,
+      color: json['color'] as String?,
+      mode: mode,
+      aggregateIds: aggregateIds,
+      version: (json['version'] as int?) ?? 1,
+    );
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) {
+      return true;
+    }
+    return other is ReminderPayload &&
+        other.eventId == eventId &&
+        other.title == title &&
+        other.startAt == startAt &&
+        other.endAt == endAt &&
+        other.timezone == timezone &&
+        other.location == location &&
+        other.notes == notes &&
+        other.color == color &&
+        other.mode == mode &&
+        _listEquals(other.aggregateIds, aggregateIds) &&
+        other.version == version;
+  }
+
+  @override
+  int get hashCode {
+    return Object.hash(
+      eventId,
+      title,
+      startAt,
+      endAt,
+      timezone,
+      location,
+      notes,
+      color,
+      mode,
+      Object.hashAll(aggregateIds),
+      version,
+    );
+  }
+}
+
+enum ReminderPayloadMode {
+  single('single'),
+  aggregate('aggregate');
+
+  const ReminderPayloadMode(this.value);
+
+  final String value;
+
+  static ReminderPayloadMode fromValue(String raw) {
+    return ReminderPayloadMode.values.firstWhere(
+      (item) => item.value == raw,
+      orElse: () => ReminderPayloadMode.single,
+    );
+  }
+}
+
+bool _listEquals(List<String> left, List<String> right) {
+  if (left.length != right.length) {
+    return false;
+  }
+  for (var i = 0; i < left.length; i++) {
+    if (left[i] != right[i]) {
+      return false;
+    }
+  }
+  return true;
+}
@@ -0,0 +1,106 @@
+import 'dart:math';
+
+import '../data/services/calendar_service.dart';
+import '../../../core/notifications/local_notification_service.dart';
+import 'models/reminder_action.dart';
+import 'models/reminder_payload.dart';
+import 'reminder_outbox_store.dart';
+
+class ReminderActionExecutor {
+  final CalendarService _calendarService;
+  final LocalNotificationService _notificationService;
+  final ReminderOutboxStore _outboxStore;
+  final Random _random;
+
+  ReminderActionExecutor({
+    required CalendarService calendarService,
+    required LocalNotificationService notificationService,
+    required ReminderOutboxStore outboxStore,
+    Random? random,
+  }) : _calendarService = calendarService,
+       _notificationService = notificationService,
+       _outboxStore = outboxStore,
+       _random = random ?? Random();
+
+  Future<void> handleAction({
+    required ReminderAction action,
+    required ReminderPayload payload,
+  }) async {
+    final ids = payload.mode == ReminderPayloadMode.aggregate
+        ? payload.aggregateIds
+        : <String>[payload.eventId];
+
+    if (action == ReminderAction.cancel) {
+      for (final id in ids) {
+        await _notificationService.cancelEventReminder(id);
+        await _archiveEvent(id, ReminderAction.cancel);
+      }
+      return;
+    }
+
+    if (action == ReminderAction.snooze10m ||
+        action == ReminderAction.timeout30s) {
+      for (final id in ids) {
+        await _snoozeEvent(id);
+      }
+    }
+  }
+
+  Future<void> replayPendingActions() async {
+    final pending = await _outboxStore.listPending();
+    for (final item in pending) {
+      if (item.targetStatus != 'archived') {
+        await _outboxStore.markDone(item.opId);
+        continue;
+      }
+      try {
+        await _calendarService.archiveEvent(item.eventId);
+        await _outboxStore.markDone(item.opId);
+      } catch (error) {
+        await _outboxStore.markRetry(item.opId, error.toString());
+      }
+    }
+  }
+
+  Future<void> _snoozeEvent(String eventId) async {
+    final event = await _calendarService.getEventById(eventId);
+    if (event == null) {
+      return;
+    }
+    final now = DateTime.now();
+    final endAt = event.endAt;
+    if (endAt != null && !now.isBefore(endAt)) {
+      await _notificationService.cancelEventReminder(eventId);
+      await _archiveEvent(eventId, ReminderAction.autoArchive);
+      return;
+    }
+
+    final nextAt = now.add(const Duration(minutes: 10));
+    if (endAt != null && !nextAt.isBefore(endAt)) {
+      await _notificationService.cancelEventReminder(eventId);
+      await _archiveEvent(eventId, ReminderAction.autoArchive);
+      return;
+    }
+
+    await _notificationService.scheduleReminderAt(event, nextAt);
+  }
+
+  Future<void> _archiveEvent(String eventId, ReminderAction action) async {
+    final opId =
+        '${DateTime.now().millisecondsSinceEpoch}-${_random.nextInt(1 << 32)}';
+    final outboxItem = ReminderOutboxItem(
+      opId: opId,
+      eventId: eventId,
+      action: action,
+      targetStatus: 'archived',
+      occurredAt: DateTime.now(),
+    );
+    await _outboxStore.enqueue(outboxItem);
+    try {
+      await _calendarService.archiveEvent(eventId);
+      await _outboxStore.markDone(opId);
+    } catch (error) {
+      await _outboxStore.markRetry(opId, error.toString());
+    }
+  }
+}
@@ -0,0 +1,202 @@
+import 'dart:convert';
+
+import 'package:shared_preferences/shared_preferences.dart';
+
+import 'models/reminder_action.dart';
+
+class ReminderOutboxItem {
+  final String opId;
+  final String eventId;
+  final ReminderAction action;
+  final String? targetStatus;
+  final DateTime occurredAt;
+  final int retryCount;
+  final DateTime? nextRetryAt;
+  final ReminderOutboxState state;
+  final String? lastError;
+
+  const ReminderOutboxItem({
+    required this.opId,
+    required this.eventId,
+    required this.action,
+    required this.occurredAt,
+    this.targetStatus,
+    this.retryCount = 0,
+    this.nextRetryAt,
+    this.state = ReminderOutboxState.pending,
+    this.lastError,
+  });
+
+  String get idempotencyBucket {
+    final bucket =
+        occurredAt.millisecondsSinceEpoch ~/
+        const Duration(minutes: 1).inMilliseconds;
+    return '$eventId|${action.value}|$bucket';
+  }
+
+  ReminderOutboxItem copyWith({
+    int? retryCount,
+    DateTime? nextRetryAt,
+    ReminderOutboxState? state,
+    String? lastError,
+  }) {
+    return ReminderOutboxItem(
+      opId: opId,
+      eventId: eventId,
+      action: action,
+      targetStatus: targetStatus,
+      occurredAt: occurredAt,
+      retryCount: retryCount ?? this.retryCount,
+      nextRetryAt: nextRetryAt ?? this.nextRetryAt,
+      state: state ?? this.state,
+      lastError: lastError ?? this.lastError,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'opId': opId,
+      'eventId': eventId,
+      'action': action.value,
+      'targetStatus': targetStatus,
+      'occurredAt': occurredAt.toIso8601String(),
+      'retryCount': retryCount,
+      'nextRetryAt': nextRetryAt?.toIso8601String(),
+      'state': state.value,
+      'lastError': lastError,
+    };
+  }
+
+  factory ReminderOutboxItem.fromJson(Map<String, dynamic> json) {
+    return ReminderOutboxItem(
+      opId: (json['opId'] as String?) ?? '',
+      eventId: (json['eventId'] as String?) ?? '',
+      action: ReminderAction.fromValue(
+        (json['action'] as String?) ?? 'timeout_30s',
+      ),
+      targetStatus: json['targetStatus'] as String?,
+      occurredAt: DateTime.parse(json['occurredAt'] as String),
+      retryCount: (json['retryCount'] as int?) ?? 0,
+      nextRetryAt: json['nextRetryAt'] != null
+          ? DateTime.parse(json['nextRetryAt'] as String)
+          : null,
+      state: ReminderOutboxState.fromValue(
+        (json['state'] as String?) ?? 'pending',
+      ),
+      lastError: json['lastError'] as String?,
+    );
+  }
+}
+
+enum ReminderOutboxState {
+  pending('pending'),
+  done('done'),
+  dead('dead');
+
+  const ReminderOutboxState(this.value);
+  final String value;
+
+  static ReminderOutboxState fromValue(String raw) {
+    return ReminderOutboxState.values.firstWhere(
+      (item) => item.value == raw,
+      orElse: () => ReminderOutboxState.pending,
+    );
+  }
+}
+
+class ReminderOutboxStore {
+  static const String _key = 'calendar_reminder_outbox_v1';
+  final SharedPreferences _prefs;
+
+  ReminderOutboxStore(this._prefs);
+
+  Future<void> enqueue(ReminderOutboxItem item) async {
+    final current = await _readAll();
+    final duplicated = current.any(
+      (existing) =>
+          existing.state == ReminderOutboxState.pending &&
+          existing.idempotencyBucket == item.idempotencyBucket,
+    );
+    if (duplicated) {
+      return;
+    }
+    current.add(item);
+    await _writeAll(current);
+  }
+
+  Future<List<ReminderOutboxItem>> listPending() async {
+    final all = await _readAll();
+    final now = DateTime.now();
+    return all
+        .where((item) => item.state == ReminderOutboxState.pending)
+        .where(
+          (item) => item.nextRetryAt == null || !item.nextRetryAt!.isAfter(now),
+        )
+        .toList();
+  }
+
+  Future<void> markDone(String opId) async {
+    final all = await _readAll();
+    final updated = all
+        .map(
+          (item) => item.opId == opId
+              ? item.copyWith(
+                  state: ReminderOutboxState.done,
+                  nextRetryAt: null,
+                )
+              : item,
+        )
+        .toList();
+    await _writeAll(updated);
+  }
+
+  Future<void> markRetry(String opId, String error) async {
+    final all = await _readAll();
+    final updated = all.map((item) {
+      if (item.opId != opId) {
+        return item;
+      }
+      final nextRetryCount = item.retryCount + 1;
+      if (nextRetryCount >= 8) {
+        return item.copyWith(
+          retryCount: nextRetryCount,
+          state: ReminderOutboxState.dead,
+          lastError: error,
+          nextRetryAt: null,
+        );
+      }
+      final delayMinutes = nextRetryCount == 1 ? 0 : 1 << (nextRetryCount - 1);
+      return item.copyWith(
+        retryCount: nextRetryCount,
+        lastError: error,
+        nextRetryAt: DateTime.now().add(Duration(minutes: delayMinutes)),
+      );
+    }).toList();
+    await _writeAll(updated);
+  }
+
+  Future<List<ReminderOutboxItem>> _readAll() async {
+    try {
+      final raw = _prefs.getString(_key);
+      if (raw == null || raw.isEmpty) {
+        return [];
+      }
+      final list = jsonDecode(raw) as List<dynamic>;
+      return list
+          .whereType<Map>()
+          .map(
+            (item) =>
+                ReminderOutboxItem.fromJson(Map<String, dynamic>.from(item)),
+          )
+          .toList();
+    } catch (_) {
+      await _prefs.remove(_key);
+      return [];
+    }
+  }
+
+  Future<void> _writeAll(List<ReminderOutboxItem> items) async {
+    final raw = jsonEncode(items.map((item) => item.toJson()).toList());
+    await _prefs.setString(_key, raw);
+  }
+}
@@ -0,0 +1,80 @@
+import '../data/models/schedule_item_model.dart';
+
+class ReminderOverlapGroup {
+  final DateTime fireAt;
+  final List<ScheduleItemModel> events;
+
+  const ReminderOverlapGroup({required this.fireAt, required this.events});
+
+  bool get isAggregate => events.length > 1;
+}
+
+class ReminderOverlapPolicy {
+  const ReminderOverlapPolicy();
+
+  List<ReminderOverlapGroup> groupByMinute(
+    Iterable<ScheduleItemModel> events, {
+    required DateTime now,
+  }) {
+    final buckets = <String, List<ScheduleItemModel>>{};
+    final minuteToFireAt = <String, DateTime>{};
+
+    for (final event in events) {
+      final fireAt = resolveFirstFireAt(event, now: now);
+      if (fireAt == null) {
+        continue;
+      }
+      final minute = DateTime(
+        fireAt.year,
+        fireAt.month,
+        fireAt.day,
+        fireAt.hour,
+        fireAt.minute,
+      );
+      final key = minute.toIso8601String();
+      buckets.putIfAbsent(key, () => <ScheduleItemModel>[]).add(event);
+      minuteToFireAt[key] = minuteToFireAt[key] ?? fireAt;
+    }
+
+    final groups = buckets.entries
+        .map(
+          (entry) => ReminderOverlapGroup(
+            fireAt: minuteToFireAt[entry.key]!,
+            events: entry.value,
+          ),
+        )
+        .toList();
+
+    groups.sort((left, right) => left.fireAt.compareTo(right.fireAt));
+    return groups;
+  }
+
+  DateTime? resolveFirstFireAt(
+    ScheduleItemModel event, {
+    required DateTime now,
+  }) {
+    if (event.status != ScheduleStatus.active) {
+      return null;
+    }
+    final reminderMinutes = event.metadata?.reminderMinutes;
+    if (reminderMinutes == null) {
+      return null;
+    }
+    final remindAt = event.startAt.subtract(Duration(minutes: reminderMinutes));
+    final endAt = event.endAt;
+
+    if (endAt != null && !now.isBefore(endAt)) {
+      return null;
+    }
+
+    if (now.isBefore(remindAt)) {
+      return remindAt;
+    }
+
+    if (endAt != null && now.isBefore(endAt)) {
+      return now.add(const Duration(seconds: 5));
+    }
+
+    return null;
+  }
+}
@@ -9,6 +9,7 @@ import '../../data/models/schedule_item_model.dart';
 import '../../data/services/calendar_service.dart';
 import '../calendar_state_manager.dart';
 import '../calendar_time_utils.dart';
+import '../utils/event_color_resolver.dart';
 import '../dayweek/day_event_layout_engine.dart';
 import '../dayweek/day_timeline_metrics.dart';
 import '../dayweek/day_view_scale.dart';
@@ -614,7 +615,10 @@ class _CalendarDayWeekScreenState extends State<CalendarDayWeekScreen>
    required DayEventLayout layout,
    required double boardHeight,
  }) {
-    final eventColor = _parseColor(layout.event.metadata?.color);
+    final eventColor = resolveEventColor(
+      status: layout.event.status,
+      colorHex: layout.event.metadata?.color,
+    );
    final isCompact = layout.visualHeight < 20;
    final tapHeight = layout.visualHeight < _minEventTapHeight
        ? _minEventTapHeight
@@ -687,17 +691,6 @@ class _CalendarDayWeekScreenState extends State<CalendarDayWeekScreen>
    );
  }

-  Color _parseColor(String? hex) {
-    if (hex == null || hex.isEmpty) {
-      return AppColors.blue600;
-    }
-    try {
-      return Color(int.parse(hex.replaceFirst('#', '0xFF')));
-    } catch (_) {
-      return AppColors.blue600;
-    }
-  }
-
  Widget _buildBottomDock() {
    return BottomDock(
      activeTab: DockTab.calendar,
@@ -10,6 +10,7 @@ import '../../../../shared/widgets/detail_header_action_menu.dart';
 import '../../../../shared/widgets/destructive_action_sheet.dart';
 import '../../data/services/calendar_service.dart';
 import '../../data/models/schedule_item_model.dart';
+import '../utils/event_color_resolver.dart';
 import '../widgets/create_event_sheet.dart';
 import '../widgets/calendar_share_dialog.dart';

@@ -223,7 +224,7 @@ class _CalendarEventDetailScreenState extends State<CalendarEventDetailScreen> {
                  _formatReminderText(event.metadata?.reminderMinutes),
                ),
                const SizedBox(height: 14),
-                _buildColorField(event.metadata?.color),
+                _buildColorField(event),
                const SizedBox(height: 14),
                if (event.metadata?.location != null) ...[
                  _buildDetailField('地点', event.metadata!.location!),
@@ -275,7 +276,10 @@ class _CalendarEventDetailScreenState extends State<CalendarEventDetailScreen> {
                width: 4,
                height: 20,
                decoration: BoxDecoration(
-                  color: _parseColor(event.metadata?.color),
+                  color: resolveEventColor(
+                    status: event.status,
+                    colorHex: event.metadata?.color,
+                  ),
                  borderRadius: BorderRadius.circular(2),
                ),
              ),
@@ -343,8 +347,11 @@ class _CalendarEventDetailScreenState extends State<CalendarEventDetailScreen> {
    );
  }

-  Widget _buildColorField(String? colorHex) {
-    final color = _parseColor(colorHex);
+  Widget _buildColorField(ScheduleItemModel event) {
+    final color = resolveEventColor(
+      status: event.status,
+      colorHex: event.metadata?.color,
+    );
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
@@ -400,15 +407,6 @@ class _CalendarEventDetailScreenState extends State<CalendarEventDetailScreen> {
    );
  }

-  Color _parseColor(String? hex) {
-    if (hex == null || hex.isEmpty) return AppColors.blue600;
-    try {
-      return Color(int.parse(hex.replaceFirst('#', '0xFF')));
-    } catch (_) {
-      return AppColors.blue600;
-    }
-  }
-
  Widget _buildInputContainer() {
    return Container(
      height: 80,
@@ -7,6 +7,7 @@ import '../../../../core/theme/design_tokens.dart';
 import '../../../../shared/widgets/app_pressable.dart';
 import '../calendar_state_manager.dart';
 import '../calendar_time_utils.dart';
+import '../utils/event_color_resolver.dart';
 import '../widgets/bottom_dock.dart';
 import '../widgets/create_event_sheet.dart';
 import '../../data/models/schedule_item_model.dart';
@@ -360,7 +361,10 @@ class _CalendarMonthScreenState extends State<CalendarMonthScreen>
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                ...displayEvents.map((event) {
-                  final color = _parseColor(event.metadata?.color);
+                  final color = resolveEventColor(
+                    status: event.status,
+                    colorHex: event.metadata?.color,
+                  );
                  return AppPressable(
                    borderRadius: BorderRadius.circular(AppRadius.sm),
                    onTap: () {
@@ -415,15 +419,6 @@ class _CalendarMonthScreenState extends State<CalendarMonthScreen>
    );
  }

-  Color _parseColor(String? hex) {
-    if (hex == null || hex.isEmpty) return AppColors.blue600;
-    try {
-      return Color(int.parse(hex.replaceFirst('#', '0xFF')));
-    } catch (_) {
-      return AppColors.blue600;
-    }
-  }
-
  void _showMonthPicker() {
    var selectedYear = _currentMonth.year;
    var selectedMonth = _currentMonth.month;
@@ -0,0 +1,23 @@
+import 'package:flutter/material.dart';
+
+import '../../../../core/theme/design_tokens.dart';
+import '../../data/models/schedule_item_model.dart';
+
+Color resolveEventColor({
+  required ScheduleStatus status,
+  required String? colorHex,
+}) {
+  if (status == ScheduleStatus.archived) {
+    return AppColors.slate400;
+  }
+
+  if (colorHex == null || colorHex.isEmpty) {
+    return AppColors.blue600;
+  }
+
+  try {
+    return Color(int.parse(colorHex.replaceFirst('#', '0xFF')));
+  } catch (_) {
+    return AppColors.blue600;
+  }
+}
@@ -669,9 +669,9 @@ class _CreateEventSheetState extends State<CreateEventSheet>
      try {
        final notificationService = sl<LocalNotificationService>();
        await notificationService.upsertEventReminder(saved);
-      } catch (e) {
+      } catch (_) {
        if (mounted) {
-          Toast.show(context, '提醒创建失败：$e', type: ToastType.warning);
+          Toast.show(context, '提醒创建失败，请检查通知权限', type: ToastType.warning);
        }
      }

@@ -13,12 +13,23 @@ import 'features/auth/presentation/bloc/auth_bloc.dart';
 import 'features/auth/presentation/bloc/auth_event.dart';
 import 'features/auth/presentation/bloc/auth_state.dart';
 import 'features/calendar/data/services/calendar_service.dart';
+import 'features/calendar/reminders/reminder_action_executor.dart';
 import 'features/chat/presentation/bloc/chat_bloc.dart';

 void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await configureDependencies();
  await AppConstants.init();
+  sl<LocalNotificationService>().bindActionHandler(({
+    required action,
+    required payload,
+  }) {
+    return sl<ReminderActionExecutor>().handleAction(
+      action: action,
+      payload: payload,
+    );
+  });
+  await sl<LocalNotificationService>().initialize();

  final authBloc = sl<AuthBloc>();
  authBloc.add(AuthStarted());
@@ -29,6 +40,7 @@ void main() async {
      sessionBootstrapper: AuthSessionBootstrapper(
        calendarService: sl<CalendarService>(),
        notificationService: sl<LocalNotificationService>(),
+        reminderActionExecutor: sl<ReminderActionExecutor>(),
      ),
    ),
  );