UnityAI/rules/20-开发规则.md

# 开发规则

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

## 基本原则

- 优先遵循项目已有模式。
- 修改范围保持在当前功能或模块内。
- 不手动修改生成代码，除非生成器不可用且已记录原因。
- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。
- 正常分析项目时忽略 Unity/IDE 本地状态目录。
- 运行时代码不引用 Editor 程序集。
- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。

---

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

### 代码组织

- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。
- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。
- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。
- 只在解释非显然意图时添加注释，不写无意义注释。

### 日志与异常

- 异常只用于异常情况，不用于正常流程控制。
- 错误日志包含方法名和关键上下文，不包含敏感信息。
- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。

### 其他

- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。
- 保持 public API 小而明确。
- 避免超长方法和深层嵌套。

---

## 核心库访问规则

### 核心库范围

以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程：

| 路径 | 说明 |
|------|------|
| `Assets/StrayFog/Core` | 基础框架核心 |
| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
| `Assets/Game/GameGeneralScripte` | 通用工具层 |

### 访问方式

业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：

```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 工具中均可点击。
- 代码示例必须可编译（或明确标注为伪代码）。

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [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) | 对象池最佳实践落地 |