youle_cocos/docs/superpowers/specs/2026-09-05-local-platform-login-design.md

本地真实启动、加载与登录联调设计

日期：2026-09-05。代码基线：master@66246c8。 状态：用户已确认本文及第8节九项资源写入清单（2026-09-05）；启动、加载和两次真实登录已验收通过，详见 ../reports/2026-09-05-local-platform-login-acceptance.md。下文“已核实的基础”为设计时记录。

1. 本批交付

在 Creator 浏览器预览中运行独立 LocalPlatformLogin 场景，使用现有 PlatformRuntime、PlatformUiController、WireClient 和已合并的 local 配置/账号来源，连接本地真实 gateway，验证启动、加载、点击游客登录和登录结果显示。

本批不修改生产 GameEntry 契约，不选择真实子游戏，不接其他业务 RPC，不替换现有 Login/Launch/MainMenu 场景，不复做 3A。登录成功页为本批结果页，不宣称平台大厅功能验收。

服务器、远程配置服务、settings/WVJB 契约零改动。默认 prod、BUILD_IDENTITY 及原生配置优先级保持不变。

2. 已核实的基础

• MCP：Creator 3.8.8，工程 G:/Works/YouleGamesCocosCreator/cocoscreator_projects/YouleNexus；当前 Login 场景 Canvas/LoginFlow_Node 挂旧 LoginFlow。
• MCP：Login_Layer.prefab UUID b209cefb-b381-4c7c-b765-94a5ab75a89c；Layer614_Loading.prefab UUID 4db0114a-f751-4931-bfaf-4fef31430583，均 imported=true、invalid=false。此状态不替代运行时依赖验证。
• 登录节点相对根路径 group-2/游客登录，只有 UITransform/Sprite/Widget；group-2/版本显示 为 Label。加载节点 group-40/载入动画 只有 UITransform/Sprite/Widget，没有 Animation。
• gateway 程序 G:/Works/JinXianProjects/gateway/game-gateway.exe，3088 仍监听。
• 已查阅 server_agent/rpc.js 的 player_login：缺 openid/unionid 或昵称头像同时为空会直接忽略；请求 version 与身份作用域的 game_version 比较。server_platform/class.config.js 从配置 URL 周期读取并按全局、agent、game、channel、market 取值。这些源码不能证明运行进程当前缓存或数据库内容。
• 目前无本轮登录成功证据。请求 version 保持现有来源值；不得试填历史 10000 或把历史回包 gameversion=41 当成当前值。
• 当前主 checkout 有 46 个未跟踪 meta 和 2 个已跟踪 meta 删除项，比上轮合并验收新增 5 项 local 来源 meta。本批保留全部 48 项，开始实施时重新记录路径、状态和哈希。

依据：仓库 AGENTS.md、既有 startup-config-account 设计及完成计划、platform-ui-wiring 设计及已完成计划、zero-coupling 迁移设计、docs/protocol/01、02 登录章节、04 登录数据结构，以及 native-bridge-contract/cocos-mcp 技能。

3. 结构与所有权

新增代码限于 assets/scripts/local-platform-login/，由独立场景引用，禁止生产启动场景或 SDK 导入。入口在构建 DEBUG 且非 native 的浏览器预览中才允许运行；失败必须发生在连接和账号写入前。

六个职责文件：

• LocalPlatformLogin.ts：唯一 Cocos 组件入口，持有序列化 Prefab/Node 引用，读取宿主输入，创建资源与帧端口，注册/释放本批观察钩子。
• local-login-host.ts：纯 TS 应用组合，创建唯一 Controller 与 Runtime，持有一次 local 配置解析结果，协调账号准备与登录操作；不增加 Store/Router/启动状态机。
• local-login-view.ts：Cocos PlatformViewPort、FrameScheduler 和实例绑定；投影既有 PageModel/OverlayModel，不拼登录包、不修改 Store。
• local-login-transport.ts：严格浏览器 WebSocket Transport，注入构造器和错误报告端口，处理连接生命周期。
• local-login-wire.ts：开发用途的 WireClient 范围包装与证据观察；只限制本批范围，不改协议内容。
• local-login-game-entry.ts：显式诊断夹具及其生命周期记录，不包含任何真实子游戏实现。

