迁移质量门槛与验收字段

本文件在需要建立迁移台账、判断完成度、排查运行差异或设计集中验收时读取。主流程见 SKILL.md；详细 API 和子系统配方见 reference.md。涉及存档时读取第 5 节。

1. 功能台账

每个玩家可达功能用稳定 featureId 建立唯一的当前记录，不按源文件或资源数量计数：

featureId / 功能：
source：1.0 来源、入口与规则依据
implementation：2.0 目标、运行入口、配置 / 原生系统 / 自定义代码
decisions：用户确认的范围与规则改动
temporaryLimits：原因、影响、解除条件（如有）
dependencies：
state：source-mapped / skeleton / compiled / runtime-smoke-passed / accepted
lastVerifiedBuild / sessionId：实际验证的构建/依赖版本与场次
evidence：migration/evidence/...（日志 / 截图 / 录屏 / 数据快照 / 用户确认）
remaining：未完成项、阻塞原因或不适用理由
supersedes：被本次结果替代的历史批次/记录

把确认框、物品详情、奖励弹窗等支持组件归入所属功能；空类、无入口脚本和纯调试入口单独标记，不直接计入玩家功能分母。

每批结束更新当前记录；历史报告保留并指向当前状态，不能只追加“已完成”报告却让总表仍显示未迁移。规则找不到原版依据时标为待确认，不能把临时实现决定写成原版规则。

证据文件随项目保存，例如 migration/evidence/<批次>/<featureId>/，日志注明场次和操作。原机器绝对路径可作来源信息，但不能是唯一证据。可重复的验证脚本放在生产编译范围之外，并记录运行方法；避免为了排除编译错误而删除唯一的复验过程。

2. 三层完成边界

审计时分别判断：

数据层：配置、链接、数值和资源路径是否已映射
逻辑层：入口、目标、生命周期、奖励、失败和清理是否实际运行
表现层：客户端单位、状态栏、模型、动画、特效、声音和 UI 是否可见且符合预期

compiled 只表示代码可构建；runtime-smoke-passed 表示至少一个真实场景链路运行通过；accepted 还需要完成人工表现/交互验收。

3. 入口与可达性

迁移前从 1.0 入口向下追踪：

GameStart / MainUI
-> Manager.Init / Event
-> Panel.Open / Request
-> GameplayTransaction
-> Reward / Progress / Persistence

每个 GameDataUnit、技能、Buff、场景和奖励条目都要检查是否有实际引用或创建入口。报告中区分：

reachable-player-feature
support-component
debug-or-gm-only
platform-dependent
dead-or-empty
unknown-reachability

不要因数据条目存在就宣称功能已生效，也不要因大量未使用的源文件存在就扩大正式缺口。

4. 运行和表现验收

每个纵切至少记录：

• 场景、玩家、入口操作和期望结果；
• 创建数、归属、阵营、AI、伤害、死亡和清理；
• 服务端日志路径与关键结构化标记；
• 与功能类型匹配的证据：客户端日志 / 截图 / 录屏（表现或交互功能），服务端日志 / 重进恢复结果 / 数据快照（纯服务端或持久化功能）；
• 失败原因和下一步排查位置。

遇到“能创建但不可见”“有伤害但无血条”“模型重复或落点偏移”时，按以下链路排查：

服务端结算
-> 单位/技能同步
-> 客户端 GameData 定义
-> 阵营/状态栏选择
-> 模型、动画、Actor、粒子和挂点资源
-> UI 布局与交互

服务端创建的单位，客户端必须拥有同一单位链接及客户端所需的 GameDataUnit、Model、状态栏和表现数据；不要把整个单位定义包进 #if SERVER。

4.1 模型与资源依赖检查

模型或技能资源应按依赖闭包检查，而不是只检查最外层路径：

Prefab / Model
-> Mesh / MDL
-> Material / Texture
-> Animation
-> Collision
-> Socket
-> Actor / Particle

对每项记录：

存在 / 缺失
本地 / 云端
客户端可解析 / 仅服务端可解析
依赖完整 / 依赖不完整

迁移 1.0 项目时，资源验收还要单独记录：

