ft/CodexOutput/upserver/B3BatchMigration/M2/M2-PlayFab移植修改清单-分模块-2026-09-30.md

# M2 PlayFab→KV 移植修改清单（分模块）

日期：2026-09-30。编制：原 ZCode（审查侧），基于已完成的全部核验（合批正式前审 2165/2165、C2d 交付 113 项中 112 一致、防跑偏十项源码实证、C3c 审查 R1 13/13）。范围：当前工作树 `Client/Assets/Scripts` 全部迁移改动＝**111 个修改文件 + 14 个新增文件（含 meta）**。每项均标注性质：〔平移〕=提供方/身份/接线替换；〔原样〕=经 C2d 核减后与原行为一致（含登记未修的旧缺陷）；〔待接线〕=依赖 C3c 服务端四问，未动或不可放行。

## A. KV 存储基础设施（新增模块，`Services/PlayerData/`）

| 文件（新增） | 内容 |
|---|---|
| `PlayerKVClient/CacheStore/SyncState/SyncCoordinator/LoginContext/GameSessionBridge/GameLoadCoordinator/GameLoadGuard/GameLoadTransaction/GameplayBindings/SaveSchema/LoginPrepareResult/DecodedSave/KeyRead* 等系列` | 早期阶段建立：HTTP 协议、KV 缓存、3A 同步状态机、3B 串行同步、登录上下文（epoch/租约/三 handler）、会话桥、加载编排（Prepare/Decode/Apply）、加载 Guard、31 模块事务、严格解码器。本合批内 `GameplayBindings` 改窄接口 `IKVUserLoadReceiver`、`GameLoadCoordinator` 成功结果携带 `PlayerKVAccountDescriptor` |
| `PlayerKVRuntimeSelection.cs`（新） | 启动一次捕获 SaveBackend→提供方选择；固定正式 URL、AGG 拒绝、101/102 准入 |
| `IPlayerSaveStore.cs` + `PlayerSaveStores.cs`（本合批新增） | 共用存档契约与 KV/PF 双实现：Read 三态、Write 接受语义、WriteAndConfirmAsync、40 秒单调度者、固定会话绑定〔平移〕 |
| `IKVUserLoadReceiver.cs` / `IKVUserLifecycle.cs`（本合批新增） | 31 模块接收窄契约（消费者=Bind）；生命周期观察窄契约（消费者=PFLoginAct/QuitAct） |
| `PlayerKVEditorValidationHost.cs` | 受控验证宿主（离线全链验证入口，不改业务） |

## B. 核心管理器（`Core/`）

- `KVMgr.cs`（新增）：四个静态入口 ReadKV/WriteKV/FlushKVAsync/WaitForKVTicketAsync，Guard 检查后转发固定 handle——替代 PlayFabMgr 的存档入口生态位〔平移〕。
- `PlayFabMgr.cs`：四个 KV 入口移除；Guard 接线（Lifecycle/Compare/Update/ReadLocal/Sync/PrefsSave/Immediate 七检查点）；kv-loop 分支；新增内部 `FlushBufferedData` 委托原 SyncData（供 PF store）。PF 原同步/缓存/40 秒定时器**全部保留**〔平移+保留 PF〕。
- `CustomServerMgr.cs`：`kvOnly` 租约运输（BindKVForValidation/BindKVForGame/EnableKVBusiness/DisableKVBusiness）、KVUnauthorized 事件、Cookie 同源返回、主线程 Post、15 秒超时〔平移〕。

## C. 用户服务与身份（`Services/`）

