feat: 实现日历提醒 in-app fallback 机制及通知服务重构

2026-03-20 01:30:34 +08:00
parent 7fd536e976
commit d574128815
55 changed files with 4565 additions and 647 deletions
@@ -9,18 +9,16 @@

 ## Goal

-定义日程提醒弹窗在 Android/iOS 的统一行为语义，覆盖提醒触发、用户操作、超时、离线补偿、归档与重装恢复，确保多端一致性和可恢复性。
+定义日程提醒弹窗在 Android/iOS 的统一行为语义，覆盖提醒触发、用户操作、离线补偿、归档与重装恢复，确保多端一致性和可恢复性。

 ---

 ## Canonical Rules

-1. 提醒弹窗动作语义跨平台一致：`cancel`、`snooze_10m`、`timeout_30s`。
-2. `timeout_30s` 语义固定为忽略当前弹窗并按 10 分钟后再次提醒，不直接归档。
-3. `cancel` 必须归档对应日程（`status=archived`）。
-4. 到达事件结束时间后（`now >= end_at`）必须停止提醒并归档。
-5. 归档后的 UI 渲染必须灰色显示；不强制改写原始 metadata 颜色。
-6. 前端动作上报后端采用最终一致性：本地 outbox + 重放机制。
+1. 提醒弹窗动作语义跨平台一致：`archive`、`snooze10m`。
+2. 展示文案“取消”必须映射到内部动作 `archive`，并归档对应日程（`status=archived`）。
+3. 归档后的 UI 渲染必须灰色显示；不强制改写原始 metadata 颜色。
+4. 前端动作上报后端采用最终一致性：本地 outbox + 重放机制。

 ---

@@ -55,10 +53,13 @@

 动作枚举：

- `cancel`: 用户取消提醒并归档事件
- `snooze_10m`: 用户点击稍后提醒，重排到 `now + 10m`
- `timeout_30s`: 用户 30s 未处理，按 `snooze_10m` 处理
- `auto_archive`: 系统判定事件已过期，自动归档
+- `archive`: 内部归档动作（UI 展示文案为“取消”）
+- `snooze10m`: 用户点击稍后提醒，重排到 `now + 10m`
+
+### UI Label Mapping
+
+- 按钮展示文案“取消”仅为 UI 文案，不作为协议动作值。
+- “取消”按钮点击后的上报动作值必须为 `archive`。

 ---