res/ 是否按相对路径合并到目标项目
ui/image/ 是否完整复制（含序列帧和贴图）
ui/spine/ 或 ui/Spine/ 是否完整复制（含 atlas、skel/json、贴图）
同名资源冲突及最终采用的版本
Client-Resource 是否通过
ref/objref.txt 是否包含需统计的关键云资源（项目 res/ 随项目封装，不以 objref 为存在证明）
目标运行环境的自定义云端资源是否存在

发现模型不可见时，按以下顺序排查：

客户端 GameDataUnit
-> Model Link
-> 资源依赖闭包
-> 动画片段名称和大小写
-> 缩放、朝向、位置和 Socket
-> Client-Resource / ref/objref.txt / 客户端运行日志

不要用伪造 .mdl、材质或动画文件来掩盖缺失资源；可以使用已确认可用的 2.0 替代模型，但必须记录为临时替代。

4.2 技能表现时间轴与重复触发

特殊技能至少核对：

施法 -> 预警 -> 载体/投射物 -> 移动
-> 命中 -> 爆炸/伤害 -> 延迟清理

预警中心、投射物落点、爆炸中心和伤害搜索中心应按 2.0 的目标类型和执行上下文逐阶段确认；视觉参考半径与逻辑伤害半径应显式校准。若使用持久 Actor slot，必须遵守 Actor 的非 transient 和服务端生命周期规则；若使用一次性表现，使用 PlayTransient 或等价的延迟清理路径。

表现验收覆盖：

首次触发
连续第二次触发
切换技能或页签后触发
关闭重开后触发

4.3 表现位置所有者与运动来源

迁移预警、投射物或落地效果前，逐阶段记录：

阶段	位置来源	高度来源	挂接对象
预警	随机点/目标点/载体	地面或目标高度	Effect/载体
投射物	施法者/载体/目标点	Mover/模型动画/Socket	Unit/Actor
爆炸	命中点/载体/默认目标	地面	Effect/Actor
伤害搜索	爆炸中心	地面	ExecutionContext
清理	载体/Actor	—	Unit/Actor

检查以下问题：

• 预警、投射物落点、爆炸和伤害是否使用同一中心；
• 运动由 Mover、模型动画、Socket 还是 Actor 提供，是否重复叠加；
• 起点和终点水平坐标相同时，所选投射物模式 / Mover 是否会立即完成或产生不稳定朝向；
• 是否为了制造方向而加入改变真实落点的水平偏移；
• 模型和 Actor 是否重复创建同一外观；
• 载体是否在附着表现完成前被清理。

场景坐标和技能数值可以沿用 1.0 源数据；效果节点间的目标传递、挂接对象、投射物模式和生命周期必须按 2.0 运行语义重新确认。不要仅因表现是“垂直下落”就默认加入水平偏移、放弃 GameDataEffectLaunchMissile 或强制改用地面载体。

4.4 配置、生成投影与运行值

为每种高风险映射选一个代表条目，记录下列四层；涉及哪一端就核对哪一端的投影和运行值：

层次	核对内容
源意图	原配置、实际调用链和预期行为；含原模板继承结果
保存后配置	编辑器/MCP 写入后保存并重新读取，确认值、引用、继承及集合仍在
生成投影	生成的 DataGenerated/TriggerGenerated 声明、赋值、注册和调用结构
运行值	实际实例/Cache 中生效的值与玩家操作结果

优先选非默认值暴露静默忽略：任务 TargetCount = 3，实际推进应为 1/3、2/3、3/3；碰撞 Footprint 用两个可辨识格子核对运行集合；继承筛选器核对最终元素而非只看子节点；技能记录首次效果时间、间隔与次数。临时探针只用于隔离测试，不改变正式平衡数据。

每个数据批次保存后，使用目标宿主实际支持的 data_save_and_generate，传 generateAll: true、validate: true，检查 generationWarningCount 和结构化 diagnostics。GDATA001 表示已知字段的赋值全部或部分被省略，即使后续编译成功也不能通过该字段的迁移验收。修复源类型、值或引用后重新全量生成，确认迁移引入的诊断已消除；依赖库的既有诊断单独记录范围与影响，不能隐藏或声称全局无警告。未知编辑器/项目扩展字段与 GDATA001 不同，按 data-editor 的约定保留。

日志需按本次生成时间或操作对应：修正前的历史警告不是本次仍失败的证据，增量生成无诊断也不能证明未处理文件已经通过。

