docs: update 1.1 story
This commit is contained in:
420
docs/stories/1.1.story.md
Normal file
420
docs/stories/1.1.story.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user