500ms 最短展示时长只在组件入口定义一次，作为必需参数传入宿主。Prefab 引用只由场景序列化属性提供；不在加载失败时按另一地址或 UUID 重试。文中 UUID 是审阅证据，不在多个运行模块重复定义。

4. 从启动到登录

1. Cocos 导入独立场景，场景直接依赖 Loading Prefab，加载实例与文字状态在启动前已可用；Login Prefab 通过序列化引用声明依赖。
2. 入口验证 DEBUG/browser、宿主参数和序列化引用。宿主以构建值 mode=debug、hostKind=h5 和浏览器实际 query 调用 resolveLocalStartup；URL 必须显式提供 profile=local，不拼接隐藏默认 query。版本/渠道覆盖沿现有 query 来源传入。
3. 唯一配置 Promise 同时服务诊断 GameEntry.gameId、账号来源和 Runtime 的 resolveRuntimeConfig 端口。gameId 引用解析后的有效身份，Runtime 的严格相等校验保留；不复制 BUILD token。
4. Controller 连接 Runtime 后执行 start；loading 由 Controller/ScenePort 驱动。资源端口检查 Prefab 及依赖、实例化 Login_Layer、检查绑定节点和组件、注册事件并完成一个真实渲染帧。失败拒绝资源门，不用空 Promise/计时器冒充加载。
5. Loading 首次实际绘制完成时记录单调时间；minimum-display 端口等待从该帧起满 500ms。资源完成与最短时长互相独立。FrameScheduler 使用 Cocos 帧事件，取消函数确实移除监听。
6. 配置、资源、socket、minimum-display 四门齐备，Controller 才激活登录页；start() Promise 完成不能代替 socket 已打开或 ready=true。
7. 用户点击游客节点：先将本次操作置为忙碌并禁止重复触发；await sources.prepareLogin()，随后 controller.login(account)。isSessionActive 使用已登录状态及本次登录待响应标志，保证活动操作不能重建账号。
8. getLoginDeviceSnapshot 返回同次 prepare 的结果；既有 buildLoginRequest 构造信封，WireClient 发送。无账号/设备默认值，无额外登录出口。
9. 原始回包经现有 codec/router/session 更新唯一 Store；Controller 的 lobby PageModel 显示本次登录结果。界面玩家 ID、昵称、豆豆来自 PageModel，不直接拿请求或 raw 回包填 UI。

配置解析期间加载外观由已存在的 scene shell 保持可见；Runtime 接管后由 Controller 管理显示，不把 shell 当成第二个业务启动状态机。若解析失败，在同一 shell 显示错误且不创建 Runtime/socket。

5. 诊断 GameEntry 的严格边界

诊断 key/route 采用明确的 local-platform-login 标识，route 不属于 platform/agent/room；从不作为出站协议 route。该夹具只存在于上述开发目录，普通启动与 SDK 无引用。

GameSessionHost 构造时 assertGameEntry 会调用一次 createModule 并 dispose，所以工厂不能直接抛错。每次 createModule 返回具有实例编号和 created/disposed 状态的诊断对象；dispose 改变状态并记录释放，支持安全重复释放。attach、handlePlatformEvent、handleGameMessage、restore 与 resolveSeatCount 均记录越界并抛出包含操作名的错误，不提供座位数、房间规则或空处理结果。

正常启动验收要求仅有校验所需的创建/释放，零 attach/restore/游戏消息调用。夹具不是原生能力或子游戏验收替代物，也不是生产失败兜底。

为避免登录恢复先写入房间 Store，wire 范围包装在向 Runtime 交付 player_login 前复用既有 parseLoginResponse 检查结果；合法成功响应含 room 时记录并终止本次验证，原包不删字段、不改 roomcode、不自动换号或退房。其他解析错误按原错误终止。纯解析复用不形成第二份状态来源。

6. 连接、协议与错误

