multica/docs/onboarding-refactor-plan.md

Onboarding v3 — Thin Server, Frontend-Orchestrated Welcome

1. 背景

两次错位重构(MUL-2438 + da0ecb6a)叠加产出了一个味道很重的 onboarding:

• users.onboarded_at 在 4 个 handler 里分别 MarkUserOnboarded,每处副作用还不一样
• 同样的"种 install-runtime issue"在 4 个调用点重复,靠 advisory lock 在底层做去重
• Step 3 Connect 与 Skip 路径不对称(一个延迟 mark,一个立即 mark)
• 工作区 Modal 自己 query runtime 列表挑第一个,完全丢弃用户在 Step 3 的选择
• onboarded_at 字段同时承担"完成状态"和"Modal 触发条件"双语义

最初的 v2 方案(本 wip 分支的 PR 1-7)走"持久化字段 + 工作区 init 4 分支 dispatcher"路线 — 把 Step 3 的选择 PATCH 进 users.onboarding_runtime_id / onboarding_runtime_skipped,工作区入口读这两个字段决定弹什么。可工作,但把过去 React 内存里的瞬态意图变成了数据库的持久化字段,后端业务复杂度不降反升:多了一个 OnboardingService,多了一个 WorkspaceContentService,handler 多了一个 EnsureOnboardingContent endpoint,前端多了 4 分支 dispatcher 组件。

数据分析师确认生产里 0 个 mid-flow 用户(有 workspace + onboarded_at IS NULL),v2 加的两字段没有真实使用,可以安全删除。

v3 在 v2 之上做更激进的清理:后端 onboarding 业务复杂度归零,Helper agent / starter issue / 中英文案全部在前端 hook 里调通用 createAgent / createIssue 完成。

2. 设计 — 5 条核心原则

1. users.onboarded_at 是唯一 onboarding 状态字段(删 v2 加的两字段)
2. Onboarding 阶段(Step 1-3)纯收集,Step 3 按钮 = mark + welcome-store.set + navigate
3. 后端 onboarding 业务复杂度归零 — 删 BootstrapOnboarding* / OnboardingService / WorkspaceContentService / EnsureOnboardingContent 全套;后端 onboarding 只剩 mark + 问卷
4. 进工作区 hook 看 welcome-store,有信号 → 按 runtime/skip 分两路调通用 createAgent / createIssue
5. Helper instructions / starter prompt / install-runtime issue 描述(EN/ZH)全部在前端 TS 模块(packages/views/onboarding/templates/)

外加双向路由 hard gate:apps/web/app/[workspaceSlug]/layout.tsx 拦未 onboarded → /onboarding;apps/web/app/(auth)/onboarding/page.tsx 拦已 onboarded → workspace。桌面端用 App.tsx 的 overlay 决策达成同样效果(no URL bar, no router.replace)。

3. 4 类用户链路

3.1 新用户,Step 3 选 runtime

Step 3 [开始探索]
  → completeOnboarding("full", workspace.id)      ─ 后端只 mark
  → welcomeStore.set({wsId, choice:"runtime", runtimeId})
  → navigate(/<slug>/issues)
workspace layout gate: onboarded_at != NULL ✓ 放行
<WelcomeAfterOnboarding /> consumes welcome-store:
  phase 1: full-screen loading "Preparing your Helper…"
           api.listAgents → 查重名 Multica Helper(workspace 可见的)
           → 找到 → 复用
           → 没找到 → api.createAgent({name, instructions: HELPER_INSTRUCTIONS[lang], runtime_id, ...})
  phase 2: blocking Modal(无关闭按钮 / Escape no-op / outside-click no-op)
           Helper avatar + name + description + 3 张 starter cards
  phase 3: 用户挑卡 → api.createIssue({title, description: prompt,
           assignee_type:"agent", assignee_id: agent.id}) → navigate(issue)

3.2 新用户,Step 3 点 Skip

Step 3 [跳过]
  → completeOnboarding("runtime_skipped", workspace.id)
  → welcomeStore.set({wsId, choice:"skip"})
  → navigate(/<slug>/issues)
workspace layout gate ✓ 放行
<WelcomeAfterOnboarding /> consumes signal:
  Modal 打开(可关闭)
  后台并发 api.createIssue × 2:
    - Connect a runtime to start using agents
    - Create your first Multica Agent
  渲染 2 张 issue 卡;点卡 → navigate;关 Modal → 留在 /issues 列表