若配置存在而运行为空，定位到写入/保存、生成器、注册或运行时边界。集合 getter 可能返回副本，生成器只调用 AddRange 而未通过 setter 回写也可能丢值。此类结果应记录版本、最小复现和受影响批次，按缺陷排查；不能手改生成代码、改玩法来掩盖，或据此宣称该能力永久不支持。语义例子见 reference.md 4.9。

4.5 视觉与平台证据

UI 树快照可证明控件结构和数值，不能证明画面无遮挡、动画连贯、声音正确或移动端触控可用。按功能使用截图、录屏、音频或用户实机确认。截图返回 window_minimized 时，仅将视觉项记为待验收；继续独立的数据/逻辑工作，集中恢复前台后补验。桌面结果不能直接计作移动端通过。

4.6 故障测试项目复刻

只复刻故障相关部分时，保留一份简短的测试条件对照，区分源配置、目标实际值和测试辅助：

条件	记录内容
资源与表现	模型、粒子、材质和动画路径，缩放、偏移、挂接及继承设置
触发与生命周期	原 AI/玩家操作，施法阶段、冷却、重复频率、实例数、清理与重进方式
场景与对象	预放数量、归属、位置、相机及模板继承产生的属性差异
测试辅助	自动轮播、快捷键、替代模板或临时处理改变了哪些条件
验收环境	编辑器/客户端、SDK 与依赖版本，平台、画质及已知相关图形配置，操作和证据

自动轮播可用于反复观察，但不能冒充原 AI 的完整行为。运行时数量与预放定义不符或场景加载重复时，先对照定义、实际实例和加载日志定位；必要的项目临时处理应记录副作用与待查原因，不能推广为通用迁移配方，也不能据此宣称框架问题已修复。“未复现”限定于实际测试条件，保留用户现场确认及其适用范围。

5. 持久化验收

涉及背包、成长、装备、任务、商店、抽奖或排行榜时，检查：

权威状态
-> 快照事件
-> CloudData 读取
-> CloudData 写入
-> 目标存档默认值/版本兼容（承接旧账号时另验旧档转换）
-> 关闭并重新进入后的真实恢复

5.1 保存调度与退出

高频状态维护 dirty 标记和版本化快照，按玩家串行合并提交；提交期间产生的新改动继续保留 dirty，旧提交成功不能清掉新版本。覆盖显式保存、正常退出和断线，并确认自动消耗、仓库转移等状态变化进入同一保存链。关键交易等待提交完成后再向客户端报告成功。日志区分本局状态有效、保存排队、提交完成和结果未知。

在清理玩家会话/销毁实体前捕获稳定用户身份及待保存状态。若保存函数要求玩家仍在线，仅在断线回调调用它并不能保证保存；调度和快照生命周期须支持离线收尾，并核对宿主实际允许的完成窗口。进程内待保存快照不能提供进程退出后的恢复保证。

尊重项目已有调用约束。例如禁止定时器中直接调用云接口时，可由定时器标脏/生成快照，再由允许的异步保存入口处理；不能因调用位置受限就省略保存。没有此项目约束时，也不要把它推广为框架规则。

5.2 断线、结果未知与重进

用隔离的测试身份覆盖以下情况，并在重新进入后读取真实云状态：

时机	验收结果
显式保存 / 正常退出	恢复已确认保存的版本，关键字段与快照一致
提交前断线	按约定完成收尾或明确回滚到最近确认版本；不得报告未提交的状态已持久化
提交后、收到响应前断线	按稳定操作 ID/幂等记录核对结果，重试不重复扣费或发奖
旧会话晚完成，新会话已进入	旧快照不能覆盖新状态；需跨会话协调的功能应有相应机制与证据

等待中断或响应未收到不能据此认定提交失败，更不能直接重放奖励。区分本局互斥锁、选档票据、事务和跨会话原子条件写入的保证；先查询版本再普通写入不等于 compare-and-set。具体云数据原语查 cloud-data，按已确认 API 设计，不编造原子性。

6. 完成度报告

需要汇报“完成多少”时，至少分开统计：

PlayableCompletion
CoreExperienceCompletion
FeatureParityCompletion
VisualPlatformParity

同时输出状态数量：

Accepted=
RuntimeSmokePassed=
Compiled=
SourceMapped=
Blocked=
NotStarted=

剩余工作按逻辑复杂度、数据量、UI、持久化、表现风险和外部依赖分级，不按文件数量平均计算。