Files
ui/docs/stories/1.1.story.md

23 KiB
Raw Blame History

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. 创建基础的 .gitignoreREADME.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.axamlApp.axaml.cs 应用程序入口点
    • 创建 MainWindow.axamlMainWindow.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 ManagementDirectory.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 文档注释:所有 publicprotected 成员必须有 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

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

审查中已完成:

  • 修复代码格式化问题 (LF → CRLF)
  • 验证所有 AC 完全满足
  • 验证编译和测试通过
  • 验证项目结构符合架构规范

无需 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: PASSdocs/qa/gates/1.1-project-infrastructure-setup.yml

Quality Score: 98/100

决策理由:

  • 所有 7 个验收标准完全满足
  • 代码质量优秀,符合所有编码标准
  • 编译和测试全部通过
  • 项目结构完全符合架构规范
  • 唯一发现的格式问题已在审查中修复

✓ Ready for Done

本故事已完全完成,质量优秀,建议标记为 Done 并进入下一个 Story 的开发。

后续行动:

  1. Scrum Master 或 Product Owner 进行最终验收
  2. Dev Agent 可以开始 Story 1.2 (如果存在) 的开发
  3. 无需返工或额外修改