136 lines
15 KiB
Markdown
136 lines
15 KiB
Markdown
# 本地真实启动、加载与登录联调设计
|
||
|
||
日期：2026-09-05。代码基线：master@66246c8。
|
||
状态：用户已认可独立联调场景与诊断 GameEntry 方向；本文待书面审阅，资源写入清单尚待明确授权。
|
||
|
||
## 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. 隔离工作区与编辑器切换
|
||
|
||
实施创建新 codex/local-platform-login 分支和 .worktrees/local-platform-login，基于包含本设计与后续计划的 master；不重建已清理的旧 worktree。先完成纯 TS TDD/审查再进入编辑器阶段。
|
||
|
||
Creator 资源操作只能对新 worktree 的 YouleNexus 执行。切换前记录主工程原有 48 项变更哈希，并确认当前编辑器是否存在未保存场景；不得自动保存或丢弃未知改动。将已授权且已验证的当前项目配置用于隔离工程时，不复制认证密钥，不共享 assets/library/temp。
|
||
|
||
切换后必须通过 MCP get_project_info 证明 projectPath 精确为隔离路径；MCP 仍指向主 checkout 时不执行任何写入或预览。编辑器切换若无可用授权工具，由用户打开明确路径，不能用主工程测试隔离代码。依赖 node_modules 可复用，Creator 缓存由自身生成。
|
||
|
||
预览仅启动新场景，并明确携带 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。
|