ui/docs/stories/1.1.story.md

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 中集中管理所有包版本：

<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 文件中引用包时不指定版本号：

<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）：

[*.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 声明局部变量

代码格式化检查：

dotnet format --verify-no-changes

Example Application Structure

示例应用必须包含以下核心文件：

Program.cs - 应用程序入口点：

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 - 应用程序资源：

<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 要求）：

<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）：

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

示例占位测试类：

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);
    }
}

运行测试：

# 运行所有测试
dotnet test

# 运行特定测试类
dotnet test --filter "FullyQualifiedName~PlaceholderTests"

Project Configuration Files

.editorconfig - 已存在于项目根目录，确保一致的代码格式

.gitignore - 已存在于项目根目录，包含 .NET 和 Avalonia 相关忽略规则

Directory.Packages.props - 如果已存在则更新，否则创建新文件

Build and Run Commands

编译所有项目：

dotnet build

运行测试：

dotnet test

运行示例应用：

dotnet run --project src/Example/Example.csproj

格式化代码：

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.