3.3 被邀请用户

AcceptInvitation handler:
  事务内 qtx.CreateMember + qtx.MarkUserOnboarded(必须保留!)
navigate(/<slug>/issues) 不带 welcome-store 信号
workspace layout gate ✓ 放行
<WelcomeAfterOnboarding /> 无信号 → 渲染 null

3.4 老用户回访

resolvePostAuthDestination: hasOnboarded ✓ + workspace[0] → /<slug>/issues
layout gate ✓ 放行
welcome-store 无信号 → 不弹

4. 数据 / 字段终态

字段	含义	谁读
users.onboarded_at	唯一 onboarding 完成信号	layout hard gate × 2
users.onboarding_questionnaire	问卷答案	OnboardingFlow 预填
(PostHog OnboardingCompleted event)	Skip vs Connect 历史分析	数据分析

删掉:onboarding_runtime_id、onboarding_runtime_skipped 列 + user_onboarding_runtime_choice_check CHECK 约束。Welcome 触发改用前端 Zustand transient store(packages/core/onboarding/welcome-store.ts),read-once-then-clear 语义。

5. 关键设计决策

D1:NavigationAdapter 不支持 state → Zustand transient store

packages/views/navigation/types.ts 的 push(path: string): void 不接 state,所以不能用 navigate(path, {state}) 模式。改用 packages/core/onboarding/welcome-store.ts:Step 3 完成时 set({...}),Welcome hook mount 时 consume()(一次读 + 清空)。store 非 persist → 刷新即丢 = Welcome Modal 不会被刷新重弹,符合"一次性体验"预期。

D2:Desktop 路由 hard gate 走 overlay 而非 router.replace

桌面端 onboarding 是 WindowOverlay,不是 react-router 路由。apps/desktop/src/renderer/src/App.tsx 的 overlay 决策 effect 增加规则:!hasOnboarded 一律 setCurrentWorkspace(null,null) + open onboarding overlay(不管 wsCount)。web 端在 layout.tsx 用 router.replace(paths.onboarding()) 直接跳。两套实现在效果上等价。

D3:resolvePostAuthDestination 改回 onboarded-first

V2 改成了 workspace-presence-first(为了不把 mid-flow 用户踢回 onboarding),v3 还原成 onboarded-first。理由:layout hard gate 会在 !onboarded 时强制 redirect,resolver 直接走 workspace 只是浪费一次 navigation;mid-flow 在 v3 下概率极低(仅 Step 2 完关 app 这一窗口)。

D4:Helper instructions / 长文案放 TS 模块,不放 i18n JSON

instructions 是 94 行 markdown,issue 描述是 60+ 行带列表 / 代码块。放在 packages/views/onboarding/templates/ 下 3 个 TS 模块,每个导出 {en, zh} 字符串 const。短文案(Modal 标题 / 副标题 / 按钮 / 卡片标题)仍走 i18n JSON。

D5:重名 Helper 防重

刷新 / StrictMode 双 mount 都可能让 hook 多次进入。前端用:

1. useRef 一次性锁 prevents 同 mount 内重复触发
2. Welcome 信号 consume() 一读即清,即使 React 多次 mount 也只第一次拿到信号
3. 进 createAgent 前先 api.listAgents 查重名 + visibility="workspace" + !archived,有则复用

D6:失败处理

• runtime 路径:阻塞 Modal + 失败 retry UI(无关闭),用户卡死时 onAbandon 把信号清空恢复路由
• skip 路径:Modal 可关闭,每条 issue 失败显示 per-card retry
• onboarded_at 已 set,失败不阻塞 — 用户最坏情况是手动建 agent / 关 Modal 用空 workspace

6. 文件改动盘点(相对 main)

删