每次 Transport.connect（包括重连）都调用 assertLocalConnectionTarget，地址必须来自唯一 local 配置。发送时检查 socket OPEN；非字符串入站帧明确报错，不 String(object) 或替换空串；事件按 socket 实例隔离，旧连接回调不得污染新连接。error/close 去重，显式 stop 不产生后续重连。关闭失败保留原因。连接构造/地址校验错误必须先经注入错误端口记录并终止本批，再抛出；不能只依赖 WireClient 的 connect 异常重连分支，否则原错误会丢失。

WireClient 保持握手忽略、服务器单向心跳、现有超时与重连规则。出站业务信封本批只允许 agent/player_login；拒绝后不调用真实 send。所有切服请求及房间/子游戏消息触发范围终止，不向新地址连接。其他 agent/platform 推送保留观察记录，按既有处理链交付；不新增 RPC handler 或主动查询。

范围包装终止时先注销 Runtime 订阅并关闭 Wire，再由宿主停止 Runtime 与 Controller 更新；不得在 Wire 事件栈里重入出站请求。终止通知单次生效，首个错误与清理错误均保留。UI 最后显示明确失败；不会将断线、kick、非零 state 或资源错误转换成登录成功。

登录拒绝与 kick 保留原始服务器原因，终止该次验证。未收到响应时保留 Runtime 既有重连行为，由验收操作者通过停止按钮终止观察；本批不改协议时间常量，不自动提高 version 重试。

7. 场景与 UI

新场景 assets/scenes/LocalPlatformLogin.scene，设计分辨率沿主工程 1600×720，含 Canvas、相应 Camera、Host、LoadingRoot、LoginRoot、ResultRoot、StatusOverlay 与 StopButton。Host 只挂新 LocalPlatformLogin，不挂 LoginFlow/LaunchFlow/SceneStart/RoomEventProbe。

LoadingRoot 使用 Layer614_Loading 链接实例，并由运行时对 group-40/载入动画 做持续旋转；不新增 .anim。LoginRoot 由资源端口实例化 Login_Layer。

运行时对游客登录节点注册 TOUCH_END，检查节点和 Sprite/UITransform；只绑定一次，销毁时解绑。不为当前没有的 Button 组件设置假绑定。微信/手机/QQ/快速登录等非本批入口在运行实例上隐藏，登录中遮罩与输入忙碌状态同步；源 prefab 不保存修改。版本 Label 显示有效 config.identity.version。

ResultRoot 为开发结果页，显示“登录成功”及玩家 ID/昵称/豆豆，不呈现未实现的大厅操作。avatar 值保留于 PageModel 证据，本批不下载外部头像。StatusOverlay 显示加载阶段、失败原因与停止状态；停止按钮仅关闭本次连接与监听，不清账号缓存。不得启动旧 MainMenu。

8. 精确资源写入申请

下列路径均相对 cocoscreator_projects/YouleNexus/。这是待授权的有限清单；认可本文之前不操作资源。

新建的序列化资源共九个：

1. assets/scenes/LocalPlatformLogin.scene
2. assets/scenes/LocalPlatformLogin.scene.meta
3. assets/scripts/local-platform-login.meta
4. assets/scripts/local-platform-login/LocalPlatformLogin.ts.meta
5. assets/scripts/local-platform-login/local-login-host.ts.meta
6. assets/scripts/local-platform-login/local-login-view.ts.meta
7. assets/scripts/local-platform-login/local-login-transport.ts.meta
8. assets/scripts/local-platform-login/local-login-wire.ts.meta
9. assets/scripts/local-platform-login/local-login-game-entry.ts.meta

上述 scene 通过 funplay MCP 创建、绑定、保存；所有 meta 由 Creator 生成，绝不手改。既有 Login_Layer.prefab、widgets/Layer614_Loading.prefab 及其 meta 只读复用；现有场景、prefab、anim、meta 不修改、不删除、不提交。

若 Creator 自动导入生成清单以外的 meta，保留并报告，不能混入提交。若引用依赖非法或 MCP 不能持久保存脚本绑定，停止受影响资源步骤并说明具体原因，不以序列化文本编辑绕过。

