basegames/zeling_v2

Fork 0

Files

Joywayer ebbbb7332e 多轮审查和修复

2026-05-12 15:34:08 +08:00

21 KiB

Raw Permalink Blame History

Architecture 与 Assets/Scripts 一致性评估

评估日期：2026-05-11
评估范围：Docs/Architecture 与 Assets/Scripts
评估目标：验证架构设计文档、覆盖矩阵与当前代码实现的一致性，识别已落地能力、命名或落点漂移、以及文档声明但尚未实现的项。

1. 结论摘要

本次核对结果显示：项目的“模块边界”层面整体一致性较高，但“文档完成度声明”与“具体类型级实现”之间存在明显偏差。

综合判断如下：

结构层一致性：高
核心运行时模块落地度：高
文档与代码的命名同步度：中
覆盖矩阵可信度：中偏低
类型级细节一致性：中

总体结论：

Docs/Architecture 对项目的分层、模块切分、程序集边界和主要通信模式描述，和 Assets/Scripts 的实际结构高度吻合。
Core、Combat、Enemy、World、Narrative、Camera、QuestChallenge 等模块的“主干设计”已经明显落地。
但 00_CoverageIndex 中“架构完整度 100%”的表述，和当前代码状态并不完全一致；至少存在若干文档明确声明、且被标为完成，但代码库中未找到对应类型的情况。
部分文档摘要仍保留旧命名或旧组件名，导致 README/索引文档与模块正文、模块正文与代码之间出现双重漂移。

如果按工程可执行性而不是文档完整性来评估，当前状态更适合定义为：

主体架构已成形
多数核心模块已落地
文档细节需要一轮“去过时化”和“完成度回标”

2. 评估方法

本次评估采用以下方法进行交叉核对：

以 Docs/Architecture/README.md 作为总索引，提取架构模块列表与模块职责。
以各模块文档中的“路径 + 类型名 + 代码片段”作为声明依据。
到 Assets/Scripts 中查找对应 C# 文件、命名空间、目录位置和注释中的架构锚点。
将发现分为四类：
- 强一致：文档声明与代码实现基本一致
- 部分一致：实现存在，但路径、命名或职责边界有漂移
- 文档有、代码未见：文档明确声明且索引视为完成，但代码库未找到
- 代码有、文档弱覆盖：代码中存在明确实现，但未在架构文档中得到足够表达

说明：

本评估基于仓库静态内容，不包含 Unity 场景对象、Prefab 绑定、Inspector 序列化引用以及 Addressables 资产配置的运行时验证。
因此本报告评估的是“代码结构与架构文档一致性”，不是“游戏功能是否可玩”。

3. 总体观察

3.1 高一致区域

以下区域表现出较强的一致性：

Core
Combat
Enemy
World
Narrative
Camera
QuestChallenge

这些模块通常同时满足以下特征：

Docs/Architecture 中存在独立模块文档
Assets/Scripts 中存在对应目录或子目录
关键类型名可在代码中直接找到
代码注释中有反向引用具体架构章节

3.2 主要不一致模式

当前不一致主要不是“完全没实现”，而是以下几种更常见的偏差：

文档摘要仍使用旧名字，代码已演进为新实现。
模块正文给出的路径与真实目录落点不同，但职责本身存在。
覆盖矩阵将某些能力标记为“完整”，但同名类型在代码库中未找到。
架构文档偏重“框架基类”，对具体敌种、具体业务脚本、独立子系统的覆盖不足。

3.3 风险判断

最主要风险不在代码本身，而在文档对研发协作的误导：

新成员可能误以为某些接口或工具已经存在
代码审查时可能参考到过时路径或旧组件名
后续迭代可能在已有实现外再造重复 abstraction
覆盖矩阵的“100% 完整”会掩盖实际缺口

4. 逐模块评估

4.1 Core 模块

文档依据：

Docs/Architecture/03_CoreModule.md
Docs/Architecture/README.md

关键声明：

