# Story 1.1: 项目基础设施搭建并初始化示例应用
## Status
**Done**
---
## Story
**As a** 控件库开发者，
**I want** 建立完整的项目结构和依赖配置，并创建一个可运行的示例应用，
**so that** 我可以在稳定的基础设施上开始控件开发，并有一个测试载体来验证功能。
---
## Acceptance Criteria
1. 创建 Monorepo 目录结构，包含以下项目：
- `src/Penguin.AvaloniaUI/`（核心控件库，.NET 8 类库）
- `src/Example/`（示例应用，Avalonia 桌面应用）
- `src/Penguin.AvaloniaUI.Tests/`（单元测试项目，xUnit）
2. 配置 `Penguin.AvaloniaUI` 项目的核心依赖：
- Avalonia 11.x（最新稳定版）
- Avalonia.ReactiveUI
- Semi.Avalonia（如果评估后可用）
3. 配置 `Example` 项目引用 `Penguin.AvaloniaUI` 项目
4. Example 应用能够成功启动，显示一个基础窗口，包含：
- 标题："Penguin.AvaloniaUI Demo"
- 一个 TextBlock 显示 "Hello World"
- 窗口大小：800x600
5. 项目能够在 Windows 平台成功编译和运行
6. 创建基础的 `.gitignore` 和 `README.md`
7. 快速评估 Semi.Avalonia 的可用性：
- 如果 Semi.Avalonia 可用，在 Example 中应用其基础样式
- 如果不可用或过于复杂，记录决策并准备自定义样式系统
---
## Tasks / Subtasks
- [X] **Task 1: 创建项目目录结构和解决方案** (AC: 1)
- [X] 创建 `src/Penguin.AvaloniaUI/` 核心控件库项目（.NET 9.0 类库）
- [X] 创建 `src/Example/` 示例应用项目（Avalonia 桌面应用）
- [X] 创建 `src/Penguin.AvaloniaUI.Tests/` 单元测试项目（xUnit）
- [X] 创建或更新解决方案文件 `Penguin.AvaloniaUI.sln`，包含所有三个项目
- [X] 验证所有项目都能成功加载到解决方案中
- [X] **Task 2: 配置统一包版本管理** (AC: 2)
- [X] 创建或更新 `Directory.Packages.props` 文件，配置 Central Package Management
- [X] 添加 Avalonia 11.3.7 包版本定义
- [X] 添加 ReactiveUI.Avalonia 11.3.0 包版本定义
- [X] 添加 xUnit 2.6.6 和 xUnit.runner.visualstudio 2.5.6 包版本定义
- [X] 确保所有项目 `.csproj` 文件启用 `ManagePackageVersionsCentrally`
- [X] **Task 3: 配置 Penguin.AvaloniaUI 核心库项目依赖** (AC: 2)
- [X] 在 `Penguin.AvaloniaUI.csproj` 中添加 Avalonia 包引用（不指定版本号）
- [X] 在 `Penguin.AvaloniaUI.csproj` 中添加 ReactiveUI.Avalonia 包引用
- [X] 创建基本的命名空间结构（Controls/、Layouts/、Themes/、Utils/ 目录）
- [X] 评估 Semi.Avalonia 可用性并记录决策
- [X] 如果 Semi.Avalonia 可用，添加 Semi.Avalonia 包引用
- [X] **Task 4: 配置 Example 示例应用项目** (AC: 3, 4)
- [X] 在 `Example.csproj` 中添加对 `Penguin.AvaloniaUI` 项目的引用
- [X] 在 `Example.csproj` 中添加 Avalonia 桌面应用必需的包引用
- [X] 创建 `App.axaml` 和 `App.axaml.cs` 应用程序入口点
- [X] 创建 `MainWindow.axaml` 和 `MainWindow.axaml.cs` 主窗口
- [X] 在 MainWindow 中设置标题为 "Penguin.AvaloniaUI Demo"
- [X] 在 MainWindow 中添加 TextBlock 显示 "Hello World"
- [X] 设置窗口默认大小为 800x600
- [X] 创建 `Program.cs` 配置 Avalonia 应用启动
- [X] **Task 5: 配置测试项目** (AC: 1)
- [X] 在 `Penguin.AvaloniaUI.Tests.csproj` 中添加 xUnit 包引用
- [X] 在测试项目中添加对 `Penguin.AvaloniaUI` 项目的引用
- [X] 创建测试项目的目录结构（Controls/、Layouts/、Themes/、Utils/）
- [X] 创建一个简单的占位测试类验证测试框架工作正常
- [X] **Task 6: 编译和运行验证** (AC: 5)
- [X] 执行 `dotnet build` 确保所有项目成功编译
- [X] 执行 `dotnet test` 确保测试项目可以运行
- [X] 启动 Example 应用，验证窗口正确显示
- [X] 验证窗口标题、TextBlock 内容和窗口尺寸符合要求
- [X] **Task 7: 创建项目文档和配置文件** (AC: 6)
- [X] 验证并更新 `.gitignore` 文件（应已存在）
- [X] 更新 `README.md` 添加项目简介、技术栈和快速开始指南
- [X] 验证 `.editorconfig` 文件存在且配置正确
- [X] 在 README 中记录 Semi.Avalonia 评估决策
---
## Dev Notes
本节包含从架构文档中提取的所有相关技术信息，开发者应仔细阅读以确保实现符合项目标准。
### Technology Stack
[Source: docs/architecture/tech-stack.md]
本项目使用以下技术栈，开发时必须严格遵守：
| Technology | Version | Purpose |
| ------------------------- | ------- | ----------------------------------------------------------- |
| .NET | 9.0 | 应用运行时环境（注意：需要从原计划的 .NET 8 更新为 .NET 9） |
| Avalonia | 11.3.7 | 跨平台桌面 UI 框架 |
| ReactiveUI.Avalonia | 11.3.0 | 响应式 MVVM 实现 |
| xUnit | 2.6.6 | 单元测试框架 |
| xUnit.runner.visualstudio | 2.5.6 | Visual Studio 测试运行器 |
**重要：统一包版本管理**
项目使用 Central Package Management，在 `Directory.Packages.props` 中集中管理所有包版本：
```xml
true
```
在各项目的 `.csproj` 文件中引用包时**不指定版本号**：
```xml
```
### Project Structure
[Source: docs/architecture/unified-project-structure.md]
Monorepo 项目结构必须按照以下组织：
```
D:\32_avalonia.ui/
├── src/
│ ├── Penguin.AvaloniaUI/ # 核心控件库项目
│ │ ├── Controls/ # 业务场景控件（命名空间: Penguin.AvaloniaUI.Controls.*）
│ │ ├── Layouts/ # 布局控件（命名空间: Penguin.AvaloniaUI.Layouts）
│ │ ├── Themes/ # 主题系统（命名空间: Penguin.AvaloniaUI.Themes）
│ │ ├── Utils/ # 工具类（命名空间: Penguin.AvaloniaUI.Utils.*）
│ │ ├── Assets/ # 资源文件
│ │ ├── Penguin.AvaloniaUI.csproj
│ │ └── AssemblyInfo.cs
│ │
│ ├── Example/ # 示例应用项目
│ │ ├── App.axaml
│ │ ├── App.axaml.cs
│ │ ├── ViewModels/ # 视图模型
│ │ │ └── MainWindowViewModel.cs
│ │ ├── Views/ # 视图/页面
│ │ │ ├── MainWindow.axaml
│ │ │ ├── MainWindow.axaml.cs
│ │ │ └── Pages/
│ │ ├── Models/ # 测试数据模型
│ │ ├── Assets/
│ │ ├── Example.csproj
│ │ └── Program.cs
│ │
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试项目
│ ├── Controls/
│ ├── Layouts/
│ ├── Themes/
│ ├── Utils/
│ └── Penguin.AvaloniaUI.Tests.csproj
├── docs/ # 项目文档
├── .editorconfig
├── .gitignore
├── Directory.Packages.props
├── README.md
└── Penguin.AvaloniaUI.sln
```
**关键命名空间映射：**
- Controls/ → `Penguin.AvaloniaUI.Controls.*`
- Layouts/ → `Penguin.AvaloniaUI.Layouts`
- Themes/ → `Penguin.AvaloniaUI.Themes`
- Utils/ → `Penguin.AvaloniaUI.Utils.*`
### Coding Standards
[Source: docs/architecture/coding-standards.md]
**命名空间组织规则：**
- 使用文件范围命名空间（File-scoped namespace），减少缩进层级
- 命名空间单独一行，格式：`namespace Penguin.AvaloniaUI.Controls;`
**命名约定：**
- 控件类：PascalCase，功能名称 + 控件类型后缀（例：`PropertyGrid`, `TwoColumnLayout`）
- 私有字段：camelCase，下划线前缀（例：`_currentTheme`）
- 方法：PascalCase，动词开头（例：`ApplyTheme()`, `RefreshProperties()`）
**代码风格（基于 .editorconfig）：**
```ini
[*.cs]
indent_style = space
indent_size = 4
end_of_line = crlf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[*.axaml]
indent_size = 2
```
**关键规则：**
- XML 文档注释：所有 `public` 和 `protected` 成员必须有 XML 注释（`///`）
- 错误处理：公开 API 方法必须验证参数（如 `ArgumentNullException`）
- 使用 `var` 声明局部变量
**代码格式化检查：**
```bash
dotnet format --verify-no-changes
```
### Example Application Structure
示例应用必须包含以下核心文件：
**Program.cs** - 应用程序入口点：
```csharp
using Avalonia;
using System;
namespace Example;
class Program
{
[STAThread]
public static void Main(string[] args) => BuildAvaloniaApp()
.StartWithClassicDesktopLifetime(args);
public static AppBuilder BuildAvaloniaApp()
=> AppBuilder.Configure()
.UsePlatformDetect()
.LogToTrace();
}
```
**App.axaml** - 应用程序资源：
```xml
```
**MainWindow.axaml** - 主窗口（AC 4 要求）：
```xml
```
### Semi.Avalonia Evaluation
在配置核心库依赖时，需要快速评估 Semi.Avalonia 的可用性：
**评估步骤：**
1. 尝试通过 NuGet 查找 `Semi.Avalonia` 包
2. 检查包的文档和示例
3. 评估集成复杂度（时间成本 < 1 小时）
**决策标准：**
- 如果可用且集成简单：添加到 Directory.Packages.props 并在 Example 中引用
- 如果不可用或过于复杂：记录在 README 中，并注明将使用自定义样式系统（后续故事实现）
**记录格式（README.md）：**
```markdown
## Style System Decision
- **Date**: [当前日期]
- **Decision**: [使用 Semi.Avalonia / 使用自定义样式系统]
- **Rationale**: [简短说明原因]
```
### Testing
[Source: docs/architecture/testing-strategy.md]
**测试项目配置：**
- 测试框架：xUnit 2.6.6
- 测试项目命名：`Penguin.AvaloniaUI.Tests`
- 测试文件组织：按照源代码目录结构镜像组织（Controls/、Layouts/、Themes/、Utils/）
**测试命名约定：**
- 测试类：`{ClassName}Tests`
- 测试方法：`{MethodName}_{Scenario}_{ExpectedResult}`
**示例占位测试类：**
```csharp
namespace Penguin.AvaloniaUI.Tests;
public class PlaceholderTests
{
[Fact]
public void SampleTest_WithValidInput_ShouldPass()
{
// Arrange
var expected = true;
// Act
var actual = true;
// Assert
Assert.Equal(expected, actual);
}
}
```
**运行测试：**
```bash
# 运行所有测试
dotnet test
# 运行特定测试类
dotnet test --filter "FullyQualifiedName~PlaceholderTests"
```
### Project Configuration Files
**.editorconfig** - 已存在于项目根目录，确保一致的代码格式
**.gitignore** - 已存在于项目根目录，包含 .NET 和 Avalonia 相关忽略规则
**Directory.Packages.props** - 如果已存在则更新，否则创建新文件
### Build and Run Commands
**编译所有项目：**
```bash
dotnet build
```
**运行测试：**
```bash
dotnet test
```
**运行示例应用：**
```bash
dotnet run --project src/Example/Example.csproj
```
**格式化代码：**
```bash
dotnet format
```
### Important Notes
1. **目标框架版本**：AC 中提到 .NET 8，但 Tech Stack 指定 .NET 9.0，请使用 .NET 9.0
2. **项目引用**：Example 项目必须通过项目引用（ProjectReference）而非包引用（PackageReference）来引用 Penguin.AvaloniaUI
3. **初始目录创建**：在创建项目时，必须同时创建 Controls/、Layouts/、Themes/、Utils/ 等子目录，即使它们暂时为空
4. **Semi.Avalonia**：这是一个可选依赖，评估时间不应超过合理范围，如果遇到困难应选择自定义实现方案
---
## Change Log
| Date | Version | Description | Author |
| ---------- | ------- | ---------------------- | ------------------ |
| 2025-10-16 | 1.0 | Initial story creation | Scrum Master (Bob) |
---
## Dev Agent Record
### Agent Model Used
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
### Debug Log References
无调试问题
### Completion Notes
- ✅ 所有 7 个任务及其子任务已成功完成
- ✅ Semi.Avalonia 评估结果：可用且集成简单（版本 11.2.1.9），已成功集成
- ✅ 编译成功：所有 3 个项目（核心库、示例应用、测试项目）
- ✅ 测试通过：1/1 测试用例通过
- ✅ 示例应用成功启动并运行，显示正确的窗口标题和内容
- ✅ Central Package Management 已配置，所有包版本统一管理
- ✅ 项目结构符合架构规范，所有必需的子目录已创建
- ✅ 文档已完成：README.md（中文）、.editorconfig 已更新
**关键决策：**
- 使用 Semi.Avalonia 作为样式系统（xmlns:semi="https://irihi.tech/semi"）
- 使用 Context7 工具查找 API 使用方法，成功解决了 Semi.Avalonia 命名空间问题
### File List
**新建文件：**
- Directory.Packages.props（统一包版本管理）
- src/Penguin.AvaloniaUI/Controls/（目录）
- src/Penguin.AvaloniaUI/Layouts/（目录）
- src/Penguin.AvaloniaUI/Themes/（目录）
- src/Penguin.AvaloniaUI/Utils/（目录）
- src/Penguin.AvaloniaUI/Assets/（目录）
- src/Example/Views/MainWindow.axaml
- src/Example/Views/MainWindow.axaml.cs
- src/Example/ViewModels/（目录）
- src/Example/Models/（目录）
- src/Example/Assets/（目录）
- src/Penguin.AvaloniaUI.Tests/PlaceholderTests.cs
- src/Penguin.AvaloniaUI.Tests/Controls/（目录）
- src/Penguin.AvaloniaUI.Tests/Layouts/（目录）
- src/Penguin.AvaloniaUI.Tests/Themes/（目录）
- src/Penguin.AvaloniaUI.Tests/Utils/（目录）
- README.md
**修改文件：**
- src/Penguin.AvaloniaUI/Penguin.AvaloniaUI.csproj（移除硬编码版本号）
- src/Example/Example.csproj（添加 Semi.Avalonia，移除硬编码版本号）
- src/Example/App.axaml（添加 Semi.Avalonia 主题）
- src/Example/App.axaml.cs（更新命名空间为 file-scoped）
- src/Penguin.AvaloniaUI.Tests/Penguin.AvaloniaUI.Tests.csproj（修正 xUnit 版本，移除硬编码版本号）
- .editorconfig（添加 C# 和 AXAML 规则）
---
## QA Results
### Review Date: 2025-10-16
### Reviewed By: Quinn (Test Architect)
### Code Quality Assessment
**Overall Grade: EXCELLENT (98/100)**
本次审查针对 Story 1.1 的项目基础设施搭建进行了全面的质量验证。实现质量非常高,所有验收标准完全满足,项目结构清晰,技术选型合理。开发者展现了对 Avalonia、.NET 9.0 和现代化 C# 开发实践的深刻理解。
**优点:**
- ✅ 项目结构完全符合架构文档规范
- ✅ Central Package Management 配置正确,版本管理统一
- ✅ 命名空间组织合理,使用 file-scoped namespace
- ✅ .editorconfig 配置完善,代码风格一致
- ✅ Semi.Avalonia 集成成功,决策记录清晰
- ✅ README.md 内容完整,包含技术栈和快速开始指南
- ✅ 所有项目成功编译,测试通过
### Refactoring Performed
在审查过程中,QA Agent 执行了以下代码质量改进:
- **Files**: `src/Example/App.axaml.cs`, `src/Example/Program.cs`, `src/Example/Views/MainWindow.axaml.cs`
- **Change**: 修复行尾符从 LF 转换为 CRLF
- **Why**: 项目配置要求使用 CRLF (Windows 标准),确保跨团队协作时的一致性
- **How**: 使用 `dotnet format` 自动修复所有格式问题,确保符合 .editorconfig 规范
### Compliance Check
- ✓ **Coding Standards**: 完全符合 `docs/architecture/coding-standards.md`
- 命名空间使用 file-scoped 格式 ✓
- 命名约定正确 (PascalCase for classes, camelCase with underscore for private fields) ✓
- 代码格式符合 .editorconfig (修复后) ✓
- ✓ **Project Structure**: 完全符合 `docs/architecture/unified-project-structure.md`
- Monorepo 结构正确 (src/Penguin.AvaloniaUI, src/Example, src/Penguin.AvaloniaUI.Tests) ✓
- 子目录组织合理 (Controls/, Layouts/, Themes/, Utils/) ✓
- 命名空间映射正确 ✓
- ✓ **Testing Strategy**: 符合 `docs/architecture/testing-strategy.md`
- xUnit 2.6.6 配置正确 ✓
- 测试项目结构镜像源代码组织 ✓
- 占位测试类命名符合约定 (PlaceholderTests) ✓
- ✓ **All ACs Met**: 所有 7 个验收标准完全满足
- AC1: Monorepo 结构 ✓
- AC2: 核心依赖配置 ✓
- AC3: 项目引用 ✓
- AC4: 示例应用 ✓
- AC5: 编译和运行 ✓
- AC6: 文档 ✓
- AC7: Semi.Avalonia 评估 ✓
### Requirements Traceability (Given-When-Then)
**AC1 - 项目结构:**
- Given: 需要创建 Monorepo 目录结构
- When: 开发者创建三个项目并配置解决方案
- Then: `Penguin.AvaloniaUI.sln` 包含所有三个项目且目录结构符合规范
- **Test Coverage**: ✅ 通过目录结构验证和编译测试
**AC2 - 核心依赖:**
- Given: 需要配置 Avalonia 11.3.7 和 ReactiveUI.Avalonia 11.3.0
- When: 使用 Central Package Management 统一管理包版本
- Then: `Directory.Packages.props` 包含正确版本,项目文件不含硬编码版本
- **Test Coverage**: ✅ 通过编译验证和包引用检查
**AC3 - 项目引用:**
- Given: Example 项目需要使用 Penguin.AvaloniaUI 库
- When: 通过 ProjectReference 引用核心库
- Then: Example 可以编译并访问 Penguin.AvaloniaUI 的类型
- **Test Coverage**: ✅ 通过编译验证
**AC4 - 示例应用:**
- Given: 需要创建可运行的示例应用
- When: 配置 MainWindow 和 App 入口点
- Then: 应用启动并显示 "Penguin.AvaloniaUI Demo" 窗口 (800x600) 和 "Hello World" 文本
- **Test Coverage**: ✅ 通过运行验证 (Dev Agent 报告)
**AC5 - 编译和运行:**
- Given: 所有项目需要在 Windows 平台成功编译
- When: 执行 `dotnet build` 和 `dotnet test`
- Then: 编译成功 (0 错误),测试通过 (1/1)
- **Test Coverage**: ✅ 通过自动化构建和测试
**AC6 - 文档:**
- Given: 需要基础文档和配置文件
- When: 创建 .gitignore, README.md, .editorconfig
- Then: 所有文件存在且内容完整
- **Test Coverage**: ✅ 通过文件存在性和内容验证
**AC7 - Semi.Avalonia 评估:**
- Given: 需要快速评估 Semi.Avalonia 可用性
- When: 尝试集成并记录决策
- Then: Semi.Avalonia 11.2.1.9 成功集成,决策记录在 README.md
- **Test Coverage**: ✅ 通过编译验证和文档检查
### Test Architecture Assessment
**测试覆盖率:** 基础设施项目,测试范围适当
- **当前测试:** 1 个占位测试 (PlaceholderTests.SampleTest_WithValidInput_ShouldPass)
- **评估:** ✅ PASS - 对于基础设施搭建故事,占位测试是适当的
- 故事重点是项目配置和结构,而非业务逻辑实现
- 测试框架已正确配置并可运行
- 后续故事将添加实际功能测试
**测试设计质量:**
- 测试命名遵循约定: `{MethodName}_{Scenario}_{ExpectedResult}` ✓
- 测试结构清晰: Arrange-Act-Assert 模式 ✓
- xUnit 配置正确,包含 coverlet 代码覆盖率工具 ✓
**建议 (非阻塞):**
- 未来故事中为每个控件添加单元测试
- 考虑添加集成测试验证 Semi.Avalonia 主题加载
### Non-Functional Requirements (NFRs)
**Security:** ✅ PASS
- 无安全敏感代码
- .gitignore 正确配置,不会泄露敏感信息
**Performance:** ✅ PASS
- 编译时间: 1.69秒 (优秀)
- 测试执行时间: 3ms (优秀)
- 无性能瓶颈
**Reliability:** ✅ PASS
- 所有测试通过 (1/1)
- 编译无错误或警告
- 项目依赖版本稳定
**Maintainability:** ✅ PASS
- 代码清晰,命名准确
- 项目结构逻辑清晰
- 文档完整
- 遵循现代 C# 编码规范
### Risk Profile
**总体风险等级: 低 (Low)**
| 风险类别 | 等级 | 说明 |
| -------- | ---- | ----------------------------- |
| 安全风险 | 低 | 基础设施项目,无安全敏感操作 |
| 性能风险 | 低 | 编译和运行性能良好 |
| 维护风险 | 低 | 代码清晰,结构合理 |
| 技术债务 | 极低 | 格式问题已修复,无明显技术债务 |
### Improvements Checklist
审查中已完成:
- [X] 修复代码格式化问题 (LF → CRLF)
- [X] 验证所有 AC 完全满足
- [X] 验证编译和测试通过
- [X] 验证项目结构符合架构规范
无需 Dev 处理的改进项 (未来考虑):
- [ ] 在 CI 流程中添加 `dotnet format --verify-no-changes` 检查
- [ ] 考虑配置 IDE 自动应用 .editorconfig 设置
### Security Review
**安全评估: 无风险 (Not Applicable)**
本故事为基础设施搭建,不涉及:
- 用户认证或授权
- 数据存储或传输
- 外部 API 调用
- 敏感信息处理
未来故事中需要关注的安全要点:
- PropertyGrid 反射操作的安全边界
- 主题系统中的资源加载安全
- 文件对话框的路径验证
### Performance Considerations
**性能评估: 优秀**
实测性能指标:
- 编译时间: 1.69秒 (3个项目)
- 测试执行时间: 3ms (1个测试)
- 应用启动时间: 正常 (Dev Agent 验证)
无性能瓶颈或优化需求。
### Files Modified During Review
QA Agent 在审查过程中修改了以下文件:
**修改文件 (代码格式化):**
- `src/Example/App.axaml.cs` (行尾符修复: LF → CRLF)
- `src/Example/Program.cs` (行尾符修复: LF → CRLF)
- `src/Example/Views/MainWindow.axaml.cs` (行尾符修复: LF → CRLF)
**新建文件 (QA 输出):**
- `docs/qa/gates/1.1-project-infrastructure-setup.yml` (质量门决策文件)
**注意:** Dev Agent 需要在下次提交时更新 Story 的 File List,将 QA 修改的文件和新建的质量门文件加入记录。
### Gate Status
**Gate: PASS** → `docs/qa/gates/1.1-project-infrastructure-setup.yml`
**Quality Score: 98/100**
决策理由:
- 所有 7 个验收标准完全满足
- 代码质量优秀,符合所有编码标准
- 编译和测试全部通过
- 项目结构完全符合架构规范
- 唯一发现的格式问题已在审查中修复
### Recommended Status
**✓ Ready for Done**
本故事已完全完成,质量优秀,建议标记为 Done 并进入下一个 Story 的开发。
**后续行动:**
1. Scrum Master 或 Product Owner 进行最终验收
2. Dev Agent 可以开始 Story 1.2 (如果存在) 的开发
3. 无需返工或额外修改