9. 主 checkout 分支与编辑器路径

用户于2026-09-05明确改为主 checkout 上使用 Git 分支，覆盖此前 worktree 约定。实施路径固定为 G:/Works/YouleGamesCocosCreator，分支 codex/local-platform-login；Creator 工程固定为该目录下 cocoscreator_projects/YouleNexus，无需来回切换工程。

迁移时旧 worktree 无代码改动，任务记录已复制并校验哈希；临时 worktree 已清理，分支保留。仍先完成纯 TS TDD/审查，再进行已授权的编辑器资源操作。

开始资源操作前，通过 MCP get_project_info 核实上述固定 projectPath，并确认未保存内容；不自动保存或丢弃未知场景。主 checkout 原有48项 meta 状态以及后来新增的 scene-2d.scene/scene-2d.scene.meta，共50项文件状态和内容均纳入保护基线。只精确暂存本批文件，不使用 git add . 或自动 stash。

新增资源仍只能由 MCP/Creator 写入，范围严格遵循第8节。Creator 自动生成的清单外 meta 保留并报告，不混入提交。Git 切分支不能视为未提交文件隔离，必须在提交和合并前复核保护基线。

预览仅启动新场景，并明确携带 profile=local；不把默认启动场景或默认 profile 改成本地。不额外更改构建配置，也不发布包含诊断入口的正式包。

10. 真实服务证据

验收前只读核实 gateway 监听、实际服务路由及身份来源；沿现有源码/本地配置定位实际运行服务，不把同目录另一套源码当成已部署版本。日志不得输出认证密钥。

首个真实请求使用现有 BUILD + 明确 query 解析结果，记录其来源及 version 类型。请求本身是验证服务器是否接受这些值的证据，不能提前标记“已匹配”。服务器拒绝后沿对应配置/数据库只读追溯；没有证据不猜版本或渠道，不改服务。

运行证据分为：时间顺序与四门状态；发送/接收信封；Store 与 PageModel 摘要；Creator 截图。Transport 在 codec 之前记录握手、收发帧和时间，避免忽略握手后失去观测证据；观察端口不得修改或重新发送信封。原始数据仅用于本地诊断，分享和提交的记录掩去 openid/unionid/machineid 等账号设备标识及敏感内容，保留字段类型、state、范围结论和证据对应关系。记录不充当新的运行配置或账号来源。

11. 验收标准

• 纯 TS：非法环境/远程地址零连接；资源失败/慢 socket/500ms 未满时无登录；重复点击只发一次；准备失败不发送；实际配置只解析一次。
• 诊断：启动校验创建与释放完整；所有游戏操作失败；房间恢复回包在进入 Runtime 前终止且不删原包；非登录出站零发送。
• Transport：OPEN 前 send 失败；非文本失败；旧 socket 回调隔离；error/close 不重复通知；stop 后无新连接；每次连接目标受检查。
• 联合：真实 Runtime/Controller/WireClient/来源模块与可控 Transport 测试通过；这不替代引擎验收。
• Creator：依赖和绑定有效；加载图真实显示并旋转，至少500ms；四门齐备后游客入口可用；点击后有可见忙碌反馈；无旧网络栈实例。
• 真实登录：记录 local URL、握手/连接证据、agent/player_login 请求和 state=0 响应；Store logged-in 且 room outside；结果页玩家 ID/昵称/豆豆与 PageModel/服务器语义一致；第二次独立预览复用账号与机器并成功登录。
• 停止：销毁/停止清除事件、帧订阅和 socket；不得重连或继续渲染；预览无新增异常。
• 回归：显式枚举 framework-tests/**/*.test.ts，指定 import-boundaries.test.mjs 与 presentation-boundaries.test.mjs，类型/导入检查和 git diff --check；禁止旧生成器入口。
• 每项实施使用 subagent-driven-development，TDD、规格和质量审查；最后整分支审查。现有主工程变更保留，资源 diff 只包含授权清单。

任何真实服务器、绑定或 UI 验收失败都表示本批未通过；不得转入其他 RPC。完整通过后才讨论下一批非房间平台 RPC。