GameManager
SceneLoader
GlobalObjectPool
SettingsManager
ServiceLocator

代码核对结果：

Assets/Scripts/Core/GameManager.cs
Assets/Scripts/Core/SceneLoader.cs
Assets/Scripts/Core/Pool/GlobalObjectPool.cs
Assets/Scripts/Core/SettingsManager.cs
Assets/Scripts/Core/ServiceLocator.cs

评估：强一致。

说明：

核心入口、场景加载、对象池、设置管理和服务定位器均已落地。
代码注释与文档术语基本保持一致。

4.2 Combat 模块

文档依据：

Docs/Architecture/06_CombatModule.md

关键声明：

DamageInfo
HitBox
HurtBox
Projectile
StatusEffectManager
Parry 相关能力

代码核对结果：

Assets/Scripts/Combat/DamageInfo.cs
Assets/Scripts/Combat/HitBox.cs
Assets/Scripts/Combat/HurtBox.cs
Assets/Scripts/Combat/Projectile.cs
Assets/Scripts/Combat/LinearProjectile.cs
Assets/Scripts/Combat/ParryableProjectile.cs
Assets/Scripts/Combat/StatusEffects/StatusEffectManager.cs
Assets/Scripts/Parry/ParrySystem.cs

评估：强一致。

说明：

战斗主干类型已形成完整骨架。
状态效果和投射物已经细分到独立实现层。
Combat 与 Parry 的跨模块拆分也与项目整体程序集边界匹配。

4.3 Enemy 模块

文档依据：

Docs/Architecture/07_EnemyModule.md

关键声明：

EnemyBase
EnemyStats
EnemyMovement
EnemyCombat
EnemyNavAgent
BossBase
AttackPatternSO
TelegraphSystem
LootTableSO
LootResolver
BatchLOSSystem

代码核对结果：

Assets/Scripts/Enemies/EnemyBase.cs
Assets/Scripts/Enemies/EnemyStats.cs
Assets/Scripts/Enemies/EnemyMovement.cs
Assets/Scripts/Enemies/EnemyCombat.cs
Assets/Scripts/Enemies/Navigation/EnemyNavAgent.cs
Assets/Scripts/Enemies/Boss/BossBase.cs
Assets/Scripts/Enemies/Boss/AttackPatternSO.cs
Assets/Scripts/Enemies/Boss/Patterns/TelegraphSystem.cs
Assets/Scripts/Enemies/LootTableSO.cs
Assets/Scripts/Enemies/LootResolver.cs
Assets/Scripts/Enemies/AI/BatchLOSSystem.cs

评估：强一致。

补充观察：

Assets/Scripts/Enemies/FlyingEnemy.cs 之类具体敌种实现存在，但架构文档对具体敌种覆盖较弱，更偏向于描述框架层而非实例层。

4.4 World 模块

文档依据：

Docs/Architecture/08_WorldModule.md

关键声明：

RoomTransition
SavePoint
HazardZone
Collectible
AbilityUnlock
InteractableDetector
WorldStateRegistry
CollectibleSpawner

代码核对结果：

Assets/Scripts/World/RoomTransition.cs
Assets/Scripts/World/SavePoint.cs
Assets/Scripts/World/HazardZone.cs
Assets/Scripts/World/Collectible.cs
Assets/Scripts/World/AbilityUnlock.cs
Assets/Scripts/World/InteractableDetector.cs
Assets/Scripts/World/WorldStateRegistry.cs
Assets/Scripts/World/CollectibleSpawner.cs

评估：强一致。

说明：

世界交互、场景切换、收集物、存档点等核心能力均可找到直接实现。

4.5 Narrative 模块

文档依据：

Docs/Architecture/14_NarrativeModule.md

关键声明：

IInteractable
InteractionPromptController
DialogueManager
InteractableNPC
NarrativeNPC
EventChainManager
CutsceneManager

代码核对结果：