• server/internal/service/onboarding.go
• server/internal/service/workspace_content.go
• server/internal/handler/onboarding.go:BootstrapOnboardingRuntime、BootstrapOnboardingNoRuntime handler 整体 + 相关常量(onboardingAssistantInstructions 94 行 markdown、onboardingAssistantName、onboardingIssueTitle、onboardingIssueDescription、onboardingAssistantAvatarURL、onboardingAssistantDescription、onboardingAgentTemplate)
• server/internal/handler/workspace.go:EnsureOnboardingContent handler
• server/cmd/server/router.go:3 条路由(runtime-bootstrap / no-runtime-bootstrap / ensure-onboarding-content)
• server/internal/handler/handler.go:OnboardingService / WorkspaceContent 字段 + 实例化
• server/internal/handler/onboarding_test.go:5 个 Bootstrap* 测试 + 2 个 PatchOnboarding 测试(只留 JoinCloudWaitlist 测试)
• packages/views/workspace/workspace-onboarding-init.tsx + 测试
• packages/views/workspace/onboarding-helper-modal.tsx + 测试
• packages/core/onboarding/store.ts:recordOnboardingRuntimeChoice / recordOnboardingRuntimeSkipped / bootstrapRuntimeOnboarding / bootstrapNoRuntimeOnboarding
• packages/core/api/client.ts:bootstrapOnboardingRuntime / bootstrapOnboardingNoRuntime / ensureOnboardingContent + Response interfaces + EMPTY consts
• packages/core/api/schemas.ts:两个 Bootstrap schemas + User schema 的两字段
• packages/core/types/workspace.ts:User 的两个新字段
• packages/views/locales/{en,zh-Hans}/onboarding.json:onboarding_helper_modal.* 和 workspace_init.* keys

改

• server/migrations/098_user_onboarding_runtime_choice.up.sql:反转为 DROP CONSTRAINT/COLUMN IF EXISTS(同名文件、保留 098 序号)
• server/migrations/098_user_onboarding_runtime_choice.down.sql:no-op + 注释说明不可逆
• server/pkg/db/queries/user.sql:PatchUserOnboarding 回退到只接 questionnaire
• server/internal/handler/onboarding.go:CompleteOnboarding 简化为直接 qtx.MarkUserOnboarded(无 service 包装)+ PatchOnboarding 只接 questionnaire
• server/internal/handler/invitation.go:AcceptInvitation 改回直接 qtx.MarkUserOnboarded(保留 mark 调用 — 注释强调 layout gate 依赖)
• server/internal/handler/workspace.go:CreateWorkspace 删 ClaimStarterContentStateIfUnset 调用(后端不再触碰 starter_content_state)
• server/internal/handler/auth.go:UserResponse / userToResponse 删两字段
• server/internal/handler/workspace_test.go:测试断言保留,注释更新引用 layout gate 而非 OnboardingHelperModal
• apps/web/app/[workspaceSlug]/layout.tsx:加 hard gate effect + 改挂 <WelcomeAfterOnboarding />
• apps/desktop/src/renderer/src/App.tsx:overlay 决策加规则 — !hasOnboarded 一律开 onboarding overlay 并先 setCurrentWorkspace(null,null)
• apps/desktop/src/renderer/src/components/workspace-route-layout.tsx:<WorkspaceOnboardingInit /> → <WelcomeAfterOnboarding />
• packages/core/onboarding/index.ts:精简 exports + 加 welcome-store exports
• packages/core/paths/resolve.ts:回到 onboarded-first 优先级
• packages/core/paths/resolve.test.ts:断言同步翻新
• packages/views/onboarding/onboarding-flow.tsx:handleRuntimeNext 改为 await completeOnboarding + welcomeStore.set + navigate
• apps/web/test/helpers.tsx:mockUser 删两字段
• packages/views/package.json exports:删 v2 两个 workspace 入口,加 ./workspace/welcome-after-onboarding

加

• packages/core/onboarding/welcome-store.ts + 测试:Zustand transient store
• packages/views/onboarding/templates/helper-instructions.ts:Helper agent 系统提示词,EN/ZH 各一份
• packages/views/onboarding/templates/install-runtime-issue.ts:Skip 路径第 1 条 issue 文案(从 server 的 EN/ZH 双语描述完整搬过来)
• packages/views/onboarding/templates/create-agent-guide-issue.ts:Skip 路径第 2 条新 issue 文案(EN/ZH)
• packages/views/onboarding/templates/index.ts:barrel + pickContentLang(language)
• packages/views/workspace/welcome-after-onboarding.tsx:替代 v2 两个组件的统一 Welcome 体验
• packages/views/workspace/welcome-after-onboarding.test.tsx:5 个测试覆盖 runtime / skip / 重名复用 / navigate / 渲染门
• packages/views/locales/{en,zh-Hans}/onboarding.json:新增 welcome_after_onboarding.{loading_helper,error_*,retry,dismiss_error,runtime.{title,subtitle,helper_description,cards.*},skip.{title,subtitle,open_issue,close,cards.*}}

7. 老用户兼容性

生产数据(数据分析师 read-only audit):

• users_with_workspace = 33,172
• 其中 onboarded_at IS NULL = 0

