docs: update architecture

2025-10-16 15:08:42 +08:00
parent 6b4c227d3c
commit 6c17e02731
15 changed files with 4889 additions and 18 deletions
--- a/docs/architecture/development-workflow.md
+++ b/docs/architecture/development-workflow.md
@@ -0,0 +1,180 @@
+# Development Workflow
+
+本节定义控件库的开发环境配置和日常开发流程，确保开发者能够快速上手并保持高效开发。
+
+---
+
+### Local Development Setup
+
+**前置要求：**
+
+```bash
+# 必需
+- .NET 9.0 SDK (https://dotnet.microsoft.com/download)
+- Visual Studio 2022 (17.8+)
+- Git 2.40+
+
+# 推荐
+- Visual Studio Avalonia 扩展 (用于 XAML 预览)
+```
+
+**初始化项目：**
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd 32_avalonia.ui
+
+# 还原 NuGet 包
+dotnet restore
+
+# 构建解决方案
+dotnet build
+
+# 运行示例应用
+dotnet run --project src/Example/Example.csproj
+```
+
+**Visual Studio 配置：**
+
+1. 打开 `Penguin.AvaloniaUI.sln`
+2. 设置 `Example` 为启动项目
+3. 选择调试配置（Debug/Release）
+4. 按 F5 启动调试
+
+---
+
+### Development Commands
+
+**常用命令：**
+
+```bash
+# 启动示例应用（开发模式，支持热重载）
+dotnet watch --project src/Example/Example.csproj
+
+# 运行所有单元测试
+dotnet test
+
+# 运行特定测试类
+dotnet test --filter "FullyQualifiedName~PropertyGridTests"
+
+# 生成代码覆盖率报告
+dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=html
+
+# 清理构建产物
+dotnet clean
+
+# 格式化代码（基于 .editorconfig）
+dotnet format
+
+# 打包 NuGet 包（Post-MVP）
+dotnet pack src/Penguin.AvaloniaUI/Penguin.AvaloniaUI.csproj -c Release
+```
+
+---
+
+### Hot Reload 配置
+
+Avalonia 11.x 支持 .NET Hot Reload，但有限制：
+
+**支持的修改：**
+- C# 方法体内的代码修改
+- XAML 资源字典的修改（颜色、样式）
+- 部分 XAML 控件属性修改
+
+**不支持的修改（需要重启）：**
+- 新增或删除控件
+- 修改控件模板结构
+- 修改依赖属性定义
+- 修改 ViewModel 属性签名
+
+**启用 Hot Reload：**
+
+在 `Example.csproj` 中确保已启用：
+
+```xml
+<PropertyGroup>
+  <AvaloniaUseHotReload>true</AvaloniaUseHotReload>
+</PropertyGroup>
+```
+
+---
+
+### Environment Configuration
+
+**控件库无需环境变量**（MVP 阶段），但示例应用可能需要：
+
+```bash
+# Example/.env (可选，用于测试外部 API 集成)
+# MVP 阶段不需要
+```
+
+**调试配置（launchSettings.json）：**
+
+```json
+{
+  "profiles": {
+    "Example": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Git Workflow
+
+**Commit Message 格式（Conventional Commits）：**
+
+```
+<type>: <description>
+
+[optional body]
+```
+
+**Type 类型：**
+- `feat`: 新功能（如 `feat: 增加了UserControl的DarkStyle`）
+- `fix`: Bug 修复（如 `fix: 修复PropertyGrid在主题切换时崩溃`）
+- `refactor`: 重构（如 `refactor: 优化ThemeManager的资源加载逻辑`）
+- `test`: 测试相关（如 `test: 添加PropertyGrid的分组功能测试`）
+- `docs`: 文档更新（如 `docs: 更新README的快速开始指南`）
+- `style`: 代码格式调整（如 `style: 统一缩进为4空格`）
+- `chore`: 构建/工具相关（如 `chore: 升级Avalonia到11.3.8`）
+
+**示例：**
+```bash
+git commit -m "feat: 实现PropertyGrid的属性分组功能"
+git commit -m "fix: 修复TwoColumnLayout在窗口缩放时的对齐问题"
+git commit -m "test: 添加ThemeManager的主题切换测试"
+```
+
+**分支命名规范：**
+- `feat/<feature-name>` - 新功能分支（如 `feat/usercontrol`）
+- `fix/<issue-number>` - Bug 修复分支（如 `fix/1123`）
+- `refactor/<description>` - 重构分支（如 `refactor/theme-system`）
+- `test/<description>` - 测试分支（如 `test/integration`）
+
+**日常开发流程：**
+
+1. **创建功能分支**：`git checkout -b feat/two-column-layout`
+2. **编写代码**：在 `src/Penguin.AvaloniaUI/` 中实现控件
+3. **编写测试**：在 `src/Penguin.AvaloniaUI.Tests/` 中添加单元测试
+4. **更新示例**：在 `src/Example/Views/Pages/` 中添加演示页面
+5. **本地验证**：
+   - 运行单元测试：`dotnet test`
+   - 启动示例应用：`dotnet run --project src/Example`
+   - 手动测试主题切换和控件交互
+6. **提交代码**：
+   ```bash
+   git add .
+   git commit -m "feat: 实现TwoColumnLayout布局控件"
+   git push origin feat/two-column-layout
+   ```
+
+---
+