【整合】框架使用规则

2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
--- a/rules/20-开发规则.md
+++ b/rules/20-开发规则.md
@@ -1,269 +1,87 @@
 # 开发规则

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
-
 ## 基本原则

- 优先遵循项目已有模式。
- 修改范围保持在当前功能或模块内。
- 不手动修改生成代码，除非生成器不可用且已记录原因。
- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。
- 正常分析项目时忽略 Unity/IDE 本地状态目录。
- 运行时代码不引用 Editor 程序集。
- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
-
---
+- 先读取附近代码和模块文档，再决定实现方式。
+- 修改范围保持聚焦，优先复用项目已有模式和公开入口。
+- 真实源码、生成代码、业务代码和资源必须按 [架构说明](10-架构说明.md) 区分。
+- 不回退任务开始前已有的修改，不顺带格式化或重序列化无关文件。
+- 一个长期事实只在一处完整定义，其他文档使用链接。

 ## C# 规则

-### 命名
+### 命名与结构

- 类名、结构体、枚举、属性、方法使用 PascalCase。
- 私有字段使用 `m_` + PascalCase，例如 `m_UserName`、`m_BagPage`。
- 方法参数使用 `_` + camelCase，例如 `_username`、`_maxpage`。
- 局部变量使用 camelCase。
- 常量：同一文件内保持一致，优先使用全大写 + 下划线（如 `C_FRAME_ROOT_PATH`）或 PascalCase。
- 抽象类优先加 `Abs` 前缀，例如 `AbsHFSingleMonoBehaviour<T>`、`AbsHFAssetRequest`。
- 单例管理器优先继承 `AbsHFSingleMonoBehaviour<T>` 或 `AbsHFSingleRunTime<T>`。
- Hotfix 类名可优先加 `HF` 前缀，例如 `HFLoginManager`、`HFBagManager`。
- 业务类型枚举可按用途加前缀，例如 `enItemType`、`enCurrencySubItemType`。
- 事件枚举可按用途加前缀，例如 `enHFSTCEvent`、`enHFCTCEvent`。
+- 类型、属性和方法使用 PascalCase。
+- 私有字段沿用项目 `m_` 前缀，例如 `m_UserName`。
+- 方法参数沿用项目 `_` 前缀，例如 `_userName`。
+- 一个文件原则上只放一个主要类型；partial 和小型辅助类型遵循附近实现。
+- public API 添加简洁中文 XML 注释，说明用途、参数和返回值。
+- 日志包含方法、资源路径、PackageId 或平台等关键上下文，不只输出“失败”。

-### 代码组织
+### 语言兼容性

- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。
- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。
- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。
- 只在解释非显然意图时添加注释，不写无意义注释。
+- 先读取 Unity 版本、asmdef 和附近代码风格，不默认使用最新 C# 语法。
+- 优先使用项目已有的显式类型、普通属性、传统 `switch` 和清晰的回调/协程写法。
+- 非必要时不引入 record、init-only、范围索引、复杂模式匹配、目标类型推断等较新语法。
+- 新语法只有在目标 Unity/编译器已验证且确实降低复杂度时使用。
+- 避免超长方法、深层嵌套和为了封装而封装的辅助层。

-### 日志与异常
+## 框架与业务边界

- 异常只用于异常情况，不用于正常流程控制。
- 错误日志包含方法名和关键上下文，不包含敏感信息。
- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。
+- 业务代码通过 `HFFunCatalogue` 等统一入口访问资源、UI、场景和其他框架能力。
+- 业务功能直接修改 `GameFunction`、`GameMono` 和对应资源。
+- 框架维护任务可以修改 `Assets/StrayFog/Core`、`Assets/StrayFog/Editor` 和 CopyToX 源码，不套用“业务不得改框架”的限制。
+- CopyToX 生成目录禁止手改；生成结果有问题时修正 ESF/General 源码或生成器。
+- 修改 ESF 后必须执行 CopyToX，并检查生成后的 HF 差异。

-### 其他
+## Unity 与异步规则

- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。
- 保持 public API 小而明确。
- 避免超长方法和深层嵌套。
+- Unity API 只在 Unity 主线程调用；后台线程只做不触碰 UnityEngine 对象的工作。
+- StreamingAssets、UnityWebRequest、CDN 和 WebGL 下载使用协程或回调。
+- 禁止在主线程用阻塞式 `while`、忙等或同步等待网络与文件结果。
+- 下载进度只在单文件完整写入并通过 MD5/完整性校验后计数。
+- 平台路径、只读 StreamingAssets、PersistentData 和外部存储回调分别验证。

---
+## UI 与 Prefab

-## 核心库访问规则
+- 修改前同时读取窗口脚本、UIMono、Prefab 层级和相关资源。
+- 单列虚拟列表使用 `SetLoopListViewItemPrefabs`、`InitListView`、`RefreshDataTotalCount`。
+- 多列虚拟列表使用 `SetLoopGridViewItemPrefabs`、`InitGridView`、`RefreshGridDataTotalCount`。
+- 模板节点保持禁用，由列表运行时创建实例；不要依赖旧 LayoutGroup 或 ContentSizeFitter 驱动虚拟列表。
+- Prefab 修改检查锚点、pivot、sizeDelta、组件启用状态、序列化引用和实际显示。
+- 避免文本方式大范围重写 Prefab；优先使用 Unity Editor、MCP 或结构化序列化工具。

