# Story 1.1: 项目基础设施搭建并初始化示例应用

## Status

**Draft**

---

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

- [ ] **Task 1: 创建项目目录结构和解决方案** (AC: 1)
  - [ ] 创建 `src/Penguin.AvaloniaUI/` 核心控件库项目（.NET 9.0 类库）
  - [ ] 创建 `src/Example/` 示例应用项目（Avalonia 桌面应用）
  - [ ] 创建 `src/Penguin.AvaloniaUI.Tests/` 单元测试项目（xUnit）
  - [ ] 创建或更新解决方案文件 `Penguin.AvaloniaUI.sln`，包含所有三个项目
  - [ ] 验证所有项目都能成功加载到解决方案中

- [ ] **Task 2: 配置统一包版本管理** (AC: 2)
  - [ ] 创建或更新 `Directory.Packages.props` 文件，配置 Central Package Management
  - [ ] 添加 Avalonia 11.3.7 包版本定义
  - [ ] 添加 ReactiveUI.Avalonia 11.3.0 包版本定义
  - [ ] 添加 xUnit 2.6.6 和 xUnit.runner.visualstudio 2.5.6 包版本定义
  - [ ] 确保所有项目 `.csproj` 文件启用 `ManagePackageVersionsCentrally`

- [ ] **Task 3: 配置 Penguin.AvaloniaUI 核心库项目依赖** (AC: 2)
  - [ ] 在 `Penguin.AvaloniaUI.csproj` 中添加 Avalonia 包引用（不指定版本号）
  - [ ] 在 `Penguin.AvaloniaUI.csproj` 中添加 ReactiveUI.Avalonia 包引用
  - [ ] 创建基本的命名空间结构（Controls/、Layouts/、Themes/、Utils/ 目录）
  - [ ] 评估 Semi.Avalonia 可用性并记录决策
  - [ ] 如果 Semi.Avalonia 可用，添加 Semi.Avalonia 包引用

- [ ] **Task 4: 配置 Example 示例应用项目** (AC: 3, 4)
  - [ ] 在 `Example.csproj` 中添加对 `Penguin.AvaloniaUI` 项目的引用
  - [ ] 在 `Example.csproj` 中添加 Avalonia 桌面应用必需的包引用
  - [ ] 创建 `App.axaml` 和 `App.axaml.cs` 应用程序入口点
  - [ ] 创建 `MainWindow.axaml` 和 `MainWindow.axaml.cs` 主窗口
  - [ ] 在 MainWindow 中设置标题为 "Penguin.AvaloniaUI Demo"
  - [ ] 在 MainWindow 中添加 TextBlock 显示 "Hello World"
  - [ ] 设置窗口默认大小为 800x600
  - [ ] 创建 `Program.cs` 配置 Avalonia 应用启动

- [ ] **Task 5: 配置测试项目** (AC: 1)
  - [ ] 在 `Penguin.AvaloniaUI.Tests.csproj` 中添加 xUnit 包引用
  - [ ] 在测试项目中添加对 `Penguin.AvaloniaUI` 项目的引用
  - [ ] 创建测试项目的目录结构（Controls/、Layouts/、Themes/、Utils/）
  - [ ] 创建一个简单的占位测试类验证测试框架工作正常

- [ ] **Task 6: 编译和运行验证** (AC: 5)
  - [ ] 执行 `dotnet build` 确保所有项目成功编译
  - [ ] 执行 `dotnet test` 确保测试项目可以运行
  - [ ] 启动 Example 应用，验证窗口正确显示
  - [ ] 验证窗口标题、TextBlock 内容和窗口尺寸符合要求

- [ ] **Task 7: 创建项目文档和配置文件** (AC: 6)
  - [ ] 验证并更新 `.gitignore` 文件（应已存在）
  - [ ] 更新 `README.md` 添加项目简介、技术栈和快速开始指南
  - [ ] 验证 `.editorconfig` 文件存在且配置正确
  - [ ] 在 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
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Avalonia" Version="11.3.7" />
    <PackageVersion Include="ReactiveUI.Avalonia" Version="11.3.0" />
    <PackageVersion Include="xUnit" Version="2.6.6" />
    <PackageVersion Include="xUnit.runner.visualstudio" Version="2.5.6" />
  </ItemGroup>
</Project>
```

在各项目的 `.csproj` 文件中引用包时**不指定版本号**：

```xml
<ItemGroup>
  <PackageReference Include="Avalonia" />
  <PackageReference Include="ReactiveUI.Avalonia" />
</ItemGroup>
```

### 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<App>()
            .UsePlatformDetect()
            .LogToTrace();
}
```

**App.axaml** - 应用程序资源：
```xml
<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="Example.App">
  <Application.Styles>
    <FluentTheme />
  </Application.Styles>
</Application>
```

**MainWindow.axaml** - 主窗口（AC 4 要求）：
```xml
<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="Example.Views.MainWindow"
        Title="Penguin.AvaloniaUI Demo"
        Width="800"
        Height="600">
  <TextBlock Text="Hello World"
             HorizontalAlignment="Center"
             VerticalAlignment="Center" />
</Window>
```

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

*This section will be populated by the development agent during implementation.*

### Agent Model Used

*To be filled by Dev Agent*

### Debug Log References

*To be filled by Dev Agent*

### Completion Notes

*To be filled by Dev Agent*

### File List

*To be filled by Dev Agent*

---

## QA Results

*This section will be populated by QA Agent after implementation.*