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

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: 写设置页接线测试

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: 写设置事件测试

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

  | "settings.updated"

• Step 2: 修改 updateUserSettings 发布事件

publishBossEvent("settings.updated");

• Step 3: 给设置页接入刷新

<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: 提交

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"