# Reminder Overlay 设计文档

## 概述

重构日历提醒机制，简化前台/后台判断逻辑，将所有提醒交互统一到独立的 ReminderOverlay 组件处理。

## 背景

当前实现复杂，涉及：
- App 启动状态判断（前台/后台）
- 离线归档请求队列 + 指数退避重试
- 通知权限降级（Android Timer 模拟）
- 聚合通知批量操作

新方案利用 iOS/Android 原生通知分组能力，实现：
- 每条通知独立 payload，点击哪条处理哪条
- 统一的 ReminderOverlay 处理所有用户交互
- 操作完成后 app 退到后台

## 设计决策

| 决策项 | 选择 |
|--------|------|
| 关闭 overlay 后的行为 | 回到首页，保持缓存状态 |
| 同分钟多条通知处理 | 按点击顺序处理当前，剩余按时间排序 |
| iOS 冷启动 payload 传递 | UserDefaults（App Groups 方案） |
| Android 通知展示 | Full-screen intent（锁屏也弹窗） |
| 稍后提醒时间选项 | 5 分钟、15 分钟（下拉选项） |
| "完成"按钮行为 | 归档 + 关闭 + 退后台 |
| "稍后提醒"按钮行为 | 弹出选项 + 延后通知 + 关闭 + 退后台 |
| UI 组件 | 新建 ReminderOverlay（不复用现有） |

## 核心流程

```
通知到达 → 用户点击通知 → 
    ├─ App 已运行 → 恢复前台 → 直接收到 payload → 打开 ReminderOverlay
    └─ App 未运行 → 
        ├─ iOS: 原生层写入 UserDefaults → Flutter 启动时读取
        └─ Android: full-screen intent 启动 → Flutter 收到 payload
    
ReminderOverlay 显示：
  - 日程标题
  - 当前时间
  - [稍后提醒 ▼] | [完成]
  
用户操作：
  ├─ 完成 → 归档请求 → 关闭 overlay → 退后台
  └─ 稍后提醒 → 选择时间 → 取消当前通知 + 注册新通知 → 关闭 overlay → 退后台

处理完当前 → 检查同分钟是否有多条 → 
  ├─ 有 → 打开下一条的 ReminderOverlay
  └─ 无 → 保持退后台状态
```

## 移除的组件

| 组件 | 文件路径 | 移除原因 |
|------|----------|----------|
| ReminderColdStartQueue | `lib/features/calendar/reminders/reminder_cold_start_queue.dart` | 不需要后台重放机制 |
| ReminderOutboxStore | `lib/features/calendar/reminders/reminder_outbox_store.dart` | 不需要离线归档队列 |
| ReminderForegroundPresenter | `lib/features/calendar/reminders/ui/reminder_foreground_presenter.dart` | 不需要前台判断 |
| ReminderPresentationCoordinator | `lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart` | 不需要防重复展示 |
| ReminderActionDedupeStore | `lib/features/calendar/reminders/reminder_action_dedupe_store.dart` | 通知原生幂等 |
| ReminderOverlapPolicy | `lib/features/calendar/reminders/reminder_overlap_policy.dart` | 改为原生分组 |
| Android Timer 模拟逻辑 | `LocalNotificationService` 内 | 不需要权限降级 |

## 新增组件

### ReminderOverlay

独立的状态管理页面，处理提醒交互。

**职责**：
- 显示日程标题和当前时间
- 提供"稍后提醒"下拉选项（5分钟/15分钟）
- 提供"完成"按钮（归档）
- 处理完成后关闭 overlay

**文件位置**：`lib/features/calendar/reminders/ui/reminder_overlay.dart`

### ReminderQueueManager

管理同分钟多条通知的处理队列。

**职责**：
- 存储同分钟的通知列表
- 按点击顺序跟踪当前处理项
- 处理完当前后调度下一项

**文件位置**：`lib/features/calendar/reminders/reminder_queue_manager.dart`

### IOSNotificationPayloadBridge

iOS 冷启动时从 UserDefaults 读取 notification payload。