-### 核心库范围
+详细规则见 [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md)。

-以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程：
+## 资源与生成规则

-| 路径 | 说明 |
-|------|------|
-| `Assets/StrayFog/Core` | 基础框架核心 |
-| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
-| `Assets/Game/GameGeneralScripte` | 通用工具层 |
+- Prefab、图集、配置、AssetBundle 和代码生成优先修改源资源或生成配置。
+- SpriteAtlas 按模块组织；打图集设置以项目生成器为准。
+- 网络消息以 proto/schema 为源头，生成输出只用于检查。
+- 资源加载、分包、MD5、下载和卸载规则见 [资源管理](../modules/frameworks/资源管理/README.md)。
+- 生成操作后检查 Git 差异，确认没有删除或覆盖用户维护的非生成文件。

-### 访问方式
+## 验证与 Git

-业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：
+- 验证范围随改动范围扩大，最低要求见 [工作流清单](40-工作流清单.md)。
+- 编译通过后仍需检查 Unity Console；UI 和平台逻辑继续做实际运行验证。
+- UnityAI 与目标 Unity 项目分别检查 Git 状态。
+- 只有用户明确要求时才提交或推送，提交格式统一为 `[模块][类型]: 描述`。

-```csharp
-// ✅ 正确：通过统一入口访问
-HFFunCatalogue.UIManager.OpenWindow<LoginWindow>();
-HFFunCatalogue.Asset.LoadAsset<GameObject>("path");
-HFFunCatalogue.Scene.LoadScene("MainScene");
+## 文档规则

-// ❌ 禁止：直接访问核心库
-HFUIWindowMgr.Instance.OpenWindow<LoginWindow>(); // 禁止
-HFABMgr.Instance.LoadAsset<GameObject>("path");   // 禁止
-```
-
-### 禁止操作
-
-| 禁止行为 | 后果 |
-|---------|------|
-| 修改核心库源代码 | 破坏框架稳定性 |
-| 删除/重命名核心库文件 | 编译错误 |
-| 直接实例化核心库内部类 | 违反封装原则 |
-| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 |
-
-### 修改流程
-
-1. 业务人员发现问题/需求 → 提交 Issue 到框架团队
-2. 框架团队评估需求
-3. 合理：开发修复 → 代码审查 → 发布新版本 → 业务团队更新引用
-4. 不合理：反馈拒绝
-
---
-
-## 业务代码结构
-
-### 目录组织
-
-业务代码主要位于 `Assets/Game/GameHFScripte/GameFunction/`，按职责分目录：
-
-```
-Assets/Game/GameHFScripte/GameFunction/
-├── Event/                       # 消息处理
-│   ├── ServerToClient/          # 服务器到客户端消息
-│   ├── ClientToClient/          # 客户端内部消息
-│   └── Handle/                  # 消息处理器
-├── GameRoot/                    # 框架调用入口
-├── Logic/                       # 游戏主要业务逻辑（存放各功能 Manager）
-├── UIWindows/                   # UI 窗口业务逻辑
-├── GameEntity/                  # 游戏实体
-├── SoundManagerPro/             # 音效管理
-├── SceneManager/                # 场景管理
-└── SDK/                         # SDK 集成
-```
-
-### 文件命名
-
-| 文件类型 | 命名规则 | 示例 |
-|---------|---------|-----|
-| 窗口类 | `XXXWindow.cs` | `LoginWindow.cs` |
-| 组件类 | `XXXComponent.cs` | `ItemCellComponent.cs` |
-| 管理器类 | `XXXManager.cs` | `UIManager.cs` |
-| 数据类 | `XXXData.cs` | `PlayerData.cs` |
-| 配置类 | `XXXConfig.cs` | `SkillConfig.cs` |
-
---
-
-## 最佳实践
-
-### 性能优化
-
- 频繁创建销毁的对象必须使用对象池。
- 合理设置对象池初始容量。
- 及时释放不再使用的资源。
- 使用异步加载避免卡顿。
- 合理使用资源缓存。
- 将图标打包到 SpriteAtlas。
- 滚动列表优先使用 `SFUI_ScrollRect.BindEvent`。
-
-### 代码组织
-
- 每个类只负责一个功能，避免庞大的 God 类。
- 通过管理器获取依赖，而非硬编码。
- 使用接口解耦依赖关系。
- 保持 public API 小而明确。
- 避免超长方法和深层嵌套。
-
-### 错误处理
-
- 异常只用于异常情况，不用于正常流程控制。
- 在关键路径添加异常处理。
- 记录错误日志便于排查，但不包含敏感信息。
- 检查参数合法性，处理空引用情况。
-
---
-
-## 常见问题
-
-### 如何扩展核心库功能？
-
-通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。
-
-### 核心库有 Bug 怎么办？
-
-提交 Issue 到框架团队，由框架团队修复并发布新版本。
-
-### 如何调试核心库代码？
-
-可以设置断点调试，但不允许修改代码。
-
-### 常用核心库 API
-
-| 类别 | 管理器 | 常用方法 |
-|-----|-------|---------|
-| 对象池 | `HFObjectMemPool` | `GetItem()`, `GiveBack()` |
-| 事件 | `IHFEventHandle` | `AddListener()`, `Dispatch()` |
-| 资源 | `HFABMgr` | `OnStartLoad()` |
-| 相机 | `HFCameraManager` | `AddCamera()`, `GetCamera()` |
-
---
-
-## Unity 资源规则
-
-### Prefab
-
- Prefab 修改保持聚焦，避免无意义的大范围 reserialize。
- UI Prefab 命名与窗口/面板对应，例如 `Login.prefab`、`ItemWindow.prefab`。
- 通用 UI 组件/Item 使用 `Item` 后缀，例如 `AvatarItem.prefab`、`ResourceItem.prefab`。
- 记录无法从代码复现的手动 Unity Editor 操作。
-
-### Scene
-
- 场景按用途命名，例如 `LoginScene`、`BattleScene`。
- 不要直接在场景里堆放运行时动态加载的资源。
-
-### Sprite Atlas
-
- 按业务或 UI 模块划分图集，例如 `SpriteAtlasAssets/Shop`、`SpriteAtlasAssets/Login`。
- 图集内图片按功能子目录组织，避免单张图集过大。
-
-### Material / Shader
-
- 优先使用项目已有 Shader，不随意引入新 Shader。
- Material 实例在运行时通过代码创建，避免直接修改共享 Material。
-
-### Audio
-
- 音效、背景音乐分目录存放。
- 短音效优先使用 AudioClip + AudioSource 池，长音乐注意卸载。
-
-### 本地化资源
-
- 资源按语言分目录，例如 `GameHFResource/CN/`、`GameHFResource/EN/`。
- 多语言共用资源放在不带语言后缀的公共目录。
-
---
-
-## 配置和数据规则
-
- 优先修改源表、proto 或 schema，而不是生成输出。
- 数据/schema 修改后，按项目流程重新生成。
- 缺失的生成步骤记录到 [工作流清单](40-工作流清单.md) 或对应模块文档。
- 详细规则见 [数据/配置框架](../modules/frameworks/数据配置框架.md)。
-
---
-
-## 网络和 Protobuf 规则
-
- `.proto` 是消息结构源头。
- schema 修改后重新生成 C# 输出。
- route/message-id 映射变化要和 schema 变化一起记录。
- 详细规则见 [网络框架](../modules/frameworks/网络系统.md)。
-
---
-
-## UI 框架规则
-
-UI 窗口、Prefab、层级、生命周期、事件释放和 UIMono 绑定规则见 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
-
---
-
-## 文档编写规则
-
- 每个 `.md` 文件末尾必须包含 **文档关联** 表。
- 模块文档变更必须同步更新 [模块索引](../modules/模块索引.md)。
- 不要在多个文档中重复维护同一份事实表。
- 使用相对路径链接，确保在 GitHub / IDE / AI 工具中均可点击。
- 代码示例必须可编译（或明确标注为伪代码）。
-
---
+- 长期文档只记录稳定架构、公共 API、生成流程和使用规则。
+- 重大变更的讨论和文档落盘方式遵循 [工作流清单](40-工作流清单.md)。
+- 文档使用相对链接；代码示例必须可编译或明确标注伪代码。
+- 模块入口或状态变化时更新 [模块索引](../modules/模块索引.md)。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [rules/项目规则入口.md](项目规则入口.md) | 开发规则是项目规则入口索引的关键规则 |
-| [rules/10-架构说明.md](10-架构说明.md) | 程序集边界、依赖方向与 C# / Unity 规则互相引用 |
-| [modules/模块索引.md](../modules/模块索引.md) | 模块索引中的框架模块文档是开发规则的具体落地 |
-| [UI 框架](../modules/frameworks/UI窗口系统/README.md) | UI 命名、Prefab、层级等规则的具体说明 |
-| [网络框架](../modules/frameworks/网络系统.md) | 网络、Protobuf 规则的具体说明 |
-| [数据/配置框架](../modules/frameworks/数据配置框架.md) | 配置表、生成输出规则的具体说明 |
-| [实体系统](../modules/frameworks/实体系统/README.md) | Entity 编码规范与核心库访问规则落地 |
-| [通用框架](../modules/frameworks/通用框架/README.md) | 核心库范围与通用层规则落地 |
-| [对象池与运行时对象管理](../modules/frameworks/内存对象管理/README.md) | 对象池最佳实践落地 |
+| [架构说明](10-架构说明.md) | 源码与生成目录边界 |
+| [工作流清单](40-工作流清单.md) | 实施与验证流程 |
+| [文档同步规则](50-文档同步规则.md) | 长期文档更新条件 |
+| [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) | UI 专项规范 |
+| [资源管理](../modules/frameworks/资源管理/README.md) | 资源专项规范 |