# 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`

---