@@ -68,7 +69,7 @@
 {
  "opId": "uuid",
  "eventId": "uuid",
-  "action": "cancel|snooze_10m|timeout_30s|auto_archive",
+  "action": "archive|snooze10m",
  "targetStatus": "archived|null",
  "occurredAt": "iso8601-with-offset",
  "retryCount": 0,
@@ -80,11 +81,23 @@

 ### Constraints

- 幂等键：`(eventId, action, occurredAtBucket)`。
- 重试策略：指数退避，最大重试次数可配置。
- `cancel` 和 `auto_archive` 都映射到后端 `PATCH status=archived`。
+- 幂等键：`actionExecutionId = notificationId + "|" + actionId + "|" + fireTimeBucket`。
+- `notificationId`: 本地通知唯一 id（整数或其字符串化值）。
+- `actionId`: 内部动作 id，取值仅允许 `archive` 或 `snooze10m`。
+- `fireTimeBucket`: 触发时间按“分钟”向下取整后的 epoch minute（`millisecondsSinceEpoch / 60000`）。
+- 执行前必须先按 `actionExecutionId` 查重；若命中历史执行，直接 ACK，不得产生任何业务副作用。
+- 重试策略：指数退避。默认参数：首次重试 0 分钟，之后依次 1/2/4/8/16/32/64 分钟；最大重试次数默认 8（可配置但需跨端一致）。
+- `archive` 映射到后端 `PATCH status=archived`。
 - Outbox 记录必须本地持久化，App 重启后可恢复。

+### cold-start Queue Replay Contract
+
+- App cold-start 恢复 outbox/动作队列时，必须按入队顺序进行回放。
+- 单条回放失败只记录失败并进入重试，不得阻塞后续条目继续回放。
+- 回放过程必须复用 `actionExecutionId` 做去重，防止重复归档或重复稍后提醒。
+- 回放执行模型为全局串行（concurrency=1），处理顺序与入队顺序一致。
+- ACK 时序：仅在动作被成功执行或命中幂等去重时返回 ACK；失败条目进入重试状态并继续处理下一条。
+
 ---

 ## Scheduling and Compensation Rules
@@ -99,13 +112,15 @@

 1. `now < remindAt`：按 `remindAt` 正常调度。
 2. `remindAt <= now < endAt`：立刻补偿提醒（建议 `+5s`），然后进入 10 分钟节奏。
-3. `now >= endAt`：不再提醒，走归档流程。
+3. `now >= endAt`：不再补发提醒；后续状态流转由上层业务策略决定（不在本协议强制范围内）。
+4. `endAt = null`：视为无结束时间，沿用规则 1/2，不适用规则 3。

 ---

 ## Uniqueness and Dedupe Rules

 - 通知唯一键：`hash(eventId + cycleStartEpochMinutes + mode)`。
+- `cycleStartEpochMinutes` 定义为“该轮提醒触发时间（fireAt）按分钟向下取整后的 epoch minute”。
 - 每次创建提醒前必须取消同 dedupe key 的旧提醒（upsert 语义）。
 - 补偿提醒在同一 cycle 窗口内最多触发一次。
 - 启动恢复时要同时参考 pending notification 和 outbox 状态，避免重复调度。
@@ -0,0 +1,391 @@
+# Calendar Reminder Unified Interaction Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 交付“系统通知主触达 + 前台统一提醒面板”的提醒链路，保证 iOS/Android 在前台、后台、终止态都可执行“稍后提醒”和“取消并归档（内部 archive）”。
+
+**Architecture:** `LocalNotificationService` 仅做调度与平台桥接；`ReminderActionExecutor` 作为唯一动作执行器；新增 `ReminderPresentationCoordinator` + `ReminderActionSheet` 负责前台展示；新增持久化幂等与 cold-start 回放，避免动作丢失/重复执行。
+
+**Tech Stack:** Flutter, flutter_local_notifications, SharedPreferences, Dart isolate callback, AndroidManifest receiver, iOS AppDelegate callback, Flutter tests.
+
+---
+
+## File Structure (Locked Before Tasks)
+
+### Protocol (Must First)
+- Modify: `docs/protocols/calendar/reminder-alert-lifecycle.md`
+
+### Reminder Core
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+- Create: `apps/lib/core/notifications/reminder_notification_callbacks.dart`
+- Modify: `apps/lib/features/calendar/reminders/models/reminder_action.dart`
+- Modify: `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
+- Create: `apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart`
+- Create: `apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart`
+
+### Foreground UI
+- Create: `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
+- Create: `apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart`
+
+### App & Platform Wiring
+- Modify: `apps/lib/main.dart`
+- Modify: `apps/android/app/src/main/AndroidManifest.xml`
+- Modify: `apps/ios/Runner/AppDelegate.swift`
+
+### Tests
+- Modify: `apps/test/features/calendar/reminders/reminder_action_executor_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_action_sheet_test.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart`
+- Create: `apps/test/platform/android_manifest_notification_action_test.dart`
+- Create: `apps/test/platform/ios_app_delegate_notification_callback_test.dart`
+
+### Cleanup
+- Create: `docs/todo/calendar-reminder-migration-checklist.md`
+
+---
+
+### Task 0: 协议先行更新（必须）
+
+**Files:**
+- Modify: `docs/protocols/calendar/reminder-alert-lifecycle.md`
+
+- [ ] **Step 1: 更新动作语义文案**
+```text
+展示文案“取消”映射到内部动作 archive
+```
+- [ ] **Step 2: 增加幂等键协议**
+```text
+actionExecutionId = notificationId + actionId + fireTimeBucket
+```
+- [ ] **Step 3: 增加 cold-start queue 回放协议**
+```text
+顺序回放，单条失败不阻塞后续
+```
+- [ ] **Step 4: 运行协议自检**
+Run: `rg "archive|actionExecutionId|cold-start" docs/protocols/calendar/reminder-alert-lifecycle.md`
+Expected: 命中新增规则
+- [ ] **Step 5: Commit**
+```bash
+git add docs/protocols/calendar/reminder-alert-lifecycle.md
+git commit -m "docs: align reminder protocol with archive and idempotency"
+```
+
+### Task 1: 动作语义收敛（TDD）
+
+**Files:**
+- Modify: `apps/test/features/calendar/reminders/reminder_action_executor_test.dart`
+- Modify: `apps/lib/features/calendar/reminders/models/reminder_action.dart`
+- Modify: `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
+
+- [ ] **Step 1: 写失败测试（archive 入口）**
+```dart
+test('archive action cancels reminder and archives event', () async {});
+```
+- [ ] **Step 2: 运行失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_executor_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 最小实现（增加 archive 枚举并接入 executor）**
+```dart
+enum ReminderAction { archive('archive'), snooze10m('snooze_10m'), ... }
+```
+- [ ] **Step 4: 运行通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_executor_test.dart`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/lib/features/calendar/reminders/models/reminder_action.dart apps/lib/features/calendar/reminders/reminder_action_executor.dart apps/test/features/calendar/reminders/reminder_action_executor_test.dart
+git commit -m "refactor: unify reminder action semantics to archive"
+```
+
+### Task 2: 持久化幂等（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
+- Create: `apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart`
+
+- [ ] **Step 1: 写失败测试（重启后仍去重）**
+```dart
+test('same actionExecutionId is rejected after restart', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 实现最小 store**
+```dart
+Future<bool> markIfNew(String actionExecutionId)
+```
+- [ ] **Step 4: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart
+git commit -m "feat: add persistent reminder action dedupe store"
+```
+
+### Task 3: 冷启动回放队列（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
+- Create: `apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart`
+
+- [ ] **Step 1: 写失败测试（顺序回放）**
+```dart
+test('replays actions in receive order', () async {});
+```
+- [ ] **Step 2: 写失败测试（单条失败不阻塞）**
+```dart
+test('continues replay after one action failure', () async {});
+```
+- [ ] **Step 3: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
+Expected: FAIL
+- [ ] **Step 4: 最小实现队列**
+```dart
+Future<void> replaySequentially(Future<void> Function(...) handler)
+```
+- [ ] **Step 5: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
+Expected: PASS
+- [ ] **Step 6: Commit**
+```bash
+git add apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart
+git commit -m "feat: add reminder cold-start replay queue"
+```
+
+### Task 4: 通知桥接映射（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+
+- [ ] **Step 1: 写失败测试（cancel 文案映射 archive）**
+```dart
+test('maps cancel action button to ReminderAction.archive', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 接入 dedupe store + bridge**
+```dart
+if (!await dedupeStore.markIfNew(actionExecutionId)) return;
+```
+- [ ] **Step 4: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart
+git commit -m "feat: map reminder notification actions through unified bridge"
+```
+
+### Task 5: 前台协调器（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
+- Create: `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
+
+- [ ] **Step 1: 写失败测试（仅前台展示）**
+```dart
+test('shows reminder sheet only in app active state', () async {});
+```
+- [ ] **Step 2: 写失败测试（去重窗口）**
+```dart
+test('suppresses duplicate presentation in dedupe window', () async {});
+```
+- [ ] **Step 3: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
+Expected: FAIL
+- [ ] **Step 4: 最小实现协调器**
+- [ ] **Step 5: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
+Expected: PASS
+- [ ] **Step 6: Commit**
+```bash
+git add apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart
+git commit -m "feat: add reminder foreground presentation coordinator"
+```
+
+### Task 6: 前台提醒面板组件（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_action_sheet_test.dart`
+- Create: `apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart`
+
+- [ ] **Step 1: 写失败测试（稍后提醒按钮）**
+```dart
+testWidgets('tap snooze triggers snooze callback', (tester) async {});
+```
+- [ ] **Step 2: 写失败测试（归档按钮）**
+```dart
+testWidgets('tap archive triggers archive callback', (tester) async {});
+```
+- [ ] **Step 3: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_sheet_test.dart`
+Expected: FAIL
+- [ ] **Step 4: 最小实现 token 驱动 UI**
+- [ ] **Step 5: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_sheet_test.dart`
+Expected: PASS
+- [ ] **Step 6: Commit**
+```bash
+git add apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart apps/test/features/calendar/reminders/reminder_action_sheet_test.dart
+git commit -m "feat: add reusable reminder action sheet"
+```
+
+### Task 7: App 接线与后台入口（TDD）
+
+**Files:**
+- Modify: `apps/lib/main.dart`
+- Create/Modify: `apps/lib/core/notifications/reminder_notification_callbacks.dart`
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+- Create: `apps/test/features/calendar/reminders/reminder_notification_callbacks_test.dart`
+
+- [ ] **Step 1: 写失败测试（后台入口是 top-level + pragma）**
+```dart
+test('background notification callback is top-level entry-point', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_callbacks_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 接线 initialize 注册前台/后台回调**
+- [ ] **Step 4: 接线 foreground presenter 到 coordinator**
+- [ ] **Step 5: 接线 action handler 到 executor**
+- [ ] **Step 6: reminders 套件回归**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
+Expected: PASS
+- [ ] **Step 7: Commit**
+```bash
+git add apps/lib/main.dart apps/lib/core/notifications/reminder_notification_callbacks.dart apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_notification_callbacks_test.dart
+git commit -m "feat: wire reminder callbacks for foreground and background"
+```
+
+### Task 8: Android 平台配置可执行校验（TDD）
+
+**Files:**
+- Create: `apps/test/platform/android_manifest_notification_action_test.dart`
+- Modify: `apps/android/app/src/main/AndroidManifest.xml`
+
+- [ ] **Step 1: 写失败测试（缺 ActionBroadcastReceiver）**
+```dart
+test('android manifest contains ActionBroadcastReceiver', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/platform/android_manifest_notification_action_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 增加 receiver 配置**
+- [ ] **Step 4: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/platform/android_manifest_notification_action_test.dart`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/android/app/src/main/AndroidManifest.xml apps/test/platform/android_manifest_notification_action_test.dart
+git commit -m "fix: register android action receiver for reminder notifications"
+```
+
+### Task 9: iOS 平台配置可执行校验（TDD）
+
+**Files:**
+- Create: `apps/test/platform/ios_app_delegate_notification_callback_test.dart`
+- Modify: `apps/ios/Runner/AppDelegate.swift`
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+
+- [ ] **Step 1: 写失败测试（registrant callback）**
+```dart
+test('ios app delegate registers flutter local notifications callback', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/platform/ios_app_delegate_notification_callback_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 实现 callback 注册 + category version bump (`calendar_reminder_v2`)**
+- [ ] **Step 4: 跑通过测试与 reminders 回归**
+Run (workdir=`apps`): `flutter test test/platform/ios_app_delegate_notification_callback_test.dart`
+Expected: PASS
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/ios/Runner/AppDelegate.swift apps/lib/core/notifications/local_notification_service.dart apps/test/platform/ios_app_delegate_notification_callback_test.dart
+git commit -m "fix: enable ios reminder action handling in background"
+```
+
+### Task 10: Android 13+ 权限降级与埋点（TDD）
+
+**Files:**
+- Create: `apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart`
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+
+- [ ] **Step 1: 写失败测试（未授权降级到应用内）**
+```dart
+test('fallbacks to in-app path when notifications permission denied', () async {});
+```
+- [ ] **Step 2: 跑失败测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_permission_fallback_test.dart`
+Expected: FAIL
+- [ ] **Step 3: 最小实现权限检查 + 降级埋点**
+- [ ] **Step 3: 最小实现权限检查 + 降级埋点**
+```text
+埋点字段至少包含：actionExecutionId、permissionState、appLifecycleState、platform
+```
+- [ ] **Step 4: 跑通过测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_permission_fallback_test.dart`
+Expected: PASS
+- [ ] **Step 5: Commit**
+```bash
+git add apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart
+git commit -m "feat: add reminder permission fallback path and telemetry"
+```
+
+### Task 11: 旧代码清单与即时清理
+
+**Files:**
+- Create: `docs/todo/calendar-reminder-migration-checklist.md`
+- Modify/Delete: `apps/lib/**`, `apps/test/**`（以清单为准）
+
+- [ ] **Step 1: 建立迁移清单（文件/符号/决策/责任人）**
+- [ ] **Step 2: 清理前扫描**
+Run: `rg "calendar_reminder_actions_v1|ReminderAction.cancel|_oldReminderEntry|_legacyReminderRoute" apps/lib apps/test`
+Expected: 输出待清理命中（仅代码引用，不含注释/文档示例）
+- [ ] **Step 3: 删除无用旧代码、无效测试、旧 fixture**
+- [ ] **Step 4: 清理后扫描**
+Run: `rg "calendar_reminder_actions_v1|ReminderAction.cancel|_oldReminderEntry|_legacyReminderRoute" apps/lib apps/test`
+Expected: no matches（注释/文档示例允许存在需在清单标注）
+- [ ] **Step 5: Commit**
+```bash
+git add docs/todo/calendar-reminder-migration-checklist.md apps/lib apps/test
+git commit -m "refactor: remove obsolete reminder paths after migration"
+```
+
+### Task 12: 最终验证与交付
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: reminders 全量测试**
+Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
+Expected: PASS
+- [ ] **Step 2: calendar 相关测试**
+Run (workdir=`apps`): `flutter test test/features/calendar`
+Expected: PASS
+- [ ] **Step 3: 手工矩阵 6/6 验证**
+```text
+Android: 前台/后台/杀进程
+iOS: 前台/后台锁屏/升级后
+```
+- [ ] **Step 4: 输出证据与指标**
+```text
+命令结果、回放日志、重试日志、重复执行率=0（按 actionExecutionId 统计）
+```
+
+---
+
+## Execution Notes
+
+- 任务顺序不可打乱：协议 -> 动作语义 -> 幂等 -> 回放 -> 桥接 -> UI -> 平台 -> 清理。
+- 每个任务只做最小改动并回归对应测试。
+- 视觉组件严格使用 `apps/lib/core/theme/design_tokens.dart`。
+- 若实现中与 spec 冲突，先改 spec/协议再继续写代码。
@@ -0,0 +1,524 @@
+# 待办事项四象限拖拽实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现四象限待办页面的拖拽排序和跨象限移动功能
+
+**Architecture:** 使用 Flutter `LongPressDraggable` + `DragTarget` 实现拖拽，`AnimatedContainer` 实现排序动画，乐观更新模式同步后端
+
+**Tech Stack:** Flutter, go_router, provider/state management
+
+---
+
+## 文件结构
+
+```
+apps/lib/features/todo/
+├── ui/screens/todo_quadrants_screen.dart  (修改: 添加拖拽状态管理)
+├── ui/widgets/
+│   └── todo_drag_item.dart  (创建: 可拖拽待办项组件)
+└── data/todo_api.dart  (检查: 确认 API 支持更新 priority)
+```
+
+---
+
+## 前置检查
+
+- [ ] **Step 1: 检查 TodoApi 支持更新 priority**
+
+文件: `apps/lib/features/todo/data/todo_api.dart`
+
+```dart
+// 确认有 updateTodo 方法支持更新 priority
+Future<TodoResponse> updateTodo(String id, {int? priority, ...})
+```
+
+---
+
+## Task 1: 添加拖拽状态管理
+
+**文件:**
+- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart:26-40`
+
+- [ ] **Step 1: 添加拖拽相关状态和回调**
+
+在 `_TodoQuadrantsScreenState` 中添加:
+
+```dart
+class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
+  // ... existing states ...
+  
+  // 拖拽状态
+  String? _draggingTodoId;
+  int? _dragTargetQuadrant; // 1, 2, 3
+  int? _dragInsertIndex;     // 插入位置索引
+  
+  // 辅助方法
+  bool get _isDragging => _draggingTodoId != null;
+  
+  void _onDragStart(String todoId) {
+    setState(() {
+      _draggingTodoId = todoId;
+    });
+  }
+  
+  void _onDragEnd() {
+    setState(() {
+      _draggingTodoId = null;
+      _dragTargetQuadrant = null;
+      _dragInsertIndex = null;
+    });
+  }
+  
+  void _onDragEnterQuadrant(int quadrant) {
+    setState(() {
+      _dragTargetQuadrant = quadrant;
+    });
+  }
+  
+  void _onDragUpdateInsertIndex(int index) {
+    setState(() {
+      _dragInsertIndex = index;
+    });
+  }
+  
+  Future<void> _onDrop(String todoId, int targetQuadrant, int insertIndex) async {
+    // 实现乐观更新 + 后端同步
+  }
+}
+```
+
+- [ ] **Step 2: 将 TodoDragItem 回调传入正确的 State 方法**
+
+在 `_buildQuadrant` 构建 TodoDragItem 时传入：
+
+```dart
+TodoDragItem(
+  todo: item,
+  quadrant: quadrantValue,
+  onDragStarted: () => _onDragStart(item.id),
+  onDragEnd: _onDragEnd,
+)
+```
+
+- [ ] **Step 3: 运行测试验证编译通过**
+
+```bash
+cd apps && flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
+```
+
+---
+
+## Task 2: 创建 TodoDragItem 组件
+
+**文件:**
+- 创建: `apps/lib/features/todo/ui/widgets/todo_drag_item.dart`
+
+- [ ] **Step 1: 创建 Stateful 拖拽组件**
+
+```dart
+class TodoDragItem extends StatefulWidget {
+  final TodoResponse todo;
+  final int quadrant; // 1, 2, 3
+  final VoidCallback onDragStarted;
+  final VoidCallback onDragEnd;
+  
+  const TodoDragItem({
+    super.key,
+    required this.todo,
+    required this.quadrant,
+    required this.onDragStarted,
+    required this.onDragEnd,
+  });
+  
+  @override
+  State<TodoDragItem> createState() => _TodoDragItemState();
+}
+
+class _TodoDragItemState extends State<TodoDragItem> {
+  @override
+  Widget build(BuildContext context) {
+    return LongPressDraggable<String>(
+      data: '${widget.todo.id}:${widget.quadrant}',
+      delay: const Duration(milliseconds: 150),
+      feedback: Material(
+        elevation: 8,
+        borderRadius: BorderRadius.circular(8),
+        child: Transform.scale(
+          scale: 1.03,
+          child: SizedBox(
+            width: 280,
+            child: _buildDragFeedback(),
+          ),
+        ),
+      ),
+      childWhenDragging: Opacity(
+        opacity: 0.5,  // Spec: 占位框 opacity 0.5
+        child: widget.child,
+      ),
+      onDragStarted: widget.onDragStarted,
+      onDragEnd: (_) => widget.onDragEnd(),
+      child: widget.child,
+    );
+  }
+  
+  Widget _buildDragFeedback() {
+    return Container(
+      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+      decoration: BoxDecoration(
+        color: AppColors.white,
+        borderRadius: BorderRadius.circular(8),
+        boxShadow: [
+          BoxShadow(
+            color: AppColors.slate400.withValues(alpha: 0.3),
+            blurRadius: 12,
+            offset: const Offset(0, 4),
+          ),
+        ],
+      ),
+      child: Text(
+        widget.todo.title,
+        style: const TextStyle(
+          fontSize: 13,
+          fontWeight: FontWeight.w600,
+          color: AppColors.slate700,
+        ),
+      ),
+    );
+  }
+}
+```
+
+- [ ] **Step 2: 验证编译**
+
+```bash
+flutter analyze lib/features/todo/ui/widgets/todo_drag_item.dart
+```
+
+---
+
+## Task 3: 实现 DragTarget 象限接收
+
+**文件:**
+- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart` 的 `_buildQuadrant` 方法
+
+- [ ] **Step 1: 将象限容器改为 DragTarget**
+
+```dart
+Widget _buildQuadrant({
+  required String title,
+  required Color textColor,
+  required Color dividerColor,
+  required Color borderColor,
+  required List<TodoResponse> items,
+  required int quadrantValue, // 1, 2, 3
+  required Future<void> Function(TodoResponse) onComplete,
+  required void Function(TodoResponse) onTap,
+}) {
+  return DragTarget<String>(
+    onWillAcceptWithDetails: (details) {
+      // 解析拖拽数据
+      final parts = details.data.split(':');
+      final todoId = parts[0];
+      // 标记目标象限
+      _onDragEnterQuadrant(quadrantValue);
+      return true;
+    },
+    onAcceptWithDetails: (details) {
+      final parts = details.data.split(':');
+      final todoId = parts[0];
+      _onDrop(todoId, quadrantValue, 0); // TODO: 计算插入位置
+    },
+    onLeave: (_) {
+      // 清除高亮
+    },
+    builder: (context, candidateData, rejectedData) {
+      final isDragOver = candidateData.isNotEmpty;
+      return AnimatedContainer(
+        duration: const Duration(milliseconds: 200),
+        decoration: BoxDecoration(
+          border: Border.all(
+            color: isDragOver ? AppColors.blue400 : borderColor,
+            width: isDragOver ? 2 : 1,
+          ),
+          boxShadow: isDragOver ? [
+            BoxShadow(
+              color: AppColors.blue200.withValues(alpha: 0.4),
+              blurRadius: 12,
+            ),
+          ] : null,
+        ),
+        child: _buildQuadrantContent(...),
+      );
+    },
+  );
+}
+```
+
+- [ ] **Step 2: 验证编译**
+
+```bash
+flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
+```
+
+---
+
+## Task 4: 实现跨象限移动和象限内排序逻辑
+
+**文件:**
+- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`
+
+- [ ] **Step 1: 实现 _onDrop 方法（支持跨象限移动和象限内排序）**
+
+```dart
+Future<void> _onDrop(String todoId, int targetQuadrant, int insertIndex) async {
+  final todo = _todos.firstWhere((t) => t.id == todoId);
+  final sourceQuadrant = todo.priority;
+  
+  // 乐观更新：先保存当前状态用于回滚
+  final previousTodos = List<TodoResponse>.from(_todos);
+  
+  if (sourceQuadrant == targetQuadrant) {
+    // 象限内排序：重新排列列表顺序
+    setState(() {
+      final currentIndex = _todos.indexWhere((t) => t.id == todoId);
+      if (currentIndex != insertIndex) {
+        final item = _todos.removeAt(currentIndex);
+        _todos.insert(insertIndex, item);
+        // 更新 sort_order (前端维护的排序索引)
+        for (int i = 0; i < _todos.length; i++) {
+          _todos[i] = _todos[i].copyWith(sortOrder: i);
+        }
+      }
+      _onDragEnd();
+    });
+    
+    // 后端同步 sort_order
+    try {
+      // 只更新 sort_order 字段
+      await _todoApi.updateTodo(todoId, sortOrder: insertIndex);
+    } catch (e) {
+      _rollbackAndShowError(previousTodos, '排序失败');
+    }
+  } else {
+    // 跨象限移动：更新 priority
+    setState(() {
+      final index = _todos.indexWhere((t) => t.id == todoId);
+      if (index != -1) {
+        _todos[index] = _todos[index].copyWith(priority: targetQuadrant);
+      }
+      _onDragEnd();
+    });
+    
+    // 后端同步 priority
+    try {
+      await _todoApi.updateTodo(todoId, priority: targetQuadrant);
+      if (mounted) {
+        Toast.show(context, '已移动', type: ToastType.success);
+      }
+    } catch (e) {
+      _rollbackAndShowError(previousTodos, '移动失败');
+    }
+  }
+}
+
+void _rollbackAndShowError(List<TodoResponse> previousTodos, String message) {
+  setState(() {
+    _todos = previousTodos;
+  });
+  if (mounted) {
+    Toast.show(context, message, type: ToastType.error);
+  }
+}
+```
+
+- [ ] **Step 2: 检查 TodoApi.updateTodo 签名**
+
+如果 `updateTodo` 不支持 `sortOrder` 参数，需要在 `TodoApi` 中添加：
+
+```dart
+// apps/lib/features/todo/data/todo_api.dart
+Future<TodoResponse> updateTodo(
+  String id, {
+  int? priority,
+  int? sortOrder, // 添加此参数
+  String? title,
+  String? description,
+}) async {
+  // 调用后端 API 更新
+}
+```
+
+- [ ] **Step 3: 验证编译和功能**
+
+```bash
+flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
+flutter analyze lib/features/todo/data/todo_api.dart
+```
+
+---
+
+## Task 5: 添加插入指示器
+
+**文件:**
+- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`
+
+- [ ] **Step 1: 添加插入位置状态和指示器 Widget**
+
+```dart
+// 在 State 中添加
+int? _dragInsertIndex; // 拖拽插入位置
+
+// 添加插入指示器 Widget
+Widget _buildInsertIndicator() {
+  return Container(
+    height: 2,
+    margin: const EdgeInsets.symmetric(vertical: 4),
+    decoration: BoxDecoration(
+      color: AppColors.blue500,
+      borderRadius: BorderRadius.circular(1),
+      boxShadow: [
+        BoxShadow(
+          color: AppColors.blue400.withValues(alpha: 0.3),
+          blurRadius: 4,
+        ),
+      ],
+    ),
+  );
+}
+```
+
+- [ ] **Step 2: 在象限内容列表中渲染插入指示器**
+
+在 `_buildQuadrant` 的 items 列表中，根据 `_dragInsertIndex` 插入指示器：
+
+```dart
+// items 列表构建
+final widgets = <Widget>[];
+for (int i = 0; i < items.length; i++) {
+  if (_dragInsertIndex == i && _dragTargetQuadrant == quadrantValue) {
+    widgets.add(_buildInsertIndicator());
+  }
+  widgets.add(TodoDragItem(
+    todo: items[i],
+    quadrant: quadrantValue,
+    onDragStarted: () => _onDragStart(items[i].id),
+    onDragEnd: _onDragEnd,
+  ));
+}
+```
+
+- [ ] **Step 3: 验证编译**
+
+```bash
+flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
+```
+
+---
+
+## Task 6: 添加 Spring 动画和退出/进入动画比例
+
+**文件:**
+- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`
+
+- [ ] **Step 1: 使用真正的 Spring 动画替代 elasticOut**
+
+Flutter 的 `SpringSimulation` 需要使用 `AnimationController`。对于跨象限移动的 feedback，可以使用 `Curves.bounceOut` 或自定义 spring：
+
+```dart
+// 使用 SpringSimulation 的替代方案 - CurvedAnimation + bounceOut
+// 跨象限移动动画 (进入时间短，退出时间长，符合 spec)
+ AnimatedContainer(
+   duration: Duration(
+     milliseconds: _isDragging ? 200 : 150, // 进入 150ms < 退出 200ms
+   ),
+   curve: Curves.easeOutCubic,
+   // ...
+ )
+```
+
+对于真正的 spring 物理效果，可以在 `pubspec.yaml` 添加 `flutter_animate` 包：
+
+```yaml
+dependencies:
+  flutter_animate: ^4.5.0
+```
+
+然后使用：
+```dart
+import 'package:flutter_animate/flutter_animate.dart';
+
+child.animate().spring(
+  type: SpringType.bouncy,
+  duration: 300.ms,
+)
+```
+
+- [ ] **Step 2: 验证编译**
+
+```bash
+flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
+```
+
+---
+
+## Task 7: 集成测试
+
+**文件:**
+- 创建: `apps/test/features/todo/quadrant_drag_test.dart`
+
+- [ ] **Step 1: 编写核心功能测试**
+
+```dart
+testWidgets('跨象限拖拽 - 成功后显示 Toast', (tester) async {
+  // mock TodoApi
+  when(() => todoApi.updateTodo(any(), priority: any(named: 'priority')))
+    .thenAnswer((_) async => mockTodo);
+  
+  await pumpWidgetWithScaffolding(tester, todoApi: todoApi);
+  
+  // 执行拖拽
+  final todoItem = find.text('测试待办');
+  await tester.drag(todoItem, const Offset(0, 200)); // 拖到下一象限
+  await tester.pumpAndSettle();
+  
+  expect(find.text('已移动'), findsOneWidget);
+});
+
+testWidgets('跨象限拖拽 - 失败后回滚并显示错误', (tester) async {
+  when(() => todoApi.updateTodo(any(), priority: any(named: 'priority')))
+    .thenThrow(Exception('网络错误'));
+  
+  await pumpWidgetWithScaffolding(tester, todoApi: todoApi);
+  
+  final todoItem = find.text('测试待办');
+  await tester.drag(todoItem, const Offset(0, 200));
+  await tester.pumpAndSettle();
+  
+  expect(find.text('移动失败'), findsOneWidget);
+  // 验证 UI 回滚到原始状态
+});
+
+testWidgets('象限内排序 - 位置正确交换', (tester) async {
+  // 验证排序逻辑
+});
+```
+
+- [ ] **Step 2: 运行测试**
+
+```bash
+cd apps && flutter test test/features/todo/quadrant_drag_test.dart
+```
+
+---
+
+## 验收标准
+
+- [ ] 长按待办项 150ms 后启动拖拽
+- [ ] 拖拽时卡片 scale 1.03 + 阴影，原位置显示 opacity 0.5 占位
+- [ ] 拖到目标象限时，象限边框高亮发光 (2px blue400)
+- [ ] 目标位置显示 2px 蓝色插入指示器
+- [ ] 释放后卡片以平滑动画到达新位置
+- [ ] 跨象限移动后本地 UI 立即更新
+- [ ] 后端同步失败时回滚本地状态并显示错误 Toast
+- [ ] 编译无错误，测试通过
@@ -0,0 +1,215 @@
+# 日历提醒统一交互设计（iOS/Android）
+
+## 1. 背景与问题
+
+当前日历提醒模块存在以下问题：
+
+1. iOS 通知动作（"稍后提醒"/"取消"）在横幅场景下可见性不稳定，用户误判为无按钮。
+2. Android 与 iOS 的通知动作回调链路不一致，导致按钮点击在部分状态下无效。
+3. 前台提醒体验依赖系统默认样式，Android 观感较弱，不符合产品视觉语言。
+4. 提醒动作与弹窗交互代码存在历史分叉，维护成本高，且存在潜在无用旧代码残留。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+- 支持 App 关闭状态下的到点提醒（系统通知主触达）。
+- 统一提醒动作语义：
+  - `稍后提醒` = 延后 10 分钟。
+  - `取消` = 归档日历事件。
+- 前台状态提供一套跨平台复用的应用内提醒面板，提升视觉质量。
+- 无论动作来自系统通知还是应用内面板，都进入同一业务执行链路。
+- 在新链路稳定后，清除无用旧代码与重复入口。
+
+### 2.2 非目标
+
+- 不改变提醒策略（仍按当前 reminderMinutes + 重复提醒策略）。
+- 不改动日历事件核心数据结构与后端协议。
+- 不在本次引入新的提醒类型（例如自定义延后时长、多级动作）。
+
+## 3. 总体方案
+
+采用“系统通知主触达 + 前台应用内面板增强”的混合方案：
+
+1. **系统通知层（平台差异化）**
+   - Android/iOS 继续使用 `flutter_local_notifications`。
+   - 平台分别补齐通知动作接收能力，确保前台/后台/终止态都可触发动作。
+
+2. **动作执行层（跨平台统一）**
+   - 以 `ReminderActionExecutor` 作为唯一动作入口。
+   - 内部动作 ID 固定为：`ReminderAction.snooze10m` 与 `ReminderAction.archive`。
+   - UI 文案中的“取消”仅为展示文案，内部统一映射到 `archive`。
+
+3. **前台呈现层（跨平台复用）**
+   - 新增应用内 `ReminderActionSheet`（共享组件，遵循设计 token）。
+   - 仅在应用前台触发，用于替代系统默认弹窗体验。
+
+4. **展示策略（避免双提醒）**
+   - 前台（App active）：默认只展示 `ReminderActionSheet`，不展示系统通知横幅。
+   - 后台/终止态：只展示系统通知。
+
+## 4. 关键设计决策
+
+### 4.1 是否需要 iOS/Android 各写一套弹窗组件
+
+不需要。应用内提醒组件采用一套 Flutter 共享实现。
+
+需要分平台处理的是系统通知配置与回调桥接，不是应用内 UI 组件本身。
+
+### 4.2 到点提醒是否继续使用“弹窗”
+
+主流做法是系统通知，不是纯应用内弹窗。原因：
+
+- App 关闭态仅系统通知可达。
+- 锁屏、通知中心具备天然可达性与系统一致性。
+- 可直接承载动作按钮（稍后提醒、取消并归档）。
+
+前台场景再补应用内面板，兼顾体验与一致行为。
+
+### 4.3 iOS 动作按钮显示问题
+
+iOS 横幅通常不保证直接展示全部动作按钮，需展开通知查看动作。该行为属于系统 UI 规则。
+
+此外 iOS 通知 category 存在缓存特性，category 变更后可能需要重装或升级 category id 才能稳定生效。
+
+## 5. 模块与职责划分
+
+### 5.1 保留并增强
+
+- `apps/lib/core/notifications/local_notification_service.dart`
+  - 仅负责通知调度与平台动作回调桥接。
+  - 不负责前台 UI 展示。
+  - 补齐后台动作回调接入。
+
+- `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
+  - 作为唯一动作执行器。
+  - 保持归档 outbox 重试机制。
+
+### 5.2 新增
+
+- `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
+  - 感知 app 前后台状态。
+  - 前台触发应用内提醒面板。
+  - 作为前台展示唯一入口，禁止其他模块直接弹出提醒面板。
+
+- `ReminderActionSheet`（共享组件）
+  - 展示事件摘要 + 两个动作按钮。
+  - 保证与系统通知动作语义一致。
+
+### 5.3 平台接入补齐
+
+- Android:
+  - 在 `apps/android/app/src/main/AndroidManifest.xml` 增加 `ActionBroadcastReceiver`。
+  - 配置并接入 `onDidReceiveBackgroundNotificationResponse`。
+  - Android 13+ 先做 `POST_NOTIFICATIONS` 授权检查；未授权时降级应用内提示并记录埋点。
+  - 后台回调函数必须为 top-level 且加 `@pragma('vm:entry-point')`。
+
+- iOS:
+  - 在 `apps/ios/Runner/AppDelegate.swift` 配置 plugin registrant callback（用于后台 action isolate）。
+  - 后台回调函数必须为 top-level 且加 `@pragma('vm:entry-point')`。
+  - `UNNotificationCategory` 在应用启动早期完成注册（早于提醒调度）。
+  - 为 category id 增加版本化策略（`calendar_reminder_v{n}`），避免缓存导致动作更新不生效。
+
+## 6. 动作流转（统一）
+
+### 6.1 稍后提醒
+
+触发源（系统通知按钮或应用内面板按钮）
+-> 统一映射为 `ReminderAction.snooze10m`
+-> `ReminderActionExecutor._snoozeEvent`
+-> 重新计算下一次时间并 `scheduleReminderAt`
+
+### 6.2 取消（归档）
+
+触发源（系统通知按钮或应用内面板按钮）
+-> 统一映射为 `ReminderAction.archive`
+-> 取消本地提醒
+-> 写 outbox 并调用归档接口
+-> 成功标记 done，失败进入 retry/backoff
+
+### 6.3 动作回传契约（前台/后台/终止态统一）
+
+- 每次动作生成幂等键：`actionExecutionId = notificationId + actionId + fireTimeBucket`。
+- 执行前先查重（本地持久化幂等表）；命中时直接 ACK，不重复执行业务副作用。
+- 终止态动作进入 cold-start queue 回放，按接收时间顺序处理。
+- 单条动作失败不阻塞后续动作；失败进入 retry/backoff 并可观测。
+
+## 7. 旧代码收集与清理计划
+
+### 7.1 旧代码清单建立
+
+改造前先建立“提醒模块迁移清单”，按三类标记：
+
+- `保留`：仍由新架构使用。
+- `替换`：保留接口，重写实现。
+- `删除`：无引用、重复职责、历史临时逻辑。
+
+迁移清单字段必须包含：`文件路径`、`符号名`、`处理决策（保留/替换/删除）`、`责任人`。
+
+### 7.2 清理时机
+
+- 新链路在 Android+iOS 均验证通过后，立即执行删除。
+- 不做“先保留一版再说”的长期并存。
+
+### 7.3 清理范围
+
+- 无效弹窗触发入口。
+- 不再使用的提醒动作映射分支。
+- 重复回调注册与过时常量（旧 action id / 旧 category id）。
+- 不再有保护价值的旧测试与旧 fixture。
+
+### 7.4 清理验收
+
+- 以“旧标识 0 引用”为验收标准，至少覆盖：旧 action id、旧 category id、旧入口函数名。
+- 输出固定 grep 关键字清单并逐条验收。
+- 提醒链路测试通过。
+- 删除项对应测试通过，且无悬挂 fixture/snapshot 引用。
+- 手工回归覆盖前台/后台/终止态三种状态。
+
+## 8. 测试与验证
+
+### 8.1 自动化
+
+- 新增/更新 reminders 相关单测：
+  - 动作映射正确性（notification/app sheet -> executor）。
+  - `archive` 的 outbox 行为与重试退避逻辑。
+  - `snooze10m` 在边界时间的调度行为。
+  - 同一 `actionExecutionId` 重复投递仅执行一次（幂等）。
+  - 终止态 cold-start queue 回放不丢失且顺序一致。
+  - 前台面板与系统通知并发触发时仅产生一次业务副作用。
+
+### 8.2 手工验证矩阵
+
+- Android:
+  - 前台：面板按钮可用。
+  - 后台：通知动作可用。
+  - 杀进程：通知动作可用。
+
+- iOS:
+  - 前台：面板按钮可用。
+  - 后台/锁屏：通知展开后动作可用。
+  - 安装升级后 category 动作可用。
+
+## 9. 风险与缓解
+
+- **风险**：iOS category 缓存导致动作更新不生效。
+  - **缓解**：category id 版本化 + 明确重装验证步骤。
+
+- **风险**：后台动作 isolate 未正确注册导致点击丢失。
+  - **缓解**：AppDelegate/Manifest 严格按插件要求配置，并做终止态回归。
+
+- **风险**：前台面板与系统通知并发触发造成重复操作。
+  - **缓解**：PresentationCoordinator 增加去重窗口与事件级幂等保护。
+
+- **风险**：通知权限未授权导致后台提醒不可达。
+  - **缓解**：启动期权限检查 + 降级提示 + 埋点追踪。
+
+## 10. 完成定义（DoD）
+
+- App 关闭状态下，系统通知可触达并可执行两个动作。
+- `取消` 在业务上严格等价于归档。
+- 前台统一提醒面板上线，Android 样式符合项目视觉语言。
+- 动作执行链路唯一，平台仅保留桥接差异。
+- 历史无用代码完成清理，且通过验证。
+- 手工矩阵 6/6 场景通过（Android 前台/后台/杀进程 + iOS 前台/后台锁屏/升级后）。
+- 动作日志可追踪，重复执行率=0（基于 `actionExecutionId` 统计）。
@@ -0,0 +1,113 @@
+# 待办事项四象限拖拽交互设计
+
+## 概述
+
+四象限待办页面支持待办项在象限内排序以及跨象限拖拽移动，同时保持与后端的数据同步。
+
+## 交互设计
+
+### 拖拽状态
+
+| 状态 | 视觉反馈 |
+|------|----------|
+| 按住（未拖拽） | 卡片 scale 1.0，轻微阴影 |
+| 拖拽开始 | 卡片 scale 1.03 + 阴影加深，原位置保留半透明占位框 |
+| 拖拽中 | 卡片跟随手指（transform），目标象限边框高亮发光 |
+| 释放-象限内排序 | 卡片平滑移动到新位置（200ms ease-out） |
+| 释放-跨象限移动 | 卡片以 spring 动画弹入目标位置 |
+| 操作完成 | 显示成功 Toast |
+
+### 动画参数
+
+- **micro-interaction**: 150-300ms
+- **easing**: ease-out 进入，ease-in 退出
+- **spring**: 用于跨象限移动，natural feel
+- **scale feedback**: 0.95-1.05 on press
+- **exit faster than enter**: 退出时长是进入的 60-70%
+
+### 防误触
+
+- 拖拽启动延迟：100-150ms 确认是长按而非点击
+- 仅在按住并移动超过阈值后启动拖拽
+
+## 数据流
+
+### 状态管理
+
+```
+_QuadrantScreenState
+  ├── List<TodoResponse> _todos
+  ├── DragState _dragState (null / dragging)
+  └── int? _dragTargetQuadrant (1, 2, 3)
+```
+
+### API 交互
+
+1. **象限内排序**：调用 `PUT /todos/{id}` 更新 `priority` 和 `sort_order`
+2. **跨象限移动**：调用 `PUT /todos/{id}` 更新 `priority`
+
+### 乐观更新
+
+- 用户释放后立即更新本地 UI
+- 后端请求失败时回滚 + 显示错误 Toast
+
+## 组件结构
+
+```
+TodoQuadrantsScreen
+├── _QuadrantDragContainer (LongPressDraggable + DragTarget)
+│   ├── _QuadrantCard (象限容器)
+│   └── _TodoDragItem (可拖拽待办项)
+└── _DragFeedbackWidget (拖拽中的视觉反馈)
+```
+
+## 状态定义
+
+| 状态 | 描述 |
+|------|------|
+| `idle` | 正常显示 |
+| `dragging` | 正在拖拽某项 |
+| `dragOverQuadrant` | 拖拽到某象限上方 |
+| `reordering` | 正在执行排序动画 |
+
+## 优先级定义
+
+| 象限 | Priority Value |
+|------|---------------|
+| 重要紧急 | 1 |
+| 紧急不重要 | 3 |
+| 重要不紧急 | 2 |
+
+## 视觉规范
+
+### 卡片样式
+
+- **正常**: `color: AppColors.todoCardBg`, `borderRadius: 14px`
+- **拖拽中**: `opacity: 0.5` 在原位置显示占位
+- **跟随手指**: `scale: 1.03`, `shadow: elevated`
+
+### 象限边框高亮
+
+- **正常**: `border: 1px solid {quadrantBorderColor}`
+- **dragOver**: `border: 2px solid AppColors.blue400`, `boxShadow: 0 0 12px AppColors.blue200`
+
+### 插入指示器
+
+- 高度 2px，圆角 1px
+- 颜色：`AppColors.blue500`
+- 位置：两个待办项之间
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 后端请求失败 | 回滚本地状态，显示错误 Toast |
+| 网络断开 | 显示网络错误提示 |
+| 并发冲突 | 以最新数据为准，提示用户刷新 |
+
+## 实现要点
+
+1. 使用 Flutter `LongPressDraggable` + `DragTarget` 实现拖拽
+2. 使用 `AnimatedContainer` / `AnimatedPositioned` 实现平滑动画
+3. 乐观更新：先更新 UI，后请求后端
+4. 拖拽反馈使用 `Transform` 而非改变位置，避免 CLS
@@ -0,0 +1,27 @@
+# Calendar Reminder Migration Checklist
+
+## Scope
+
+本清单用于跟踪提醒模块迁移后旧代码清理，字段固定为：文件路径、符号名、处理决策、责任人、状态。
+
+## Items
+
+| File | Symbol | Decision | Owner | Status | Notes |
+|---|---|---|---|---|---|
+| `apps/lib/features/calendar/reminders/models/reminder_action.dart` | `ReminderAction.cancel` | delete | agent | done | 枚举项删除，保留字符串兼容映射到 `archive` |
+| `apps/lib/features/calendar/reminders/models/reminder_action.dart` | `ReminderAction.timeout30s` | delete | agent | done | 枚举项删除，保留字符串兼容映射到 `snooze10m` |
+| `apps/lib/features/calendar/reminders/models/reminder_action.dart` | `ReminderAction.autoArchive` | delete | agent | done | 枚举项删除，保留字符串兼容映射到 `archive` |
+| `apps/lib/features/calendar/reminders/models/reminder_action.dart` | `ReminderAction.normalized` | delete | agent | done | canonical 枚举后不再需要 |
+| `apps/lib/core/notifications/local_notification_service.dart` | `_actionSnooze = 'snooze_10m'` | replace | agent | done | 统一为 `_actionSnooze = 'snooze10m'` |
+| `apps/lib/core/notifications/local_notification_service.dart` | `_iosCategoryId = 'calendar_reminder_actions_v1'` | replace | agent | done | 已升级为 `calendar_reminder_v2` |
+
+## Verification Commands
+
+```bash
+rg "calendar_reminder_actions_v1|ReminderAction\.cancel|_oldReminderEntry|_legacyReminderRoute" apps/lib apps/test
+rg "snooze_10m" apps/lib apps/test
+```
+
+Expected:
+- 第一条：no matches
+- 第二条：仅允许出现在兼容映射分支（若存在）