- `KVUserService.cs`（新增）：正式 KV 登录编排（认证→31 模块 Apply→释放 Guard→原 handle→三提示服务→启用租约→**就绪后同步发布 UserId/ApiPlayerId/InternalId/IsAuthorized**→发一次 `EvtAPISvrLoginSuccess`→Login 返回 Done）；不继承/不引用 PlayFabUserService 与 SDK；显式失败成员表；新 PlayerId 身份〔平移〕。他人资料 `GetPlayInfo/GetPlayLv` 当前未命中返回 null/抛错——**原语义形状恢复列为 C3c ①可批未实施**。
- `UserService.cs`：`IUserService` 移除 `EntityKey`（PF DTO 出共用契约）、`CustomId` 加 setter、移除 formal KV 分支；PF 登录/资料/其他玩家缓存原样保留〔平移〕。
- `UserService.KVLoad.cs`：formal 段已迁出至 KVUserService；保留受控验证成员（ConfigureKVForValidation/LoadKVForValidationAsync 等）〔平移〕。
- `UserService.KVGameplayLoop.cs`：Editor kv-loop 测试通道（PF 身份背景），按设计不改仅回归。
- `AggUserService.cs`：仅 B3-C168 retain-agg 零行为修改。
- `ChatService.cs`：对 HEAD 仅 BOM 差异〔原样〕。

## D. 登录/舞台流程（`Stages/`）

