Refresh settings page in realtime

docs/superpowers/plans/2026-04-07-settings-page-realtime.md

@@ -0,0 +1,99 @@
+# Settings Page Realtime Refresh 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:** 让 `/me/settings` 在用户设置变更后自动刷新。
+
+**Architecture:** 复用现有 `boss-events -> /api/v1/events -> RealtimeRefresh` SSE 链路，新增一个语义明确的 `settings.updated` 事件。`updateUserSettings` 写入文件状态后发布事件，设置页只监听这个事件。
+
+**Tech Stack:** Next.js App Router, TypeScript, Node test runner, SSE
+
+---
+
+### Task 1: 写红灯测试
+
+**Files:**
+- Create: `tests/settings-page-realtime-refresh.test.ts`
+- Create: `tests/settings-state-events.test.ts`
+
+- [ ] **Step 1: 写设置页接线测试**
+
+```ts
+assert.match(source, /<RealtimeRefresh/, "expected settings page to render RealtimeRefresh");
+assert.match(source, /events=\{\["settings\.updated"\]\}/, "expected settings page to refresh on settings.updated");
+```
+
+- [ ] **Step 2: 跑页面测试确认失败**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts`
+Expected: FAIL，因为设置页还没有接 `RealtimeRefresh`。
+
+- [ ] **Step 3: 写设置事件测试**
+
+```ts
+await updateUserSettings({ liveUpdates: false });
+assert.equal(events.at(-1)?.event, "settings.updated");
+```
+
+- [ ] **Step 4: 跑事件测试确认失败**
+
+Run: `npx tsx --test tests/settings-state-events.test.ts`
+Expected: FAIL，因为 `updateUserSettings` 还没有发布 `settings.updated`。
+
+### Task 2: 补实现
+
+**Files:**
+- Modify: `src/lib/boss-events.ts`
+- Modify: `src/lib/boss-data.ts`
+- Modify: `src/app/me/settings/page.tsx`
+
+- [ ] **Step 1: 扩展 `BossEventName`**
+
+```ts
+  | "settings.updated"
+```
+
+- [ ] **Step 2: 修改 `updateUserSettings` 发布事件**
+
+```ts
+publishBossEvent("settings.updated");
+```
+
+- [ ] **Step 3: 给设置页接入刷新**
+
+```tsx
+<RealtimeRefresh events={["settings.updated"]} />
+```
+
+- [ ] **Step 4: 跑本轮测试确认转绿**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts`
+Expected: PASS
+
+### Task 3: 验证与提交
+
+**Files:**
+- Test: `tests/settings-page-realtime-refresh.test.ts`
+- Test: `tests/settings-state-events.test.ts`
+
+- [ ] **Step 1: 跑相关 realtime 测试**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts tests/config-pages-realtime-refresh.test.ts tests/config-state-events.test.ts tests/realtime-refresh-utils.test.ts tests/project-scoped-realtime-refresh.test.ts tests/status-pages-realtime-refresh.test.ts`
+Expected: PASS
+
+- [ ] **Step 2: 跑 lint**
+
+Run: `npm run lint`
+Expected: exit code 0
+
+- [ ] **Step 3: 跑 build**
+
+Run: `npm run build`
+Expected: exit code 0
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add docs/superpowers/specs/2026-04-07-settings-page-realtime-design.md docs/superpowers/plans/2026-04-07-settings-page-realtime.md tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts src/lib/boss-events.ts src/lib/boss-data.ts src/app/me/settings/page.tsx
+git commit -m "Refresh settings page in realtime"
+```