Assets/Scripts/World/IInteractable.cs
Assets/Scripts/Dialogue/InteractionPromptController.cs
Assets/Scripts/Dialogue/DialogueManager.cs
Assets/Scripts/Dialogue/InteractableNPC.cs
Assets/Scripts/Dialogue/NarrativeNPC.cs
Assets/Scripts/EventChain/EventChainManager.cs
Assets/Scripts/Cutscene/CutsceneManager.cs

评估：强一致，但存在模块拆分补充说明不足。

说明：

叙事实现实际横跨 Dialogue、Cutscene、EventChain、World 四个位置。
文档虽有描述，但从目录组织上看，EventChain 已经是独立程序集级实现面，建议在 Architecture 入口层明确强调这一点。

4.6 Camera 模块

文档依据：

Docs/Architecture/17_CameraModule.md

关键声明：

CameraStateController
RoomVisibleArea
CameraTriggerZone
RoomCamera
CameraConfigSO
CameraBlendProfileSO

代码核对结果：

Assets/Scripts/Camera/CameraStateController.cs
Assets/Scripts/Camera/RoomVisibleArea.cs
Assets/Scripts/Camera/CameraTriggerZone.cs
Assets/Scripts/Camera/RoomCamera.cs
Assets/Scripts/Camera/CameraConfigSO.cs
Assets/Scripts/Camera/CameraBlendProfileSO.cs

评估：强一致。

4.7 Save 模块

文档依据：

Docs/Architecture/12_SaveModule.md
Docs/Architecture/00_CoverageIndex.md

关键声明：

SaveData
ISaveStorage
SaveManager
SaveMigrator
EmergencySaveService
CrashReporter
SaveValidator
IDlcSaveExtension

代码核对结果：

已找到：
- Assets/Scripts/Core/Save/SaveData.cs
- Assets/Scripts/Core/Save/ISaveStorage.cs
- Assets/Scripts/Core/Save/SaveManager.cs
- Assets/Scripts/Core/Save/SaveMigrator.cs
- Assets/Scripts/Core/Save/EmergencySaveService.cs
- Assets/Scripts/Core/Save/CrashReporter.cs
未找到同名实现：
- SaveValidator
- IDlcSaveExtension

评估：部分一致，且存在高优先级文档失真。

说明：

存档主骨架已实现。
但文档中对 SaveValidator 与 IDlcSaveExtension 给出了明确路径、接口/类定义和调用方式，覆盖矩阵也将其视为已完成。
代码库内未检出这两个同名类型，因此这部分不能视为“已实现”，最多只能视为“设计方案已写入文档”。

4.8 Input 模块

文档依据：

Docs/Architecture/04_InputModule.md

关键声明：

InputReaderSO
InputBuffer
RebindPanel
ConflictDetector
RebindPersistence

代码核对结果：

Assets/Scripts/Input/InputReaderSO.cs
Assets/Scripts/Input/InputBuffer.cs
Assets/Scripts/UI/Settings/RebindPanel.cs
Assets/Scripts/Input/ConflictDetector.cs
未找到独立类型：RebindPersistence

评估：部分一致。

说明：

RebindPanel 与 ConflictDetector 已存在。
文档对 RebindPersistence 的表述更像“InputReaderSO 内部持久化能力的抽象命名”，而不是仓库中真实存在的独立 C# 类型。
这里的问题不一定是缺功能，更可能是文档层把“能力”写成了“类名”。

4.9 Player 模块

文档依据：

Docs/Architecture/05_PlayerModule.md

关键声明：

PlayerController
PlayerMovement
PlayerStats
PlayerCombat
FormController
WeaponManager
SkillManager
SpringSystem
FSM States

代码核对结果：

Assets/Scripts/Player/States/PlayerController.cs
Assets/Scripts/Player/PlayerMovement.cs
Assets/Scripts/Player/PlayerStats.cs
Assets/Scripts/Player/PlayerCombat.cs
Assets/Scripts/Player/FormController.cs
Assets/Scripts/Player/WeaponManager.cs
Assets/Scripts/Skills/SkillManager.cs
Assets/Scripts/Player/SpringSystem.cs