**职责**：
- App 启动时检查是否有待处理的通知 launch
- 读取 payload 并打开对应的 ReminderOverlay
- 处理完成后清理 UserDefaults

**文件位置**：`lib/core/notifications/ios_notification_payload_bridge.dart`

## 平台差异处理

### iOS

1. **通知点击启动 App**：
   - 配置 `setPluginRegistrantCallback`（已有）
   - iOS 原生层将 payload 写入 UserDefaults
   - Flutter 启动时 `IOSNotificationPayloadBridge` 读取数据

2. **通知分组**：
   - 使用 `threadIdentifier` 分组
   - 同一分钟的通知使用相同的 `threadIdentifier`

### Android

1. **Full-screen intent**：
   - `AndroidNotificationDetails` 设置 `fullScreenIntent: true`
   - 锁屏时直接弹出全屏 overlay

2. **通知分组**：
   - 使用 `groupKey` 分组
   - 同一分钟的通知使用相同的 `groupKey`

## API 变化

### 归档请求

仍然使用现有的 `CalendarService.archiveEvent()`，但不再需要失败重试逻辑。

```
POST /api/v1/calendar/events/{eventId}/archive
```

### 通知 Payload

```json
{
  "eventId": "evt_xxx",
  "title": "日程标题",
  "startAt": "2026-03-20T10:00:00Z",
  "endAt": "2026-03-20T11:00:00Z",
  "timezone": "Asia/Shanghai",
  "mode": "single",
  "fireTimeBucket": 1774060800000
}
```

## 数据流

### 通知发送流程（不变）

```
CalendarService.upsertEventReminder()
  → LocalNotificationService.upsertEventReminder()
  → flutter_local_notifications.zonedSchedule()
```

### 通知点击处理流程

```
用户点击通知
  ├─ App 运行中 → onDidReceiveNotificationResponse(payload)
  └─ App 未运行
      ├─ iOS → 原生写入 UserDefaults → Flutter 启动 → 读取 → 打开 overlay
      └─ Android → full-screen intent → Flutter 收到 payload → 打开 overlay

ReminderOverlay 打开
  ├─ 用户点击"完成" → archiveEvent() → 关闭 → 检查队列 → 有下一条则打开下一条
  └─ 用户点击"稍后提醒" → cancelNotification() + scheduleReminderAt() → 关闭 → 检查队列 → 有下一条则打开下一条
```

## 错误处理

| 场景 | 处理方式 |
|------|----------|
| 归档请求失败 | 显示 toast 提示用户，操作已完成（下次打开 app 时同步） |
| 延后通知注册失败 | 显示 toast 提示用户，当前提醒已取消 |
| 同分钟多条处理时其中一条失败 | 跳过该条，处理下一条 |

## 文件变更清单

### 删除

- `lib/features/calendar/reminders/reminder_cold_start_queue.dart`
- `lib/features/calendar/reminders/reminder_outbox_store.dart`
- `lib/features/calendar/reminders/reminder_action_dedupe_store.dart`
- `lib/features/calendar/reminders/reminder_overlap_policy.dart`
- `lib/features/calendar/reminders/ui/reminder_foreground_presenter.dart`
- `lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
- `lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart`
- 相关测试文件

### 新增

- `lib/features/calendar/reminders/ui/reminder_overlay.dart`
- `lib/features/calendar/reminders/reminder_queue_manager.dart`
- `lib/core/notifications/ios_notification_payload_bridge.dart`

### 修改

- `lib/core/notifications/local_notification_service.dart`（移除权限降级逻辑）
- `lib/main.dart`（集成 IOSNotificationPayloadBridge）
- 相关测试文件

## 测试策略

### 单元测试
- ReminderQueueManager: 队列排序、下一条调度
- IOSNotificationPayloadBridge: payload 读写

### 集成测试
- 通知点击 → overlay 打开 → 操作 → 关闭
- 同分钟多条通知顺序处理

### 手动测试
- iOS 冷启动点击通知
- Android 锁屏点击 full-screen intent 通知
- 稍后提醒 5 分钟/15 分钟验证