→ 没有 mid-flow 用户需要 backfill 或邮件通知。migration 098 反转 SQL 在生产里是 no-op(没有列要删,因为生产从未运行过 v2 的 add-column);在 dev 数据库上 IF EXISTS 保护让任何状态都能干净收敛到"无字段"。

老用户(onboarded_at != NULL)100% 安全:

• web layout hard gate if (user.onboarded_at == null) → 永不触发
• desktop App.tsx overlay 决策 !hasOnboarded && wsCount > 0 → 永不触发
• welcome-store 在 onboarding-flow.tsx Step 3 之外永不 set → Welcome Modal 永不弹

被邀请用户(invitee)的 AcceptInvitation 必须保留 qtx.MarkUserOnboarded — 注释里强调:"DO NOT REMOVE 否则 layout gate 把 invitee 踢回 /onboarding"。

8. 验收 — invariant + deprecation shim

每条可用 grep 或单元测试机械验证:

1. onboarded_at 的写入收敛到 3 个 handler:CompleteOnboarding(v3 主路径)、AcceptInvitation(invitee 必须)、BootstrapOnboarding*(shim,见 §10)。全部直接调 qtx.MarkUserOnboarded,无 service 包装。grep -rln "qtx.MarkUserOnboarded\|h.Queries.MarkUserOnboarded" server/internal/handler/ | grep -v _test.go
2. v3 前端永不调旧 bootstrap endpoint:grep -rn "bootstrapOnboardingRuntime\|bootstrapOnboardingNoRuntime\|ensureOnboardingContent" packages/ apps/ → 0 命中
3. v2 字段全删:grep -rn "onboarding_runtime_id\|onboarding_runtime_skipped" packages/ apps/ → 0 命中
4. Welcome Modal 不再自查环境:grep -rn "runtimeListOptions" packages/views/workspace/ → 0 命中
5. welcome-store 信号只来自 onboarding-flow,只被 welcome-after-onboarding 消费(grep -rln "useWelcomeStore" 应该只命中 4 个文件:store、welcome 组件、onboarding-flow、各自的测试)
6. 老用户登录 → 直接进工作区 → 不弹 Modal、无 loading veil(场景 4 手动验证)

10. Deprecation shim — BootstrapOnboarding*

为什么保留:v3 server 发布到 desktop auto-update 完成之间有 ~30 分钟真空期,期间老桌面会调旧 endpoint。删了 endpoint → 老桌面 404 → 新用户 onboarding 死循环。

位置:server/internal/handler/onboarding_shim.go(独立文件,所有 deprecated 代码都在这里;v3 主路径 onboarding.go 不含一行 shim 代码)。

约束:

• 简化版实现:handler 直接 qtx.MarkUserOnboarded + qtx.CreateAgent + qtx.CreateIssue + qtx.SetStarterContentState,不重新引入 OnboardingService / WorkspaceContentService 抽象层(那是 v2 的复杂度,已经死了)
• 文案常量完整保留(onboardingAssistantInstructions 94 行 markdown、enNoRuntimeIssueDescription 等),和前端 packages/views/onboarding/templates/ 双轨并行,这两份必须保持同步直到 shim 删除
• claimStarterContentStateIfUnset 局部 helper 也保留,因为老桌面靠这个字段抑制 legacy starter-content dialog
• 5 个回归测试(TestBootstrapOnboarding*)保留,保护 shim 行为不被无意改动

删除条件:X-Client-Version telemetry 确认无任何活跃 desktop 在调这俩 endpoint(典型窗口:2-3 个 release 后)。删的时候一并删:

• server/internal/handler/onboarding_shim.go 整文件
• server/cmd/server/router.go 里 2 条 deprecated 注释 + 路由
• server/internal/handler/onboarding_test.go 末尾 5 个 TestBootstrapOnboarding*

9. 未来工作

• starter_content_state 列(老桌面端兼容)— v3 后端不再触碰,但列保留(老桌面读 NULL → 渲染 legacy 导入 dialog)。可在 desktop 0.2.x 之前的版本全部 EOL 后单独 PR 删
• OnboardingCompletionPath 里的 cloud_waitlist enum 值实际无人发送 — 可清理
• apps/web/app/[workspaceSlug]/layout.test.tsx(新增)+ apps/desktop/src/renderer/src/App.test.tsx(新增用例)覆盖两端 hard gate 的 redirect 行为 — 当前由手动 E2E 覆盖