评估：部分一致。

说明：

核心能力都存在。
但 PlayerController 并不在 Player 根目录，而是在 Player/States 下。
SkillManager 也被拆分到独立的 Skills 模块，而不是完全留在 Player 模块目录中。
这类偏差对运行时影响不大，但会误导按文档定位代码的开发者。

4.10 Progression 模块

文档依据：

Docs/Architecture/09_ProgressionModule.md

关键声明：

AbilityType
AbilityGate
Equipment/Charm/Tool/Skill 等能力与成长系统

代码核对结果：

Assets/Scripts/Player/AbilityType.cs
Assets/Scripts/World/AbilityGate.cs
Assets/Scripts/Equipment/...
Assets/Scripts/Skills/...

评估：主体一致，但 AbilityType 定义存在明显漂移。

关键差异：

文档枚举项包含：AerialDash、InvincibleDash、ClimbVines、UseTools、ReadShrine、UseGrapple 等
代码枚举项包含：AirDash、SuperJump、Dive、Spell1、Spell2、Spell3、SpiritForm、SpiritDash、FastTravel 等

判断：

这不是简单命名差异，而是能力模型本身发生了演进。
当前文档中 AbilityType 的示例和真实代码已不属于同一版本。

影响：高。

AbilityType 直接影响存档兼容、关卡门禁和能力查询语义。
如果开发者依据文档新增位标志，存在破坏现有位序或存档含义的风险。

4.11 UI 模块

文档依据：

Docs/Architecture/10_UIModule.md

关键声明：

UIManager
HUDController
BossHPBar
PauseMenuController
DeathScreenController
SettingsPanelController
SaveSlotController
SaveIndicator
LoadingOverlay
IBossHPProvider

代码核对结果：

多数 UI 控制器可在 Assets/Scripts/UI 中找到
BossHPBar 存在：Assets/Scripts/UI/HUD/BossHPBar.cs
未找到独立接口：IBossHPProvider

评估：部分一致。

说明：

UI 模块大多数实体存在。
但文档明确给出 IBossHPProvider 路径和接口定义，仓库内未发现同名接口。
这意味着 BossHPBar 的依赖抽象层与文档不一致，或者文档记录了一个尚未落地的重构目标。

4.12 VFX / Feedback 模块

文档依据：

Docs/Architecture/18_VFXFeedbackModule.md
Docs/Architecture/README.md

关键声明：

IFeedbackPlayer
PlayerFeedback
EnemyFeedback
FeedbackConfigSO
VFXPool
HitFXSpawner
HurtFlashController
PaletteSwapSystem
PostProcessManager
RegionLightController

代码核对结果：

VFXPool、HitFXSpawner 等主干命名可在 Assets/Scripts/VFX 中找到
但 README 层摘要与模块正文、代码之间存在术语漂移

评估：部分一致。

说明：

模块正文比 README 更接近现状。
README 的摘要更像较旧版本的名称集合，不适合作为准确索引。

4.13 Liquid / Puzzle 模块

文档依据：

Docs/Architecture/21_LiquidPuzzleModule.md
Docs/Architecture/README.md

关键声明：

README 摘要中可见旧名称：LiquidSimulator、LiquidTile、LiquidTriggerZone、HazardLiquid
模块正文与代码更接近的名称：LiquidZone、SwimState 等

代码核对结果：

Assets/Scripts/World/Liquid/LiquidZone.cs
Assets/Scripts/Player/States/SwimState.cs
Assets/Scripts/World/Liquid/LiquidPhysicsConfigSO.cs
Assets/Scripts/World/Liquid/UnderwaterPostProcessingController.cs

评估：部分一致。

说明：

模块真实实现明显采用了 LiquidZone 体系。
README 摘要没有同步更新，保留了旧名，造成总览页与真实实现不一致。

