《同福客栈》登录流程技术文档

1. 目标

把现有 登录流程梳理 压成一条可直接接线的技术实现文档，只覆盖 29 号版本真正可执行的最小闭环：

• 页面刷新后统一进入 掌柜府第
• 玩家显式选择 继续 / 重玩 / 换档 / 切账本
• 支持多账本与 slot 选择
• 保持现有 GlobalProfile / playthrough 存储边界

这不是整套账号系统大版本，也不是成就墙、多周目高级词条或账号商店需求。

2. 范围边界

• 只处理启动流、主菜单流、账本选择流、slot 选择流和继续/重玩/换档确认流。
• 只整理最小数据契约、组件边界、运行时状态流和验收口径。
• 不修改 SAVE_SCHEMA_VERSION。
• 不把成就墙、传承商店、账号高级养成、多周目词条、联机同步带进本轮。
• 不在本轮定义新的视觉大改版，只承认 掌柜府第 作为登录主菜单壳。

3. 运行时主流程

3.1 启动分流

1. 页面 mount / 刷新
2. 读取账号索引与当前激活账本
3. 按账号存在性分流：
   • 无账本：进入 新手落籍
   • 有账本：进入 落籍选档
4. 统一进入 掌柜府第
5. 玩家显式选择动作后，才进入主游戏

3.2 主菜单闭环

掌柜府第 只承认以下动作：

• 继续上次的周目
• 重开新周目
• 选历史存档
• 切换账本
• 新建账本

其中 继续上次的周目 不允许静默进游戏，必须先过一次 继续 / 重玩 / 换档 确认弹层。

3.3 slot 与周目行为

• 开新周目：玩家手动挑 slot，不自动分配
• recent slot 丢失：继续 按钮置灰，不伪造恢复入口
• 3 个 slot 全满：先提示归档或清理，再允许开新周目
• FirstRunGuide：只在新周目第一帧触发；续档、换档、切账本不触发

4. 数据契约

4.1 账号索引层

新增账号索引概念，作为多账本入口层：

• key: tongfu_account_index_v1
• 用途：
  • 维护账本列表
  • 维护当前激活 profileId
  • 维护每个账本的 recentActiveSlot

最小字段：

• schemaVersion
• updatedAt
• activeProfileId
• profiles[]

每个 profiles[] 条目至少包含：

• profileId
• accountName
• createdAt
• updatedAt
• recentActiveSlot
• legacyPoints

4.2 账本存储层

每账本一份 GlobalProfile：

• key: tongfu_global_profile_{profileId}_v1

现有单份 GlobalProfile 的实现边界需要被重构为：

• 启动先读账号索引
• 再按 activeProfileId 读取目标 GlobalProfile

4.3 周目 / slot 边界

本轮不改 slot 数据结构，只要求补最小桥接能力：

• archiveSlot(slotId)
• resetSlot(slotId)
• recentActiveSlot 与当前激活账本保持同步

现有 playthroughSlots / playthroughRuntimeBridge 继续负责：

• slot 摘要
• recent slot 引用
• 运行态到 slot 的同步

GlobalProfile 仍然不直接保存单局运行态。

5. 组件边界

本轮主流程接线只承认以下组件边界：

• <WelcomeGate>

  • 顶层入口分流
  • 决定渲染落籍页 / 账本选择页 / 掌柜府第 / 主游戏

• <NewAccountScreen>

  • 新手建账本入口

• <AccountPickerScreen>

  • 多账本选择页

• <InnKeeperHall>

  • 登录主菜单壳
  • 承载 继续 / 重开 / 换档 / 切账本 / 新建账本

• <ResumeConfirmModal>

  • 继续 / 重玩 / 换档 强制确认

• <SlotPickerModal>

  • 开新周目时玩家手动挑 slot

• <SlotCard>

  • 承载 slot 摘要与空槽 / 活跃 / 归档状态

• <AccountExportDialog>

  • 删除账本前导出

6. 最小实现顺序

1. 扩 accountProfileStorage，补账号索引与按 profileId 读写能力
2. 建 WelcomeGate 顶层分流
3. 建 InnKeeperHall 主菜单流
4. 建 ResumeConfirmModal
5. 建 SlotPickerModal
6. 把 recentActiveSlot 与激活账本同步接回现有运行时桥

本轮 29 号只要求能形成一条可派发 lane，不要求整包实现全部组件。

7. 验收口径

满足以下条件即可视为这条 lane 完成：

1. 刷新后统一进入 掌柜府第，不存在静默续档
2. 继续上次的周目 先过显式确认，不直接进游戏
3. 重开新周目 需要玩家手动选择 slot
4. 多账本切换与当前激活账本概念清楚
5. recent slot 丢失、slot 满、隐私模式等边界有明确降级策略
6. 不破坏现有 GlobalProfile / playthrough 存储边界

8. 明确不做什么

• 不扩整套账号系统
• 不接成就墙
• 不接传承商店
• 不接高级多周目词条
• 不重做账号视觉系统
• 不改无关主游戏业务逻辑
• 不把这条 lane 并入 胜利结束收尾

9. 建议派发方式

建议 PM 把这条线作为 29 的一条独立接线 task 派给短工：

• lane 名：登录流程接线与主菜单进入闭环
• worker 身份：[短工]#登录流程接线@v1.0

推荐文件边界：

• src/components/welcome/**
• src/utils/accountProfileStorage.ts
• src/utils/playthroughSlots.ts
• src/utils/playthroughRuntimeBridge.ts
• 必要时最小触达 src/App.tsx