vampire-like/docs/AssemblyOrganization.md

SepCore 程序集组织规范

本文档定义 Assets/GameMain/Scripts 下 C# 代码的程序集（Assembly Definition）拆分规则，用于指导新代码的归属判断和现有代码的维护。

---

1. 设计原则

1.1 核心约束

• 单向依赖：下层不引用上层，上层可以引用下层。
• GameEntry 红线：凡是有 GameEntry. 引用的代码，一律不能放在 Base。
• 框架适配：UnityGameFramework 是组件化平级协作架构，GameEntry 作为全局访问点天然要求它能看到所有 Component。因此 Component 及其扩展方法统一归到 Runtime，不放在 Base。

1.2 依赖方向

SepCore.Procedure（编排层）
    ↓ 可引用
SepCore.Presentation（表现层）
    ↓ 可引用
SepCore.Runtime（运行时基础设施层）
    ↓ 可引用
SepCore.Base（核心定义层）

Editor 程序集独立，引用除 Presentation 外的所有运行时程序集：

SepCore.Editor
    ↓ 可引用
SepCore.Procedure / SepCore.Runtime / SepCore.Base / UnityGameFramework.*

---

2. 各层职责与判断标准

2.1 SepCore.Base — 核心定义层

定位：最稳定、最少变化、零外部依赖的纯基础设施。

判断标准：

• 不引用 GameEntry
• 不引用任何自定义 MonoBehaviour Component
• 不引用 UnityGameFramework.Runtime 中的具体 Component（框架基础类型如 EntityLogic 除外）
• 以数据结构、常量、枚举、纯算法为主

当前归属目录：

目录	说明
Base/DataTable/	DR* 数据表行定义、BinaryReaderExtension、DataTableExtension
Base/Definition/Constant/	Constant.* 常量
Base/Definition/DataStruct/	BuildInfo、VersionInfo 等纯数据结构
Base/Definition/Enum/	SceneType、UIFormType 等枚举
Base/Entity/EntityData/	EntityDataBase（纯数据类）
Base/Entity/EntityLogic/	EntityBase（继承框架 EntityLogic，无 GameEntry 引用）
Base/Utility/	AssetUtility、WebUtility、LitJsonHelper（纯静态工具）

2.2 SepCore.Runtime — 运行时基础设施层

定位：所有 GameFrameworkComponent、全局访问点（GameEntry）、以及对框架组件的扩展方法。

判断标准：

• 包含 GameEntry. 引用
• 继承或扩展框架 Component（如 DefaultLocalizationHelper、UIFormLogic）
• 对 SoundComponent、UIComponent、EntityComponent 等做扩展方法
• 自定义的 GameFrameworkComponent（如 BuiltinDataComponent）

当前归属目录：

目录	说明
Runtime/BuiltinComponent/	EntityExtension、SoundExtension、UIComponentExtension、XmlLocalizationHelper
Runtime/UIBase/	UGuiForm（基类）、UIExtension、DialogParams、UGuiGroupHelper、CommonButton
Runtime/Base/	GameEntry.cs、GameEntry.Builtin.cs、GameEntry.Custom.cs
Runtime/CustomComponent/BuiltinData/	BuiltinDataComponent.cs
Runtime/Debugger/	ChangeLanguageDebuggerWindow.cs

引用配置：

• UnityGameFramework.Runtime
• GameFramework
• SepCore.Base

2.3 SepCore.Presentation — 表现层

定位：最顶层的业务 UIForm，只包含具体界面的逻辑，不含可复用的 UI 基础设施。

判断标准：

• 继承 UGuiForm（Runtime 层基类）或直接继承 MonoBehaviour
• 不向外暴露被其他 Component/Procedure 直接引用的类型（除非通过 GameObject 或基类解耦）
• 允许调用 GameEntry.*

当前归属目录：

目录	说明
UI/	DialogForm、UpdateResourceForm

引用配置：

• SepCore.Runtime
• SepCore.Base
• UnityGameFramework.Runtime
• GameFramework