4.14 Supporting 模块

文档依据：

Docs/Architecture/16_SupportingModules.md

关键声明：

LocalizationManager
AchievementManager
PlatformManager
DebugCheatSystem
AntiSoftlockSystem
AccessibilityManager
AnalyticsManager

代码核对结果：

AchievementManager 实际位于 Assets/Scripts/Progression/AchievementManager.cs
Accessibility 相关实现位于 Support 子层
平台相关实现位于 Platform / Support 交叉区域

评估：部分一致。

说明：

功能存在，但“支撑模块”更像是文档维度的归类，而不总是对应单一物理目录。
其中 AchievementManager 被放在 Progression 下更符合运行时职责，但与 SupportingModules 的组织口径不完全一致。

4.15 BossSkill 模块

文档依据：

Docs/Architecture/23_BossSkillModule.md
Docs/Architecture/README.md

关键声明：

BossSkillSO
BossSkillExecutor
SkillSequenceSO
VulnerabilityWindow
BossOrchestrator 集成
README 摘要中还提到 BossPhaseController

代码核对结果：

Assets/Scripts/Enemies/Boss/BossSkillSO.cs
Assets/Scripts/Enemies/Boss/BossSkillExecutor.cs
Assets/Scripts/Enemies/Boss/SkillSequenceSO.cs
BossPhaseController 未找到同名实现

评估：部分一致。

说明：

模块正文和代码大体对齐。
但 README 摘要中的 BossPhaseController 未在代码中体现，说明入口摘要比正文更过时。

5. 重点问题清单

以下问题按优先级排序。

P1. 覆盖矩阵“100% 完整”结论失真

证据：

Docs/Architecture/00_CoverageIndex.md 声称架构完整度 100%
但 SaveValidator、IDlcSaveExtension、IBossHPProvider、BossPhaseController 等同名类型在代码库中未找到

影响：高。

会导致文档被高估为“可直接实施现状说明”，而实际上其中一部分仍属于“设计稿状态”。

建议：

将 CoverageIndex 的状态从“完整”改为“已定义 / 已实现 / 部分实现 / 待实现”四态。

P2. Progression 的 AbilityType 文档与代码版本明显脱节

证据：

Docs/Architecture/09_ProgressionModule.md 中的枚举值与 Assets/Scripts/Player/AbilityType.cs 不一致

影响：高。

该枚举是 bitmask，错误文档会直接影响存档位定义和门禁逻辑。

建议：

以代码为准回写文档，或在文档中明确“当前实现版本”和“设计目标版本”的差别。

P3. README 摘要层存在多处旧名称残留

典型例子：

Liquid 模块摘要中的 LiquidSimulator / LiquidTile / LiquidTriggerZone
Boss 模块摘要中的 BossPhaseController
VFX 摘要的旧术语

影响：中高。

README 是入口文档，过时摘要会比模块正文更容易误导。

建议：

优先更新 README，使其只承担“导航”和“当前真实入口”职责，不再保留历史名词。

P4. 文档将“能力描述”写成“独立类型”，造成查找失败

典型例子：

RebindPersistence

影响：中。

读者会误以为仓库中应存在该类。

建议：

将这类条目重写为“由 InputReaderSO 提供的持久化能力”，避免伪类型名。

P5. 物理目录与文档逻辑目录存在合理但未解释的偏移

典型例子：

PlayerController 位于 Player/States
SkillManager 位于 Skills
AchievementManager 位于 Progression
EventChain 独立成模块级目录

影响：中。

偏移本身不是 bug，但若文档不解释，会增加代码定位成本。

建议：

在 README 或对应模块文档中增加“实现落点说明”小节。

6. 一致性评级

本报告给出如下评级：

维度	评级	说明
模块划分一致性	A	目录结构、程序集边界、模块切分与架构文档高度一致
核心系统落地度	A-	Core、Combat、Enemy、World、Narrative、Camera 等主干已经落地
文档摘要准确性	B-	README 与 CoverageIndex 含明显过时内容
类型级一致性	B-	若干文档中的明确类型在代码中不存在
文档可作为“当前事实来源”的可靠性	B	可用于理解架构，但不能无条件视为当前实现真相

