72 lines
6.8 KiB
Markdown
72 lines
6.8 KiB
Markdown
# s101 客户端迁移方案与评审
|
||
|
||
当前入口已更新为《客户端迁移详细修改方案.md》：KV接口缺失已由a3d3faa解决，开发批次、技术裁决和剩余行为确认以详细方案为准。下文保留早期调研记录。
|
||
|
||
日期：2026-09-15。状态：调研完成，契约待补齐；当前为评审草案，不是开发放行记录。
|
||
|
||
用户已确认：正式 API 基址为 http://s101.local:18080/。此前将 s101 当成 192.168.9.101 是错误推断；对旧 IP 的超时不能说明正式服务不可达。Hub 路由及认证字段仍需服务端契约确认。
|
||
|
||
正确地址实测：GET / 返回 HTTP 200、n3ftapi 0.0.1-nogit；GET /account/svrtime 返回 HTTP 200。GET /swagger/v1/swagger.json、/swagger/index.html、/openapi/v1.json、/api-docs 返回 HTTP 404。连通性已确认，完整接口契约仍未获取。
|
||
|
||
## 首批可独立实施范围（已请求确认）
|
||
- 修改 DebugConfig 的 s101EventAPIUrl 与 CustomServerMgr 的旧默认 API 地址为 http://s101.local:18080/。
|
||
- RTService.WithUrl 内明确指定 WebSockets-only 和 SkipNegotiation=true，保留 Cookie、gamehub 和已有事件/重连行为。
|
||
- 不推断静态资源、Func 服务、RTM 服务的新地址；这些地址不与 API 端口混用。
|
||
- 本批验证配置与 Unity 编译；认证后成功连接仍须登录链路可用才能验收。
|
||
- 首批技术自审：范围清晰，无存档格式变更，现有 .NET SignalR 客户端支持所需选项。裁决：技术方案可执行，等待用户确认；未以此宣称整个迁移方案评审通过。
|
||
|
||
## 目标
|
||
客户端适配服务器新接口，登录 s101 正式服务；移除 PlayFab SDK，保证游戏 KV 持久化；跳过 SignalR negotiate，连接自建服务并恢复业务消息。
|
||
|
||
## 已核实事实
|
||
- UserService.Login 先登录 PlayFab，调用 async void LoginApiServer 后直接返回 Done；业务登录失败不会阻止这个成功返回。
|
||
- account/Login 当前发送 playerId/playerProfile，期望 state/internalId；尚未取得服务器新契约，不推断这些字段仍然有效。
|
||
- PlayFabMgr 使用 PlayFab UserDataRecord 和 UpdateUserData；同步失败只记日志，未确认成功就已轮换队列。
|
||
- SignalRService 使用 API 基址拼 gamehub，携带 Cookie，自动重连，没有 SkipNegotiation/WebSockets-only 配置。
|
||
- SDK 直接依赖还包含好友、排行榜、公告、玩家资料；IUserService 暴露 EntityKey。仅删除 package 会破坏编译及相关功能。
|
||
- 当前日志中 5292 与 18080 均有登录请求取消记录；本次对两端口的 Swagger 地址做只读连接探测，均超时，未收到 HTTP 响应。
|
||
- 当前工作区及抽查的相邻项目未找到本任务服务端契约。不能把端口超时直接归因于请求字段错误。
|
||
|
||
## 路线比较
|
||
| 路线 | 优点 | 问题 | 建议 |
|
||
| --- | --- | --- | --- |
|
||
| 按契约建立业务模型及服务适配，逐步替换，最后删除 SDK | 可保留存档和游戏能力，测试边界清晰 | 要覆盖 SDK 的外围功能 | 推荐 |
|
||
| 先删 SDK，再逐个修复编译错误 | 依赖暴露直接 | 无法保证行为和存档语义，缺少替代接口时无法交付 | 不采用 |
|
||
| 保留 SDK，仅改变 URL 或增加同名兼容 API | 初期修改较少 | 不能证明移除了 SDK，容易继续依赖旧协议 | 不作为最终方案 |
|
||
|
||
## 设计
|
||
### 登录与会话
|
||
以服务端明确的账号凭据、稳定玩家 ID、会话及资料响应为唯一契约。保留渠道 SDK 入口，移除 PlayFab 登录步骤。登录协调过程必须等待身份认证、业务授权和必要 KV 初始化完成才返回 Done。拒绝、超时、无效数据分别返回可重试或明确失败。登出/换号清理会话、实时连接及用户缓存；重登应合并并发请求，避免 401 触发循环。
|
||
|
||
### KV
|
||
将存档记录改为游戏自有模型，远端读写集中在适配层。优先保留现有业务调用入口、Unity 序列化引用和 key，避免迁移时无关的大规模重命名。现有账号与新身份的映射必须由服务端确认，防止旧存档读成新账号空存档。
|
||
|
||
队列写入使用稳定快照，成功后仅确认对应批次；失败保留待写项，新修改不能被旧批次重试覆盖。时间戳单位、版本控制、批次大小、可见性与跨玩家读取根据服务器契约实现。空远端数据和请求失败必须区分，禁止用默认空数据覆盖已有存档。
|
||
|
||
### SignalR
|
||
使用正式 Hub 地址、SkipNegotiation=true 和 WebSockets-only；凭据跟随服务端 Cookie 或 Token 机制，不猜测认证方式。保留既有事件名和调用语义。建立连接、断线恢复和会话更新分别验收。跳过的是 HTTP 协商，不删除 SignalR 协议握手。
|
||
|
||
依据：https://learn.microsoft.com/en-us/aspnet/core/signalr/configuration?view=aspnetcore-10.0
|
||
|
||
### SDK 清理
|
||
梳理并替换好友、排行榜、公告、玩家资料和对战匹配的 SDK 调用/类型。EventFishingDuelPanel 还调用 PlayFabMultiplayerAPI 创建/查询/取消匹配票据、查询匹配结果；这部分不能漏删或静默禁用。若服务器尚无替代能力，将其列为契约缺口，不用空结果或静默禁用掩盖。最后移除两个包及本地 SDK，清理 asmdef GUID、裁剪引用和热更新构建输入；生成项目文件及构建产物由 Unity 生成，不手工改旧 DLL。
|
||
|
||
## 开发边界
|
||
允许范围：登录、会话、KV 及其直接业务适配、SignalR、必要配置与 SDK/构建依赖、相应测试。
|
||
不包含：服务器部署或修改、生产存档迁移、付费行为、无关玩法重构、修改真实玩家数据。联调使用专用账号，日志不记录密码、Token、Cookie 或完整存档。
|
||
|
||
## 验证
|
||
测试清单见 TODO.md。通过标准必须同时覆盖编译、契约测试和 s101 真实联调；静态配置正确不能替代登录/持久化/实时消息成功。KV 重登读取需排除本地缓存影响。运行证据必须记录目标地址、部署版本、客户端提交及结果，并脱敏。
|
||
|
||
## 评审裁决
|
||
| 项目 | 裁决 | 理由/开发边界 |
|
||
| --- | --- | --- |
|
||
| 总体迁移路线 | 建议采用，待书面确认 | 按契约逐步替换，最后清 SDK |
|
||
| 登录方案 | 暂不放行 | 缺新认证请求、响应、身份映射及会话定义 |
|
||
| KV 方案 | 暂不放行 | 缺读写路由、版本/时间戳规则和旧存档兼容定义 |
|
||
| SignalR 配置方向 | 技术依据充分；实施待方案确认 | WebSockets-only + SkipNegotiation；真实认证和地址仍需核实 |
|
||
| SDK 删除 | 暂不放行 | 需明确外围能力替代方式并先完成调用迁移 |
|
||
| 当前允许工作 | 调研、契约盘点、TODO 与文档 | 不依据未知契约编写生产代码 |
|
||
|
||
自审：已明确事实与未知项、失败语义、数据保护、实施顺序和验收边界。此草案不冒充完整评审；获取契约后补全具体接口映射并更新裁决。
|