ft/CodexOutput/upserver/服务端契约核查.md

服务端契约核查

更新说明：2026-09-15 已复核新增提交 a3d3faa，KV 的 Get/Set/Delete 已实现。本文旧“未找到KV”记录仅描述 696fc8c 基线；最新结论见《KV更新复核.md》。

日期：2026-09-15。源码：C:/projects/N3-Server-CN，main，696fc8c（2026-09-09）；工作区干净。本记录基于本地检出，不推断它与 s101 已部署版本完全一致。

已确认

用户补充裁决：移除 PlayFabId 作为玩家身份，采用数字涂游 ID（tuyou-id）。来源为涂游 SDK LoginInfo.userId / StrUserId，已有登录态可从 TYSdkFacade.TYAccountInfo.userId 获取。客户端 UserId 与 account/Login.playerId 使用该 ID 的十进制字符串；不进行 hex 转换，也不在缺失 ID 时回退 PlayFab ID。

保留服务端现有 JSON 字段名 playerId；部分历史 DTO 的 PlayFabId/FriendPlayFabId 字段名不等于仍依赖 PlayFab 身份，按现有服务端契约传入涂游 ID。整体字段改名需双方同步，不在客户端单边修改。

能力	源码契约	客户端适配结论
登录	POST /account/Login；playerId 必填，playerProfile 可选	保留路由，改用渠道 SDK 十进制 ID，不再发送 PlayFab hex ID
身份	PlayerIdUtil.Parse 使用 long.Parse，拒绝负数	ID 作为十进制字符串传输；不能将旧 hex 解析转十进制冒充渠道身份
登录响应	state、InternalId、CreateTime、svrTime、newCreate；默认 MVC JSON 命名策略	用专用 DTO 接收，等待成功后更新身份/时间并触发登录成功；不能 HTTP 200 即判成功
会话	state=Success 才 SignInAsync，Cookie NameIdentifier=request.playerId	复用 HttpClient CookieContainer 给 SignalR
实时	MapHub(/gamehub).RequireAuthorization()	目标为 http://s101.local:18080/gamehub；已改的 WebSockets-only/SkipNegotiation 与 Cookie 配置方向正确
好友	POST /friend/GetFriendsList，用户 ID 取 Cookie claim	可替换客户端 PlayFab GetFriendsList；后续核对具体响应映射
KV	当前 API/BLL/AdminAPI/docs 未找到通用 UserData/KV 读写端点	尚不能实现 PlayFabMgr 的远端替换；需要确认其他分支、最新版本或独立服务

证据

• LeaderboardAPI/Controllers/AccountApi.cs：登录路由、签发 Cookie、失败仍可返回 HTTP 200。
• LeaderboardBLL/Models/AccountModel.cs：请求和响应字段。
• LeaderboardBLL/Services/PlayerInfo/AccountService.cs：登录更新 DBPlayer 并返回内部 ID；响应不包含游戏 KV 全量数据。
• LeaderboardBLL/Utils/PlayerIdUtil.cs：long 十进制解析。
• LeaderboardAPI/Program.cs：Cookie 配置、默认 AddControllers、/gamehub 授权路由。
• LeaderboardAPI/Controllers/FriendApi.cs：GetFriendsList。
• LeaderboardAPI.IntegrationTests/TestInfrastructure.cs：真实登录拿 Cookie，WebSockets 连接 /gamehub；本地版本设置 WebSockets，未设置 SkipNegotiation。
• docs/notes/aliyun-migration/03-playfab-removal.md：渠道 bigint 身份、全新区服不迁移旧 PlayFab 数据、部分 DTO 保留 PlayFabId 字段名。

对既有方案的修正

1. s101 主机名与旧 IP 是不同目标；正式地址已由用户确认并实测可达。
2. /gamehub 路由与 Cookie 鉴权已从源码确认，不再列为未知。
3. 新身份来自渠道 SDK；客户端 AggUserService 已将 loginInfo.StrUserId 存入 CustomId，可作为后续登录适配入口。编辑器身份规则需在登录实施方案中明确。
4. 服务端迁移文档描述全新区服不做存量迁移；不自行从旧账号缓存向新身份上传存档，待确认当前任务是否沿用该决策。
5. KV 契约仍是独立缺口。移除 SDK 还涉及其他直调能力，不能仅替换登录和包引用。

当前裁决

SignalR 子集：实现已完成，源码契约核查通过，仍待 Unity 编译及认证后直连实测。 登录/KV 全量迁移：继续完善具体方案；KV 未找到，不能以猜测端点开始实现。 本次未修改服务端、未创建正式玩家、未写入远端存档。