- `LoginStage.cs`：按冻结选择注册 PlayFabUserService/AggUserService/**KVUserService** 及对应存档实现；`RequestNextAct` KV 双闸之一（保留）〔平移〕。
- `PFLoginAct.cs`：中立 formal 检测（读 RuntimeSelection）、共用接口 CustomId 赋值、KV 就绪/错误状态经 `IKVUserLifecycle`、输入/重试/销毁流程原样〔平移〕。
- `QuitAct.cs`：经窄契约观察 KV 关闭（validation/formal 两实现）〔平移〕。
- `FishingStage.cs`/`FishingAct.cs`：store 注入消费、身份发布后时序、暂停恢复核旧 lifetime；5 秒软门不作为 KV 凭据〔平移〕。**双闸保留至 PF 调用计数=0**。

## E. 数据中心 31 存档模块（`DataCenter/` 等，27 文件）

- 全部 31 模块新增 `ResetForKVLoad`/`ReplaceFromKVDecoded` 受控加载入口（KV 档按序同步 Apply，Guard/回滚/主线程约束）〔平移〕。
- **202 项业务存档调用**迁 `IPlayerSaveStore`（原键、原序列化、原 remoteStore 参数、原调用时序）：PlayerData/SmallGame/PlayerFishData（含鱼竿配件）/PlayerShopData/FishingEventData（主体 16+PVP/单双人 11）/Buff/Camp/Achievement/Box/Guide/BattlePass/Signin/Trigger/Club/Challenge/Chains/Disco/Partner/Cube/EventPack/Piggy/Bargain/FootPrint/Shooting/Potion/Pinball/Scratch/Pinata/Digging/LuckyTask×2/MiniBP/EventToken/水族馆/累计充值/配对游戏/Bingo/Break/Can/GatherCore/Mow/Smash/广告轮/扫荡/拼图等〔平移〕。
- 2 项即时消耗（`FishingBehaviorB.ConsumeBaitOnPlayfab`、`FishingTurntablePanel.ConsumeOnPlayfab`）：`SyncDataImmidiate`→`WriteAndConfirmAsync` 存储替换，**调用者时序原样**（不等待、无条件 isDataSynced、原随机/动画顺序）〔原样〕。
- 余 4 项：3 项 Club/Setting 已有固定 KV 提示路线保留 PF 分支；1 项 `BaseEventData.UploadData` 无消费者待最终清理。

## F. 业务服务层（`Services/` 15 文件）

- `InGameMailService/InGameMailHandler`：Cookie 身份、缓存按新 UserId 分键、回包核生命周期〔平移〕；**批量 HasRead→HasReward 旧语义原样保留**（缺陷已登记待移植后授权）〔原样〕。
- `FriendService`：普通 `friend/*` 请求字段值换新 UserID（字段名保留）〔平移〕；`GetFriendData` 的 PF SDK 读取**待 C3c 裁决未动**〔待接线〕。
- `ClubService`：提示键走原 handle 固定路线、`GetSelfClub` 经租约〔平移〕。
- `SurveyService`：两键原键名迁 KV、十进制尾数 %10 抽样、原同步签名原样〔平移+原样〕。
- `SettingService/LocalNotificationService`：B01 固定 owner 读写〔平移〕。
- `AntiCheatManager`：`CheckBan` playerID=新 UserId〔平移〕。
- `RTService/SignalRService`：SessionVersion/Cookie 消费、旧连接失效〔平移〕；真连接未验。
- `FootPrintService/EventTokenService/TileNewsManager(候选) 等`：store/身份接线〔平移/待接线〕。

## G. UI 层（Setting 6、Shop 4、LuckyTask 3、Partner 4、Social 3、各活动 UI）

- 全部为 store 注入后的**最小适配**：await 后核旧 store/会话、资源过期回调不更新新界面〔平移〕。
- `EventFishingDuelPanel.cs`：EntityKey 消费改 PF 具体能力分支（EntityKey 已移出共用契约）；KV 匹配路径 `MachingEnd(null)` 为开发性结束**不得放行**〔待接线〕。
- `SocialFriends/SocialLeadboardItem` 等解码 UI：**零修改**（`/100000`、`%100000` 解码依赖服务端 LevelB 投影，见 C3c）。
- `HomePanel`：**零修改**（补单原异步流程，与 HEAD 字节一致）。

## H. 活动系统（`FishingEvent` 全类型、Offer、礼包等）

- Type2 签到/Type3 礼包战令/Type4·7 动态活动（沙Dig/伙伴/魔药/弹珠/Bingo/CubeMelt/射击/Break/Can/GatherCore/Mow/Smash）/Type8 LuckyTask/Type9 MiniBP·OfferJourney：存档读写迁 store，原条件、原键、原序列化、原异常处理（含原逐活动 catch 继续）〔平移+原样〕。
- 通用 `EventDataRepository`/`AEventDataManager`：泛型活动仓库迁固定 store〔平移〕。

## I. 编辑器与测试（`CodexOutput/upserver/`，非生产）

- `KVGameLoadTests`（90 组 2006 断言）、`KVSyncTests/KVSyncCoordinatorTests/KVLoginContextTests/B01Tests/B02RouteTests/KVFishingConsume·RewardValidation`、ServiceHost 双条件宿主（18 组 254 断言）、`M2MergedContractTests/M2MergedGameplayTests`、ExitRegression、PlayerProbe。
- Editor 工具：kv-loop 许可通道、`S101LoginWindow` 最小认证探针。

## J. 其他

- `AOTScripts/Boostrap.cs`/`SubBoostrap.cs`：RuntimeSelection 捕获与注册时序〔平移〕。
- `TimeManager/TimeRefreshManager.cs`：LastLoginTime 哨兵三分映射（MinValue→null 首登分支）〔平移〕。
- `DebugFunc`/配置投影/manifest 等辅助。

## 已核减回原样的项（C2d，避免误读为"已修复"）

邮件批量枚举缺陷、钓鱼/转盘调用者等待、Survey/Friend 的 Task 化与领取锁、商店/签到确认与订单去重、PlayerSaveAction 聚合、坏档抛错汇总、Chat 重试——**全部恢复原实现**，登记在《纯平移主会话裁决与C2d实施记录》待移植完成后另行授权。

## 尚未迁移（PF SDK 残余，待 C3c 四问）

等级榜统计写/读（`UpdatePlayerStatisticsAsync/GetLeaderboardAsync`）、好友列表（`GetFriendsListAsync`）、公告（`GetTitleNewsAsync`）、Duel 匹配（Multiplayer 四调用）、他人资料远端读取——此五类是当前首场景 PF 计数≠0 的全部来源。