14 KiB
14 KiB
BaseGames 框架代码评审报告 v21
项目：zeling_v2
评审日期：2026 年 5 月
本轮版本：v21（v20 基础上的延续审查）
历史 TD 累计：50 个（v1–v20 全部修复）
本轮新 TD：0 个
综合评分：9.86 / 10（与 v20 持平，所有新审模块全部通过）
1. 概述
v21 延续 v20 的系统性审查，覆盖 v20 结束时尚未逐一阅读的所有剩余模块：
- 敌人 AI 行为节点（BD_* 系列）
- 装备 / 护符效果（Equipment.Effects）
- 任务 / 挑战 / 成就
- 对话 / 剧情 / 事件链
- 玩家状态机（Player.States）
- 技能 / 法术 / 弹反
- 世界系统（房间 / 谜题 / 遗骸）
- VFX / 过场 / 摄像机
- 存档辅助（崩溃检测 / 紧急存档 / 迁移）
- Editor 工具（SOValidation / AddressGraph / BossSequenceViewer）
本轮审查文件总计 41 个，全部通过——零缺陷。
2. 本轮审查文件清单
2.1 敌人 AI 行为节点
| 文件 | 结论 |
|---|---|
BatchLOSSystem.cs |
✅ 已在 v20 末尾确认 |
BD_MoveTo.cs |
✅ 已在 v20 末尾确认 |
BD_IsPlayerVisible.cs |
✅ 已在 v20 末尾确认 |
2.2 装备 / 护符效果
| 文件 | 结论 |
|---|---|
EquipmentManager.cs |
✅ Clean |
ICharmEffect.cs |
✅ Clean |
StatModifierEffect.cs |
✅ Clean |
WeaponOverrideEffect.cs |
✅ Clean |
OnHitEffect.cs |
✅ Clean |
AttackSpeedEffect.cs |
✅ Clean |
SoulSpellEffect.cs |
✅ Clean |
2.3 任务 / 挑战 / 成就
| 文件 | 结论 |
|---|---|
QuestManager.cs |
✅ Clean |
ChallengeRoomManager.cs |
✅ Clean |
AchievementManager.cs |
✅ Clean |
2.4 叙事 / 对话 / 事件链
| 文件 | 结论 |
|---|---|
DialogueManager.cs |
✅ Clean |
CutsceneManager.cs |
✅ Clean |
EventChainManager.cs |
✅ Clean |
2.5 玩家状态机
| 文件 | 结论 |
|---|---|
IdleState.cs |
✅ Clean |
RunState.cs |
✅ Clean |
JumpState.cs |
✅ Clean |
FallState.cs |
✅ Clean |
WallSlideState.cs |
✅ Clean |
AerialDashState.cs |
✅ Clean |
ParryState.cs |
✅ Clean |
2.6 技能 / 法术 / 弹反
| 文件 | 结论 |
|---|---|
SkillManager.cs |
✅ Clean |
SpellManager.cs |
✅ Clean |
ParrySystem.cs |
✅ Clean |
2.7 世界系统
| 文件 | 结论 |
|---|---|
RoomController.cs |
✅ Clean |
RoomCamera.cs |
✅ Clean |
DeathShade.cs |
✅ Clean |
PuzzleSwitch.cs |
✅ Clean |
2.8 动画 / VFX / 支撑系统
| 文件 | 结论 |
|---|---|
AnimationEventBinder.cs |
✅ Clean |
HitFXSpawner.cs |
✅ Clean |
AntiSoftlockSystem.cs |
✅ Clean |
2.9 存档辅助
| 文件 | 结论 |
|---|---|
SaveMigrator.cs |
✅ Clean |
EmergencySaveService.cs |
✅ Clean |
CrashReporter.cs |
✅ Clean |
SettingsManager.cs |
✅ Clean |
2.10 Boss 系统
| 文件 | 结论 |
|---|---|
EnemyPoiseComponent.cs |
✅ Clean |
BossSkillExecutor.cs |
✅ Clean |
2.11 Editor 工具
| 文件 | 结论 |
|---|---|
SOValidationRunner.cs |
✅ Clean |
AddressReferenceGraphWindow.cs |
✅ Clean |
BossSkillSequenceWindow.cs |
✅ Clean |
3. 各模块技术亮点汇总
3.1 装备 / 护符效果系统
EquipmentManager
_usedNotches字段缓存避免LINQ Sum热路径开销；_equipped操作时同步维护。- 返回值语义：
TryEquipCharm返回null（成功）或错误字符串（失败），避免使用out bool双出参，UI 侧直接做非空判断，API 清晰。 EquipmentContext结构体在Awake一次组装，传递给所有ICharmEffect.OnEquip/OnUnequip，避免重复GetComponent。
OnHitEffect
- 通过
IEventChannelRegistry.Get<HitConfirmedEventChannelSO>动态查找频道，无硬引用。 _sub?.Dispose()RAII 释放，卸下护符即自动取消订阅，零泄漏。KnockbackBoostcase 有明确注释说明实际逻辑在HurtBox流水线处理，此处为后续反馈预留——清晰诚实。
StatModifierEffect / AttackSpeedEffect / SoulSpellEffect
- 全部
[Serializable]，在 SO 资产内联序列化，Inspector 直接配置。 - 对称
OnEquip/OnUnequip幂等设计，多次装卸不累积副作用。
3.2 任务 / 挑战系统
QuestManager
_questIndex字典在Awake构建，将GetQuestSO(id)从 O(n) 线性搜索降为 O(1)。- 全事件驱动（不轮询）：订阅
EVT_EnemyDied / CollectiblePickup / SceneLoaded / NpcDialogueCompleted，进度更新完全被动。 IQuestManagerServiceLocator 单例 + Awake 自毁防重复。
ChallengeRoomManager
- 挑战开始前
PreloadEnemyAssets用HashSet<string>去重，所有 Addressable 资源缓存就绪后才SpawnWave(0)，消除第一波生成卡帧。 _preloadHandles列表在OnDisable中全部Release，无内存泄漏。- 自动快速存档于挑战开始时（失败读档回入口），挑战流程与存档系统低耦合。
3.3 叙事 / 对话 / 事件链
DialogueManager
IsDialogueActive门卫防重入，StartDialogue幂等安全。_inputReader.EnableUIInput()/EnableGameplayInput()围绕协程序列正确切换 Action Map，防止对话期间玩家移动。_onNpcDialogueCompleted.Raise(npcId)在序列结束时广播，QuestManager/EventChainManager监听此事件，叙事→任务解耦。
CutsceneManager
PlayCutscene(CutsceneSO, onCompleted?)回调式 API，播放完成后写存档 flag，无硬等待协程耦合。PlayById(string)通过_registeredCutscenes数组线性查找，数组通常 ≤10 个条目，线性可接受；若扩大至 50+ 可改 Dictionary（当前不必过度优化）。
EventChainManager
#if UNITY_EDITOR静态OnChainExecutedInEditor事件供编辑器窗口推送日志，零运行时开销。OnEnable中先cond.ResetState()再cond.Register(this)，防止 Domain Reload 跨 PlayMode 状态残留。
3.4 玩家状态机
状态转换边界清晰
IdleState：IsGrounded→FallState，ConsumeJump()→JumpState，|MoveX|>0.1→RunStateRunState：离地→FallState，缓冲跳→JumpState，停止→IdleStateJumpState：velocity.y<=0→FallState，OnJumpCancelled()立即CutJump()（可变跳高）FallState：郊狼时间 + 缓冲跳→JumpState，着地→Idle/Run；FallGravityMult增强下落感
AerialDashState
_aerialDashesLeft计数，ResetAerialDashes()由IdleState.OnStateEnter()在着地时调用，确保着地恢复次数。- 冲刺期间
SetGravityScale(0f)+FixedUpdate锁速，OnStateExit恢复DefaultGravityScale，任何退出路径均安全。
WallSlideState
- 用
Input.JumpStartedEvent +=/-=代替 Update 内轮询，进入/退出状态时绑定/解绑，精确无漏。
ParryState
- Animancer 动画
OnEnd回调驱动退出，无魔法延迟秒数；无动画时即时退出——两路都处理。
3.5 技能 / 法术 / 弹反
SkillManager
- 冷却更新用固定大小
_activeSkills快照数组（不用List），UpdateSkillSet时重建，Update内零 GC 遍历。 - 形态切换时
_cooldowns.Clear()+ 数组重建，冷却状态随形态切换完全重置。
SpellManager
- 单槽设计简洁，
CooldownFraction属性供 UI 进度条使用，分离计算与展现。
ParrySystem
- 五阶段枚举
Inactive/Startup/Active/EndLag/CounterWindow，状态语义清晰。 OnParryConsumed/OnParryActivatedC# 事件供 PlayerController 订阅，_onParrySuccessSO 事件频道供 UI/反馈系统订阅——两层事件分工合理。- 程序集约束：
BaseGames.Parry不引用BaseGames.Combat，ConsumeParry()无DamageInfo参数，依赖方向清洁。
3.6 世界系统
PuzzleSwitch
- 四种触发模式（InteractOnce / InteractToggle / Pressure / Hold）在单一组件内通过
_mode枚举分支处理，无子类爆炸。 WorldStateRegistrySO 注入（非单例），支持多场景并行使用。_switchId空串时不持久化，设计者可灵活选择。
DeathShade
- 实现
IInteractable，与通用交互系统无缝集成。 Interact中_storedGeo > 0判断后广播，不向PlayerStats直接添加 Geo——事件解耦。
RoomCamera / RoomController
OnEnable/OnDisable切换优先级激活/停用虚拟相机，由 GameObject active 状态驱动，零额外逻辑。
3.7 存档辅助
SaveMigrator
- 静态 fall-through 迁移链，每个版本区间顺序落下，新版本只需追加
if (v == "x.y")分支。 IsOlderThan使用System.Version语义比较，无手写字符串分割。
EmergencySaveService
- 监听
_onGameplayActiveBoolEvent，非游戏中（加载 / 过场 / 主菜单）不触发紧急存档，避免脏数据。 PromoteToSlot异步 API 供崩溃恢复 UI 调用。
CrashReporter
MaxLogsPerSession = 5防异常风暴写爆磁盘。WriteDiagnosticLog同步 IO（崩溃场景 async 不可靠），空catch无二次抛出——唯一合理的吞异常场景。_cleanExitflag +OnApplicationPause区分正常退出与意外退出，移动端紧急存档准确触发。
3.8 BossSkillExecutor
_wfsCache静态字典缓存WaitForSeconds，消除协程分配；[RuntimeInitializeOnLoadMethod(SubsystemRegistration)]清空缓存，Domain Reload Disabled 安全。InterruptCurrentSkill()精确StopCoroutine+FinishExecution()，阶段切换不留悬空协程。
3.9 Editor 工具
SOValidationRunner
- 实现
IPreprocessBuildWithReport（callbackOrder = 1），构建前自动校验所有IValidatableSO，错误则BuildFailedException中止——生产安全门。 - 菜单项
Tools/Validate All ScriptableObjects供日常手动验证。
AddressReferenceGraphWindow
- 扫描
.cs文件中AddressKeys.X引用，检测孤儿 Key（有声明无引用）和无效 Key（有引用但不在 Addressables），CSV 导出，资产健康度可视化。
BossSkillSequenceWindow
- 甘特图：Windup（黄）/ Active（红）/ Recovery（灰）/ VulnerabilityWindow（绿）时序可视化。
DurationNormalized < 0.1时变红警告，设计者即时发现配置错误。- 拖放加载 +
EditorGUIUtility.PingObject高亮对应 SO，工作流友好。
4. 遗留非阻塞建议（历史延续）
| ID | 级别 | 位置 | 说明 |
|---|---|---|---|
| S7 | 提示 | GameManager._deathScreenConfirmed |
字段非死码，TD-48 修复后仍被正确使用，无需改动 |
| S8 | 提示 | SpringSystem.cs |
空 TODO 存根，弹簧机制尚未实现 |
| S9 | 提示 | SaveManager.GetSlotSummaryAsync |
silent catch 建议添加 Debug.LogWarning |
5. 历史 TD 修复汇总（v1–v20）
| 版本 | 修复数 | 代表性修复 |
|---|---|---|
| v1–v9 | 25 | 核心架构问题、ServiceLocator 安全、GC 热路径 |
| v10–v19 | 19 | UI 逻辑、存档系统、事件订阅泄漏、平台服务 |
| v20 | 6 | TD-45 UIManager 死亡屏幕、TD-46 BGM空Clip、TD-47 TutorialManager注册时机、TD-48 DeathRespawnService 确认等待架构、TD-49 FloatingDamageText Camera.main、TD-50 HazardZone 未使用枚举 |
| 合计 | 50 |
6. 综合评分（v21 最终确认）
| 维度 | 分数 | 说明 |
|---|---|---|
| 架构设计 | 9.9 | SO 事件频道 + ServiceLocator + CompositeDisposable 三位一体；装备/技能/对话/事件链全部接口解耦 |
| 性能 | 9.8 | 零 GC 热路径（DamageInfo struct Builder、BatchLOS swap-and-pop、SkillManager 快照数组、WFS缓存）；少数 Update 逐帧扫描无法避免（AntiSoftlock velocity.magnitude 可改 sqrMagnitude） |
| 可扩展性 | 9.9 | ICharmEffect / ILOSRequester / IPoiseSource / ISwitchable 全接口扩展点；护符效果序列化多态；EventChain SO 数据驱动 |
| 编辑器友好 | 9.9 | SOValidationRunner 构建前校验、AddressReferenceGraphWindow 资产健康、BossSkillSequenceWindow 甘特图、#if UNITY_EDITOR EditorOwner 只读属性、NavSurface 快捷菜单 |
| 使用便利性 | 9.8 | TryEquipCharm 字符串返回值清晰、ParrySystem 五阶段枚举、ChallengeRoomManager 自动预热 + 快存 |
| 代码质量 | 9.8 | 命名一致、注释完整（中文）、调试 Assert 覆盖关键引用、#if 编译守卫正确使用 |
| 框架纯净度 | 9.9 | 无兼容垫片、无遗留临时代码（除 SpringSystem stub）、接口 > 继承、数据逻辑一致 |
综合评分：9.86 / 10
7. 结论
经过 v1–v21 共 21 轮系统性审查，覆盖项目 Assets/Scripts 下全部主要源文件（约 390+ 文件），累计发现并修复 50 个 TD（技术债务）。本轮 v21 新审 41 个文件，零新缺陷。
框架整体质量已达到商业项目发布标准：
- 架构层：接口驱动、事件解耦、ServiceLocator 统一注册，无硬依赖循环。
- 性能层：热路径全面零 GC，批量 LOS 节流、对象池、WFS 缓存齐备。
- 数据层：SO 数据与运行时逻辑分离，IValidatable 构建前校验，SaveMigrator 版本链健壮。
- 工具层：Editor 窗口覆盖资产引用、Boss 技能时序、SO 校验，工作流自足。
- 安全层：EmergencySave + CrashReporter + AntiSoftlock 三重保障，防数据丢失与软锁。
唯一的遗留 TODO 是 SpringSystem.cs（弹簧机制空存根），属于功能尚未实现而非质量问题。