# 贡献指南

感谢你为 Space Engineers Blueprint Editor 提交改进。项目同时跨越 WinUI 3、WPF、.NET 8、.NET Framework 4.8 和《Space Engineers》游戏 API；较小、目标明确且可复现的变更最容易审查。

## 开始之前

1. 阅读 [README](README.md)、[开发指南](docs/DEVELOPMENT.md)和[架构说明](docs/ARCHITECTURE.md)。
2. 搜索已有 Issue，确认问题没有被重复报告。
3. 对大范围架构调整，先用 Issue 说明目标、兼容性影响和迁移方式。
4. 准备一个无 Mod、体积小且可公开的测试蓝图，保留原始副本。

## 报告问题

一个可操作的问题报告应包含：

- 应用版本或提交哈希。
- Windows 与《Space Engineers》版本。
- 游戏安装来源和非默认路径信息；不要粘贴隐私敏感的完整用户名路径。
- 复现步骤、期望行为和实际行为。
- 错误文本、相关日志或截图。
- 蓝图是否使用 DLC、Mod、旧版方块或 Steam Cloud。
- 若能安全共享，提供最小复现蓝图；提交前清理个人信息。

请勿上传游戏 DLL、`Content` 资源、Steam 凭据或无权分发的工坊内容。

## 开发流程

1. 从最新目标分支创建功能分支。
2. 只修改解决问题所需的文件，保留工作区中不相关的用户改动。
3. 遵循现有命名、可空性和 MVVM 模式。
4. 同时更新受影响的中英文资源和文档。
5. 在 `Debug|x64` 下构建并完成相应手工验证。
6. 提交简洁、可独立理解的 commit。

推荐的基本验证命令：

```powershell
dotnet build SpaceEngineersBlueprintEditor.sln -c Debug -p:Platform=x64 --nologo
```

游戏路径配置见[开发指南的游戏目录检测章节](docs/DEVELOPMENT.md#游戏目录检测)。

## 代码约定

### 通用原则

- 启用并尊重可空引用类型，不用无意义的 `!` 隐藏真实问题。
- 优先使用清晰的类型和方法名；注释解释原因、约束和游戏 API 怪异点。
- 不在 UI 线程执行蓝图反序列化、定义扫描或图像转换等重任务。
- 对文件覆盖、递归删除、升级和缓存清理等操作提供明确确认与错误反馈。
- 新异步流程应考虑异常传播、重复触发和页面离开后的生命周期。
- 不把本机绝对路径、服务器凭据或个人配置写入源码。

### WinUI 与 MVVM

- 页面状态和命令放在 ViewModel；只有控件事件桥接或窗口句柄等 UI 专属逻辑留在 code-behind。
- 使用现有 `ServiceManager`、导航参数服务和消息/加载服务，避免新建平行的全局状态系统。
- 用户可见文本必须本地化。XAML 优先使用 `x:Uid`，C# 使用现有 `GetLocalized()` 方式。
- 大集合使用延迟加载或增量处理，避免在主线程一次性反射完整蓝图树。

### 游戏 API 与核心层

- 必须在首次使用游戏类型前初始化 `GameAssemblyLoader`。
- 游戏程序集引用保持 `Private=false`，不要复制或提交 `Bin64` DLL。
- `SpaceEngineersCore` 面向 `net48`；使用新 C# 特性前确认目标框架所需的编译器辅助类型。
- 对未知、Mod 或版本不匹配的定义采用可诊断的降级行为，不要静默生成无效方块。
- 修改 `InnerModel` 平台/渲染桩时，只实现调用路径需要的最小语义，并记录触发原因。

### 文件与保存

- 所有保存操作都应尽量使用同目录临时文件和原子替换。
- 保留或明确处理游戏的 `sbcB5` 备份语义。
- 只反序列化本应用生成的带类型 JSON；不要把 `TypeNameHandling` 用于不受信任输入。
- 测试删除、覆盖或迁移逻辑时使用临时目录，不使用真实玩家蓝图目录。

### 三维与钣金编辑

- 修改三维消息协议时同步更新 C# 场景模型、ViewModel、WebView2 桥接和本地 HTML。
- 本地 WebView 资源不得引入远程脚本；保持虚拟主机映射和消息输入边界清晰。
- 变换方块时同步维护方块组等坐标引用，并验证多格方块占位。
- Skeleton 偏移必须限制在游戏可编码范围，中性 Bone 应移除而不是重复写入。
- 明确撤销/重做覆盖范围，不要让界面暗示未记录的操作可以撤销。

## 文档约定

- Markdown 使用相对链接，确保 GitHub 仓库和本地查看都能工作。
- Mermaid 使用 GitHub 支持的语法；节点中包含空格、括号或标点时使用引号。
- 功能说明以已经接入 UI 且可验证的行为为准，实验代码要标注状态。
- 构建命令使用 PowerShell 示例，并说明 x64 与游戏路径要求。
- 改动功能、路径、项目结构或限制时，同步更新 README 和对应专题文档。

## 验证清单

根据改动范围完成以下项目：

- [ ] 解决方案 `Debug|x64` 构建无错误。
- [ ] 没有新增或提交游戏 DLL、个人蓝图、缓存、`bin`、`obj` 或本机配置。
- [ ] 应用能自动或通过显式路径加载游戏。
- [ ] 受影响的蓝图可读取、另存并在游戏测试世界中验证。
- [ ] 若修改编辑器，三维选择/变换/撤销和钣金 Bone 写入均已用测试副本验证。
- [ ] 对未知定义、缺文件和无效路径有可理解的错误信息。
- [ ] 英文与简体中文资源键同步。
- [ ] Markdown 链接、代码块、表格和 Mermaid 图可渲染。
- [ ] 当前仓库没有标准自动化测试覆盖的部分已说明手工验证方法。

## Pull Request 说明

PR 描述请包含：

- 解决了什么问题，为什么这样实现。
- 影响的项目和用户流程。
- 验证环境与验证结果。
- UI 变更前后截图或短视频。
- 蓝图格式、保存兼容性、游戏版本或发布布局风险。
- 尚未解决的问题和后续工作。

尽量避免把重构、依赖升级、格式化和功能修改混在同一个 PR 中。

## 许可证

提交代码或文档即表示你有权贡献这些内容，并同意其按仓库的 [MIT License](LICENSE.txt) 分发。