综合评级：B+

解释：

从工程结构看，这是一套已经较成熟的模块化代码库。
从文档治理看，Architecture 文档更接近“设计与实现混合体”，部分章节已经演变为前瞻设计，不再完全等于当前代码状态。

7. 修正建议

建议按以下顺序处理文档治理问题。

第一优先级

修正 Docs/Architecture/00_CoverageIndex.md 的完成度口径。
修正 Docs/Architecture/09_ProgressionModule.md 中 AbilityType 的当前实现定义。
修正 Docs/Architecture/README.md 中已过时的模块摘要名称。

第二优先级

在 Save、UI、BossSkill、Input 等模块文档中，将“已实现”与“设计建议”明确分栏。
对未在代码中找到的类型增加状态标记：
- 设计中
- 计划实现
- 已被内联到其他类
- 已废弃

第三优先级

在 Player、Progression、Narrative、Supporting 等文档中补充“真实代码落点说明”。
对具体敌种、EventChain、Support 下功能子系统增加简短架构附录，避免只有框架文档、没有实现面索引。

8. 建议的文档治理规则

为避免文档再次与实现脱节，建议建立以下规则：

Architecture README 只保留当前已存在的模块入口和当前术语，不承载历史命名。
CoverageIndex 不再使用单一“完整/不完整”，改为多状态矩阵。
模块文档中的代码块若为“目标方案”，必须明确标记为“设计草案”；若为“当前实现”，路径和类型名必须可在仓库直接检索。
所有 bitmask、事件频道、序列化结构等高风险契约，优先以代码为准回写文档。
每次较大重构后，至少同步更新 README、CoverageIndex 和对应模块文档三处入口。

9. 最终判断

这套架构文档并不是“失真严重”，相反，它对项目的整体模块化设计、程序集边界、职责拆分和通信方式提供了很强的指导价值；问题主要出在：部分文档已经领先于当前实现，另一些文档仍停留在旧版本命名上，而覆盖矩阵又把这些差异全部抹平成了“100% 完整”。

因此，更准确的表述应当是：

架构主线与代码实现整体一致
核心模块普遍已落地
文档细节存在中等强度漂移
覆盖矩阵结论高估了当前一致性

如果只从“是否还能指导开发”来看，答案是可以；如果从“是否能作为当前实现的严格事实来源”来看，答案是否定的，尤其在 Save、Progression、UI 抽象接口和 README 摘要层面，需要尽快回收偏差。

21 KiB Raw Permalink Blame History Unescape Escape

Architecture 与 Assets/Scripts 一致性评估

1. 结论摘要

2. 评估方法

3. 总体观察

3.1 高一致区域

3.2 主要不一致模式

3.3 风险判断

4. 逐模块评估

4.1 Core 模块

4.2 Combat 模块

4.3 Enemy 模块

4.4 World 模块

4.5 Narrative 模块

4.6 Camera 模块

4.7 Save 模块

4.8 Input 模块

4.9 Player 模块

4.10 Progression 模块

4.11 UI 模块

4.12 VFX / Feedback 模块

4.13 Liquid / Puzzle 模块

4.14 Supporting 模块

4.15 BossSkill 模块

5. 重点问题清单

P1. 覆盖矩阵“100% 完整”结论失真

P2. Progression 的 AbilityType 文档与代码版本明显脱节

P3. README 摘要层存在多处旧名称残留

P4. 文档将“能力描述”写成“独立类型”，造成查找失败

P5. 物理目录与文档逻辑目录存在合理但未解释的偏移

6. 一致性评级

7. 修正建议

第一优先级

第二优先级

第三优先级

8. 建议的文档治理规则

9. 最终判断

21 KiB

Raw Permalink Blame History