refactor(todo): 移除 due_at 字段，改用 order 字段管理象限内顺序

2026-03-20 11:09:38 +08:00
parent d574128815
commit fbf15bc937
22 changed files with 1458 additions and 1524 deletions
@@ -0,0 +1,274 @@
+# 前端导航解耦与统一缓存重构设计
+
+## 1. 背景与问题定义
+
+当前 `apps` 端在日历（日/月）与待办页面中存在以下系统性问题：
+
+1. 页面切换语义错误：将业务 tab 切换实现为 `push/go` 混用，导致页面重建与路由栈膨胀。
+2. 数据刷新触发错误：页面通过路由监听触发 `load`，频繁重复请求后端。
+3. 状态职责耦合：导航状态、页面状态、数据状态边界不清，导致“切换逻辑改动会牵出数据 bug”。
+4. 回主页语义不一致：Dock 首页按钮被 `canPop -> pop` 策略污染，行为变成“返回上页”。
+5. 缓存能力分散：仅存在局部的个人信息缓存（`SettingsUserCache`），缺少统一可复用缓存模块。
+
+目标是完成一次结构化重构，建立「解耦的导航切换 + 统一缓存 + 可控一致性」体系。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. Home/Calendar/Todo 切换不重建主页面（保持页面实例与滚动状态）。
+2. 日/月视图切换不触发整页重建和无必要网络请求。
+3. 建立统一缓存模块，合并个人信息缓存并覆盖 Calendar/Todo 数据读取。
+4. 启动体验采用「本地优先 + 后台静默刷新」策略，减少进入 App 的重复请求。
+5. 数据只在必要时刷新：手动下拉、写操作失效、生命周期关键点、缓存策略命中。
+6. 主页按钮语义固定为“回主页”，不再变成“返回上一页”。
+
+### 2.2 非目标
+
+1. 本次不改后端协议与接口契约。
+2. 本次不引入复杂离线同步冲突解决（如多端 CRDT）。
+3. 本次不引入全量本地数据库迁移（先基于 SharedPreferences 持久化层）。
+
+## 3. 复杂度与风险分级
+
+- Complexity: `S3`
+  - 跨 router、calendar、todo、settings、DI 的架构级调整。
+- Risk Tier: `L1`
+  - 不触及鉴权协议和支付等高风险域，但涉及导航返回栈与数据一致性高回归区。
+
+## 4. 架构总览
+
+### 4.1 导航分层
+
+采用两级导航：
+
+1. 一级（主容器）：`StatefulShellRoute.indexedStack`
+   - 分支：Home / Calendar / Todo
+   - 作用：保活分支页面，避免 tab 切换重建。
+2. 二级（分支内部）
+   - Calendar 分支：管理 month/day 主视图切换 + event detail/edit/share 子路由。
+   - Todo 分支：管理 list/detail/edit 子路由。
+
+### 4.2 状态与数据边界
+
+1. 导航状态：Shell 当前分支 index、Calendar 内部视图类型。
+2. UI 状态：选中日期、滚动位置、拖拽态、loading/error。
+3. 数据状态：统一缓存模块管理（内存 + 持久化 + 网络回写）。
+
+结论：页面只发“意图”，不直接承担缓存与路由策略。
+
+## 5. 统一缓存模块设计
+
+## 5.1 模块结构
+
+新增 `apps/lib/core/cache/`：
+
+1. `cache_key.dart`
+   - 统一 key 命名规范。
+2. `cache_policy.dart`
+   - TTL、软/硬过期、最小刷新间隔、刷新原因枚举。
+3. `cache_entry.dart`
+   - 标准缓存实体（data/fetchedAt/expiresAt/version/dirty）。
+4. `cache_store.dart`
+   - 抽象接口（get/set/remove/invalidateNamespace）。
+5. `memory_cache_store.dart`
+   - 会话级热缓存。
+6. `persistent_cache_store.dart`
+   - 本地冷缓存（SharedPreferences JSON）。
+7. `hybrid_cache_store.dart`
+   - 两级缓存协调与 singleflight 去重。
+8. `cache_invalidator.dart`
+   - 统一精准失效入口。
+
+### 5.2 key 设计（首版）
+
+1. 用户信息
+   - `user:profile:me`
+2. 日历
+   - `calendar:day:YYYY-MM-DD`
+   - `calendar:month:YYYY-MM`
+3. 待办
+   - `todo:list:pending`
+   - `todo:list:priority:<n>`（按需）
+   - `todo:detail:<id>`（按需）
+
+### 5.3 策略设计（平衡型）
+
+读取顺序：`memory -> persistent -> network`。
+
+刷新策略：
+
+1. 软过期（stale-while-revalidate）
+   - 先展示缓存，后台静默刷新。
+2. 硬过期
+   - 超过硬过期后必须请求网络或提示数据过旧。
+3. 最小刷新间隔
+   - 避免频繁切换/回前台引发抖动请求。
+
+建议默认值：
+
+1. `user:profile`：软过期 30min，硬过期 24h。
+2. `calendar:day`：软过期 2min，硬过期 30min。
+3. `calendar:month`：软过期 5min，硬过期 60min。
+4. `todo:list:pending`：软过期 2min，硬过期 30min。
+
+### 5.4 个人信息缓存合并方案
+
+现有 `SettingsUserCache` 并入统一缓存模块：
+
+1. 新建 `UserProfileRepository`（或在现有 settings service 中引入统一缓存）。
+2. `getProfile()` 通过 hybrid cache 获取 `user:profile:me`。
+3. 更新 profile 成功后立即写回缓存并同步持久化。
+4. 登出/会话失效时统一调用 `invalidateNamespace('user')`。
+
+## 6. 一致性风险与解决方案
+
+平衡型缓存会存在“短暂陈旧窗口”。本设计通过以下机制将体验风险降到可接受范围。
+
+### 6.1 触发刷新矩阵
+
+1. 手动下拉刷新：强制网络刷新。
+2. 写操作成功：精准失效受影响 key 并触发回填。
+3. App 回前台：若超过最小刷新间隔，触发静默刷新。
+4. 网络离线 -> 在线：触发静默刷新。
+5. 进入关键详情页：按策略进行 freshness check。
+
+### 6.2 写后一致性
+
+1. 乐观更新：本地先更新 UI 与缓存，避免“我刚改完却没变”。
+2. 失败回滚：API 失败时恢复旧值并 Toast 提示。
+3. 精准失效：不做全局清空，只失效关联 key，兼顾一致性与性能。
+
+### 6.3 并发安全
+
+1. singleflight：同 key 同时只允许一个网络请求。
+2. 版本保护：缓存写入比较 `updatedAt/version`，拒绝旧响应覆盖新状态。
+3. 失败兜底：请求失败不清空旧缓存，保持可读并允许重试。
+
+### 6.4 可见性保障
+
+1. 页面可显示“上次同步时间”（轻提示）。
+2. 硬过期数据需可见提醒（弱提示，不阻断基础浏览）。
+3. 提供稳定手动刷新入口。
+
+## 7. 导航与页面职责重构
+
+### 7.1 路由重构
+
+1. `app_router` 引入 shell 分支，不再平铺所有主页面。
+2. Dock 切换改为 branch index 切换，不再 `push` 主页面。
+3. Calendar 内部 month/day 切换改为视图切换，不新增栈层。
+4. 事件详情/编辑等保留 `push`（细节页合理叠栈）。
+
+### 7.2 回主页逻辑修正
+
+1. Dock Home 统一执行“切到 Home 分支/`go('/home')`”。
+2. `returnToHomePreserveState` 仅用于非 Dock 的返回策略场景。
+3. 消除 `canPop -> pop` 对主页按钮语义的影响。
+
+### 7.3 页面职责收敛
+
+1. Calendar/Todo 页面移除路由监听触发 `load`。
+2. 页面只调用 repository：
+   - `get(policy)`
+   - `refresh(force: true)`
+   - `mutate(...) + invalidate(...)`
+3. 页面不直接感知“缓存在哪一层”。
+
+## 8. 分阶段实施计划（里程碑）
+
+### M1 导航壳层与切换语义
+
+1. 引入 shell + 分支保活。
+2. Dock 接口改造与主 tab 切换实现。
+3. Home 按钮语义修正。
+
+### M2 统一缓存骨架
+
+1. 新增 core cache 模块。
+2. 接入 user profile（替换 `SettingsUserCache`）。
+3. DI 注入 cache store 与 invalidator。
+
+### M3 Calendar 接入
+
+1. 引入 `CalendarRepository` 与 day/month key。
+2. 移除 route listener 自动刷新。
+3. 切换 month/day 时默认走缓存，不触发无必要请求。
+
+### M4 Todo 接入
+
+1. 引入 `TodoRepository` 与 list/detail key。
+2. 拖拽、完成、编辑后的精准失效。
+3. 下拉刷新走强制网络。
+
+### M5 清理与验证
+
+1. 清理旧缓存与重复加载逻辑。
+2. 补齐测试与性能观测。
+3. 评估参数并收敛默认策略。
+
+## 9. 验收标准
+
+### 9.1 体验验收
+
+1. Home/Calendar/Todo 切换无明显重建卡顿。
+2. 日/月切换响应明显变快。
+3. 首次冷启动可先看到本地缓存内容。
+4. Dock Home 始终回主页。
+
+### 9.2 网络验收
+
+1. 切换页面时网络请求显著减少。
+2. 写操作后关联数据可及时更新。
+3. 手动刷新可强制拉取并回写缓存。
+
+### 9.3 一致性验收
+
+1. 不出现旧响应覆盖新数据。
+2. 离线后恢复在线可自动静默同步。
+3. 软过期/硬过期行为符合策略定义。
+
+## 10. 测试与验证计划
+
+### 10.1 单元测试
+
+1. `hybrid_cache_store`：命中链路、singleflight、软硬过期判定。
+2. `cache_invalidator`：写操作触发的 key 精准失效。
+3. repository：读缓存、后台刷新、失败兜底、版本保护。
+
+### 10.2 组件/页面测试（高回归）
+
+1. Dock 切换不重建分支主页面。
+2. 日/月切换不重复触发全量加载。
+3. Home 按钮行为稳定。
+
+### 10.3 集成回归
+
+1. Calendar -> Todo -> Calendar 多轮切换请求计数。
+2. Todo 完成后列表更新与缓存一致性。
+3. profile 更新后设置页/其他依赖页可见一致。
+
+## 11. 风险与回滚
+
+### 11.1 主要风险
+
+1. 导航壳层改造可能引发深链与返回栈回归。
+2. 缓存策略参数不当可能造成陈旧感。
+3. 早期失效 key 设计不完整可能出现局部不刷新。
+
+### 11.2 控制策略
+
+1. 按里程碑逐步落地，每个里程碑可单独回滚。
+2. 默认保留手动刷新兜底。
+3. 增加请求计数与缓存命中日志（开发态）。
+
+### 11.3 回滚策略
+
+1. 若 M1 不稳定，可先回退 shell 改造并保留缓存模块。
+2. 若缓存接入问题集中，可按域回退（user/calendar/todo 分域开关）。
+
+## 12. 待确认参数（实施前锁定）
+
+1. 软/硬过期默认值是否按本设计直接采用。
+2. 是否立即展示“上次同步时间”。
+3. 是否在首版启用“网络恢复自动静默刷新”。
@@ -0,0 +1,438 @@
+# 前端导航解耦与统一缓存重构 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 完成 Home/Calendar/Todo 的解耦切换与统一缓存改造，实现本地优先显示、后台静默刷新、写后精准失效，并修复 Dock 回主页语义。
+
+**Architecture:** 路由层采用 `StatefulShellRoute.indexedStack` 维持主分支保活；数据层新增 `core/cache` 统一缓存模块（memory + persistent + hybrid）；业务层通过 repository 接入缓存策略，页面仅负责发意图和渲染状态。写操作触发精准失效，读取遵循 soft/hard TTL + minimum refresh interval。
+
+**Tech Stack:** Flutter, go_router, get_it, shared_preferences, flutter_test, mocktail
+
+---
+
+### Task 1: 建立统一缓存核心模型与策略
+
+**Files:**
+- Create: `apps/lib/core/cache/cache_entry.dart`
+- Create: `apps/lib/core/cache/cache_key.dart`
+- Create: `apps/lib/core/cache/cache_policy.dart`
+- Test: `apps/test/core/cache/cache_policy_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:social_app/core/cache/cache_policy.dart';
+
+void main() {
+  test('soft expired should allow stale read with background refresh', () {
+    final now = DateTime(2026, 3, 20, 12);
+    final policy = CachePolicy(
+      softTtl: const Duration(minutes: 2),
+      hardTtl: const Duration(minutes: 30),
+      minRefreshInterval: const Duration(minutes: 1),
+    );
+
+    final fetchedAt = now.subtract(const Duration(minutes: 3));
+    final decision = policy.evaluate(now: now, fetchedAt: fetchedAt);
+    expect(decision.canUseCached, true);
+    expect(decision.shouldRefreshInBackground, true);
+    expect(decision.mustBlockForNetwork, false);
+  });
+}
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/core/cache/cache_policy_test.dart`
+Expected: FAIL with missing cache policy symbols.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class CacheDecision {
+  final bool canUseCached;
+  final bool shouldRefreshInBackground;
+  final bool mustBlockForNetwork;
+  const CacheDecision({
+    required this.canUseCached,
+    required this.shouldRefreshInBackground,
+    required this.mustBlockForNetwork,
+  });
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd apps && flutter test test/core/cache/cache_policy_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/core/cache/cache_entry.dart apps/lib/core/cache/cache_key.dart apps/lib/core/cache/cache_policy.dart apps/test/core/cache/cache_policy_test.dart
+git commit -m "feat: add unified cache policy primitives"
+```
+
+### Task 2: 实现 memory/persistent/hybrid cache store（含 singleflight）
+
+**Files:**
+- Create: `apps/lib/core/cache/cache_store.dart`
+- Create: `apps/lib/core/cache/memory_cache_store.dart`
+- Create: `apps/lib/core/cache/persistent_cache_store.dart`
+- Create: `apps/lib/core/cache/hybrid_cache_store.dart`
+- Test: `apps/test/core/cache/hybrid_cache_store_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('same key concurrent load should execute loader once', () async {
+  var calls = 0;
+  final store = HybridCacheStore(...);
+  Future<String> loader() async {
+    calls += 1;
+    return 'ok';
+  }
+  await Future.wait([
+    store.getOrLoad<String>('k', loader: loader),
+    store.getOrLoad<String>('k', loader: loader),
+  ]);
+  expect(calls, 1);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/core/cache/hybrid_cache_store_test.dart`
+Expected: FAIL with missing HybridCacheStore.
+
+**Step 3: Write minimal implementation**
+
+```dart
+final Map<String, Future<dynamic>> _inflight = {};
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd apps && flutter test test/core/cache/hybrid_cache_store_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/core/cache/cache_store.dart apps/lib/core/cache/memory_cache_store.dart apps/lib/core/cache/persistent_cache_store.dart apps/lib/core/cache/hybrid_cache_store.dart apps/test/core/cache/hybrid_cache_store_test.dart
+git commit -m "feat: implement hybrid cache store with singleflight"
+```
+
+### Task 3: 接入 DI 与统一失效器
+
+**Files:**
+- Create: `apps/lib/core/cache/cache_invalidator.dart`
+- Modify: `apps/lib/core/di/injection.dart`
+- Test: `apps/test/core/cache/cache_invalidator_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('invalidate calendar day should also invalidate month key', () {
+  final inv = CacheInvalidator(...);
+  inv.invalidateCalendarDay(DateTime(2026, 3, 20));
+  expect(inv.wasInvalidated('calendar:day:2026-03-20'), true);
+  expect(inv.wasInvalidated('calendar:month:2026-03'), true);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/core/cache/cache_invalidator_test.dart`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class CacheInvalidator {
+  void invalidateCalendarDay(DateTime date) { /* invalidate day + month */ }
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd apps && flutter test test/core/cache/cache_invalidator_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/core/cache/cache_invalidator.dart apps/lib/core/di/injection.dart apps/test/core/cache/cache_invalidator_test.dart
+git commit -m "refactor: wire unified cache and invalidator in di"
+```
+
+### Task 4: 合并个人信息缓存（替换 SettingsUserCache）
+
+**Files:**
+- Modify: `apps/lib/features/settings/data/services/settings_user_cache.dart`
+- Create: `apps/lib/features/settings/data/services/user_profile_cache_repository.dart`
+- Modify: `apps/lib/features/settings/ui/screens/settings_screen.dart`
+- Test: `apps/test/features/settings/data/services/settings_user_cache_test.dart`
+- Create: `apps/test/features/settings/data/services/user_profile_cache_repository_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('repository should return persistent cache first then refresh in background', () async {
+  // Arrange cached profile in persistent store
+  // Assert immediate cached result + refresh called once
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/features/settings/data/services/user_profile_cache_repository_test.dart`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class UserProfileCacheRepository {
+  Future<UserResponse> getProfile({bool forceRefresh = false}) async { ... }
+}
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test test/features/settings/data/services/settings_user_cache_test.dart test/features/settings/data/services/user_profile_cache_repository_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/features/settings/data/services/settings_user_cache.dart apps/lib/features/settings/data/services/user_profile_cache_repository.dart apps/lib/features/settings/ui/screens/settings_screen.dart apps/test/features/settings/data/services/settings_user_cache_test.dart apps/test/features/settings/data/services/user_profile_cache_repository_test.dart
+git commit -m "refactor: merge profile cache into unified cache repository"
+```
+
+### Task 5: 路由改造为 StatefulShellRoute + Dock 切换分支
+
+**Files:**
+- Modify: `apps/lib/core/router/app_router.dart`
+- Modify: `apps/lib/core/router/app_routes.dart`
+- Modify: `apps/lib/features/calendar/ui/widgets/bottom_dock.dart`
+- Modify: `apps/lib/features/home/ui/navigation/home_return_policy.dart`
+- Test: `apps/test/core/router/app_routes_test.dart`
+- Modify: `apps/test/features/home/ui/navigation/home_return_policy_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('dock home action should always resolve to goHome', () {
+  final action = resolveHomeReturnAction(canPop: true, isAuthEntry: false);
+  expect(action, HomeReturnAction.goHomeForDock);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/features/home/ui/navigation/home_return_policy_test.dart`
+Expected: FAIL with old behavior.
+
+**Step 3: Write minimal implementation**
+
+```dart
+enum HomeReturnAction { pop, goHome, goHomeForDock }
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test test/core/router/app_routes_test.dart test/features/home/ui/navigation/home_return_policy_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/core/router/app_router.dart apps/lib/core/router/app_routes.dart apps/lib/features/calendar/ui/widgets/bottom_dock.dart apps/lib/features/home/ui/navigation/home_return_policy.dart apps/test/core/router/app_routes_test.dart apps/test/features/home/ui/navigation/home_return_policy_test.dart
+git commit -m "feat: switch main navigation to stateful shell tabs"
+```
+
+### Task 6: Calendar repository 化并移除路由监听刷新
+
+**Files:**
+- Create: `apps/lib/features/calendar/data/services/calendar_repository.dart`
+- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart`
+- Modify: `apps/lib/features/calendar/ui/screens/calendar_month_screen.dart`
+- Modify: `apps/lib/features/calendar/ui/calendar_state_manager.dart`
+- Create: `apps/test/features/calendar/data/services/calendar_repository_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('getDayEvents returns cache immediately and refreshes in background', () async {
+  // Arrange cache day key
+  // Assert cached list emitted before network completion
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/features/calendar/data/services/calendar_repository_test.dart`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class CalendarRepository {
+  Future<List<ScheduleItemModel>> getDayEvents(DateTime date, {bool forceRefresh = false}) async { ... }
+}
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test test/features/calendar/data/services/calendar_repository_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/features/calendar/data/services/calendar_repository.dart apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart apps/lib/features/calendar/ui/screens/calendar_month_screen.dart apps/lib/features/calendar/ui/calendar_state_manager.dart apps/test/features/calendar/data/services/calendar_repository_test.dart
+git commit -m "refactor: decouple calendar screens from route-driven reload"
+```
+
+### Task 7: Todo repository 化与写后精准失效
+
+**Files:**
+- Create: `apps/lib/features/todo/data/todo_repository.dart`
+- Modify: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`
+- Modify: `apps/lib/features/todo/data/todo_api.dart`
+- Create: `apps/test/features/todo/todo_repository_test.dart`
+- Modify: `apps/test/features/todo/quadrant_drag_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('complete todo should optimistically update and invalidate pending list key', () async {
+  // assert local list updated first, invalidator called
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/features/todo/todo_repository_test.dart`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class TodoRepository {
+  Future<void> completeTodo(String id) async { ... }
+}
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test test/features/todo/todo_repository_test.dart test/features/todo/quadrant_drag_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/features/todo/data/todo_repository.dart apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart apps/lib/features/todo/data/todo_api.dart apps/test/features/todo/todo_repository_test.dart apps/test/features/todo/quadrant_drag_test.dart
+git commit -m "feat: add todo cache repository and precise invalidation"
+```
+
+### Task 8: App 生命周期与网络恢复刷新策略
+
+**Files:**
+- Create: `apps/lib/core/cache/cache_refresh_coordinator.dart`
+- Modify: `apps/lib/main.dart`
+- Create: `apps/test/core/cache/cache_refresh_coordinator_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('resume should trigger refresh only when min interval elapsed', () {
+  // Arrange last refreshed timestamp
+  // Assert callback invocation count
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/core/cache/cache_refresh_coordinator_test.dart`
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+```dart
+class CacheRefreshCoordinator with WidgetsBindingObserver { ... }
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd apps && flutter test test/core/cache/cache_refresh_coordinator_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/core/cache/cache_refresh_coordinator.dart apps/lib/main.dart apps/test/core/cache/cache_refresh_coordinator_test.dart
+git commit -m "feat: add app lifecycle refresh coordinator"
+```
+
+### Task 9: 全量验证与文档同步
+
+**Files:**
+- Modify: `docs/protocols/*`（仅当路由/数据契约文档需更新时）
+- Modify: `docs/plans/2026-03-20-navigation-cache-decoupling-design.md`（回填最终参数）
+
+**Step 1: Run focused tests**
+
+Run:
+
+```bash
+cd apps && flutter test test/core/cache test/features/settings/data/services/settings_user_cache_test.dart test/features/calendar test/features/todo test/features/home/ui/navigation/home_return_policy_test.dart test/core/router/app_routes_test.dart
+```
+
+Expected: PASS.
+
+**Step 2: Run app-level verification**
+
+Run: `cd apps && flutter test`
+Expected: PASS.
+
+**Step 3: Static checks**
+
+Run: `cd apps && flutter analyze`
+Expected: No errors.
+
+**Step 4: Manual verification checklist**
+
+1. 冷启动先显示缓存，随后静默更新。
+2. Home/Calendar/Todo 来回切换不重建主页面。
+3. 日/月切换不触发无必要请求。
+4. Dock Home 始终回主页。
+5. 写后数据可见一致，失败可回滚提示。
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-03-20-navigation-cache-decoupling-design.md docs/protocols
+git commit -m "docs: finalize navigation decoupling and unified cache rollout"
+```
+
+## 实施顺序约束
+
+1. 必须先完成 Task 1-3 再改业务页面（否则会出现重复实现）。
+2. Task 5（路由壳层）与 Task 6/7（业务接入）要分开提交，便于回滚。
+3. 每个 Task 的测试必须在本 Task 完成后立即执行，避免堆积回归。
+4. 不允许在未通过 focused tests 的情况下进入全量验证。
+
+## 回滚策略
+
+1. 若导航回归：回滚 Task 5 提交，保留缓存模块提交。
+2. 若缓存一致性异常：优先回滚 Task 6/7 的 repository 接入提交。
+3. 若生命周期刷新过于频繁：关闭 Task 8 coordinator 挂载，保留手动刷新兜底。
+
+## Done 定义
+
+1. 所有测试与 analyze 通过。
+2. 主页按钮行为稳定，无“返回上一页”误行为。
+3. 切换页面请求数明显下降，写后一致性符合设计预期。
+4. 统一缓存已接管用户信息、日历、待办三域。
@@ -0,0 +1,43 @@
+# Todo Data Protocol
+
+## Scope
+
+Defines the backend/frontend data contract for `/api/v1/todos`.
+
+## Field Definitions
+
+- `id`: string (UUID)
+- `owner_id`: string (UUID)
+- `title`: string, `1..255`
+- `description`: string or `null`, max `1000`
+- `priority`: int, quadrant value in `[1, 4]`
+- `order`: int, zero-based ordering inside the same `priority` bucket, `>= 0`
+- `status`: enum string: `pending | done | canceled`
+- `completed_at`: datetime string or `null`
+- `created_at`: datetime string
+- `updated_at`: datetime string
+- `schedule_items`: array
+
+## Request Contracts
+
+### Create Todo (`POST /api/v1/todos`)
+
+- required: `title`
+- optional: `description`, `priority`, `order`, `schedule_item_ids`
+- `order` omitted: backend assigns append position in the target quadrant.
+
+### Update Todo (`PATCH /api/v1/todos/{todo_id}`)
+
+- optional: `title`, `description`, `priority`, `order`, `status`, `schedule_item_ids`
+- `order` is interpreted inside the todo's final `priority` quadrant.
+
+## Ordering Rules
+
+- Todo list API returns items sorted by `priority ASC`, then `order ASC`.
+- Drag reorder in same quadrant updates `order` to a continuous sequence starting from `0`.
+- Drag move across quadrants updates both `priority` and `order`, and source/target quadrants should both stay contiguous from `0`.
+
+## Compatibility Notes
+
+- `due_at` is removed from todo protocol.
+- Clients must not send or depend on `due_at` for todo ordering.
@@ -1,391 +0,0 @@
-# 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/协议再继续写代码。
@@ -1,524 +0,0 @@
-# 待办事项四象限拖拽实现计划
-
-> **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
- [ ] 编译无错误，测试通过
@@ -1,215 +0,0 @@
-# 日历提醒统一交互设计（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` 统计）。
@@ -1,113 +0,0 @@
-# 待办事项四象限拖拽交互设计
-
-## 概述
-
-四象限待办页面支持待办项在象限内排序以及跨象限拖拽移动，同时保持与后端的数据同步。
-
-## 交互设计
-
-### 拖拽状态
-
-| 状态 | 视觉反馈 |
-|------|----------|
-| 按住（未拖拽） | 卡片 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