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

# 开发规则

## 基本原则

- 先读取附近代码和模块文档，再决定实现方式。
- 修改范围保持聚焦，优先复用项目已有模式和公开入口。
- 真实源码、生成代码、业务代码和资源必须按 [架构说明](10-架构说明.md) 区分。
- 不回退任务开始前已有的修改，不顺带格式化或重序列化无关文件。
- 一个长期事实只在一处完整定义，其他文档使用链接。

## C# 规则

### 命名与结构

- 类型、属性和方法使用 PascalCase。
- 私有字段沿用项目 `m_` 前缀，例如 `m_UserName`。
- 方法参数沿用项目 `_` 前缀，例如 `_userName`。
- 一个文件原则上只放一个主要类型；partial 和小型辅助类型遵循附近实现。
- public API 添加简洁中文 XML 注释，说明用途、参数和返回值。
- 日志包含方法、资源路径、PackageId 或平台等关键上下文，不只输出“失败”。

### 语言兼容性

- 先读取 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 与异步规则

- 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)。

## 资源与生成规则

- Prefab、图集、配置、AssetBundle 和代码生成优先修改源资源或生成配置。
- SpriteAtlas 按模块组织；打图集设置以项目生成器为准。
- 网络消息以 proto/schema 为源头，生成输出只用于检查。
- 资源加载、分包、MD5、下载和卸载规则见 [资源管理](../modules/frameworks/资源管理/README.md)。
- 生成操作后检查 Git 差异，确认没有删除或覆盖用户维护的非生成文件。

## 验证与 Git

- 验证范围随改动范围扩大，最低要求见 [工作流清单](40-工作流清单.md)。
- 编译通过后仍需检查 Unity Console；UI 和平台逻辑继续做实际运行验证。
- UnityAI 与目标 Unity 项目分别检查 Git 状态。
- Git 提交规则见 [项目规则入口](项目规则入口.md)。

## 文档规则

- 长期文档只记录稳定架构、公共 API、生成流程和使用规则。
- 重大变更的讨论和文档落盘方式遵循 [工作流清单](40-工作流清单.md)。
- 文档使用相对链接；代码示例必须可编译或明确标注伪代码。
- 模块入口或状态变化时更新 [模块索引](../modules/模块索引.md)。

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [架构说明](10-架构说明.md) | 源码与生成目录边界 |
| [工作流清单](40-工作流清单.md) | 实施与验证流程 |
| [文档同步规则](50-文档同步规则.md) | 长期文档更新条件 |
| [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) | UI 专项规范 |
| [资源管理](../modules/frameworks/资源管理/README.md) | 资源专项规范 |