服务端云存档的迁移

1. clientCloud 与 serverCloud 是两套独立存储这是整个迁移过程中代价最大的一个坑。旧版单机架构使用 clientCloud（客户端云存储）保存玩家进度，迁移到服务端权威架构后改用 serverCloud。我们最初以为切换 API 就行了，结果发现：serverCloud 根本读不到 clientCloud 里的数据——它们是完全独立的存储空间，key 相同也不互通。上线后玩家登录直接变成新档，之前几十小时的进度"消失"了。教训：切换存储后端时，必须设计数据迁移层。我们最终的方案是双层迁移：

所有对 UIMain 的引用改为 getUIMain().Build()，保证实际调用时模块已完成初始化。

3. 存档格式的历史包袱——三种 key 格式并存SaveManager.lua 在迭代过程中用过三种存储 key 格式：

4. Manager 层的耦合设计增加迁移难度旧的 Manager（如 BuildingManager、TechManager）内部直接调用 SaveManager.Save() 做持久化。迁移到服务端架构后，持久化应该由 Server 统一管控。需要把所有 Manager 改为无副作用的纯逻辑计算：只修改传入的 game state，不主动触发存档。这涉及到对 13 个 Manager 文件的逐一审查和修改。

5. 远程事件的序列化限制UrhoX 的远程事件通过 VariantMap 传递数据，value 类型有限（String、Int、Bool 等），不能直接传 Lua table。所有游戏状态和操作参数都需要手动用 cjson.encode/decode 序列化为 JSON 字符串。同时需要注意单次传输的数据量限制，全量状态同步（STATE_SYNC）在游戏后期数据量较大时需要关注。

6. LSP 对引擎全局变量的误报IsServerMode、serverCloud、clientCloud、SERVER_MAX_PLAYERS 等是引擎在运行时注入的全局变量，LSP 无法感知它们的存在，会产生大量 undefined-global 警告。需要在文件头部用 ---@diagnostic disable-next-line: undefined-global 或 ---@type 注解手动声明。