feat(apps): refine login consent and calendar day/month UX

2026-03-20 19:00:24 +08:00
parent 2e94908eaa
commit fcf98b1142
11 changed files with 359 additions and 58 deletions
@@ -2,14 +2,61 @@

 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

-**Goal:** 完成 Home/Calendar/Todo 的解耦切换与统一缓存改造，实现本地优先显示、后台静默刷新、写后精准失效，并修复 Dock 回主页语义。
+**Goal:** 完成导航分级回退（一级唯一 Home）与统一缓存改造，实现本地优先显示、后台静默刷新、写后精准失效，并落地“提醒取消即实时归档 + App 关闭时延迟归档兜底”。

-**Architecture:** 路由层采用 `StatefulShellRoute.indexedStack` 维持主分支保活；数据层新增 `core/cache` 统一缓存模块（memory + persistent + hybrid）；业务层通过 repository 接入缓存策略，页面仅负责发意图和渲染状态。写操作触发精准失效，读取遵循 soft/hard TTL + minimum refresh interval。
+**Architecture:** 路由层采用“一级唯一 Home + 二级业务页 + 三级细节页”的分级返回模型，二级页面返回统一回 Home，退出入口仅 Home；数据层新增 `core/cache` 统一缓存模块（memory + persistent + hybrid）；业务层通过 repository 接入缓存策略与失效器。提醒动作采用实时归档优先，pending outbox 仅用于 App 不可用场景兜底。

 **Tech Stack:** Flutter, go_router, get_it, shared_preferences, flutter_test, mocktail

 ---

+### Task 0: 锁定导航分级与退出语义（一级/二级/三级）
+
+**Files:**
+- Modify: `apps/lib/core/router/app_router.dart`
+- Modify: `apps/lib/features/home/ui/navigation/home_return_policy.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/todo/ui/screens/todo_quadrants_screen.dart`
+- Modify: `apps/lib/features/settings/ui/screens/settings_screen.dart`
+- Test: `apps/test/features/home/ui/navigation/home_return_policy_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('second-level pages should return to home instead of exiting app', () {
+  final action = resolveHomeReturnAction(
+    canPop: false,
+    isAuthEntry: false,
+    forceGoHome: true,
+  );
+  expect(action, HomeReturnAction.goHome);
+});
+```
+
+**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 return behavior.
+
+**Step 3: Write minimal implementation**
+
+```dart
+if (forceGoHome) return HomeReturnAction.goHome;
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test 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/features/home/ui/navigation/home_return_policy.dart apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart apps/lib/features/calendar/ui/screens/calendar_month_screen.dart apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart apps/lib/features/settings/ui/screens/settings_screen.dart apps/test/features/home/ui/navigation/home_return_policy_test.dart
+git commit -m "feat: enforce hierarchical back navigation and home-only exit"
+```
+
 ### Task 1: 建立统一缓存核心模型与策略

 **Files:**
@@ -376,7 +423,54 @@ git add apps/lib/core/cache/cache_refresh_coordinator.dart apps/lib/main.dart ap
 git commit -m "feat: add app lifecycle refresh coordinator"
 ```

-### Task 9: 全量验证与文档同步
+### Task 9: 提醒取消实时归档与延迟归档兜底收敛
+
+**Files:**
+- Modify: `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
+- Modify: `apps/lib/features/calendar/reminders/ui/reminder_foreground_presenter.dart`
+- Modify: `apps/lib/core/notifications/local_notification_service.dart`
+- Modify: `apps/lib/main.dart`
+- Modify: `apps/test/features/calendar/reminders/reminder_action_executor_test.dart`
+- Modify: `apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+
+**Step 1: Write the failing test**
+
+```dart
+test('archive action should send remote archive immediately when app active', () async {
+  // Arrange active app + online gateway
+  // Act archive action
+  // Assert remote archive called once and local pending outbox not created
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd apps && flutter test test/features/calendar/reminders/reminder_action_executor_test.dart`
+Expected: FAIL with delayed-only behavior.
+
+**Step 3: Write minimal implementation**
+
+```dart
+if (isAppActive) {
+  await repository.archiveNow(eventId);
+} else {
+  await outbox.enqueueArchive(eventId);
+}
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd apps && flutter test test/features/calendar/reminders/reminder_action_executor_test.dart test/features/calendar/reminders/reminder_notification_bridge_test.dart`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add apps/lib/features/calendar/reminders/reminder_action_executor.dart apps/lib/features/calendar/reminders/ui/reminder_foreground_presenter.dart apps/lib/core/notifications/local_notification_service.dart apps/lib/main.dart apps/test/features/calendar/reminders/reminder_action_executor_test.dart apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart
+git commit -m "fix: prioritize realtime reminder archive with cold-start fallback"
+```
+
+### Task 10: 全量验证与文档同步

 **Files:**
 - Modify: `docs/protocols/*`（仅当路由/数据契约文档需更新时）
@@ -409,6 +503,8 @@ Expected: No errors.
 3. 日/月切换不触发无必要请求。
 4. Dock Home 始终回主页。
 5. 写后数据可见一致，失败可回滚提示。
+6. 二级页面侧滑返回只回 Home，不直接退出。
+7. 提醒点击取消时立刻归档；仅在 App 不可用时走 pending 兜底。

 **Step 5: Commit**

@@ -419,16 +515,17 @@ git commit -m "docs: finalize navigation decoupling and unified cache rollout"

 ## 实施顺序约束

-1. 必须先完成 Task 1-3 再改业务页面（否则会出现重复实现）。
-2. Task 5（路由壳层）与 Task 6/7（业务接入）要分开提交，便于回滚。
+1. 必须先完成 Task 0-3 再改业务页面（否则会出现重复实现）。
+2. Task 0（分级返回）与 Task 5（路由壳层）要分开提交，便于单独回滚。
 3. 每个 Task 的测试必须在本 Task 完成后立即执行，避免堆积回归。
 4. 不允许在未通过 focused tests 的情况下进入全量验证。

 ## 回滚策略

-1. 若导航回归：回滚 Task 5 提交，保留缓存模块提交。
+1. 若返回语义回归：先回滚 Task 0 提交，再评估 Task 5。
 2. 若缓存一致性异常：优先回滚 Task 6/7 的 repository 接入提交。
 3. 若生命周期刷新过于频繁：关闭 Task 8 coordinator 挂载，保留手动刷新兜底。
+4. 若提醒实时归档异常：回滚 Task 9，仅保留 outbox 兜底路径。

 ## Done 定义

@@ -436,3 +533,5 @@ git commit -m "docs: finalize navigation decoupling and unified cache rollout"
 2. 主页按钮行为稳定，无“返回上一页”误行为。
 3. 切换页面请求数明显下降，写后一致性符合设计预期。
 4. 统一缓存已接管用户信息、日历、待办三域。
+5. 二级页面不再可直接侧滑退出 App。
+6. 提醒归档满足“实时优先、关闭兜底”策略。