2.4 SepCore.Procedure — 编排层

定位：游戏生命周期流程（Procedure），作为最顶层协调者，可以引用所有人。

判断标准：

• 继承 ProcedureBase
• 直接引用具体 UIForm 类型（如 UpdateResourceForm）是允许的，因为 Procedure 是最顶层

当前归属目录：

目录	说明
Procedure/	ProcedureBase + 所有 Procedure 子类

引用配置：

• SepCore.Presentation
• SepCore.Runtime
• SepCore.Base
• UnityGameFramework.Runtime
• GameFramework

2.5 SepCore.Editor — 编辑器扩展层

定位：编辑器工具、自定义 Inspector、构建事件等，仅在 Editor 下编译。

引用配置：

• UnityGameFramework.Editor
• UnityGameFramework.Runtime
• SepCore.Runtime
• SepCore.Base
• GameFramework

注意：Editor 不引用 SepCore.Presentation，避免编辑器逻辑依赖业务表现层。

---

3. 程序集引用矩阵

引用方 \ 被引用方	Base	Runtime	Presentation	Procedure	Editor
Base	—	✗	✗	✗	✗
Runtime	✓	—	✗	✗	✗
Presentation	✓	✓	—	✗	✗
Procedure	✓	✓	✓	—	✗
Editor	✓	✓	✗	✗	—

---

4. 常见反模式

4.1 Base 层引用 GameEntry

❌ 错误：把 XmlLocalizationHelper、ChangeLanguageDebuggerWindow 等引用 GameEntry 的文件放在 Base。

✅ 正确：凡是调用 GameEntry.* 的文件，一律放到 Runtime 或更高层。

4.2 Runtime 层引用 Presentation 的具体类型

❌ 错误：BuiltinDataComponent 持有 UpdateResourceForm 类型的字段。

✅ 正确：BuiltinDataComponent 暴露 GameObject，由 Procedure（最顶层）通过 GetComponent<UpdateResourceForm>() 获取。

4.3 GameEntry 留在 Base

❌ 错误：GameEntry.Custom.cs 引用了 BuiltinDataComponent（Runtime），但 GameEntry 放在 Base。

✅ 正确：GameEntry 的所有 partial 文件必须和 BuiltinDataComponent 在同一程序集，即 Runtime。

4.4 扩展方法乱放在 Utility/

❌ 错误：把 SoundComponent.PlayMusic 这类扩展方法放在 Utility/SoundExtension.cs。

✅ 正确：对 Component 的扩展方法跟着被扩展方走，放在 BuiltinComponent/（Runtime）下，或按模块分散到各子系统的 Runtime 目录中。

---

5. 命名空间约定

程序集拆分后，命名空间保持与原始文件夹路径一致，便于代码导航：

程序集	命名空间示例
SepCore.Base	SepCore.DataTable、SepCore.Definition、SepCore.Utility
SepCore.Runtime	SepCore.Runtime（根命名空间）、SepCore.UI、SepCore.Entity、SepCore.Sound
SepCore.Presentation	SepCore.UI（与 Runtime 共享，因为 DialogForm 等原本就在 SepCore.UI）
SepCore.Procedure	SepCore.Procedure
SepCore.Editor	SepCore.Editor

允许 Runtime 和 Presentation 共享同一个根命名空间（如 SepCore.UI），因为 C# 命名空间可以跨程序集。Presentation 的 DialogForm 在 SepCore.UI 下，Runtime 的 UGuiForm 也在 SepCore.UI 下，这是合法的。

---

6. 新增代码决策流程

当不确定新文件该放哪一层时，按以下顺序判断：

1. 是否只在 Editor 使用？ → SepCore.Editor
2. 是否继承 ProcedureBase？ → SepCore.Procedure
3. 是否继承 UGuiForm 或 MonoBehaviour 且是具体业务界面？ → SepCore.Presentation
4. 是否引用 GameEntry、是否是 Component、是否是对 Component 的扩展？ → SepCore.Runtime
5. 其余所有纯数据/定义/工具 → SepCore.Base

---