chuan/ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 我也不知道完成了什么，先放着

Browse Source
This commit is contained in:
chuan
2025-12-07 00:35:42 +08:00
parent c4a9b8d8d4
commit dad8113da2
43 changed files with 192 additions and 10331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.claude/settings.local.json
View File

@@ -1,3 +0,0 @@
{
"outputStyle": "default"
}

4
Directory.Packages.props
View File

@@ -2,13 +2,13 @@
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Avalonia" Version="11.3.7" />
<PackageVersion Include="Avalonia.Desktop" Version="11.3.7" />
<PackageVersion Include="Avalonia.Themes.Fluent" Version="11.3.7" />
<PackageVersion Include="Avalonia.Fonts.Inter" Version="11.3.7" />
<PackageVersion Include="Avalonia.Diagnostics" Version="11.3.7" />
<PackageVersion Include="AvaloniaUI.DiagnosticsSupport" Version="2.1.0" />
<PackageVersion Include="ReactiveUI.Avalonia" Version="11.3.0" />
<PackageVersion Include="Semi.Avalonia" Version="11.2.1.9" />
<PackageVersion Include="xunit" Version="2.6.6" />
@@ -16,4 +16,4 @@
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
<PackageVersion Include="coverlet.collector" Version="6.0.0" />
</ItemGroup>
</Project>
</Project>

2439
docs/architecture.md
View File

File diff suppressed because it is too large Load Diff

104
docs/architecture/coding-standards.md
View File

@@ -1,104 +0,0 @@
# Coding Standards
本节定义**最小但关键**的编码规范，专注于项目特定的规则，防止常见错误。这些规范将被开发者和 AI Agent 遵循。
---
### Critical Rules
以下规则是**强制性**的，违反将导致代码审查不通过：
- **命名空间组织：** 所有控件必须放在 `Penguin.AvaloniaUI.Controls.*` 命名空间下，布局控件在 `Penguin.AvaloniaUI.Layouts`，主题在 `Penguin.AvaloniaUI.Themes`。不得跨命名空间引用内部实现细节。
- **依赖属性定义：** 所有公开的可绑定属性必须定义为 `StyledProperty`，使用 `AvaloniaProperty.Register<>` 注册，不得使用字段或普通属性。
- **XAML 资源引用：** 所有颜色、字体、间距必须从主题资源字典引用，禁止硬编码颜色值（如 `#FFFFFF`）。使用 `{DynamicResource TextPrimary}` 而非 `{StaticResource}`，确保主题切换生效。
- **ReactiveUI 集成：** ViewModel 必须继承 `ReactiveObject`，属性变化使用 `this.RaiseAndSetIfChanged(ref _field, value)`，不得直接触发 `PropertyChanged` 事件。
- **错误处理：** 公开 API 方法必须验证参数（如 `ArgumentNullException`），内部方法可使用 `Debug.Assert`。不得吞没异常（空 catch 块）。
- **XML 文档注释：** 所有 `public` 和 `protected` 成员必须有 XML 注释（`///`），包括 `<summary>`、`<param>`、`<returns>`。示例：
```csharp
/// <summary>
/// 应用指定的主题类型
/// </summary>
/// <param name="type">主题类型（Light 或 Dark）</param>
public static void ApplyTheme(ThemeType type)
```
- **禁止反射动态创建控件：** PropertyGrid 可以使用反射解析属性，但不得使用 `Activator.CreateInstance` 动态创建编辑器控件。使用工厂模式或字典映射。
- **主题资源命名约定：** 语义化颜色必须使用统一前缀：`TextPrimary`、`TextSecondary`、`BackgroundPrimary`、`SurfaceElevated`。不得使用 `Color1`、`MyBlue` 等非语义化命名。
- **API查询规则：** 在使用不熟悉的API的时候，优先使用 **mcp-context7** 进行上下文查找。
---
### Naming Conventions
| 元素类型 | 命名规则 | 示例 |
| --------- | ---------------------------------------------- | ---------------------------------------------------- |
| 控件类 | PascalCase，功能名称 + 控件类型后缀（可选） | `PropertyGrid`, `TwoColumnLayout` |
| 依赖属性 | PascalCase，属性名 +`Property` 后缀 | `SelectedObjectProperty` |
| 私有字段 | camelCase，下划线前缀 | `_currentTheme` |
| 事件 | PascalCase，动词过去式 | `ThemeChanged`, `PropertyValueChanged` |
| 方法 | PascalCase，动词开头 | `ApplyTheme()`, `RefreshProperties()` |
| XAML 文件 | PascalCase，与类名一致 | `PropertyGrid.axaml` |
| 测试方法 | PascalCase，MethodName_Scenario_ExpectedResult | `ApplyTheme_WithDarkTheme_ShouldUpdateResources()` |
---
### File Organization Rules
- **一个文件一个类**：每个控件类单独一个 `.cs` 文件，不得在同一文件中定义多个公开类（嵌套私有类除外）。
- **XAML 与代码分离**：控件的 XAML 模板放在 `Themes/` 子目录下，与类定义分离：
```
Controls/PropertyGrid/PropertyGrid.cs
Controls/PropertyGrid/Themes/PropertyGrid.axaml
```
- **数据模型独立文件**：数据模型类（如 `PropertyItem`, `GuideStep`）与控件类分离，放在同级目录下。
- **文件格式规范**：命名空间单独放在文件顶部，减少缩进层级：
```csharp
namespace Penguin.AvaloniaUI.Controls;
public class PropertyGrid : TemplatedControl
{
// 类实现
}
```
---
### Code Style (基于 .editorconfig)
项目使用 `.editorconfig` 强制执行以下规则：
```ini
root = true
[*.cs]
indent_style = space
indent_size = 4
end_of_line = crlf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
# C# 规则
csharp_new_line_before_open_brace = all
csharp_prefer_braces = true:warning
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
[*.axaml]
indent_size = 2
```
**代码风格要点：**
- 使用 `var` 声明局部变量（如 `var count = 100;`）
- 命名空间单独一行，不使用文件范围命名空间的花括号嵌套
**运行格式化检查：**
```bash
dotnet format --verify-no-changes
```
---

357
docs/architecture/components.md
View File

@@ -1,357 +0,0 @@
# Components
基于架构模式和数据模型，系统划分为以下核心组件。每个组件负责特定功能，并通过清晰的接口与其他组件交互。
---
### PropertyGrid
**职责**：自动生成属性编辑 UI，支持多种属性类型、分组、只读属性和基础验证。
**关键接口**：
- `SelectedObject`（依赖属性）- 绑定的数据对象，变化时自动刷新属性列表
- `Properties`（ObservableCollection<PropertyItem>）- 解析后的属性列表
- `PropertyValueChanged`（事件）- 属性值变化时触发
**依赖关系**：
- 依赖 TwoColumnLayout 进行布局
- 依赖 PropertyEditors（TextBox、NumericUpDown、ComboBox 等）
- 依赖 ThemeManager 获取当前主题颜色
- 使用反射（System.Reflection）解析对象属性
**技术细节**：
- 继承自 `TemplatedControl`
- 使用 ReactiveUI 的 `WhenAnyValue` 监听 SelectedObject 变化
- 通过 `PropertyInfo.GetCustomAttributes<T>()` 读取 Attribute（如 `[Category]`、`[Browsable]`）
- 编辑器选择逻辑：根据 `PropertyItem.PropertyType` 映射到对应控件
**实现示例**（核心逻辑）：
```csharp
public class PropertyGrid : TemplatedControl
{
public static readonly StyledProperty<object?> SelectedObjectProperty =
AvaloniaProperty.Register<PropertyGrid, object?>(nameof(SelectedObject));
public object? SelectedObject
{
get => GetValue(SelectedObjectProperty);
set => SetValue(SelectedObjectProperty, value);
}
public ObservableCollection<PropertyItem> Properties { get; } = new();
protected override void OnApplyTemplate(TemplateAppliedEventArgs e)
{
base.OnApplyTemplate(e);
this.GetObservable(SelectedObjectProperty)
.Subscribe(obj => RefreshProperties(obj));
}
private void RefreshProperties(object? obj)
{
Properties.Clear();
if (obj == null) return;
var properties = obj.GetType()
.GetProperties(BindingFlags.Public | BindingFlags.Instance)
.Where(p => p.CanRead)
.Select(p => CreatePropertyItem(obj, p))
.OrderBy(p => p.Category)
.ThenBy(p => p.Order);
foreach (var prop in properties)
{
Properties.Add(prop);
}
}
}
```
---
### TwoColumnLayout
**职责**：提供"标签-编辑器"配对的布局控件，左列固定或自适应宽度，右列占据剩余空间。
**关键接口**：
- `Items`（ObservableCollection<LayoutItem>）- 行集合
- `LabelWidth`（double）- 左列宽度（默认 Auto）
- `RowSpacing`（double）- 行间距（默认 8px）
**依赖关系**：
- 无外部依赖（纯布局控件）
- 被 PropertyGrid 使用
**技术细节**：
- 继承自 `Panel` 或内部使用 `Grid`
- 重写 `MeasureOverride` 和 `ArrangeOverride` 实现自定义布局
- 响应主题系统（标签文本颜色使用 `TextSecondary`）
**布局逻辑**：
```
┌─────────────────────────────────┐
│ Label 1 │ Editor 1 │
│ Label 2 │ Editor 2 │
│ Label 3 │ Editor 3 │
└─────────────────────────────────┘
← LabelWidth → ← 剩余空间 →
```
---
### PropertyEditors（编辑器集合）
**职责**：为不同属性类型提供专用编辑器控件。
**组件列表**：
| 属性类型 | 编辑器控件 | 说明 |
|---------|-----------|------|
| string | TextBox | Avalonia 内置 |
| int, double | NumericUpDown | Avalonia 内置或自定义 |
| bool | CheckBox | Avalonia 内置 |
| enum | ComboBox | 自动填充枚举值 |
| DateTime | DatePicker + TimePicker | 组合控件 |
**关键接口**：
- 所有编辑器实现双向绑定（TwoWay Binding）
- 支持 IsEnabled 控制只读状态
- 支持 Avalonia 的 DataValidation 机制
**依赖关系**：
- 被 PropertyGrid 使用
- 依赖 ThemeManager 获取主题颜色
**扩展性**：
- 开发者可通过 `PropertyGrid.EditorTemplateSelector` 注册自定义编辑器
---
### UserGuide
**职责**：管理多步引导流程，协调 Overlay 和引导提示框的显示。
**关键接口**：
- `Steps`（ObservableCollection<GuideStep>）- 引导步骤集合
- `CurrentStepIndex`（int）- 当前步骤索引
- `NextStepCommand`（ICommand）- 下一步命令
- `PreviousStepCommand`（ICommand）- 上一步命令
- `SkipCommand`（ICommand）- 跳过命令
- `Completed`（事件）- 引导完成事件
**依赖关系**：
- 依赖 Overlay 控件显示遮罩
- 依赖 RichTooltip 显示引导提示框
- 依赖 GuideStep 数据模型
**技术细节**：
- 继承自 `ContentControl`
- 使用 ReactiveUI 的 `ReactiveCommand` 实现步骤流转
- 步骤切换时触发动画（淡入淡出，200ms）
**核心逻辑**：
```csharp
public class UserGuide : ContentControl
{
public ObservableCollection<GuideStep> Steps { get; } = new();
private int _currentStepIndex;
public ReactiveCommand<Unit, Unit> NextStepCommand { get; }
public ReactiveCommand<Unit, Unit> PreviousStepCommand { get; }
public ReactiveCommand<Unit, Unit> SkipCommand { get; }
public UserGuide()
{
NextStepCommand = ReactiveCommand.Create(() =>
{
if (_currentStepIndex < Steps.Count - 1)
{
_currentStepIndex++;
ShowCurrentStep();
}
else
{
Complete();
}
});
// ... 其他 Command 实现
}
}
```
---
### Overlay
**职责**：在窗口上层显示半透明遮罩，可选地挖空特定控件区域以聚焦目标。
**关键接口**：
- `IsVisible`（bool）- 显示/隐藏遮罩
- `TargetControl`（Control?）- 挖空目标控件
- `BackgroundOpacity`（double）- 不透明度（默认 0.5）
- `BackgroundColor`（Color）- 遮罩颜色
**依赖关系**：
- 被 UserGuide 使用
- 依赖 ThemeManager（暗色模式下调整遮罩颜色）
**技术细节**：
- 继承自 `ContentControl` 或 `Panel`
- 使用绝对定位覆盖整个窗口
- 挖空逻辑：通过 `Clip` 或多个 `Rectangle` 实现
**视觉效果**：
```
┌─────────────────────────────────┐
│████████████████████████████████│ ← 半透明遮罩
│████████┌──────────┐████████████│
│████████│ Target │████████████│ ← 挖空区域清晰可见
│████████└──────────┘████████████│
│████████████████████████████████│
└─────────────────────────────────┘
```
---
### RichTooltip
**职责**：显示支持基础富文本的增强 Tooltip。
**关键接口**：
- `Content`（string）- 提示内容，支持简单 Markdown 语法（`**粗体**`、`*斜体*`、`\n` 换行）
- `MaxWidth`（double）- 最大宽度（默认 300px）
**依赖关系**：
- 扩展 Avalonia 的 `ToolTip`
- 被 UserGuide 使用
**技术细节**：
- 内部使用 `TextBlock` 配合 `Inlines`（Run、Bold、Italic）
- 简单的 Markdown 解析器（不依赖第三方库）
- 响应主题系统（背景色 `Surface`，文本色 `TextPrimary`）
**解析示例**：
```
输入："**注意**: 这是一个重要提示。\n请仔细阅读。"
输出：
<TextBlock>
<Bold>注意</Bold>: 这是一个重要提示。
<LineBreak />
请仔细阅读。
</TextBlock>
```
---
### ThemeManager
**职责**：管理主题切换，提供全局主题访问接口。
**关键接口**：
- `ApplyTheme(ThemeType type)`（方法）- 切换主题
- `CurrentTheme`（ThemeType）- 当前主题类型
- `ThemeChanged`（事件）- 主题变化事件
**依赖关系**：
- 被所有控件使用（通过静态方法或单例）
- 依赖 Avalonia 的 `Application.Current.Resources`
**技术细节**：
- 静态类或单例模式
- 主题切换通过替换 `ResourceDictionary` 实现
- 支持动画过渡（可选，100ms 淡入淡出）
**实现示例**：
```csharp
public static class ThemeManager
{
private static ThemeType _currentTheme = ThemeType.Light;
public static event EventHandler<ThemeType>? ThemeChanged;
public static void ApplyTheme(ThemeType type)
{
if (_currentTheme == type) return;
var app = Application.Current;
if (app == null) return;
// 移除旧主题
var oldTheme = app.Resources.MergedDictionaries
.FirstOrDefault(d => d.Source?.ToString().Contains("Theme") == true);
if (oldTheme != null)
app.Resources.MergedDictionaries.Remove(oldTheme);
// 加载新主题
var uri = type == ThemeType.Light
? new Uri("avares://Penguin.AvaloniaUI/Themes/LightTheme.axaml")
: new Uri("avares://Penguin.AvaloniaUI/Themes/DarkTheme.axaml");
var newTheme = new ResourceDictionary { Source = uri };
app.Resources.MergedDictionaries.Add(newTheme);
_currentTheme = type;
ThemeChanged?.Invoke(null, type);
}
}
```
---
### Component Diagrams
```mermaid
graph TB
subgraph "业务控件层"
PropertyGrid[PropertyGrid]
UserGuide[UserGuide]
end
subgraph "基础控件层"
TwoColumnLayout[TwoColumnLayout]
Overlay[Overlay]
RichTooltip[RichTooltip]
Editors[PropertyEditors]
end
subgraph "工具层"
ThemeManager[ThemeManager]
end
subgraph "数据模型"
PropertyItem[PropertyItem]
GuideStep[GuideStep]
end
PropertyGrid --> TwoColumnLayout
PropertyGrid --> Editors
PropertyGrid --> PropertyItem
PropertyGrid --> ThemeManager
UserGuide --> Overlay
UserGuide --> RichTooltip
UserGuide --> GuideStep
UserGuide --> ThemeManager
TwoColumnLayout --> ThemeManager
Overlay --> ThemeManager
RichTooltip --> ThemeManager
Editors --> ThemeManager
style PropertyGrid fill:#4A90E2
style UserGuide fill:#4A90E2
style TwoColumnLayout fill:#7ED321
style Overlay fill:#7ED321
style RichTooltip fill:#7ED321
style ThemeManager fill:#F5A623
```
---

207
docs/architecture/data-models.md
View File

@@ -1,207 +0,0 @@
# Data Models
核心数据模型定义了控件库中业务逻辑层的数据结构。这些模型在 UI 控件层和业务逻辑层之间共享。
---
### PropertyItem
**用途**：表示 PropertyGrid 中的单个属性项，封装属性的元数据和值。
**关键属性**：
- `Name`（string）- 属性名称，显示在左列标签
- `Value`（object）- 属性当前值，支持双向绑定
- `PropertyType`（Type）- 属性的 .NET 类型，用于选择合适的编辑器
- `IsReadOnly`（bool）- 是否只读，只读属性禁用编辑器
- `Category`（string?）- 分组类别，用于属性分组显示
- `Description`（string?）- 属性描述，可选的辅助说明
- `DisplayName`（string?）- 显示名称，如果为空则使用 Name
**C# 类定义**：
```csharp
namespace Penguin.AvaloniaUI.Controls.PropertyGrid
{
/// <summary>
/// 表示 PropertyGrid 中的单个属性项
/// </summary>
public class PropertyItem : ReactiveObject
{
private object? _value;
/// <summary>
/// 属性名称
/// </summary>
public string Name { get; set; } = string.Empty;
/// <summary>
/// 属性显示名称（如果为空则使用 Name）
/// </summary>
public string? DisplayName { get; set; }
/// <summary>
/// 属性值（支持双向绑定）
/// </summary>
public object? Value
{
get => _value;
set => this.RaiseAndSetIfChanged(ref _value, value);
}
/// <summary>
/// 属性的 .NET 类型
/// </summary>
public Type PropertyType { get; set; } = typeof(object);
/// <summary>
/// 是否只读
/// </summary>
public bool IsReadOnly { get; set; }
/// <summary>
/// 分组类别（可选）
/// </summary>
public string? Category { get; set; }
/// <summary>
/// 属性描述（可选）
/// </summary>
public string? Description { get; set; }
/// <summary>
/// 原始 PropertyInfo（用于反射场景）
/// </summary>
public PropertyInfo? PropertyInfo { get; set; }
}
}
```
**关系**：
- PropertyGrid 包含多个 PropertyItem（`ObservableCollection<PropertyItem>`）
- PropertyItem 通过 PropertyType 决定使用哪个编辑器控件
---
### GuideStep
**用途**：表示 UserGuide 引导流程中的单个步骤。
**关键属性**：
- `TargetControl`（Control?）- 引导目标控件，Overlay 将聚焦此控件
- `Title`（string）- 步骤标题，显示在引导提示框顶部
- `Content`（string）- 步骤内容/提示文本，支持基础富文本
- `Position`（TooltipPosition）- 提示框相对于目标控件的位置
- `Order`（int）- 步骤顺序，用于排序
**C# 类定义**：
```csharp
namespace Penguin.AvaloniaUI.Controls.UserGuide
{
/// <summary>
/// 提示框位置枚举
/// </summary>
public enum TooltipPosition
{
Bottom,
Top,
Left,
Right
}
/// <summary>
/// 表示 UserGuide 中的单个引导步骤
/// </summary>
public class GuideStep : ReactiveObject
{
/// <summary>
/// 引导目标控件（可选，如果为空则显示全屏提示）
/// </summary>
public Control? TargetControl { get; set; }
/// <summary>
/// 步骤标题
/// </summary>
public string Title { get; set; } = string.Empty;
/// <summary>
/// 步骤内容（支持基础富文本）
/// </summary>
public string Content { get; set; } = string.Empty;
/// <summary>
/// 提示框位置
/// </summary>
public TooltipPosition Position { get; set; } = TooltipPosition.Bottom;
/// <summary>
/// 步骤顺序（用于排序）
/// </summary>
public int Order { get; set; }
/// <summary>
/// 是否允许跳过此步骤
/// </summary>
public bool Skippable { get; set; } = true;
}
}
```
**关系**：
- UserGuide 包含多个 GuideStep（`ObservableCollection<GuideStep>`）
- GuideStep 通过 TargetControl 关联到具体的 UI 控件
- Overlay 根据 TargetControl 的位置和大小进行挖空显示
---
### ThemeInfo（辅助模型）
**用途**：表示主题信息，用于 ThemeManager 管理主题切换。
**关键属性**：
- `ThemeType`（ThemeType）- 主题类型枚举（Light、Dark）
- `ResourceUri`（Uri）- 主题资源字典的 URI
**C# 类定义**：
```csharp
namespace Penguin.AvaloniaUI.Themes
{
/// <summary>
/// 主题类型枚举
/// </summary>
public enum ThemeType
{
Light,
Dark
}
/// <summary>
/// 主题信息
/// </summary>
public class ThemeInfo
{
/// <summary>
/// 主题类型
/// </summary>
public ThemeType Type { get; set; }
/// <summary>
/// 主题资源字典 URI
/// </summary>
public Uri ResourceUri { get; set; } = null!;
/// <summary>
/// 主题显示名称
/// </summary>
public string DisplayName { get; set; } = string.Empty;
}
}
```
**关系**：
- ThemeManager 使用 ThemeInfo 管理可用主题
- 主题切换时通过 ResourceUri 加载对应的 ResourceDictionary
---

180
docs/architecture/development-workflow.md
View File

@@ -1,180 +0,0 @@
# Development Workflow
本节定义控件库的开发环境配置和日常开发流程，确保开发者能够快速上手并保持高效开发。
---
### Local Development Setup
**前置要求：**
```bash
# 必需
- .NET 9.0 SDK (https://dotnet.microsoft.com/download)
- Visual Studio 2022 (17.8+)
- Git 2.40+
# 推荐
- Visual Studio Avalonia 扩展 (用于 XAML 预览)
```
**初始化项目：**
```bash
# 克隆仓库
git clone <repository-url>
cd 32_avalonia.ui
# 还原 NuGet 包
dotnet restore
# 构建解决方案
dotnet build
# 运行示例应用
dotnet run --project src/Example/Example.csproj
```
**Visual Studio 配置：**
1. 打开 `Penguin.AvaloniaUI.sln`
2. 设置 `Example` 为启动项目
3. 选择调试配置（Debug/Release）
4. 按 F5 启动调试
---
### Development Commands
**常用命令：**
```bash
# 启动示例应用（开发模式，支持热重载）
dotnet watch --project src/Example/Example.csproj
# 运行所有单元测试
dotnet test
# 运行特定测试类
dotnet test --filter "FullyQualifiedName~PropertyGridTests"
# 生成代码覆盖率报告
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=html
# 清理构建产物
dotnet clean
# 格式化代码（基于 .editorconfig）
dotnet format
# 打包 NuGet 包（Post-MVP）
dotnet pack src/Penguin.AvaloniaUI/Penguin.AvaloniaUI.csproj -c Release
```
---
### Hot Reload 配置
Avalonia 11.x 支持 .NET Hot Reload，但有限制：
**支持的修改：**
- C# 方法体内的代码修改
- XAML 资源字典的修改（颜色、样式）
- 部分 XAML 控件属性修改
**不支持的修改（需要重启）：**
- 新增或删除控件
- 修改控件模板结构
- 修改依赖属性定义
- 修改 ViewModel 属性签名
**启用 Hot Reload：**
在 `Example.csproj` 中确保已启用：
```xml
<PropertyGroup>
<AvaloniaUseHotReload>true</AvaloniaUseHotReload>
</PropertyGroup>
```
---
### Environment Configuration
**控件库无需环境变量**（MVP 阶段），但示例应用可能需要：
```bash
# Example/.env (可选，用于测试外部 API 集成)
# MVP 阶段不需要
```
**调试配置（launchSettings.json）：**
```json
{
"profiles": {
"Example": {
"commandName": "Project",
"dotnetRunMessages": true,
"environmentVariables": {
"DOTNET_ENVIRONMENT": "Development"
}
}
}
}
```
---
### Git Workflow
**Commit Message 格式（Conventional Commits）：**
```
<type>: <description>
[optional body]
```
**Type 类型：**
- `feat`: 新功能（如 `feat: 增加了UserControl的DarkStyle`）
- `fix`: Bug 修复（如 `fix: 修复PropertyGrid在主题切换时崩溃`）
- `refactor`: 重构（如 `refactor: 优化ThemeManager的资源加载逻辑`）
- `test`: 测试相关（如 `test: 添加PropertyGrid的分组功能测试`）
- `docs`: 文档更新（如 `docs: 更新README的快速开始指南`）
- `style`: 代码格式调整（如 `style: 统一缩进为4空格`）
- `chore`: 构建/工具相关（如 `chore: 升级Avalonia到11.3.8`）
**示例：**
```bash
git commit -m "feat: 实现PropertyGrid的属性分组功能"
git commit -m "fix: 修复TwoColumnLayout在窗口缩放时的对齐问题"
git commit -m "test: 添加ThemeManager的主题切换测试"
```
**分支命名规范：**
- `feat/<feature-name>` - 新功能分支（如 `feat/usercontrol`）
- `fix/<issue-number>` - Bug 修复分支（如 `fix/1123`）
- `refactor/<description>` - 重构分支（如 `refactor/theme-system`）
- `test/<description>` - 测试分支（如 `test/integration`）
**日常开发流程：**
1. **创建功能分支**：`git checkout -b feat/two-column-layout`
2. **编写代码**：在 `src/Penguin.AvaloniaUI/` 中实现控件
3. **编写测试**：在 `src/Penguin.AvaloniaUI.Tests/` 中添加单元测试
4. **更新示例**：在 `src/Example/Views/Pages/` 中添加演示页面
5. **本地验证**：
- 运行单元测试：`dotnet test`
- 启动示例应用：`dotnet run --project src/Example`
- 手动测试主题切换和控件交互
6. **提交代码**：
```bash
git add .
git commit -m "feat: 实现TwoColumnLayout布局控件"
git push origin feat/two-column-layout
```
---

428
docs/architecture/error-handling.md
View File

@@ -1,428 +0,0 @@
# Error Handling
本节定义控件库的错误处理策略，确保异常情况下的稳定性和良好的开发者体验。
---
### Error Handling Principles
**核心原则：**
1. **Fail Fast（快速失败）**：公开 API 在参数无效时立即抛出异常，不延迟到执行阶段
2. **Clear Error Messages（清晰错误信息）**：异常消息应明确指出问题和解决方案
3. **No Silent Failures（不吞没异常）**：禁止空 catch 块，必须记录或重新抛出异常
4. **Defensive Programming（防御性编程）**：内部方法使用 `Debug.Assert` 验证前置条件
---
### Exception Handling Patterns
**公开 API 参数验证：**
```csharp
namespace Penguin.AvaloniaUI.Themes;
public static class ThemeManager
{
/// <summary>
/// 应用指定的主题类型
/// </summary>
/// <param name="type">主题类型</param>
/// <exception cref="ArgumentException">当主题类型无效时抛出</exception>
public static void ApplyTheme(ThemeType type)
{
// 参数验证
if (!Enum.IsDefined(typeof(ThemeType), type))
{
throw new ArgumentException(
$"Invalid theme type: {type}. Valid values are: {string.Join(", ", Enum.GetNames(typeof(ThemeType)))}",
nameof(type));
}
// 核心逻辑
try
{
LoadThemeResources(type);
_currentTheme = type;
ThemeChanged?.Invoke(null, type);
}
catch (Exception ex)
{
throw new InvalidOperationException(
$"Failed to apply theme '{type}'. Ensure theme resources are available.",
ex);
}
}
}
```
---
**PropertyGrid 错误处理：**
```csharp
namespace Penguin.AvaloniaUI.Controls.PropertyGrid;
public class PropertyGrid : TemplatedControl
{
public static readonly StyledProperty<object?> SelectedObjectProperty =
AvaloniaProperty.Register<PropertyGrid, object?>(nameof(SelectedObject));
public object? SelectedObject
{
get => GetValue(SelectedObjectProperty);
set => SetValue(SelectedObjectProperty, value);
}
private void RefreshProperties(object? obj)
{
Properties.Clear();
if (obj == null)
{
// 空对象是合法的，清空属性列表即可
return;
}
try
{
var properties = obj.GetType()
.GetProperties(BindingFlags.Public | BindingFlags.Instance)
.Where(p => p.CanRead);
foreach (var prop in properties)
{
try
{
var item = CreatePropertyItem(obj, prop);
Properties.Add(item);
}
catch (Exception ex)
{
// 单个属性解析失败不应影响其他属性
Debug.WriteLine($"[PropertyGrid] Failed to create property item for '{prop.Name}': {ex.Message}");
// 可选：添加错误占位符
Properties.Add(new PropertyItem
{
Name = prop.Name,
DisplayName = $"{prop.Name} (Error)",
IsReadOnly = true,
Value = $"Error: {ex.Message}"
});
}
}
}
catch (Exception ex)
{
throw new InvalidOperationException(
$"Failed to parse properties for object of type '{obj.GetType().Name}'.",
ex);
}
}
private PropertyItem CreatePropertyItem(object obj, PropertyInfo prop)
{
Debug.Assert(obj != null, "Object should not be null");
Debug.Assert(prop != null, "PropertyInfo should not be null");
try
{
var value = prop.GetValue(obj);
return new PropertyItem
{
Name = prop.Name,
DisplayName = GetDisplayName(prop),
Value = value,
PropertyType = prop.PropertyType,
IsReadOnly = !prop.CanWrite,
Category = GetCategory(prop),
PropertyInfo = prop
};
}
catch (TargetInvocationException ex)
{
throw new InvalidOperationException(
$"Property '{prop.Name}' getter threw an exception.",
ex.InnerException ?? ex);
}
}
}
```
---
**UserGuide 错误处理：**
```csharp
namespace Penguin.AvaloniaUI.Controls.UserGuide;
public class UserGuide : ContentControl
{
private void ShowCurrentStep()
{
if (CurrentStepIndex < 0 || CurrentStepIndex >= Steps.Count)
{
Debug.WriteLine($"[UserGuide] Invalid step index: {CurrentStepIndex}");
return;
}
var step = Steps[CurrentStepIndex];
// 验证目标控件是否可用
if (step.TargetControl == null)
{
Debug.WriteLine($"[UserGuide] Step '{step.Title}' has no target control, showing full-screen overlay.");
// 显示全屏提示
ShowFullScreenGuide(step);
return;
}
// 检查目标控件是否在可视化树中
if (!step.TargetControl.IsVisible || !IsControlInVisualTree(step.TargetControl))
{
Debug.WriteLine($"[UserGuide] Target control for step '{step.Title}' is not visible or not in visual tree. Skipping step.");
// 自动跳到下一步
if (CurrentStepIndex < Steps.Count - 1)
{
CurrentStepIndex++;
ShowCurrentStep();
}
else
{
Complete();
}
return;
}
// 正常显示引导
ShowGuideForControl(step);
}
private bool IsControlInVisualTree(Control control)
{
try
{
return control.GetVisualRoot() != null;
}
catch
{
return false;
}
}
}
```
---
### Logging Strategy
**使用 Debug.WriteLine 进行调试日志：**
```csharp
using System.Diagnostics;
namespace Penguin.AvaloniaUI.Utils;
internal static class Logger
{
[Conditional("DEBUG")]
public static void Debug(string message)
{
System.Diagnostics.Debug.WriteLine($"[Penguin.AvaloniaUI] {message}");
}
[Conditional("DEBUG")]
public static void Warning(string message)
{
System.Diagnostics.Debug.WriteLine($"[WARNING] {message}");
}
public static void Error(string message, Exception? ex = null)
{
System.Diagnostics.Debug.WriteLine($"[ERROR] {message}");
if (ex != null)
{
System.Diagnostics.Debug.WriteLine($"Exception: {ex}");
}
}
}
```
**使用示例：**
```csharp
private void RefreshProperties(object? obj)
{
Logger.Debug($"RefreshProperties called with object type: {obj?.GetType().Name ?? "null"}");
try
{
// 核心逻辑
}
catch (Exception ex)
{
Logger.Error("Failed to refresh properties", ex);
throw;
}
}
```
---
### Error Messages Guidelines
**好的错误消息示例：**
```csharp
// ❌ 不好的错误消息
throw new Exception("Error");
throw new ArgumentException("Invalid parameter");
// ✅ 好的错误消息
throw new ArgumentNullException(nameof(selectedObject),
"SelectedObject cannot be null. Please provide a valid object instance.");
throw new InvalidOperationException(
"Cannot apply theme: Application.Current is null. Ensure ThemeManager is called after App initialization.");
throw new NotSupportedException(
$"Property type '{propertyType.Name}' is not supported by PropertyGrid. " +
$"Supported types: string, int, double, bool, enum, DateTime.");
```
**错误消息模板：**
```
{What happened}: {Why it happened}. {How to fix it}.
```
---
### Exception Types
**使用合适的异常类型：**
| 场景 | 异常类型 | 示例 |
|------|---------|------|
| 参数为 null | `ArgumentNullException` | `throw new ArgumentNullException(nameof(obj))` |
| 参数值无效 | `ArgumentException` | `throw new ArgumentException("Invalid theme type", nameof(type))` |
| 参数超出范围 | `ArgumentOutOfRangeException` | `throw new ArgumentOutOfRangeException(nameof(index))` |
| 操作在当前状态无效 | `InvalidOperationException` | `throw new InvalidOperationException("Theme resources not loaded")` |
| 功能未实现 | `NotImplementedException` | `throw new NotImplementedException("Custom editors not supported in MVP")` |
| 功能不支持 | `NotSupportedException` | `throw new NotSupportedException($"Type {type} not supported")` |
---
### Try-Catch Guidelines
**何时使用 try-catch：**
```csharp
// ✅ 捕获特定异常并提供上下文
try
{
var value = property.GetValue(obj);
}
catch (TargetInvocationException ex)
{
throw new InvalidOperationException(
$"Property '{property.Name}' getter threw an exception.",
ex.InnerException ?? ex);
}
// ✅ 记录异常并继续处理
try
{
LoadThemeResource(uri);
}
catch (Exception ex)
{
Logger.Error($"Failed to load theme resource: {uri}", ex);
// 使用默认主题
LoadDefaultTheme();
}
// ❌ 不要捕获所有异常并吞没
try
{
DoSomething();
}
catch
{
// 什么都不做 - 这是错误的！
}
// ❌ 不要捕获异常后重新抛出同一个异常
try
{
DoSomething();
}
catch (Exception ex)
{
throw ex; // 错误：会丢失调用栈
}
// ✅ 如果需要记录后重新抛出，使用 throw;
try
{
DoSomething();
}
catch (Exception ex)
{
Logger.Error("Operation failed", ex);
throw; // 正确：保留调用栈
}
```
---
### Validation Helpers
**创建参数验证辅助方法：**
```csharp
namespace Penguin.AvaloniaUI.Utils;
internal static class Guard
{
public static void NotNull<T>(T value, string paramName) where T : class
{
if (value == null)
{
throw new ArgumentNullException(paramName);
}
}
public static void NotNullOrEmpty(string value, string paramName)
{
if (string.IsNullOrEmpty(value))
{
throw new ArgumentException("Value cannot be null or empty.", paramName);
}
}
public static void InRange(int value, int min, int max, string paramName)
{
if (value < min || value > max)
{
throw new ArgumentOutOfRangeException(paramName,
$"Value must be between {min} and {max}, but was {value}.");
}
}
}
// 使用示例
public void SetProperty(string name, object value)
{
Guard.NotNullOrEmpty(name, nameof(name));
Guard.NotNull(value, nameof(value));
// 核心逻辑
}
```
---

144
docs/architecture/high-level-architecture.md
View File

@@ -1,144 +0,0 @@
# High Level Architecture
### Technical Summary
Penguin.AvaloniaUI 是一个基于 Avalonia 11.3.7 的桌面控件库，专注于业务场景控件（PropertyGrid、UserGuide 等）。采用 ReactiveUI 实现 MVVM 模式和响应式交互，目标是为上位机和 AI 桌面应用提供开箱即用的复合控件。
**核心特性**：
- **业务场景控件**：PropertyGrid（属性编辑）、UserGuide（新手引导）等高级控件
- **多主题系统**：基于 Semi Design 和苹果颜色系统，支持浅色/暗色主题运行时切换
- **响应式架构**：基于 ReactiveUI，支持 Command、Reactive、Event 混合使用
- **国际化预留**：架构支持后续多语言扩展，MVP 阶段使用单一语言
- **AOT 友好设计**：架构考虑未来 AOT 编译支持，MVP 阶段允许使用反射
**架构目标**：
- 降低上位机和 AI 桌面应用的开发成本（减少 30-50% 重复工作）
- 提供专业级 UI 体验（信息密度优先、暗色模式友好）
- 确保良好的扩展性（开发者可通过 Template 和 Style 自定义外观）
---
### Platform and Infrastructure Choice
**开发平台**：
- **IDE**：Visual Studio 2022 或 JetBrains Rider
- **运行时**：.NET 9.0
- **版本控制**：Git（本地或私有仓库）
- **包管理**：NuGet
**目标平台**：
- **主要**：Windows 10/11（桌面应用）
- **次要**：Linux 桌面（Ubuntu 20.04+、Debian 11+，主要是工业平板场景）
- **可选**：macOS（架构不排斥，但非 MVP 测试平台）
**最小支持分辨率**：1366x768
**推荐分辨率**：1920x1080 及以上
**输入方式**：
- 主要：鼠标 + 键盘
- 次要：触控笔（Linux Pad 场景）
- 不支持：多点触控手势
---
### Repository Structure
**结构类型**：Monorepo
**组织策略**：
```
D:\32_avalonia.ui/
├── src/
│ ├── Penguin.AvaloniaUI/ # 核心控件库
│ ├── Penguin.AvaloniaUI.SourceGenerators/ # Source Generator（Post-MVP）
│ ├── Example/ # 示例应用
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试
├── docs/ # 文档
│ ├── prd.md
│ ├── architecture.md
│ └── ...
└── .bmad-core/ # BMAD 框架配置
```
**核心控件库内部结构**（命名空间组织）：
- `Penguin.AvaloniaUI.Controls` - 业务场景控件（PropertyGrid、UserGuide 等）
- `Penguin.AvaloniaUI.Layouts` - 布局控件（TwoColumnLayout 等）
- `Penguin.AvaloniaUI.Themes` - 主题和样式系统
- `Penguin.AvaloniaUI.Utils` - 工具类（ThemeManager 等）
**Rationale**：
- Monorepo 简化控件库与示例应用的协同开发
- 依赖版本统一管理，避免版本冲突
- MVP 阶段项目数量少（3-4 个），复杂度可控
---
### High Level Architecture Diagram
```mermaid
graph TB
subgraph "开发者应用"
App[Avalonia Application]
end
subgraph "Penguin.AvaloniaUI 控件库"
Controls[Controls Layer<br/>PropertyGrid, UserGuide]
Layouts[Layouts Layer<br/>TwoColumnLayout, Overlay]
Themes[Themes Layer<br/>ThemeManager, ColorSystem]
Utils[Utils Layer<br/>LocalizationManager, Helpers]
end
subgraph "基础框架"
Avalonia[Avalonia UI 11.3.7]
ReactiveUI[ReactiveUI 11.3.0]
NET[.NET 9.0]
end
App --> Controls
App --> Layouts
App --> Themes
Controls --> Layouts
Controls --> Themes
Controls --> Utils
Layouts --> Themes
Themes --> Avalonia
Controls --> ReactiveUI
Avalonia --> NET
ReactiveUI --> NET
style Controls fill:#4A90E2
style Layouts fill:#7ED321
style Themes fill:#F5A623
style Utils fill:#BD10E0
```
---
### Architectural Patterns
- **MVVM (Model-View-ViewModel)**：所有控件遵循 MVVM 模式，使用 ReactiveUI 实现数据绑定和 Command
- _Rationale_：Avalonia 原生支持 MVVM，ReactiveUI 提供强大的响应式能力，降低复杂交互的实现难度
- **Templated Control Pattern**：业务控件继承自 `TemplatedControl`，通过 `ControlTemplate` 分离逻辑和外观
- _Rationale_：确保控件可定制，开发者可以通过 Style 和 Template 覆盖默认外观
- **Resource Dictionary 主题系统**：主题通过 `ResourceDictionary` 定义，运行时通过替换 `Application.Current.Resources` 实现切换
- _Rationale_：Avalonia 标准机制，无需引入额外框架，主题切换自动传播到所有控件
- **Reactive Extensions (Rx)**：使用 ReactiveUI 的 Reactive 模式处理异步事件流和属性变化
- _Rationale_：简化复杂的事件处理逻辑（如 PropertyGrid 的属性变化监听、UserGuide 的步骤流转）
- **Dependency Injection (可选)**：MVP 阶段不强制 DI，ThemeManager 等服务可通过静态类或单例访问
- _Rationale_：控件库不需要复杂的 DI 容器，保持简单；Post-MVP 可根据需要引入
- **Attribute-Driven Configuration**：PropertyGrid 通过 Attribute（如 `[Category]`、`[Browsable]`）配置属性显示
- _Rationale_：符合 .NET 生态习惯（类似 WinForms PropertyGrid），降低学习成本
- **Composition over Inheritance**：复杂控件通过组合基础控件实现（如 UserGuide 组合 Overlay + RichTooltip）
- _Rationale_：提高代码复用性，避免深层继承带来的维护问题
---

17
docs/architecture/index.md
View File

@@ -1,17 +0,0 @@
# Penguin.AvaloniaUI Architecture Document
## Table of Contents
- [Penguin.AvaloniaUI Architecture Document](#table-of-contents)
- [Introduction](#introduction)
- [High Level Architecture](#high-level-architecture)
- [Tech Stack](#tech-stack)
- [Data Models](#data-models)
- [Components](#components)
- [Unified Project Structure](#unified-project-structure)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing Strategy](#testing-strategy)
- [Error Handling](#error-handling)
- [Performance Optimization](#performance-optimization)
- [文档完成](#文档完成)

42
docs/architecture/introduction.md
View File

@@ -1,42 +0,0 @@
# Introduction
本文档定义了 **Penguin.AvaloniaUI** 控件库的完整架构，作为 AI 驱动开发的技术蓝图。
项目基于以下核心技术：
- **UI 框架**: Avalonia 11.3.7
- **MVVM 和响应式**: ReactiveUI.Avalonia 11.3.0
- **运行时**: .NET 9.0
- **目标平台**: Windows（主要）、Linux、macOS（次要）
架构范围涵盖：
- 控件组件设计（PropertyGrid、UserGuide 等）
- 主题和样式系统
- 项目结构和开发工作流
- 编码规范和测试策略
---
### Starter Template or Existing Project
**项目类型**: 现有代码基础上的开发
**当前状态**:
- 项目结构已建立（`src/Penguin.AvaloniaUI/`）
- 核心依赖已配置（Avalonia 11.3.7、ReactiveUI 11.3.0）
- PRD 已完成，定义了 3 个 Epic 和 16 个 Story
- Monorepo 结构（控件库 + 示例应用 + 测试）
**待评估项**:
- Semi.Avalonia 样式库的可用性（Story 1.1 前置任务）
- 如不可用，将采用自定义样式系统
---
### Change Log
| Date | Version | Description | Author |
|------------|---------|----------------------------------|-----------|
| 2025-10-16 | 1.0 | 初始架构文档创建（基于 PRD v1.0） | Architect |
---

415
docs/architecture/performance-optimization.md
View File

@@ -1,415 +0,0 @@
# Performance Optimization
本节定义性能优化策略和最佳实践，确保控件库满足 NFR 性能要求。
---
### Performance Targets (from NFR)
| 指标 | 目标值 | 测量方法 |
|------|--------|----------|
| UI 渲染帧率 | 60fps (16ms/frame) | Visual Studio Performance Profiler |
| 主题切换时间 | < 100ms | Stopwatch 测量 |
| PropertyGrid 生成（50 属性） | < 200ms | Stopwatch 测量 |
| 应用启动时间 | < 2s | 从启动到窗口显示 |
| 内存占用 | < 100MB (空闲时) | Task Manager / dotnet-counters |
---
### UI Rendering Performance
**关键原则：避免在 UI 线程执行耗时操作**
**❌ 反面示例 - 阻塞 UI 线程：**
```csharp
// 错误：在属性 getter 中执行反射
public ObservableCollection<PropertyItem> Properties
{
get
{
var items = new ObservableCollection<PropertyItem>();
if (SelectedObject != null)
{
// 耗时操作会阻塞 UI 渲染
var properties = SelectedObject.GetType().GetProperties();
foreach (var prop in properties)
{
items.Add(CreatePropertyItem(SelectedObject, prop));
}
}
return items;
}
}
```
**✅ 正确示例 - 异步加载：**
```csharp
private ObservableCollection<PropertyItem> _properties = new();
public ObservableCollection<PropertyItem> Properties => _properties;
private async void RefreshProperties(object? obj)
{
_properties.Clear();
if (obj == null) return;
// 在后台线程执行反射
var items = await Task.Run(() =>
{
var result = new List<PropertyItem>();
var properties = obj.GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance);
foreach (var prop in properties)
{
result.Add(CreatePropertyItem(obj, prop));
}
return result;
});
// 回到 UI 线程更新集合
foreach (var item in items)
{
_properties.Add(item);
}
}
```
---
### Reflection Optimization
**问题：反射是 PropertyGrid 的性能瓶颈**
**优化策略 1：缓存 PropertyInfo**
```csharp
private static readonly ConcurrentDictionary<Type, PropertyInfo[]> _propertyCache = new();
private PropertyInfo[] GetCachedProperties(Type type)
{
return _propertyCache.GetOrAdd(type, t =>
t.GetProperties(BindingFlags.Public | BindingFlags.Instance)
);
}
```
**优化策略 2：缓存 Attribute 读取**
```csharp
private static readonly ConcurrentDictionary<PropertyInfo, CategoryAttribute?> _categoryCache = new();
private string? GetCategory(PropertyInfo prop)
{
var attr = _categoryCache.GetOrAdd(prop, p =>
p.GetCustomAttribute<CategoryAttribute>()
);
return attr?.Category;
}
```
**优化策略 3：使用编译表达式替代反射调用（可选）**
```csharp
// 反射调用（慢）
var value = propertyInfo.GetValue(obj);
// 编译表达式（快 10-100 倍）
private static Func<object, object> CreateGetter(PropertyInfo prop)
{
var instance = Expression.Parameter(typeof(object), "instance");
var convert = Expression.Convert(instance, prop.DeclaringType!);
var property = Expression.Property(convert, prop);
var convertResult = Expression.Convert(property, typeof(object));
return Expression.Lambda<Func<object, object>>(convertResult, instance).Compile();
}
```
**性能对比：**
```
反射 GetValue: ~1000 ns/调用
编译表达式: ~10 ns/调用
直接属性访问: ~1 ns/调用
```
---
### Theme Switching Performance
**优化主题切换速度（目标 < 100ms）：**
**❌ 反面示例 - 逐个替换资源：**
```csharp
// 错误：逐个替换资源会触发多次 UI 刷新
foreach (var key in themeColors.Keys)
{
Application.Current.Resources[key] = themeColors[key];
}
```
**✅ 正确示例 - 批量替换 ResourceDictionary：**
```csharp
public static void ApplyTheme(ThemeType type)
{
var app = Application.Current;
if (app == null) return;
// 移除旧主题
var oldTheme = app.Resources.MergedDictionaries
.FirstOrDefault(d => d.Source?.ToString().Contains("Theme") == true);
if (oldTheme != null)
app.Resources.MergedDictionaries.Remove(oldTheme);
// 一次性加载新主题（单次 UI 刷新）
var uri = type == ThemeType.Light
? new Uri("avares://Penguin.AvaloniaUI/Themes/LightTheme.axaml")
: new Uri("avares://Penguin.AvaloniaUI/Themes/DarkTheme.axaml");
var newTheme = new ResourceDictionary { Source = uri };
app.Resources.MergedDictionaries.Add(newTheme);
_currentTheme = type;
ThemeChanged?.Invoke(null, type);
}
```
**预加载主题资源（可选优化）：**
```csharp
private static ResourceDictionary? _cachedLightTheme;
private static ResourceDictionary? _cachedDarkTheme;
static ThemeManager()
{
// 应用启动时预加载主题
_cachedLightTheme = LoadThemeResource(ThemeType.Light);
_cachedDarkTheme = LoadThemeResource(ThemeType.Dark);
}
public static void ApplyTheme(ThemeType type)
{
var theme = type == ThemeType.Light ? _cachedLightTheme : _cachedDarkTheme;
// 直接使用缓存的主题，无需重新加载
}
```
---
### Memory Management
**避免内存泄漏的常见陷阱：**
**问题 1：事件订阅未取消**
```csharp
// ❌ 可能导致内存泄漏
public class PropertyGrid : TemplatedControl
{
public PropertyGrid()
{
ThemeManager.ThemeChanged += OnThemeChanged;
// 没有取消订阅！
}
private void OnThemeChanged(object? sender, ThemeType type)
{
RefreshTheme();
}
}
// ✅ 正确实现 IDisposable
public class PropertyGrid : TemplatedControl, IDisposable
{
public PropertyGrid()
{
ThemeManager.ThemeChanged += OnThemeChanged;
}
public void Dispose()
{
ThemeManager.ThemeChanged -= OnThemeChanged;
}
private void OnThemeChanged(object? sender, ThemeType type)
{
RefreshTheme();
}
}
```
**问题 2：ObservableCollection 过度使用**
```csharp
// ❌ 每次都创建新集合
public ObservableCollection<PropertyItem> Properties
{
get => new ObservableCollection<PropertyItem>(GetProperties());
}
// ✅ 复用同一个集合
private ObservableCollection<PropertyItem> _properties = new();
public ObservableCollection<PropertyItem> Properties => _properties;
private void RefreshProperties()
{
_properties.Clear();
foreach (var item in GetProperties())
{
_properties.Add(item);
}
}
```
---
### Virtualization (Post-MVP)
**如果 PropertyGrid 需要支持数百个属性，使用虚拟化：**
```xml
<ItemsControl Items="{Binding Properties}">
<ItemsControl.ItemsPanel>
<ItemsPanelTemplate>
<!-- VirtualizingStackPanel 仅渲染可见项 -->
<VirtualizingStackPanel />
</ItemsPanelTemplate>
</ItemsControl.ItemsPanel>
</ItemsControl>
```
**虚拟化性能对比：**
```
100 个属性（非虚拟化）: ~300ms 生成 + 50MB 内存
100 个属性（虚拟化）: ~100ms 生成 + 10MB 内存
```
---
### Avoid Common Pitfalls
**陷阱 1：在循环中触发属性变化通知**
```csharp
// ❌ 每次循环触发 UI 刷新
for (int i = 0; i < 1000; i++)
{
Properties.Add(new PropertyItem()); // 触发 CollectionChanged
}
// ✅ 批量添加后触发一次刷新
var items = new List<PropertyItem>();
for (int i = 0; i < 1000; i++)
{
items.Add(new PropertyItem());
}
Properties.Clear();
foreach (var item in items)
{
Properties.Add(item);
}
```
**陷阱 2：频繁的字符串拼接**
```csharp
// ❌ 每次拼接创建新字符串
string result = "";
for (int i = 0; i < 100; i++)
{
result += properties[i].Name + ", ";
}
// ✅ 使用 StringBuilder
var sb = new StringBuilder();
for (int i = 0; i < 100; i++)
{
sb.Append(properties[i].Name).Append(", ");
}
var result = sb.ToString();
```
**陷阱 3：XAML 中的复杂绑定**
```xml
<!-- ❌ 每次渲染都执行转换 -->
<TextBlock Text="{Binding PropertyType, Converter={StaticResource ComplexConverter}}" />
<!-- ✅ 在 ViewModel 中预计算 -->
<TextBlock Text="{Binding PropertyTypeDisplayName}" />
```
---
### Performance Measurement
**使用 Stopwatch 测量关键操作：**
```csharp
#if DEBUG
private void RefreshProperties(object? obj)
{
var sw = Stopwatch.StartNew();
// 核心逻辑
_properties.Clear();
var items = GetProperties(obj);
foreach (var item in items)
{
_properties.Add(item);
}
sw.Stop();
Debug.WriteLine($"[PropertyGrid] RefreshProperties took {sw.ElapsedMilliseconds}ms for {items.Count} properties");
}
#endif
```
**Visual Studio Performance Profiler：**
1. 调试 → 性能探查器
2. 选择"CPU 使用情况"或".NET 对象分配跟踪"
3. 启动分析
4. 执行性能关键操作（如生成 50 个属性）
5. 停止分析并查看热点代码
**dotnet-counters 监控内存：**
```bash
# 安装工具
dotnet tool install --global dotnet-counters
# 监控运行中的应用
dotnet-counters monitor --process-id <pid> --counters System.Runtime
```
---
### Optimization Checklist
**开发时检查清单：**
- [ ] 反射操作已缓存（PropertyInfo、Attribute）
- [ ] 耗时操作（> 50ms）在后台线程执行
- [ ] 事件订阅在控件销毁时取消
- [ ] ObservableCollection 复用而非重建
- [ ] 批量更新集合，避免频繁触发 CollectionChanged
- [ ] 字符串拼接使用 StringBuilder
- [ ] XAML 绑定避免复杂转换器
- [ ] 主题切换批量替换 ResourceDictionary
**发布前性能测试：**
- [ ] PropertyGrid 50 属性生成 < 200ms
- [ ] 主题切换 < 100ms
- [ ] 应用启动 < 2s
- [ ] 空闲时内存 < 100MB
- [ ] 无明显的 UI 卡顿（帧率 > 50fps）
---

64
docs/architecture/tech-stack.md
View File

@@ -1,64 +0,0 @@
# Tech Stack
本表是项目的**单一技术事实来源**，所有开发必须使用这些确定的技术和版本。
### Technology Stack Table
| Category | Technology | Version | Purpose | Rationale |
|----------|-----------|---------|---------|-----------|
| **运行时** | .NET | 9.0 | 应用运行时环境 | 最新版本，支持最新 C# 特性，性能优异 |
| **UI 框架** | Avalonia | 11.3.7 | 跨平台桌面 UI 框架 | 现代化、跨平台、活跃社区，不向后兼容旧版本 |
| **MVVM 框架** | ReactiveUI.Avalonia | 11.3.0 | 响应式 MVVM 实现 | 强大的响应式能力，简化复杂交互逻辑，与 Avalonia 深度集成 |
| **状态管理** | ReactiveUI Observable | Built-in | 属性变化监听和数据流 | ReactiveUI 内置，无需额外依赖，统一状态管理方式 |
| **样式系统** | Semi.Avalonia + 自定义 | Latest | UI 样式和主题 | 基于 Semi Design，结合苹果颜色系统的自定义实现 |
| **颜色系统** | 苹果颜色系统（三层架构） | N/A | 语义化颜色定义 | Primitives→Semantic→Component 架构，支持浅色/暗色主题，完整的 Apple HIG 色值 |
| **布局系统** | Avalonia Layouts + 自定义 | Built-in + Custom | 控件布局 | Avalonia 内置 Panel 系统 + 自定义 TwoColumnLayout |
| **数据绑定** | Avalonia Binding | Built-in | XAML 数据绑定 | Avalonia 原生支持，与 ReactiveUI 无缝集成 |
| **单元测试** | xUnit | 2.6+ | 单元测试框架 | .NET 生态主流选择，简洁易用 |
| **包管理** | NuGet + 统一包版本管理 | Built-in | 依赖包管理 | 使用 Directory.Packages.props 统一管理包版本，避免版本冲突 |
| **版本控制** | Git | 2.40+ | 代码版本管理 | 行业标准 |
| **CI/CD** | 手动构建（MVP） | N/A | 持续集成/部署 | MVP 阶段不强制 CI/CD，Post-MVP 可引入 GitHub Actions |
| **代码格式化** | .editorconfig | Built-in | 代码风格统一 | 定义缩进、换行等规则 |
| **文档生成** | XML 文档注释 | Built-in | API 文档 | 所有 public API 必须有 XML 注释 |
| **国际化** | Avalonia IResourceProvider（预留） | Built-in | 多语言支持 | MVP 单一语言，架构预留扩展点 |
| **性能分析** | Visual Studio Profiler / dotnet-trace | Built-in | 性能测量 | 验证 NFR（60fps、100ms 主题切换、200ms PropertyGrid 生成） |
---
### 统一包版本管理配置
为了避免多项目间的包版本冲突，项目使用 **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>
```
**优势**：
- 所有项目使用相同的包版本
- 升级版本时只需修改一处
- 避免版本冲突导致的编译或运行时错误
---

330
docs/architecture/testing-strategy.md
View File

@@ -1,330 +0,0 @@
# Testing Strategy
本节定义控件库的测试方法和组织策略，确保核心功能的稳定性和可靠性。
---
### Testing Pyramid
```
E2E Tests (手动测试)
/ \
Integration Tests (可选)
/ \
Unit Tests (核心逻辑)
```
**测试重点分配：**
- **Unit Tests (70%)**：核心业务逻辑、数据模型、工具类
- **Integration Tests (可选)**：控件与 ReactiveUI 的集成、主题系统
- **Manual Tests (必须)**：UI 渲染、主题切换、用户交互
**MVP 阶段不包括：**
- UI 自动化测试（Avalonia 提供 Headless 测试包，但 MVP 阶段依赖手动测试）
- 性能基准测试（除非发现明显性能问题）
- 跨平台兼容性测试（仅在 Windows 上测试）
---
### Test Organization
**测试项目结构：**
```
Penguin.AvaloniaUI.Tests/
├── Controls/
│ ├── PropertyGridTests.cs
│ ├── UserGuideTests.cs
│ └── ...
├── Layouts/
│ └── TwoColumnLayoutTests.cs
├── Themes/
│ └── ThemeManagerTests.cs
├── Utils/
│ ├── ReflectionHelperTests.cs
│ └── Converters/
│ └── TypeToEditorConverterTests.cs
└── TestHelpers/
├── MockObjects.cs
└── TestBase.cs
```
**命名约定：**
- 测试类：`{ClassName}Tests`
- 测试方法：`{MethodName}_{Scenario}_{ExpectedResult}`
---
### Unit Test Examples
**示例 1：测试 PropertyGrid 的反射逻辑**
```csharp
namespace Penguin.AvaloniaUI.Tests.Controls;
public class PropertyGridTests
{
[Fact]
public void RefreshProperties_WithValidObject_ShouldParseAllPublicProperties()
{
// Arrange
var testObject = new TestSettings
{
Name = "Test",
Age = 25,
IsEnabled = true
};
var propertyGrid = new PropertyGrid
{
SelectedObject = testObject
};
// Act
var properties = propertyGrid.Properties;
// Assert
Assert.Equal(3, properties.Count);
Assert.Contains(properties, p => p.Name == "Name" && p.PropertyType == typeof(string));
Assert.Contains(properties, p => p.Name == "Age" && p.PropertyType == typeof(int));
Assert.Contains(properties, p => p.Name == "IsEnabled" && p.PropertyType == typeof(bool));
}
[Fact]
public void RefreshProperties_WithCategoryAttribute_ShouldGroupByCategory()
{
// Arrange
var testObject = new CategorizedSettings();
var propertyGrid = new PropertyGrid
{
SelectedObject = testObject
};
// Act
var properties = propertyGrid.Properties;
var generalCategory = properties.Where(p => p.Category == "General").ToList();
var advancedCategory = properties.Where(p => p.Category == "Advanced").ToList();
// Assert
Assert.NotEmpty(generalCategory);
Assert.NotEmpty(advancedCategory);
}
[Fact]
public void RefreshProperties_WithNullObject_ShouldClearProperties()
{
// Arrange
var propertyGrid = new PropertyGrid
{
SelectedObject = new TestSettings()
};
// Act
propertyGrid.SelectedObject = null;
// Assert
Assert.Empty(propertyGrid.Properties);
}
}
```
---
**示例 2：测试 ThemeManager**
```csharp
namespace Penguin.AvaloniaUI.Tests.Themes;
public class ThemeManagerTests
{
[Fact]
public void ApplyTheme_WithLightTheme_ShouldLoadLightResources()
{
// Arrange
var app = CreateTestApplication();
// Act
ThemeManager.ApplyTheme(ThemeType.Light);
// Assert
var textPrimary = app.Resources["TextPrimary"] as SolidColorBrush;
Assert.NotNull(textPrimary);
// 浅色主题的主要文本应为深色
Assert.True(textPrimary.Color.R < 128);
}
[Fact]
public void ApplyTheme_SwitchingThemes_ShouldTriggerThemeChangedEvent()
{
// Arrange
var eventTriggered = false;
ThemeManager.ThemeChanged += (sender, type) => eventTriggered = true;
// Act
ThemeManager.ApplyTheme(ThemeType.Dark);
// Assert
Assert.True(eventTriggered);
}
private Application CreateTestApplication()
{
// 创建测试用的 Application 实例
return new Application();
}
}
```
---
**示例 3：测试 UserGuide 步骤流转**
```csharp
namespace Penguin.AvaloniaUI.Tests.Controls;
public class UserGuideTests
{
[Fact]
public void NextStepCommand_WhenNotLastStep_ShouldIncrementIndex()
{
// Arrange
var userGuide = new UserGuide();
userGuide.Steps.Add(new GuideStep { Title = "Step 1", Order = 0 });
userGuide.Steps.Add(new GuideStep { Title = "Step 2", Order = 1 });
userGuide.Steps.Add(new GuideStep { Title = "Step 3", Order = 2 });
// Act
userGuide.NextStepCommand.Execute(null);
// Assert
Assert.Equal(1, userGuide.CurrentStepIndex);
}
[Fact]
public void NextStepCommand_WhenLastStep_ShouldTriggerCompleteEvent()
{
// Arrange
var userGuide = new UserGuide();
userGuide.Steps.Add(new GuideStep { Title = "Step 1", Order = 0 });
var completedTriggered = false;
userGuide.Completed += (sender, args) => completedTriggered = true;
// Act
userGuide.NextStepCommand.Execute(null);
// Assert
Assert.True(completedTriggered);
}
[Fact]
public void PreviousStepCommand_WhenFirstStep_ShouldNotExecute()
{
// Arrange
var userGuide = new UserGuide();
userGuide.Steps.Add(new GuideStep { Title = "Step 1", Order = 0 });
// Act
var canExecute = userGuide.PreviousStepCommand.CanExecute(null);
// Assert
Assert.False(canExecute);
}
}
```
---
### Manual Testing Checklist
以下场景**必须通过示例应用手动测试**：
**PropertyGrid：**
- [ ] 绑定包含 6 种基础类型的对象，所有编辑器正确显示
- [ ] 修改属性值，SelectedObject 对象同步更新
- [ ] 只读属性禁用编辑器或显示为灰色
- [ ] 属性按 Category 分组显示，分组标题清晰
- [ ] 主题切换时，PropertyGrid 颜色正确更新
- [ ] 50 个属性的生成时间 < 200ms（使用秒表或 Stopwatch 测量）
**UserGuide：**
- [ ] 引导流程正确显示 Overlay 遮罩
- [ ] 目标控件区域挖空显示（清晰可见）
- [ ] 提示框在目标控件附近正确定位（Top/Bottom/Left/Right）
- [ ] "下一步"/"上一步"按钮功能正常
- [ ] 步骤进度显示正确（如 "2/5"）
- [ ] "跳过"和"完成"按钮触发完成事件
**主题系统：**
- [ ] 主题切换在 100ms 内完成，无闪烁
- [ ] 所有控件的颜色正确响应主题变化
- [ ] 浅色和暗色主题的对比度舒适（文本清晰可读）
- [ ] 主题切换时无控件错位或布局异常
**跨功能集成：**
- [ ] 在 PropertyGrid 编辑时切换主题，无崩溃
- [ ] 在 UserGuide 进行中修改 PropertyGrid，无异常
- [ ] 窗口缩放时，所有控件布局正确调整
---
### Test Helpers
**创建测试辅助类减少重复代码：**
```csharp
namespace Penguin.AvaloniaUI.Tests.TestHelpers;
public static class MockObjects
{
public class TestSettings
{
public string Name { get; set; } = "Default";
public int Age { get; set; } = 0;
public bool IsEnabled { get; set; } = false;
}
public class CategorizedSettings
{
[Category("General")]
public string Name { get; set; } = "Default";
[Category("Advanced")]
public int Timeout { get; set; } = 5000;
}
}
public class TestBase
{
protected Application CreateTestApplication()
{
var app = new Application();
// 加载测试用主题资源
return app;
}
}
```
---
### Running Tests
```bash
# 运行所有测试
dotnet test
# 运行特定测试类
dotnet test --filter "FullyQualifiedName~PropertyGridTests"
# 运行特定测试方法
dotnet test --filter "Name~RefreshProperties_WithValidObject"
# 生成代码覆盖率报告
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=html
```
**Visual Studio 测试运行器：**
1. 打开 Test Explorer（测试 → 测试资源管理器）
2. 点击"运行所有测试"或右键运行特定测试
3. 查看测试结果和失败详情
---

133
docs/architecture/unified-project-structure.md
View File

@@ -1,133 +0,0 @@
# Unified Project Structure
基于 Monorepo 策略和 .NET 项目组织最佳实践，以下是详细的项目文件结构：
```plaintext
D:\32_avalonia.ui/
├── .github/ # GitHub 工作流（Post-MVP）
│ └── workflows/
│ ├── ci.yml # 持续集成
│ └── release.yml # 发布流程
│
├── src/ # 源代码目录
│ ├── Penguin.AvaloniaUI/ # 核心控件库项目
│ │ ├── Controls/ # 业务场景控件
│ │ │ ├── PropertyGrid/
│ │ │ │ ├── PropertyGrid.cs # 主控件类
│ │ │ │ ├── PropertyItem.cs # 数据模型
│ │ │ │ ├── PropertyEditorFactory.cs # 编辑器工厂
│ │ │ │ └── Themes/
│ │ │ │ ├── PropertyGrid.axaml # 默认模板
│ │ │ │ └── PropertyGrid.axaml.cs
│ │ │ ├── UserGuide/
│ │ │ │ ├── UserGuide.cs
│ │ │ │ ├── GuideStep.cs
│ │ │ │ ├── Overlay.cs
│ │ │ │ ├── RichTooltip.cs
│ │ │ │ └── Themes/
│ │ │ │ ├── UserGuide.axaml
│ │ │ │ ├── Overlay.axaml
│ │ │ │ └── RichTooltip.axaml
│ │ │ └── ... (其他控件)
│ │ │
│ │ ├── Layouts/ # 布局控件
│ │ │ ├── TwoColumnLayout.cs
│ │ │ └── Themes/
│ │ │ └── TwoColumnLayout.axaml
│ │ │
│ │ ├── Themes/ # 主题系统
│ │ │ ├── Colors/ # 三层颜色架构
│ │ │ │ ├── Primitives.axaml # 原子层：Apple 官方颜色
│ │ │ │ ├── Light.axaml # 语义层：浅色主题
│ │ │ │ └── Dark.axaml # 语义层：暗色主题
│ │ │ └── Theme.axaml # 主题入口文件
│ │ │
│ │ ├── Utils/ # 工具类
│ │ │ ├── Converters/ # 值转换器
│ │ │ │ ├── BoolToVisibilityConverter.cs
│ │ │ │ └── TypeToEditorConverter.cs
│ │ │ ├── Helpers/ # 辅助类
│ │ │ │ ├── ReflectionHelper.cs # 反射工具
│ │ │ │ └── ValidationHelper.cs # 验证工具
│ │ │ └── Extensions/ # 扩展方法
│ │ │ └── ObservableExtensions.cs
│ │ │
│ │ ├── Assets/ # 资源文件
│ │ │ └── Icons/ # 图标资源
│ │ │
│ │ ├── Penguin.AvaloniaUI.csproj # 项目文件
│ │ └── AssemblyInfo.cs # 程序集信息
│ │
│ ├── Penguin.AvaloniaUI.SourceGenerators/ # Source Generator（Post-MVP）
│ │ ├── PropertyGridGenerator.cs
│ │ └── Penguin.AvaloniaUI.SourceGenerators.csproj
│ │
│ ├── Example/ # 示例应用项目
│ │ ├── App.axaml # 应用程序资源
│ │ ├── App.axaml.cs
│ │ ├── ViewModels/ # 视图模型
│ │ │ ├── MainWindowViewModel.cs
│ │ │ ├── PropertyGridDemoViewModel.cs
│ │ │ └── UserGuideDemoViewModel.cs
│ │ ├── Views/ # 视图/页面
│ │ │ ├── MainWindow.axaml
│ │ │ ├── MainWindow.axaml.cs
│ │ │ ├── Pages/
│ │ │ │ ├── ColorSystemPage.axaml # 颜色系统演示
│ │ │ │ ├── PropertyGridPage.axaml # PropertyGrid 演示
│ │ │ │ ├── UserGuidePage.axaml # UserGuide 演示
│ │ │ │ └── ComprehensiveDemoPage.axaml # 综合演示
│ │ │ └── ...
│ │ ├── Models/ # 测试数据模型
│ │ │ ├── DemoSettings.cs # PropertyGrid 测试类
│ │ │ └── LargeSettings.cs # 50 属性测试类
│ │ ├── Assets/ # 示例应用资源
│ │ ├── Example.csproj
│ │ └── Program.cs
│ │
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试项目
│ ├── Controls/
│ │ ├── PropertyGridTests.cs
│ │ ├── UserGuideTests.cs
│ │ └── ...
│ ├── Layouts/
│ │ └── TwoColumnLayoutTests.cs
│ ├── Themes/
│ │ └── ThemeManagerTests.cs
│ ├── Utils/
│ │ └── ReflectionHelperTests.cs
│ └── Penguin.AvaloniaUI.Tests.csproj
│
├── docs/ # 项目文档
│ ├── prd.md # 产品需求文档
│ ├── architecture.md # 架构文档（本文档）
│ ├── brief.md # 项目简介
│ └── brainstorm.md # 头脑风暴
│
├── .bmad-core/ # BMAD 框架配置
│ ├── core-config.yaml
│ ├── agents/
│ ├── tasks/
│ └── templates/
│
├── .editorconfig # 编辑器配置
├── .gitignore # Git 忽略规则
├── Directory.Packages.props # 统一包版本管理
├── README.md # 项目说明
├── LICENSE # 许可证（Post-MVP）
└── Penguin.AvaloniaUI.sln # 解决方案文件
```
**关键目录说明：**
| 目录 | 用途 | 命名空间 |
|------|------|----------|
| `Controls/` | 业务场景控件实现 | `Penguin.AvaloniaUI.Controls.*` |
| `Layouts/` | 布局控件实现 | `Penguin.AvaloniaUI.Layouts` |
| `Themes/` | 主题和样式系统 | `Penguin.AvaloniaUI.Themes` |
| `Utils/` | 工具类和辅助方法 | `Penguin.AvaloniaUI.Utils.*` |
| `Example/Views/Pages/` | 示例应用页面 | `Example.Views.Pages` |
| `Example/ViewModels/` | 示例应用 ViewModel | `Example.ViewModels` |
---

487
docs/brainstorming-session-results.md
View File

@@ -1,487 +0,0 @@
# Brainstorming Session Results
**Session Date:** 2025-10-15
**Facilitator:** Business Analyst Mary
**Participant:** Project Lead
---
## Executive Summary
**Topic:** Avalonia UI 库开发 - 基于 Semi 样式库的业务场景控件库
**Session Goals:**
- 明确项目战略定位和核心价值
- 系统化梳理控件清单和优先级
- 识别技术挑战和解决方案
- 制定渐进式开发路线图
**Techniques Used:**
1. First Principles Thinking（第一性原理）
2. Morphological Analysis（形态分析）
3. SCAMPER Method（SCAMPER 方法）
4. What If Scenarios（假设情景）
**Total Ideas Generated:** 50+
### Key Themes Identified:
- **市场定位**：填补"业务场景集成控件"的市场空白
- **技术栈**：.NET 8+ / Avalonia 最新版 / ReactiveUI / AOT / 苹果颜色系统
- **开发策略**：自顶向下、MVP 优先、渐进式替换
- **目标场景**：上位机开发 + AI 桌面应用
---
## Technique Sessions
### First Principles Thinking（第一性原理）- 40 分钟
**Description:** 回归基本原理，重新思考项目的核心价值和根本问题
#### Ideas Generated:
1. **核心问题识别**
- 市面上的 UI 库都是"基础控件库"（Button、TextBox 等通用组件）
- 真正加速开发的应该是"业务场景集成控件"（PropertyGrid、LoggingControl 等）
- 每个开发者业务需求不同，所以没有人做这些集成控件
- 对于固定场景（上位机 + AI 桌面），可以打造专用工具集
2. **业务控件的共同特征**
- 与数据模型耦合（追求"合适的通用性"而非"极致通用性"）
- 由多个基础控件组合而成，但代表通用业务场景
- 例如：PropertyGrid = 自动化 UI 生成；LoggingControl = 领域数据的完整交互
3. **市场空白的原因**
- 商业逻辑：开源作者倾向做"影响面广"的基础控件
- 需求差异：每个人的业务定义不同
- 技术障碍：AOT、反射限制等
- 对于固定场景（上位机 + AI 桌面），这些限制不存在
#### Insights Discovered:
- 项目定位：私有生产力工具 > 开源通用库
- 允许高度场景化，不追求过度通用性
- PropertyGrid 可以只支持常用类型，不需要覆盖所有边缘情况
#### Notable Connections:
- Source Generator 可以解决 AOT 反射限制
- 对接系统接口（ILogger 等）而非重新发明轮子
---
### Morphological Analysis（形态分析）- 25 分钟
**Description:** 系统化识别项目维度，探索不同选项的组合
#### Ideas Generated:
1. **控件数据模式维度**
- 选择：带数据模型的 UserControl（自包含业务单元）
- 允许 CustomControl 和 UserControl 混合存在
2. **主题系统维度**
- 选择：多主题，与 Avalonia 原生集成
- 采用苹果颜色系统（语义化、自适应暗色模式）
3. **样式定制维度**
- 选择：Style Class（通过 ClassName 切换主题）
- 利用 Avalonia 的样式扩展特性
4. **交互模式维度**
- 选择：ReactiveUI 作为核心交互数据流
- Command / Reactive / Event 混合使用
#### Insights Discovered:
- 控件类型不需要过度分类，实用性优先
- 抽象维度对固定场景项目价值有限
- 应聚焦具体控件清单和功能特性
---
### SCAMPER Method（SCAMPER 方法）- 30 分钟
**Description:** 基于 Semi/Ursa 进行系统化创新改造
#### Ideas Generated:
**S - Substitute（替代）:**
1. 颜色系统 → 苹果颜色系统（统一规范、语义化）
2. 传统样式 → Style Class 系统（灵活主题切换）
**C - Combine（组合）:**
1. 战略调整：只用 Semi（样式库），不用 Ursa（控件库）
2. 部署方式：NuGet 安装依赖，逐步替换而非 Copy 源码
**A - Adapt（调整适配）:**
1. Semi/Ursa 已原生支持 AOT，无需额外适配
2. ReactiveUI 只需适配自己的代码，标准库无需特殊集成
**M - Modify/Magnify（修改/放大）:**
1. LoggingControl 需要处理百万级日志流（唯一性能焦点）
2. 虚拟化 + 过滤策略
**E - Eliminate（消除简化）:**
1. Semi 中可删除大量不需要的样式代码
2. Ursa 完全不使用，减少依赖
**R - Reverse/Rearrange（逆向/重组）:**
1. **开发顺序逆转**：自顶向下，先定义复杂控件，再分解基础控件
2. **控件依赖设计**：先指定基础控件目标，适时插入复杂控件
#### Insights Discovered:
- 自顶向下避免"不知道要做什么基础控件"的困境
- 需求驱动：只做真正用到的
- 符合"快速渐进开发"目标
---
### What If Scenarios（假设情景）- 25 分钟
**Description:** 通过挑衅性情景探索边界和潜在问题
#### Ideas Generated:
**情景：极端性能挑战（百万级日志流）**
- 虚拟化性能应该可以支撑
- 过滤策略：每次只显示部分，上下卸载
- 需要编写性能测试
**情景：跨平台扩展（桌面 + Pad）**
- 当前场景：Windows 桌面 + Linux Pad（无多点触控）
- 通过 ClassName 切换桌面/Pad 模式（核心显示不变）
**情景：开源化路径**
- 策略：先私有实现大量功能，再开源
- 不影响当前设计决策
**情景：AOT 兼容性踩坑**
- PropertyGrid 如果 AOT 不可用，可以妥协
- 其他控件必须支持 AOT
- Source Generator 作为主要解决方案
**情景：依赖替换风险**
- 最差情况：不替换，可接受
- 策略：逐步替换，可回退
**情景：团队协作与学习曲线**
- 技术栈统一：ReactiveUI 为唯一方案
- 不会的就学，不提供多套 API
**情景：快速迭代 vs 质量**
- 策略：MVP + 迭代开发
- 控件库天然适合增量开发（每个控件相对独立）
- 慢慢替换到现有项目，降低风险
#### Insights Discovered:
- 职责边界明确：UI 库只负责展示，不管数据持久化
- 风险可控：允许妥协（PropertyGrid AOT）、允许不替换（Semi）
- MVP + 渐进式验证设计合理性
---
## Idea Categorization
### Immediate Opportunities
*Ideas ready to implement now*
#### 1. **依赖策略：只用 Semi，不用 Ursa**
- Description: 安装 Semi NuGet 包作为样式基础，删除 Ursa 依赖
- Why immediate: 简化依赖，减少不必要的代码
- Resources needed: 评估 Semi 样式完整性，确定需要自定义的部分
#### 2. **采用苹果颜色系统**
- Description: 建立语义化颜色规范（primary, secondary, accent, success, warning, error 等）
- Why immediate: 是所有控件样式的基础，必须先定义
- Resources needed: 研究 Apple Human Interface Guidelines 颜色系统，制定规范文档
#### 3. **开发顺序：自顶向下**
- Description: 先定义复杂控件需求，再从中分解基础控件
- Why immediate: 避免过度设计，需求驱动开发
- Resources needed: 完成控件清单优先级排序
#### 4. **MVP 第一阶段：PropertyGrid**
- Description: 最高优先级控件，自动从数据模型生成 UI
- Why immediate: 是最常用、价值最高的控件
- Resources needed: Source Generator 技术预研（AOT 支持）
#### 5. **建立项目结构**
- Description: 设置 .NET 8+、Avalonia 最新版、ReactiveUI 的项目模板
- Why immediate: 基础设施
- Resources needed: 项目脚手架、CI/CD 配置
---
### Future Innovations
*Ideas requiring development/research*
#### 1. **控件开发路线图（分阶段）**
- Description: 按优先级逐步实现完整控件库
- Development needed:
- Phase 1: PropertyGrid
- Phase 2: UserGuide 系列控件
- Phase 3: TextEditor
- Phase 4: MarkdownRender
- Phase 5: ImageEx
- Phase 6: LoggingControl
- Phase 7: Icon + 2xN Layout
- Phase 8: CodeEditor
- Phase 9: PathSelector（接口 + 实现）
- Timeline estimate: 6-12 个月（根据实际项目需求调整）
#### 2. **Chart 控件项目**
- Description: 调研 Avalonia 现有 Chart 库，进行二次开发
- Development needed: 独立项目，包含在当前大项目下
- Timeline estimate: 单独规划
#### 3. **布局/容器优化系列**
- Description: 专注性能优化的布局控件
- Development needed:
- 先实现 2xN Layout（PropertyGrid 专用）
- 后续根据需要扩展其他布局
- Timeline estimate: 按需迭代
#### 4. **Avalonia 工具类库**
- Description: 开发效率提升工具集
- Development needed:
- VisualTreeHelper/LogicalTreeHelper（视觉树/逻辑树查找）
- ControlLocator（定位控件）
- AOT Binding Helpers（AOT 绑定辅助）
- ThemeManager Commands（主题切换命令）
- LocalizationManager Commands（语言切换命令）
- 其他工具类按需添加
- Timeline estimate: 伴随控件开发逐步完善
#### 5. **桌面/Pad 双模式支持**
- Description: 通过 ClassName 切换不同平台的样式微调
- Development needed: 样式定义、响应式布局策略
- Timeline estimate: 第二阶段
#### 6. **开源准备**
- Description: 在私有功能完善后，准备开源
- Development needed: 文档、示例、License、贡献指南
- Timeline estimate: 长期目标
---
### Moonshots
*Ambitious, transformative concepts*
#### 1. **LoggingControl 百万级日志流处理**
- Description: 支持每秒数万条日志的实时显示和过滤
- Transformative potential: 成为 Avalonia 生态中性能最强的日志控件
- Challenges to overcome:
- 虚拟化渲染优化
- 内存管理策略
- 高效的过滤算法
- 性能测试和压力测试
#### 2. **PropertyGrid 的 AOT 完全支持**
- Description: 在 AOT 模式下实现完整的动态 UI 生成
- Transformative potential: 证明 Source Generator 可以完美替代反射
- Challenges to overcome:
- Source Generator 复杂度
- 类型推断和代码生成
- 编译时元数据收集
- 可能需要妥协某些高级特性
#### 3. **渐进式替换现有项目**
- Description: 在不影响稳定性的前提下，将新控件逐步替换到生产项目
- Transformative potential: 在真实场景中验证控件设计，快速迭代
- Challenges to overcome:
- 兼容性保障
- 回退机制
- 性能对比验证
- 团队培训
---
### Insights & Learnings
*Key realizations from the session*
- **战略定位清晰**: 私有生产力工具定位允许高度场景化，不追求过度通用性，可以大胆做取舍
- **需求驱动设计**: 上位机 + AI 桌面应用的固定场景，填补"业务场景集成控件"的市场空白
- **技术栈统一**: .NET 8+ / Avalonia 最新版 / ReactiveUI / AOT，不向后兼容，换取开发效率
- **职责边界明确**: UI 库只负责展示，不管数据持久化；对接系统接口（ILogger 等），不重新发明轮子
- **快速迭代哲学**: 功能优先，测试缓缓（除非必要如性能测试）；MVP + 渐进式开发，在真实项目中验证
- **自顶向下优势**: 先定义复杂控件，再分解基础控件，避免过度设计，需求驱动
- **风险可控策略**: PropertyGrid 可以妥协 AOT；依赖替换最差不替换；控件独立可回退
- **苹果颜色系统的价值**: 语义化颜色、自适应暗色模式、动态颜色支持、设计一致性
- **ReactiveUI 的核心优势**: 统一的数据流处理模型、天然支持异步操作、便于组合复杂交互逻辑
---
## Action Planning
### Top 3 Priority Ideas
#### #1 Priority: 建立项目基础设施和颜色系统
**Rationale:**
- 所有后续开发的基础
- 颜色系统是样式定义的核心
- 项目结构影响长期可维护性
**Next steps:**
1. 创建 .NET 8+ 解决方案，配置 Avalonia 最新版 + ReactiveUI
2. 安装 Semi NuGet 包，评估样式完整性
3. 制定苹果颜色系统规范文档（语义颜色、浅色/深色主题）
4. 建立 Style Class 命名规范
5. 搭建 CI/CD 基础（构建、测试、AOT 兼容性检查）
**Resources needed:**
- Apple Human Interface Guidelines 文档
- Semi 源码分析
- Avalonia 样式系统文档
**Timeline:** 1-2 周
---
#### #2 Priority: PropertyGrid MVP 开发
**Rationale:**
- 最高价值控件
- 验证自顶向下开发策略
- 验证 AOT + Source Generator 技术路线
**Next steps:**
1. 定义 PropertyGrid 的核心功能范围（MVP）
- 支持的属性类型（string, int, bool, enum, 等）
- 基础布局（2xN Layout）
- 数据绑定方式
2. 设计 Source Generator 方案（AOT 支持）
3. 实现 2xN Layout 基础控件
4. 开发 PropertyGrid 核心逻辑
5. 在一个小型测试项目中验证
**Resources needed:**
- Source Generator 技术预研
- Roslyn API 文档
- 测试项目（上位机场景）
**Timeline:** 3-4 周
---
#### #3 Priority: 制定完整控件开发路线图
**Rationale:**
- 明确长期目标和里程碑
- 合理分配开发资源
- 识别控件间的依赖关系
**Next steps:**
1. 完成完整控件清单（包括工具类）
2. 为每个控件制定功能规格（简要）
3. 识别控件间的依赖关系（例如：UserGuide 依赖 Overlay）
4. 制定分阶段开发计划（6 个月、1 年、长期）
5. 定义 MVP 范围和"可选特性"
6. 建立控件开发模板和最佳实践文档
**Resources needed:**
- 现有项目需求分析
- 竞品控件库调研（Semi、Ursa、Material Design）
**Timeline:** 1 周
---
## Reflection & Follow-up
### What Worked Well
- 第一性原理帮助明确了项目的核心价值和市场定位
- SCAMPER 方法发现了"自顶向下开发"这一关键策略调整
- What If Scenarios 识别了潜在风险和应对方案
- 讨论过程中不断澄清边界，避免了过度设计
### Areas for Further Exploration
- **Source Generator 技术深度**: 需要专门的技术预研，验证 PropertyGrid 的 AOT 可行性
- **性能基准测试**: LoggingControl 的百万级日志场景需要建立性能基准
- **Semi 样式分析**: 详细分析 Semi 的样式结构，确定哪些需要保留、哪些需要删除
- **控件功能规格**: 每个控件需要更详细的功能设计文档
- **跨平台测试**: 验证 Windows 桌面和 Linux Pad 的样式差异
### Recommended Follow-up Techniques
- **SWOT 分析**: 评估项目的优势、劣势、机会、威胁
- **用户故事映射**: 从用户角度设计控件功能
- **技术尖峰（Spike）**: 对 Source Generator、LoggingControl 性能等关键技术进行原型验证
### Questions That Emerged
- Source Generator 能否支持 PropertyGrid 的所有预期功能？
- Semi 的样式系统如何与苹果颜色系统集成？
- LoggingControl 的虚拟化策略具体实现方案？
- 如何设计控件的可扩展性（模板、样式、行为）？
- Chart 控件选择哪个现有库进行二次开发？
- 如何平衡"快速开发"和"代码质量"？
### Next Session Planning
- **Suggested topics:**
- PropertyGrid 详细设计会议
- Source Generator 技术预研总结
- 苹果颜色系统规范制定
- 控件模板和最佳实践
- **Recommended timeframe:** PropertyGrid MVP 完成后（4-6 周后）
- **Preparation needed:**
- 完成项目基础设施搭建
- 完成 Source Generator 技术预研
- 收集现有项目中的实际使用场景
---
*Session facilitated using the BMAD-METHOD™ brainstorming framework*

671
docs/brief.md
View File

@@ -1,671 +0,0 @@
# Project Brief: Avalonia 业务场景控件库
**项目名称:** Penguin.AvaloniaUI
**创建日期:** 2025-10-15
**版本:** 1.1
**状态:** 草稿
---
## Executive Summary
本项目旨在开发一套基于 **Semi 设计系统样式**的 **Avalonia UI 业务场景控件库**，专注于上位机开发和 AI 桌面应用场景。不同于市面上常见的基础控件库（Button、TextBox 等），我们聚焦于**业务场景集成控件**（PropertyGrid、LoggingControl、UserGuide 等），这些控件能够显著加速特定场景下的应用开发。
**核心问题:** 当前 Avalonia 生态缺乏针对上位机和 AI 桌面应用的高度集成业务控件，开发者需要反复实现相似的复合控件，降低了开发效率。
**目标市场:** 使用 Avalonia 开发上位机软件和 AI 桌面应用的 .NET 开发者（私有使用，未来可能开源）。
**关键价值主张:**
- **业务场景即用**: 提供开箱即用的业务控件（PropertyGrid、UserGuide 等），而非仅提供基础砖块
- **现代技术栈**: 完全基于 .NET 8+、Avalonia 最新版、ReactiveUI、AOT 支持
- **多主题+国际化**: 内置多色彩主题系统和语言切换支持
- **渐进式集成**: 支持在现有项目中逐步替换，降低迁移风险
---
## Problem Statement
### 当前痛点
1. **基础控件库的局限性**
- 市面上 Avalonia 的 UI 库（如 Material.Avalonia、Ursa）主要提供基础控件（Button、TextBox、ComboBox）
- 真正加速开发的是**业务场景集成控件**（PropertyGrid、LoggingControl、UserGuide），但这些缺失
- 开发者被迫在每个项目中重复实现相似的复合控件
2. **上位机和 AI 桌面应用的特殊需求未被满足**
- **PropertyGrid**: 自动从数据模型生成配置 UI，是上位机应用的核心需求
- **LoggingControl**: 需要处理海量实时日志（百万级），现有控件性能不足
- **UserGuide**: 新手引导、功能提示等应用内帮助系统
- **TextEditor/MarkdownRender**: AI 应用的文本编辑和富文本显示需求
3. **技术债务和兼容性负担**
- 许多现有库为了兼容旧版本（.NET Framework、Avalonia 0.x），牺牲了现代特性
- AOT 支持不完善，反射依赖严重
- 缺乏统一的数据流处理模式（ReactiveUI）
### 影响量化
- **开发效率**: 每个上位机项目平均需要花费 **30-50% 的时间**重复实现 PropertyGrid、LoggingControl 等常见控件
- **维护成本**: 缺乏统一控件库导致代码重复，维护成本高
- **技术迭代**: 旧有控件库的技术债务阻碍了向 AOT、现代 Avalonia 特性的迁移
### 为什么现在？
- **Avalonia 已成熟**: 11.x 版本稳定，跨平台能力强，AOT 支持完善
- **Semi 设计系统可用**: Semi Design 已经移植到 Avalonia，提供了优秀的样式基础
- **.NET 8+ 和 AOT 普及**: 现代 .NET 技术栈已经足够成熟，不再需要向后兼容
- **私有场景清晰**: 上位机 + AI 桌面应用的固定场景，允许高度场景化设计
---
## Proposed Solution
### 核心理念
打造一套**业务场景优先**的 Avalonia UI 控件库，采用**自顶向下开发策略**：
- **不是**"先做基础控件，再组合成复杂控件"
- **而是**"先定义业务控件需求，再从中分解必要的基础控件"
这种方法确保我们只开发真正需要的组件，避免过度设计。
### 关键差异化优势
| 维度 | 传统控件库 | 本项目 |
| ------------------ | ------------------------- | -------------------------------------------- |
| **控件类型** | 基础控件（Button、Input） | 业务场景控件（PropertyGrid、LoggingControl） |
| **目标场景** | 通用应用 | 上位机 + AI 桌面应用 |
| **技术栈** | 兼容旧版本 | .NET 8+、AOT、ReactiveUI |
| **设计哲学** | 极致通用性 | 合适的场景化（允许取舍） |
| **开发方式** | 自底向上 | 自顶向下（需求驱动） |
### 技术方案
1. **样式系统**
- 基于 **Semi Design** 样式库（不使用 Ursa 控件库）
- 采用 **苹果颜色系统**（语义化颜色、自适应暗色模式）
- 通过 **Style Class** 实现灵活的主题切换
2. **数据流处理**
- 统一采用 **ReactiveUI** 作为核心交互模式
- 支持 Command、Reactive、Event 混合使用
- 简化异步操作和复杂交互逻辑
3. **AOT 兼容性**
- 使用 **Source Generator** 替代运行时反射（PropertyGrid 的关键技术）
- Semi 已原生支持 AOT，无需额外适配
- 允许在必要时妥协某些高级特性（如 PropertyGrid 的完全动态性）
4. **渐进式集成**
- 以 **NuGet 包**形式安装，而非 Copy 源码
- 支持在现有项目中逐步替换旧控件
- 提供回退机制，确保稳定性
### 高层愿景
将本控件库打造成 **Avalonia 上位机和 AI 桌面应用的标准工具集**，填补"业务场景集成控件"的市场空白。未来在功能完善后，考虑开源以惠及更广泛的开发者社区。
---
## Target Users
### Primary User Segment: 上位机软件开发者
**人群特征:**
- .NET 开发者，主要使用 C#
- 从事工业控制、设备监控、自动化测试等上位机软件开发
- 团队规模：个人开发者或小型团队（3-10 人）
- 通常有 WPF 或 WinForms 背景，正在迁移到 Avalonia
**当前行为和工作流:**
- 使用 Avalonia 构建跨平台桌面应用（Windows 为主，部分需要 Linux 支持）
- 频繁需要实现设备参数配置界面（PropertyGrid）
- 需要实时显示设备日志和状态信息
- 重视性能和稳定性
**核心痛点:**
- **PropertyGrid 缺失**: 每次都要手写大量 XAML 来实现配置界面
- **日志控件性能不足**: 设备日志量大时（每秒数千条）UI 卡顿
- **样式不统一**: 各个控件的视觉风格不一致，UI 显得不专业
- **缺乏成熟的业务控件**: UserGuide、PathSelector 等常见需求需要自己实现
**目标:**
- 快速构建功能完整、视觉专业的上位机应用
- 减少重复性 UI 开发工作，专注业务逻辑
- 应用性能稳定，能够处理高频数据更新
### Secondary User Segment: AI 桌面应用开发者
**人群特征:**
- .NET 开发者，构建 AI 相关的桌面工具
- 应用场景：AI 模型管理、Prompt 工具、本地 LLM 客户端等
- 关注用户体验和现代化 UI
- 希望快速迭代和原型验证
**当前行为和工作流:**
- 使用 Avalonia 构建现代化桌面应用
- 需要集成 Markdown 渲染、代码编辑器、图像预览等
- 频繁使用配置面板（PropertyGrid）管理 AI 模型参数
- 需要实时显示 AI 任务日志
**核心痛点:**
- **缺乏现成的 Markdown/代码编辑器**: 需要集成第三方库或自己实现
- **AI 参数配置麻烦**: 参数类型多样（字符串、数字、枚举、布尔值），手动写 UI 繁琐
- **日志和状态显示**: AI 任务运行时需要清晰的日志和进度反馈
- **用户引导**: AI 工具功能复杂，需要新手引导
**目标:**
- 快速构建功能丰富的 AI 桌面应用原型
- 提供专业的用户体验（类似商业软件）
- 支持复杂的参数配置和实时反馈
---
## Goals & Success Metrics
### Business Objectives
- **快速验证核心价值**: 在 **1 个月内**完成 MVP，验证 PropertyGrid 和 UserGuide 的核心功能
- **技术栈现代化**: 所有控件 100% 支持 .NET 8+ 和 AOT 编译
- **建立主题和国际化基础**: 完成多色彩主题系统和语言切换框架
- **为后续开发打基础**: 在 MVP 开发过程中积累额外的基础控件和工具库
### User Success Metrics
- **控件易用性**: 用户能够在 **10 分钟内**集成并使用 PropertyGrid
- **样式一致性**: 所有控件在多主题下风格统一，用户无需额外调整样式
- **国际化支持**: 控件内置文本支持多语言切换
- **基础文档完整性**: MVP 控件有基础的 README 和使用示例
### Key Performance Indicators (KPIs)
- **MVP 控件覆盖率**: 1 个月内完成 **PropertyGrid + UserGuide + 颜色系统 + 国际化框架**
- **AOT 兼容性**: **100%** 的控件支持 AOT 编译（PropertyGrid 可以妥协某些高级特性）
- **集成成功率**: 在测试项目中集成时，**90%** 的情况下无需代码重构（仅配置 XAML）
- **开发过程中的产出**: 在实现 PropertyGrid 和 UserGuide 时，产出 **5+ 个可复用的基础控件/工具**
---
## MVP Scope (1 个月交付)
### Core Features (Must Have)
#### 1. **苹果颜色系统 + 多主题框架**
- **描述**: 语义化颜色系统（primary, secondary, success, warning, error 等）+ 多色彩主题切换基础设施
- **MVP 理由**: 所有控件样式的基础，必须首先建立
- **交付标准**:
- 支持至少 3 种色彩主题（浅色、深色、自定义）
- 颜色自动适配，支持运行时切换
- Semi 样式与苹果颜色系统无缝集成
#### 2. **国际化框架 (i18n)**
- **描述**: 多语言切换支持，控件内置文本的语言资源管理
- **MVP 理由**: 现代应用的基础需求，提前建立避免后期重构
- **交付标准**:
- 支持至少 2 种语言（中文、英文）
- 提供语言切换 API
- 所有 MVP 控件的内置文本支持多语言
#### 3. **PropertyGrid - 属性网格控件**
- **描述**: 自动从数据模型生成配置 UI，支持常用属性类型（string, int, double, bool, enum, DateTime）
- **MVP 理由**: 最高价值控件，是上位机和 AI 应用的核心需求
- **技术关键**: 使用 Source Generator 实现 AOT 支持（可妥协）
- **交付标准**:
- 支持基础数据绑定、属性分组、只读属性
- 验证提示（基础版）
- 在开发过程中会产出依赖的基础控件（2xN Layout 等）
#### 4. **UserGuide 系列控件**
- **描述**: 新手引导（Onboarding）、功能提示（Tooltip）、应用内 Tour
- **MVP 理由**: AI 桌面应用的重要需求，提升用户体验
- **交付标准**:
- UserGuide 引导流程控件（步骤式引导）
- 增强的 Tooltip 控件（支持富文本）
- 在开发过程中会产出依赖的基础控件（Overlay、Popup 等）
#### 5. **额外产出的基础控件和工具库**
- **描述**: 在开发 PropertyGrid 和 UserGuide 过程中产出的可复用组件
- **预期包含**:
- 2xN Layout（PropertyGrid 专用布局）
- Overlay / Popup（UserGuide 依赖）
- VisualTreeHelper、LogicalTreeHelper（查找工具）
- ThemeManager Commands（主题切换命令）
- LocalizationManager（语言切换管理）
- 其他按需开发的工具类
### Out of Scope for MVP (移至 Post-MVP)
- LoggingControl（日志显示控件）
- TextEditor / CodeEditor
- MarkdownRender
- ImageEx（图像预览增强控件）
- PathSelector（文件/文件夹选择器）
- Chart 控件（独立项目）
- Icon 系统（除非 UserGuide 必需）
- 高级布局优化
- 完整的单元测试覆盖（仅对核心功能测试）
- 详尽的文档（仅提供核心控件的 README 和使用示例）
### MVP Success Criteria
MVP 成功的标志是（**1 个月内交付**）：
1. **颜色系统和主题框架可用**：至少 3 种主题，运行时流畅切换
2. **国际化框架可用**：至少支持中英文切换，所有 MVP 控件内置文本已翻译
3. **PropertyGrid 可在测试项目中使用**：支持常用类型，基础数据绑定和验证
4. **UserGuide 可在测试项目中使用**：引导流程完整，Tooltip 增强功能可用
5. **AOT 编译成功**：所有控件能够在 AOT 模式下工作（PropertyGrid 可妥协某些特性）
6. **产出 5+ 个可复用的基础控件/工具**：为后续开发打下基础
---
## Post-MVP Vision
> **注意**: 以下所有功能和技术需求将在 MVP 完成后（1 个月后）根据实际开发情况和需求重新评估和确定优先级。
### 待评估的控件和功能（MVP 后决定）
#### 高优先级候选
- **LoggingControl**: 高性能日志显示控件，支持虚拟化渲染、实时过滤、级别高亮
- 技术挑战：百万级日志流的性能优化
- 价值：上位机和 AI 应用的实时反馈核心
- **TextEditor**: 基础文本编辑器，支持语法高亮
- 可考虑集成第三方库或自行实现
- **MarkdownRender**: Markdown 渲染控件
- AI 应用的常见需求
#### 中优先级候选
- **ImageEx**: 图像预览增强控件，支持缩放、旋转、加载状态
- **PathSelector**: 文件/文件夹选择器，支持跨平台差异（Windows/Linux）
- **CodeEditor**: 高级代码编辑器，支持多语言、自动补全、错误提示
- **Icon 系统**: 统一的图标管理系统
#### 长期探索方向
- **Chart 控件库**: 独立项目，提供常见图表类型（折线图、柱状图、饼图等）
- **桌面/Pad 双模式支持**: 通过 ClassName 切换不同平台的样式微调
- **高级布局控件**: 针对复杂场景的布局优化
- **完整的业务控件生态**: 覆盖上位机和 AI 桌面应用的 90% 常见场景
- **开源准备**: 完善文档、示例、贡献指南，准备开源发布
---
## Technical Considerations
### Platform Requirements
- **Target Platforms**: Windows（主要）、Linux（次要）、macOS（可选）
- **Framework**: .NET 8+ （不向后兼容 .NET Framework 或旧版 .NET）
- **Avalonia Version**: 11.x 或更高（最新稳定版）
- **Browser/OS Support**:
- Windows: Windows 10/11
- Linux: Ubuntu 20.04+, Debian 11+（适配 Linux Pad 场景，无多点触控）
- **Performance Requirements**:
- UI 渲染: 60fps（16ms 每帧）
- LoggingControl: 支持每秒 10,000 条日志流，峰值内存 < 500MB
### Technology Preferences
- **Frontend Framework**: Avalonia 11.x
- **UI Data Flow**: ReactiveUI（统一的数据流处理模式）
- **Styling System**:
- 基于 Semi Design 样式库（NuGet 安装）
- 采用苹果颜色系统（语义化颜色、自适应暗色模式）
- 通过 Style Class 实现主题切换
- **AOT Support**:
- 使用 Source Generator 替代运行时反射（PropertyGrid）
- 避免使用动态类型和 `Reflection.Emit`
- **Testing**: xUnit + FluentAssertions（仅对性能关键部分测试）
### Architecture Considerations
#### Repository Structure
```
D:\32_avalonia.ui/
├── src/
│ ├── Penguin.AvaloniaUI/ # 核心控件库
│ │ ├── Controls/ # 控件实现
│ │ │ ├── PropertyGrid/ # 属性网格
│ │ │ ├── UserGuide/ # 用户引导系列
│ │ │ └── ... # 其他控件（按需添加）
│ │ ├── Layouts/ # 布局控件（2xN Layout 等）
│ │ ├── Themes/ # 主题和样式
│ │ │ ├── ColorSystem/ # 苹果颜色系统
│ │ │ └── StyleClasses/ # Style Class 定义
│ │ ├── Localization/ # 国际化资源
│ │ │ ├── Resources/ # 语言资源文件
│ │ │ └── LocalizationManager.cs
│ │ └── Utils/ # 工具类（TreeHelper、ThemeManager）
│ ├── Penguin.AvaloniaUI.SourceGenerators/ # Source Generator（PropertyGrid AOT 支持，可选）
│ ├── Example/ # 示例项目
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试
├── docs/ # 文档
│ ├── brief.md # 项目简报（本文档）
│ ├── brainstorming-session-results.md # 头脑风暴成果
│ └── ... # 其他文档
└── .bmad-core/ # BMAD 框架配置
```
#### Service Architecture
- **控件独立性**: 每个控件尽量独立，减少相互依赖
- **自顶向下开发**: 先定义复杂控件（PropertyGrid），再分解基础控件（2xN Layout）
- **渐进式集成**: 以 NuGet 包形式发布，支持逐步替换现有项目中的旧控件
#### Integration Requirements
- **Semi Design**: 安装 Semi.Avalonia NuGet 包，集成样式系统
- **ReactiveUI**: 核心依赖，所有控件的数据流处理基于 ReactiveUI
- **i18n Framework**: 使用 Avalonia 的本地化机制或自定义轻量级框架
#### Security/Compliance
- **无特殊安全需求**: 私有控件库，不涉及网络通信或敏感数据处理
- **License**: 私有使用，未来开源时选择 MIT License（待定）
---
## Constraints & Assumptions
### Constraints
#### Budget
- **无外部资金**: 个人/团队项目，无商业预算
- **依赖开源库**: 尽量使用开源库（Semi、ReactiveUI），避免商业库授权成本
#### Timeline
- **MVP 目标**: **1 个月**完成核心功能（颜色系统 + 国际化 + PropertyGrid + UserGuide）
- **长期目标**: MVP 完成后根据实际需求和开发情况重新规划
- **渐进式开发**: 每个控件相对独立，可以分阶段交付
#### Resources
- **开发人员**: 1-2 人（主要开发者 + 偶尔协作）
- **时间投入**: 业余时间开发（每周 10-20 小时）
- **测试资源**: 有 3 个现有上位机项目可用于真实场景验证
#### Technical
- **AOT 限制**: 避免运行时反射，使用 Source Generator 替代（PropertyGrid 可以妥协某些高级特性）
- **平台兼容性**: 主要支持 Windows，Linux 次要（Linux Pad 场景无多点触控）
- **MVP 性能要求**: 基础控件无特殊性能要求，优先功能完整性
### Key Assumptions
- **Avalonia 生态稳定**: 假设 Avalonia 11.x 及以上版本 API 稳定，无重大 Breaking Changes
- **Semi 样式可用**: 假设 Semi.Avalonia 的样式系统满足需求，不需要大幅修改
- **ReactiveUI 学习成本可接受**: 团队愿意学习 ReactiveUI，不需要提供多套 API
- **上位机和 AI 桌面应用需求明确**: 当前场景的控件需求清晰，不会频繁变化
- **AOT 可以妥协**: PropertyGrid 如果在 AOT 下无法实现完全动态性，可以接受妥协（例如只支持常用类型）
- **渐进式替换可行**: 现有项目可以逐步替换旧控件，不需要一次性全部迁移
- **开源时机可控**: 在私有使用充分验证后再开源，不影响当前设计决策
---
## Risks & Open Questions
### Key Risks (MVP 阶段)
- **时间压力**: 1 个月完成 4 个核心功能（颜色系统、国际化、PropertyGrid、UserGuide），时间紧张
- **影响**: 可能无法按时完成所有功能，或功能不够完善
- **缓解措施**: 明确 MVP 最小范围，优先核心功能；允许削减次要特性；制定灵活的里程碑计划
- **Semi 样式集成复杂度**: Semi.Avalonia 的样式结构可能与预期不符，需要大量自定义
- **影响**: 样式开发时间超出预期，延误 MVP 交付
- **缓解措施**: 快速评估 Semi 的可用性；必要时削减 Semi，仅保留核心部分或自定义样式系统
- **PropertyGrid Source Generator 技术复杂度**: 如果 Source Generator 实现困难，可能影响 MVP 交付
- **影响**: PropertyGrid 在 AOT 下不可用，或仅支持有限类型
- **缓解措施**: MVP 阶段允许妥协，先实现基础功能（不使用 Source Generator），AOT 支持留到后期
- **UserGuide 控件设计复杂度**: 引导流程、Overlay、Popup 等依赖控件可能比预期复杂
- **影响**: UserGuide 功能不完善，或占用过多开发时间
- **缓解措施**: 聚焦核心引导流程，Tooltip 增强功能可以简化；参考现有开源实现
- **时间和精力不足**: 业余时间开发，进度可能受到工作、生活影响
- **影响**: MVP 交付延期
- **缓解措施**: 制定每周里程碑，及时调整优先级；聚焦核心功能，削减非必要特性
### Open Questions (MVP 阶段)
- **Semi 的样式系统如何与苹果颜色系统集成?** 是否需要修改 Semi 源码？
- **国际化框架选择**: 使用 Avalonia 内置机制还是自定义轻量级框架？
- **PropertyGrid 的 MVP 范围**: 支持哪些属性类型？是否需要 Source Generator？
- **UserGuide 的交互流程设计**: 如何设计引导步骤的配置和流转逻辑？
- **如何设计控件的可扩展性?** 模板、样式、行为的扩展机制（MVP 阶段可能不涉及）
- **如何平衡"快速开发"和"代码质量"?** MVP 阶段单元测试覆盖到什么程度？
### Areas Needing Further Research (MVP 阶段)
- **Semi 样式分析**: 快速分析 Semi.Avalonia 的样式结构，确定可用性
- **苹果颜色系统规范**: 制定详细的颜色系统文档（颜色定义、语义化规则、多主题适配）
- **国际化最佳实践**: 研究 Avalonia 的本地化机制，选择最佳方案
- **PropertyGrid 功能规格**: 明确 MVP 范围，定义支持的属性类型和功能
- **UserGuide 设计模式**: 研究现有引导控件的设计模式，确定实现方案
- **ReactiveUI 快速入门**: 总结 ReactiveUI 在 Avalonia 控件开发中的常见用法
### MVP 后需要研究的问题
以下问题将在 MVP 完成后根据实际需求再进行研究：
- Source Generator 深度应用（PropertyGrid 的完整 AOT 支持）
- LoggingControl 的虚拟化策略和性能优化
- Chart 控件选择和二次开发
- 跨平台兼容性测试（Linux、macOS）
- 开源准备和策略
---
## Appendices
### A. Research Summary
#### 头脑风暴会议 (2025-10-15)
- **方法**: First Principles Thinking、Morphological Analysis、SCAMPER、What If Scenarios
- **成果**: 明确了项目定位（业务场景控件 > 基础控件）、技术栈（.NET 8+、Avalonia、ReactiveUI、AOT）、开发策略（自顶向下、MVP 优先）
- **关键洞察**:
- 市场空白：业务场景集成控件（PropertyGrid、LoggingControl）在 Avalonia 生态中缺失
- 私有场景优势：允许高度场景化设计，不追求过度通用性
- 自顶向下优势：需求驱动，避免过度设计
- 风险可控：PropertyGrid 可以妥协 AOT；依赖替换最差不替换
**详细内容**: 见 `docs/brainstorming-session-results.md`
---
### B. Stakeholder Input
*（目前无外部利益相关者，仅内部团队使用）*
---
### C. References
- **Apple Human Interface Guidelines**: https://developer.apple.com/design/human-interface-guidelines/color
- **Semi Design (Web)**: https://semi.design/
- **Semi.Avalonia**: https://github.com/irihitech/Semi.Avalonia
- **Avalonia Documentation**: https://docs.avaloniaui.net/
- **ReactiveUI Documentation**: https://www.reactiveui.net/
- **Source Generator Tutorial**: https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview
---
## Next Steps (MVP - 1 个月)
### 第 1 周：基础设施 + 颜色系统
#### 目标
建立项目基础设施，完成苹果颜色系统和多主题框架
#### 行动项
1. **项目基础设施**（1-2 天）
- ✅ 已完成：.NET 8+ 解决方案，Avalonia 11.x + ReactiveUI 配置
- ✅ 已完成：项目结构（Penguin.AvaloniaUI、Example、Tests）
- 安装 Semi.Avalonia NuGet 包，快速评估可用性
- 配置 AOT 编译支持
2. **苹果颜色系统实现**（3-4 天）
- 研究 Apple Human Interface Guidelines 颜色系统
- 定义语义化颜色（primary, secondary, success, warning, error, background, surface 等）
- 实现至少 3 种主题（浅色、深色、自定义）
- 实现 ThemeManager 和主题切换 API
- 将 Semi 样式与颜色系统集成
3. **基础工具类**（1 天）
- 实现 VisualTreeHelper、LogicalTreeHelper
- 实现主题切换 Command
#### 交付物
- 可运行的项目框架
- 3 种主题可流畅切换
- ThemeManager API 文档和示例
---
### 第 2 周：国际化框架 + PropertyGrid 基础
#### 目标
完成国际化框架，开始 PropertyGrid 核心功能开发
#### 行动项
1. **国际化框架实现**（2-3 天）
- 研究 Avalonia 本地化机制，选择实现方案
- 实现 LocalizationManager 和语言切换 API
- 准备中英文资源文件
- 为后续控件建立多语言支持模板
2. **PropertyGrid 设计和依赖控件**（3-4 天）
- 明确 PropertyGrid 的 MVP 功能范围（支持的属性类型）
- 实现 2xN Layout 布局控件（左侧标签，右侧编辑器）
- 设计 PropertyGrid 的数据模型和 API
- 实现基础的属性项控件（TextBox、NumericUpDown、CheckBox、ComboBox）
#### 交付物
- 国际化框架可用，支持中英文切换
- 2xN Layout 控件完成
- PropertyGrid 设计文档和基础控件
---
### 第 3 周：PropertyGrid 完整实现
#### 目标
完成 PropertyGrid 的核心功能
#### 行动项
1. **PropertyGrid 核心功能**（5-6 天）
- 实现属性自动生成逻辑（基于反射或手动配置）
- 支持常用属性类型：string, int, double, bool, enum, DateTime
- 实现属性分组功能
- 实现只读属性支持
- 实现基础验证提示
2. **PropertyGrid 测试和优化**（1-2 天）
- 在 Example 项目中集成测试
- 修复发现的 Bug
- 优化性能和用户体验
- 编写基础 README 和使用示例
#### 交付物
- PropertyGrid 可在 Example 项目中使用
- 支持常用属性类型和基础功能
- README 和使用示例
---
### 第 4 周：UserGuide 实现 + 收尾
#### 目标
完成 UserGuide 控件，整体测试和优化
#### 行动项
1. **UserGuide 依赖控件**（2-3 天）
- 实现 Overlay 控件（半透明遮罩）
- 实现增强的 Popup 控件
- 实现增强的 Tooltip 控件（支持富文本）
2. **UserGuide 核心功能**（2-3 天）
- 实现引导流程控件（步骤式引导）
- 支持引导步骤配置（目标控件、提示文本、位置）
- 实现引导步骤的流转逻辑（上一步、下一步、跳过）
- 实现引导进度显示
3. **整体测试、优化和文档**（2 天）
- 在 Example 项目中集成所有 MVP 功能
- 验证 MVP Success Criteria（主题切换、国际化、PropertyGrid、UserGuide）
- 测试 AOT 编译
- 修复发现的 Bug
- 编写 MVP 总结文档
#### 交付物
- UserGuide 可在 Example 项目中使用
- 所有 MVP 功能集成并验证通过
- MVP 总结文档，列出产出的基础控件/工具
---
### MVP 成功验收标准
1. ✅ **颜色系统和主题框架可用**：至少 3 种主题，运行时流畅切换
2. ✅ **国际化框架可用**：至少支持中英文切换，所有 MVP 控件内置文本已翻译
3. ✅ **PropertyGrid 可在测试项目中使用**：支持常用类型，基础数据绑定和验证
4. ✅ **UserGuide 可在测试项目中使用**：引导流程完整，Tooltip 增强功能可用
5. ✅ **AOT 编译成功**：所有控件能够在 AOT 模式下工作
6. ✅ **产出 5+ 个可复用的基础控件/工具**：2xN Layout、Overlay、Popup、Tooltip、ThemeManager、LocalizationManager、TreeHelper 等
---
### MVP 后的规划
MVP 完成后，进行以下活动：
1. **MVP 复盘会议**: 总结经验教训，评估实际产出
2. **Post-MVP 需求评估**: 根据 MVP 开发经验，重新评估 Post-MVP 功能优先级
3. **技术债务清理**: 优化代码质量，补充单元测试
4. **文档完善**: 编写完整的架构文档和 API 文档
---
### PM Handoff
此项目简报提供了 **Penguin.AvaloniaUI** 的完整背景信息和 MVP 计划。建议进入 **PRD 生成模式**，逐节详细设计产品需求文档，包括：
- 详细的控件功能规格（PropertyGrid、UserGuide 等）
- 用户交互流程（数据绑定、主题切换、引导流程等）
- 技术实现方案（颜色系统、国际化框架、PropertyGrid 设计等）
- MVP 开发里程碑和每周交付计划
请在生成 PRD 时，确保功能范围符合 **1 个月 MVP** 的时间线，根据实际开发进展及时调整优先级。
---
*本项目简报由 BMAD™ Business Analyst 生成，基于 2025-10-15 的头脑风暴会议成果。*

1127
docs/prd.md
View File

File diff suppressed because it is too large Load Diff

57
docs/prd/checklist-results-report.md
View File

@@ -1,57 +0,0 @@
# Checklist Results Report
### Executive Summary
**Overall PRD Completeness:** 88%
**MVP Scope Appropriateness:** Just Right
**Readiness for Architecture Phase:** **Ready**
**Most Critical Gaps:**
- 用户流程图缺失（可在架构阶段补充，MEDIUM 优先级）
- 数据实体未正式定义（PropertyItem、GuideStep 在 Stories 中有描述，HIGH 优先级建议补充专门章节）
- 性能测量工具未明确（架构阶段确定，MEDIUM 优先级）
### Category Statuses
| Category | Status | Critical Issues |
| -------------------------------- | -------- | ---------------------------------------- |
| 1. Problem Definition & Context | PASS | 无 |
| 2. MVP Scope Definition | PASS | 无 |
| 3. User Experience Requirements | PARTIAL | 缺少用户流程图（MEDIUM） |
| 4. Functional Requirements | PASS | 无 |
| 5. Non-Functional Requirements | PASS | 无 |
| 6. Epic & Story Structure | PASS | 无 |
| 7. Technical Guidance | PASS | 无 |
| 8. Cross-Functional Requirements | PARTIAL | 数据实体未正式定义（HIGH） |
| 9. Clarity & Communication | PASS | 无 |
**Overall Status:** 7/9 PASS, 2/9 PARTIAL
### Key Findings
**Strengths:**
- Epic 和 Story 结构完整，16 个 Stories 都有详细的 Acceptance Criteria
- 技术栈和架构方向明确，风险已识别并有缓解措施
- MVP 范围经过 YAGNI 和多方利益相关者验证，合理且可行
- 需求经过深度分析（YAGNI + Stakeholder Round Table），削减了约 1 周工作量
**Areas for Improvement:**
1. **HIGH 优先级：** 建议在 Requirements 部分添加"Data Models"章节，正式定义 PropertyItem、GuideStep 等核心数据结构
2. **MEDIUM 优先级：** 在架构阶段补充 2-3 个关键用户流程图（可与 UX Expert 协作）
3. **MEDIUM 优先级：** 明确性能测量工具和方法（如何测量 60fps、100ms、200ms）
### Recommendations
**For Architecture Phase:**
1. 优先完成 Semi.Avalonia 可用性评估（Story 1.1 的前置任务）
2. 与 UX Expert 协作定义苹果颜色系统的具体色值
3. 确定国际化方案（Avalonia 内置 vs 自定义）
4. 选择性能测量工具
**Timeline Realism:**
- 4 周完成 3 个 Epic、16 个 Stories：**可行**
- Epic 1: 1 周，Epic 2: 1.5-2 周，Epic 3: 1-1.5 周
- 符合 1-2 人业余时间开发（每周 10-20 小时）
---

145
docs/prd/epic-1-details-foundation-theme-infrastructure.md
View File

@@ -1,145 +0,0 @@
# Epic 1 Details: Foundation & Theme Infrastructure
### Epic Goal
建立 Penguin.AvaloniaUI 控件库项目的完整基础设施，实现基于苹果颜色系统的主题框架。该 Epic 交付一个可运行的示例应用，演示浅色和暗色主题的流畅切换，为后续控件开发提供样式和颜色基础。通过该 Epic，验证技术栈选择（Avalonia、ReactiveUI、Semi.Avalonia）的可行性。
---
### Story 1.1: 项目基础设施搭建并初始化示例应用
**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 中应用其基础样式
- 如果不可用或过于复杂，记录决策并准备自定义样式系统
---
### Story 1.2: 实现浅色主题和颜色系统
**As a** 控件库开发者，
**I want** 定义基于苹果颜色系统的语义化颜色，并实现浅色主题，
**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义：
- 定义语义化颜色资源（ResourceDictionary），包含至少以下颜色：
- Primary（主色）
- Secondary（次要色）
- Success（成功）
- Warning（警告）
- Error（错误）
- Background（背景）
- Surface（表面）
- TextPrimary（主要文本）
- TextSecondary（次要文本）
2. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`（浅色主题资源字典）：
- 为每个语义化颜色定义浅色主题的具体色值
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
3. 将浅色主题应用到 Example 应用：
- 在 `App.axaml` 中引用 `LightTheme.axaml`
- 示例窗口的背景色使用 `Background` 颜色
- TextBlock 的文本色使用 `TextPrimary` 颜色
4. 在 Example 中添加一个演示页面，展示所有语义化颜色：
- 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
- 色块大小：至少 100x50 像素
5. 浅色主题下，示例应用视觉呈现专业、清晰，无明显的配色问题
6. 在 `README.md` 中添加颜色系统的简要说明
---
### Story 1.3: 实现暗色主题
**As a** 控件库开发者，
**I want** 基于颜色系统创建暗色主题，
**so that** 控件库可以支持暗色模式，满足长时间使用场景的需求。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `DarkTheme.axaml`（暗色主题资源字典）：
- 为每个语义化颜色定义暗色主题的具体色值
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
- 暗色主题的背景色应较深（避免纯黑 #000000，推荐深灰色系）
2. 暗色主题的颜色定义应与浅色主题在语义上对应：
- Primary 在两种主题下都表示"强调色"，但色值可以不同
- Background 在浅色主题下是浅色，在暗色主题下是深色
3. 修改 Example 应用，支持手动切换到暗色主题：
- 在 `App.axaml` 中暂时保留浅色主题为默认
- 提供注释说明如何切换到暗色主题（修改 `App.axaml` 中的资源引用）
4. 在暗色主题下，颜色演示页面能够正确显示所有暗色主题的颜色
5. 暗色主题视觉呈现舒适，无过度刺眼或过暗的问题
6. 两种主题下的颜色演示页面应使用相同的 XAML 代码（通过语义化颜色资源绑定）
---
### Story 1.4: 实现运行时主题切换
**As a** 示例应用的用户，
**I want** 通过 UI 按钮动态切换浅色和暗色主题，
**so that** 我可以快速验证控件库在不同主题下的视觉效果，无需修改代码和重启应用。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `ThemeManager.cs` 类：
- 提供 `ApplyTheme(ThemeType theme)` 方法，支持动态加载主题资源
- ThemeType 枚举包含 `Light` 和 `Dark`
- 主题切换通过替换 `Application.Current.Resources` 中的资源字典实现
2. 提供一个 ReactiveUI Command：`SwitchThemeCommand`
- 接受 `ThemeType` 参数
- 调用 `ThemeManager.ApplyTheme()` 切换主题
3. 在 Example 应用的主窗口添加主题切换按钮：
- 两个按钮："浅色主题" 和 "暗色主题"（或一个 ToggleButton）
- 按钮绑定到 `SwitchThemeCommand`
- 按钮样式使用当前主题的颜色系统
4. 主题切换应流畅无闪烁：
- 切换时间 < 100ms（符合 NFR4）
- 所有使用语义化颜色的控件应自动更新外观
5. 主题切换后，颜色演示页面应立即反映新主题的颜色
6. 主题状态应持久化（可选，MVP 可以每次启动默认浅色主题）
7. 在 Example 中添加一个简单的测试页面，包含多种控件（Button、TextBox、CheckBox），验证主题切换对不同控件的影响
---

227
docs/prd/epic-2-details-propertygrid-auto-generated-configuration-ui.md
View File

@@ -1,227 +0,0 @@
# Epic 2 Details: PropertyGrid - Auto-Generated Configuration UI
### Epic Goal
实现 PropertyGrid 控件，这是控件库的核心价值所在。该控件能够从数据模型自动生成属性编辑 UI，支持 string, int, double, bool, enum, DateTime 六种基础类型，以及属性分组、只读属性等功能。Epic 完成后，上位机和 AI 应用开发者可以快速构建配置界面，无需手写大量 XAML。该 Epic 在开发过程中会产出必要的布局控件（如 TwoColumnLayout）和工具类。
---
### Story 2.1: 实现 2xN Layout 布局控件
**As a** 控件库开发者，
**I want** 创建一个专用的 2xN Layout 布局控件（左侧标签，右侧编辑器），
**so that** PropertyGrid 可以使用统一的布局来呈现属性列表，且这个布局控件可以复用到其他需要"标签-值"配对的场景。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Layouts/` 下创建 `TwoColumnLayout.cs` 控件类：
- 继承自 `Panel` 或使用 `Grid` 作为基础
- 支持添加多行，每行包含左侧标签（Label）和右侧内容（Content）
2. 提供简单的 API 来添加行：
- 可以通过 Items 集合添加行
- 每个 Item 包含 Label（string）和 Content（Control）
3. 布局行为：
- 左列（标签列）宽度固定或自适应最长标签的宽度
- 右列（内容列）占据剩余空间
- 行与行之间有合适的垂直间距（如 8px）
- 标签垂直对齐到内容控件的中心或顶部
4. 响应主题系统：
- 标签文本颜色使用 `TextSecondary`
- 背景色透明或使用 `Surface`
5. 在 Example 中创建测试页面，演示 TwoColumnLayout 的使用：
- 至少 5 行测试数据
- 包含不同类型的右侧内容（TextBox, CheckBox, ComboBox）
6. 布局在窗口缩放时应正确响应，不出现重叠或错位
---
### Story 2.2: 实现基础属性编辑器控件
**As a** 控件库开发者，
**I want** 为 PropertyGrid 支持的 6 种属性类型创建或选择合适的编辑器控件，
**so that** PropertyGrid 可以根据属性类型自动选择正确的编辑器。
#### Acceptance Criteria
1. 为以下属性类型选择或创建编辑器控件：
- **string**: 使用 Avalonia 的 `TextBox`
- **int/double**: 使用 Avalonia 的 `NumericUpDown`（如果 Semi 或 Avalonia 提供）或自定义数字输入框
- **bool**: 使用 Avalonia 的 `CheckBox`
- **enum**: 使用 Avalonia 的 `ComboBox`，Items 为枚举值列表
- **DateTime**: 使用 Avalonia 的 `DatePicker` 和 `TimePicker`（或组合控件）
2. 所有编辑器控件应响应主题系统，使用语义化颜色
3. 编辑器控件应支持基础的数据绑定：
- 双向绑定（TwoWay Binding）
- 支持 `INotifyPropertyChanged` 机制
4. 在 Example 中创建测试页面，演示所有 6 种编辑器：
- 每种编辑器独立展示
- 显示当前绑定的值（使用 TextBlock）
- 修改编辑器后，绑定的值应自动更新
5. 编辑器控件应具备基础的验证提示能力：
- 依赖 Avalonia 的内置验证机制（如 DataValidationErrors）
- 验证失败时显示红色边框或错误图标
---
### Story 2.3: 实现 PropertyGrid 核心逻辑和数据模型
**As a** 控件库开发者，
**I want** 定义 PropertyGrid 的数据模型和核心逻辑，支持从对象反射属性信息，
**so that** PropertyGrid 可以自动生成属性列表，为后续的 UI 呈现做好准备。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Controls/PropertyGrid/` 下创建以下类：
- `PropertyGrid.cs`: PropertyGrid 主控件类
- `PropertyItem.cs`: 表示单个属性的数据模型，包含：
- Name（属性名称）
- Value（属性值）
- Type（属性类型）
- IsReadOnly（是否只读）
- Category（分组类别，可选）
- Description（描述，可选）
2. PropertyGrid 提供 `SelectedObject` 属性（依赖属性）：
- 接受任意对象
- 当 SelectedObject 变化时，自动通过反射解析对象的属性
3. 反射逻辑：
- 获取对象的所有 public 属性
- 过滤掉不应显示的属性（如索引器、只写属性）
- 支持通过 Attribute 控制属性的显示（可选，如 `[Browsable(false)]`）
4. 将反射得到的属性转换为 `PropertyItem` 集合：
- 存储在 PropertyGrid 的内部集合中
- 支持属性变化通知（使用 ReactiveUI 或 INotifyPropertyChanged）
5. 创建单元测试，验证反射逻辑：
- 测试包含 6 种基础类型的测试对象
- 验证属性数量、名称、类型正确解析
- 验证只读属性标记正确识别
6. 在 Example 中创建测试页面，验证数据模型：
- 定义一个包含 6 种类型属性的测试类
- 将测试对象赋值给 PropertyGrid.SelectedObject
- 使用调试输出或 ListBox 显示解析出的 PropertyItem 列表（暂时不渲染为编辑器）
---
### Story 2.4: 实现 PropertyGrid UI 呈现和属性编辑
**As a** PropertyGrid 的用户（开发者），
**I want** PropertyGrid 能够自动将属性列表渲染为可编辑的 UI，
**so that** 我可以直接使用 PropertyGrid 控件，无需手动编写属性编辑界面。
#### Acceptance Criteria
1. PropertyGrid 使用 TwoColumnLayout 呈现属性列表：
- 左列显示属性名称（PropertyItem.Name）
- 右列根据属性类型显示对应的编辑器控件
2. 属性类型到编辑器的映射逻辑：
- string → TextBox
- int/double → NumericUpDown
- bool → CheckBox
- enum → ComboBox（自动填充枚举值）
- DateTime → DatePicker/TimePicker
3. 编辑器控件与属性值双向绑定：
- 修改编辑器时，PropertyItem.Value 自动更新
- PropertyItem.Value 变化时，编辑器自动刷新（如果 SelectedObject 外部修改）
4. 只读属性的处理：
- 如果 PropertyItem.IsReadOnly = true，编辑器应禁用（IsEnabled = false）或显示为只读文本
5. 在 Example 中创建完整的 PropertyGrid 演示页面：
- 定义一个包含所有 6 种类型的配置类（如 `DemoSettings`）
- 使用 PropertyGrid 绑定到 DemoSettings 实例
- 在页面底部显示当前配置对象的 JSON 或字符串表示，验证属性编辑生效
6. PropertyGrid 应响应主题切换，所有编辑器控件使用主题颜色
7. PropertyGrid 的默认宽度应至少 400px，高度自适应内容（或支持滚动）
---
### Story 2.5: 实现属性分组功能
**As a** PropertyGrid 的用户（开发者），
**I want** PropertyGrid 支持将属性按类别分组显示，
**so that** 当属性数量较多时，配置界面更清晰易读。
#### Acceptance Criteria
1. PropertyItem 支持 Category 属性（字符串）：
- 如果未指定 Category，默认分组为 "General" 或不分组
2. 支持通过 Attribute 在数据模型上标记分组：
- 例如使用 `[Category("Network")]` 标记属性
- 反射逻辑自动读取 Category Attribute
3. PropertyGrid 按 Category 对 PropertyItem 进行分组：
- 相同 Category 的属性显示在一起
- 分组之间有视觉分隔（如分隔线或分组标题）
4. 分组标题的呈现：
- 使用稍大的字体或加粗显示分组名称
- 分组标题使用 `TextPrimary` 颜色
- 分组标题上方有一定的间距（如 16px）
5. 支持可选的分组折叠功能（可选，MVP 可以暂时不实现折叠）：
- 如果时间允许，分组可以展开/折叠
- 默认所有分组展开
6. 在 Example 中扩展演示页面：
- DemoSettings 类的属性使用 `[Category]` 标记，分为至少 2 个分组（如 "General"、"Advanced"）
- PropertyGrid 正确显示分组
- 验证分组标题和属性的视觉层次清晰
---
### Story 2.6: PropertyGrid 集成测试和优化
**As a** 控件库开发者，
**I want** 对 PropertyGrid 进行全面测试和性能优化，
**so that** 确保 PropertyGrid 在真实场景下稳定可用，并满足性能要求（50 属性 < 200ms）。
#### Acceptance Criteria
1. 创建综合测试类，包含 50 个属性，覆盖所有支持的类型和分组
2. 在 Example 中使用该测试类验证 PropertyGrid：
- PropertyGrid 正确渲染所有 50 个属性
- UI 生成时间 < 200ms（符合 NFR5）
- 所有编辑器可正常交互，值绑定正确
3. 测试边缘情况：
- SelectedObject 为 null 时，PropertyGrid 显示空状态或提示信息
- 对象属性在运行时变化时，PropertyGrid 能够正确响应（如果支持动态刷新）
- 只读属性不能编辑
4. 主题切换测试：
- 在浅色和暗色主题下，PropertyGrid 的视觉呈现正确
- 主题切换时，PropertyGrid 无闪烁或错位
5. 性能优化（如果需要）：
- 如果初始加载超过 200ms，使用虚拟化或延迟加载优化
- 如果属性数量超过 100，考虑使用 `VirtualizingStackPanel`
6. 修复 Example 测试中发现的所有 Bug
7. 在 README 中添加 PropertyGrid 的使用文档：
- 基础用法示例（XAML 和代码）
- 支持的属性类型列表
- 如何使用 Category Attribute
- 已知限制（如暂不支持嵌套对象）
---

265
docs/prd/epic-3-details-userguide-onboarding-user-assistance.md
View File

@@ -1,265 +0,0 @@
# Epic 3 Details: UserGuide - Onboarding & User Assistance
### Epic Goal
实现 UserGuide 控件系列，为 AI 桌面应用提供完整的新手引导和应用内帮助系统。该 Epic 交付三个核心控件：Overlay（半透明遮罩）、增强 Tooltip（支持基础富文本）、UserGuide 引导流程控件（步骤式引导）。完成后，开发者可以快速为应用添加专业的用户引导功能，提升用户体验。
---
### Story 3.1: 实现 Overlay 遮罩控件
**As a** 控件库开发者，
**I want** 创建一个 Overlay 遮罩控件，能够在当前窗口上方显示半透明遮罩层，
**so that** UserGuide 可以使用它来聚焦引导目标，同时遮挡其他区域，引导用户注意力。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Controls/UserGuide/` 下创建 `Overlay.cs` 控件类：
- 继承自 `ContentControl` 或 `Panel`
- 能够覆盖整个父容器（通常是 Window）
2. Overlay 支持以下属性：
- `IsVisible`: 控制遮罩显示/隐藏
- `BackgroundOpacity`: 遮罩的不透明度（默认 0.5，范围 0-1）
- `BackgroundColor`: 遮罩颜色（默认黑色）
- `TargetControl`: 可选的目标控件，遮罩在该控件区域挖空（透明）以突出显示
3. 遮罩的视觉效果：
- 默认显示为半透明黑色覆盖层
- 如果指定了 TargetControl，该控件区域应保持清晰可见（通过 Clip 或透明矩形实现）
4. Overlay 应响应主题系统：
- 浅色主题下使用半透明黑色（默认）
- 暗色主题下使用半透明白色或深灰色（避免过暗）
5. 在 Example 中创建测试页面：
- 页面包含几个按钮或控件
- 添加一个"显示遮罩"按钮，点击后显示 Overlay
- 测试不指定 TargetControl（全屏遮罩）和指定 TargetControl（挖空特定控件）两种模式
6. 遮罩显示时，应阻止用户点击被遮罩区域的控件（除了 TargetControl）
7. Overlay 支持动画效果（可选）：
- 显示和隐藏时有淡入淡出动画（200ms）
---
### Story 3.2: 实现增强 Tooltip 控件（支持基础富文本）
**As a** 应用开发者，
**I want** 使用增强的 Tooltip 控件，支持基础富文本格式（粗体、斜体、换行），
**so that** 我可以在引导提示中强调关键信息，提升提示的可读性和吸引力。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Controls/UserGuide/` 下创建 `RichTooltip.cs` 控件类：
- 继承或扩展 Avalonia 的 `ToolTip`
- 支持 Content 为 `TextBlock` 或自定义内容
2. 支持基础富文本格式：
- **粗体**: 使用 `<Bold>` 标签或支持 Markdown 的 `**text**` 语法（选其一）
- **斜体**: 使用 `<Italic>` 标签或 Markdown 的 `*text*` 语法
- **换行**: 使用 `\n` 或自动换行
- 不支持链接、图片等复杂格式（符合 YAGNI 原则）
3. RichTooltip 应响应主题系统：
- 背景色使用 `Surface` 或 `Background`
- 文本颜色使用 `TextPrimary`
- 边框颜色使用 `Primary` 或 `Secondary`
4. 提供简单的 API 设置内容：
- 接受纯文本（自动解析格式标记）
- 或接受 `TextBlock`（手动设置格式）
5. 在 Example 中创建测试页面：
- 几个按钮，鼠标悬停时显示 RichTooltip
- 测试粗体、斜体、换行的组合效果
- 示例文本："**注意**: 这是一个重要的功能提示。\n请仔细阅读。"
6. RichTooltip 的显示位置应智能调整：
- 默认显示在目标控件下方
- 如果空间不足，自动调整到上方或左右侧
7. RichTooltip 的最大宽度应限制（如 300px），超出自动换行
---
### Story 3.3: 实现 UserGuide 引导流程数据模型和步骤管理
**As a** 控件库开发者，
**I want** 定义 UserGuide 的数据模型和步骤管理逻辑，
**so that** 开发者可以配置多步引导流程，UserGuide 控件可以管理步骤的流转。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Controls/UserGuide/` 下创建以下类：
- `UserGuide.cs`: UserGuide 主控件类
- `GuideStep.cs`: 表示单个引导步骤的数据模型，包含：
- `TargetControl`: 引导目标控件（Control 类型）
- `Title`: 步骤标题（string）
- `Content`: 步骤内容/提示文本（string，支持基础富文本）
- `Position`: 提示框相对于目标控件的位置（枚举：Bottom、Top、Left、Right）
- `Order`: 步骤顺序（int）
2. UserGuide 提供 `Steps` 属性（集合）：
- 接受 `GuideStep` 列表
- 支持在 XAML 或代码中配置
3. UserGuide 提供步骤管理功能：
- `CurrentStepIndex`: 当前步骤索引（int）
- `NextStepCommand`: 前进到下一步
- `PreviousStepCommand`: 返回上一步
- `SkipCommand`: 跳过引导
- `FinishCommand`: 完成引导
4. 步骤流转逻辑：
- 初始状态：CurrentStepIndex = 0（第一步）
- NextStep: CurrentStepIndex + 1，如果是最后一步则触发 Finish
- PreviousStep: CurrentStepIndex - 1，如果是第一步则禁用
- Skip/Finish: 隐藏 UserGuide，触发完成事件
5. 创建单元测试，验证步骤管理逻辑：
- 测试 NextStep、PreviousStep 的边界条件
- 测试步骤按 Order 排序
6. 在 Example 中创建测试页面：
- 定义包含 3-5 个 GuideStep 的引导流程
- 使用调试输出或 TextBlock 显示当前步骤信息（暂时不渲染 UI）
- 提供按钮手动触发 NextStep、PreviousStep，验证逻辑正确
---
### Story 3.4: 实现 UserGuide UI 呈现和引导交互
**As a** 应用用户，
**I want** 看到清晰的引导提示框，并通过"上一步"、"下一步"、"跳过"按钮控制引导流程，
**so that** 我可以快速了解应用的核心功能，而不会感到困惑。
#### Acceptance Criteria
1. UserGuide 开始引导时：
- 显示 Overlay 遮罩，遮挡除当前目标控件外的其他区域
- 在目标控件附近显示引导提示框（根据 GuideStep.Position）
2. 引导提示框的内容：
- 显示步骤标题（GuideStep.Title），使用稍大的字体或加粗
- 显示步骤内容（GuideStep.Content），支持基础富文本（调用 RichTooltip 逻辑）
- 显示步骤进度（如 "2/5"）
3. 引导提示框的按钮：
- "上一步"按钮（如果不是第一步）
- "下一步"按钮（如果不是最后一步）或"完成"按钮（如果是最后一步）
- "跳过"按钮（所有步骤都显示）
- 按钮绑定到 UserGuide 的 Command
4. 引导提示框应响应主题系统：
- 背景色使用 `Surface` 并带有阴影效果
- 按钮使用 `Primary` 颜色（"下一步"/"完成"）和 `Secondary` 颜色（"上一步"/"跳过"）
5. 步骤切换动画（可选）：
- 切换步骤时，提示框有淡入淡出或平移动画（200ms）
6. 在 Example 中创建完整的 UserGuide 演示：
- 定义一个包含 5 个步骤的引导流程
- 目标控件为页面上的不同按钮或区域
- 测试步骤：用户可以顺畅地前进、后退、跳过、完成引导
7. UserGuide 完成后，应触发事件或回调：
- 开发者可以监听完成事件，执行后续逻辑（如标记"引导已完成"）
---
### Story 3.5: UserGuide 边缘情况处理和集成测试
**As a** 控件库开发者，
**I want** 处理 UserGuide 的边缘情况并进行全面测试，
**so that** 确保 UserGuide 在各种场景下稳定可用，用户体验流畅。
#### Acceptance Criteria
1. 处理边缘情况：
- **目标控件不可见或已销毁**: UserGuide 应自动跳过该步骤或显示错误提示
- **窗口缩放**: 引导提示框应随窗口调整位置，不出现错位
- **多窗口场景**: UserGuide 应只在启动它的窗口内生效
- **用户点击 Overlay 遮罩**: 默认不响应（不关闭引导），或提供配置选项
2. 主题切换测试：
- 在引导进行中切换主题，UserGuide 应正确响应，无视觉错误
3. 性能测试：
- 引导流程包含 10 个步骤时，步骤切换应流畅（< 100ms）
- Overlay 和提示框的动画不应卡顿
4. 用户体验测试：
- 引导流程的视觉呈现清晰，提示框不会遮挡目标控件
- 按钮的位置和文本易于理解
- 进度指示清晰（如 "3/5"）
5. 在 Example 中创建综合测试页面：
- 模拟真实应用的引导场景（如"首次使用教程"）
- 包含至少 5 个步骤，覆盖不同位置（Top、Bottom、Left、Right）
- 测试跳过、返回、完成等所有操作
6. 修复测试中发现的所有 Bug
7. 在 README 中添加 UserGuide 的使用文档：
- 基础用法示例（XAML 和代码）
- 如何定义 GuideStep
- 如何监听完成事件
- 最佳实践建议（如引导步骤不宜过多、提示文本应简洁）
---
### Story 3.6: MVP 整体集成测试和文档完善
**As a** 控件库的用户（开发者），
**I want** 在 Example 应用中看到所有 MVP 功能的完整演示，并有清晰的文档指导，
**so that** 我可以快速学习如何使用控件库，并在自己的项目中集成。
#### Acceptance Criteria
1. 在 Example 中创建"综合 Demo"页面：
- 集成 PropertyGrid、UserGuide、主题切换功能
- 模拟一个真实的应用场景（如"AI 模型配置工具"）
- 页面包含：
- 主题切换按钮
- PropertyGrid 显示配置对象
- "开始引导"按钮，触发 UserGuide
- UserGuide 引导用户了解主题切换、PropertyGrid 使用等功能
2. 验证所有 MVP Success Criteria（来自 Brief）：
- ✅ 颜色系统和主题框架可用：至少 2 种主题，运行时流畅切换
- ✅ 国际化框架架构预留：代码结构支持后续扩展
- ✅ PropertyGrid 可在测试项目中使用：支持常用类型，基础数据绑定
- ✅ UserGuide 可在测试项目中使用：引导流程完整，Tooltip 增强功能可用
- ✅ 架构支持未来 AOT：MVP 阶段允许反射
- ✅ 产出 5+ 个可复用的基础控件/工具：TwoColumnLayout、Overlay、RichTooltip、ThemeManager 等
3. 测试跨功能集成：
- 在 PropertyGrid 编辑时触发主题切换，验证无冲突
- 在 UserGuide 进行中修改 PropertyGrid，验证无异常
4. 性能基准测试：
- PropertyGrid 50 属性生成 < 200ms（NFR5）
- 主题切换 < 100ms（NFR4）
- UI 渲染 60fps（NFR3）
5. 完善 README.md：
- 项目概述和目标
- 快速开始指南（如何运行 Example）
- 控件列表和功能概述
- 核心控件的使用示例（PropertyGrid、UserGuide）
- 已知限制和后续计划（Post-MVP）
6. 创建 CHANGELOG.md：
- 记录 MVP v1.0 的功能清单
- 标记已完成的 Epic 和 Story
7. 项目代码质量检查：
- 所有公开 API 有 XML 文档注释
- 代码符合 C# 编码规范
- 删除未使用的代码和注释
- 确保 Git 提交记录清晰
---

16
docs/prd/epic-list.md
View File

@@ -1,16 +0,0 @@
# Epic List
### Epic 1: Foundation & Theme Infrastructure
建立项目基础设施（项目结构、依赖配置、CI 准备），实现基于苹果颜色系统的主题框架，支持浅色和深色主题的运行时切换，交付可验证主题切换的示例应用
### Epic 2: PropertyGrid - Auto-Generated Configuration UI
实现 PropertyGrid 控件的核心功能，支持 6 种基础属性类型的自动 UI 生成、属性分组、只读属性和基础验证，交付可在上位机和 AI 应用中使用的配置界面解决方案
### Epic 3: UserGuide - Onboarding & User Assistance
实现 UserGuide 控件系列，包括步骤式引导流程、增强 Tooltip 和 Overlay 遮罩，交付完整的新手引导和应用内帮助系统
---

27
docs/prd/goals-and-background-context.md
View File

@@ -1,27 +0,0 @@
# Goals and Background Context
### Goals
- 在 1 个月内完成 MVP，验证 PropertyGrid 和 UserGuide 的核心功能
- 建立基于 Semi Design 和苹果颜色系统的多主题框架，支持至少 2 种主题（浅色、暗色）和运行时切换
- 实现支持国际化扩展的架构，MVP 阶段默认使用一种语言，预留语言切换扩展点
- 完成 PropertyGrid 控件，支持常用属性类型（string, int, double, bool, enum, DateTime），实现自动 UI 生成、属性分组和基础验证
- 完成 UserGuide 系列控件，包括新手引导流程和增强 Tooltip，提升用户体验
- 确保架构设计考虑未来 AOT 编译支持，MVP 阶段允许使用反射
- 在开发过程中产出 5+ 个可复用的基础控件和工具类（TwoColumnLayout、Overlay、RichTooltip、ThemeManager 等）
- 为后续控件开发（LoggingControl、TextEditor 等）打下坚实基础
### Background Context
当前 Avalonia 生态主要聚焦于基础控件库（Button、TextBox 等），但真正加速开发的是**业务场景集成控件**（PropertyGrid、LoggingControl、UserGuide），这些在上位机和 AI 桌面应用场景中尤为关键。开发者被迫在每个项目中重复实现相似的复合控件，平均花费 30-50% 的时间在这些重复工作上。此外，许多现有库为了兼容旧版本（.NET Framework、Avalonia 0.x），牺牲了现代特性，AOT 支持不完善。
本项目旨在填补这一空白，采用**自顶向下开发策略**：先定义业务控件需求，再从中分解必要的基础控件。我们专注于上位机和 AI 桌面应用场景，基于 .NET 8+、Avalonia 11.x、ReactiveUI 和 Semi Design 样式系统，打造一套现代化、高度场景化的业务控件库。与传统控件库追求极致通用性不同，我们允许合理的取舍，优先满足目标场景的核心需求，确保开发效率和技术栈的前瞻性。
### Change Log
| Date | Version | Description | Author |
|------------|---------|----------------------|----------|
| 2025-10-15 | 1.0 | Initial PRD creation | PM Agent |
---

15
docs/prd/index.md
View File

@@ -1,15 +0,0 @@
# Penguin.AvaloniaUI Product Requirements Document (PRD)
## Table of Contents
- [Penguin.AvaloniaUI Product Requirements Document (PRD)](#table-of-contents)
- [Goals and Background Context](#goals-and-background-context)
- [Requirements](#requirements)
- [User Interface Design Goals](#user-interface-design-goals)
- [Technical Assumptions](#technical-assumptions)
- [Epic List](#epic-list)
- [Epic 1 Details: Foundation & Theme Infrastructure](#epic-1-details-foundation-theme-infrastructure)
- [Epic 2 Details: PropertyGrid - Auto-Generated Configuration UI](#epic-2-details-propertygrid-auto-generated-configuration-ui)
- [Epic 3 Details: UserGuide - Onboarding & User Assistance](#epic-3-details-userguide-onboarding-user-assistance)
- [Checklist Results Report](#checklist-results-report)
- [Next Steps](#next-steps)

102
docs/prd/next-steps.md
View File

@@ -1,102 +0,0 @@
# Next Steps
### UX Expert Prompt
```
你好！我是 Penguin.AvaloniaUI 控件库的产品经理。我们刚刚完成了 MVP 的 PRD，现在需要你的 UX 专业知识来完善用户体验设计。
**项目背景：**
- 目标：为上位机和 AI 桌面应用开发者提供业务场景控件库（PropertyGrid、UserGuide 等）
- 技术栈：Avalonia UI、.NET 8+、ReactiveUI、Semi Design 样式系统
- MVP 时间线：1 个月（4 周）
- MVP 范围：主题框架 + PropertyGrid + UserGuide
**你的任务：**
1. **审查 UI Design Goals 部分**（本文档中的"User Interface Design Goals"）
- 验证设计原则是否符合上位机和 AI 应用的用户习惯
- 确认"信息密度优先"和"暗色模式友好"的设计方向
2. **补充关键用户流程图**（可选，MEDIUM 优先级）
- "开发者配置 PropertyGrid"的完整流程
- "用户使用 UserGuide 引导"的完整流程
- "主题切换"的触发路径
3. **设计苹果颜色系统的具体色值**
- 为浅色和暗色主题定义 Primary, Secondary, Success, Warning, Error, Background, Surface 等颜色的具体 HEX 值
- 确保色彩对比度符合 4.5:1 要求
- 参考：Apple Human Interface Guidelines (https://developer.apple.com/design/human-interface-guidelines/color)
4. **评估 Semi.Avalonia 的可用性**（与 Architect 协作）
- 检查 Semi Design 样式是否满足"紧凑布局"需求
- 确认 Semi 的颜色系统能否与苹果颜色系统集成
- 如果不可用，提出 Plan B（自定义样式系统）
**交付物：**
- 苹果颜色系统色值规范文档（Markdown 或 Figma）
- （可选）2-3 个关键用户流程图
- Semi.Avalonia 可用性评估报告
**时间预估：** 2-3 天
请先阅读 docs/brief.md 和本 PRD，了解项目的完整背景，然后开始你的工作。如有疑问，随时联系我！
```
---
### Architect Prompt
```
你好！我是 Penguin.AvaloniaUI 控件库的产品经理。我们刚刚完成了 MVP 的 PRD，现在需要你设计技术架构，为开发阶段提供清晰的实现蓝图。
**项目背景：**
- 目标：为上位机和 AI 桌面应用开发者提供业务场景控件库（PropertyGrid、UserGuide 等）
- 技术栈：Avalonia UI、.NET 8+、ReactiveUI、Semi Design 样式系统
- MVP 时间线：1 个月（4 周）
- MVP 范围：主题框架 + PropertyGrid + UserGuide
**你的任务：**
1. **审查 Technical Assumptions 部分**（本文档中的"Technical Assumptions"）
- 确认技术栈选择的合理性（Monorepo、单体库、ReactiveUI）
- 验证依赖管理策略（Semi.Avalonia、AOT 支持策略）
2. **设计核心架构**
- 项目结构和命名空间组织（Controls、Layouts、Themes、Utils）
- 主题系统的技术实现方案（ResourceDictionary 动态加载）
- PropertyGrid 的反射实现方案（平衡性能和可维护性）
- UserGuide 的 Overlay 和步骤管理架构
3. **明确技术决策**
- **国际化方案选择**：Avalonia 内置 IResourceProvider vs 自定义 LocalizationManager
- **PropertyGrid 反射策略**：直接反射 vs Fluent API 配置
- **Semi.Avalonia 集成方案**：完全依赖 vs 部分使用 vs 自定义样式
- **性能测量工具**：如何测量 60fps、100ms、200ms 等性能指标
4. **识别技术风险并提出缓解措施**
- Semi.Avalonia 可用性风险（与 UX Expert 协作评估）
- PropertyGrid 反射性能风险（50 属性 < 200ms）
- ReactiveUI 学习曲线风险
5. **设计架构文档结构**
- 高层架构图（项目结构、依赖关系）
- 核心控件的类图（PropertyGrid、UserGuide）
- 主题系统的序列图（主题切换流程）
- 关键数据模型定义（PropertyItem、GuideStep）
**关键约束：**
- MVP 阶段允许使用反射（AOT 支持是"架构考虑"，不是硬性要求）
- 如果 Semi.Avalonia 不可用，允许放弃并自定义样式系统
- 测试策略：单元测试 + 手动测试（不需要 UI 自动化测试）
**交付物：**
- 架构设计文档（docs/architecture.md）
- 技术决策记录（ADR）
- （可选）核心控件的技术规格书
**时间预估：** 3-5 天
请先阅读 docs/brief.md 和本 PRD，了解项目的完整背景和产品需求。优先完成 Semi.Avalonia 的评估（Story 1.1 的前置任务），因为这会影响 Epic 1 的实现方案。如有疑问，随时联系我！
```
---
**End of PRD**

54
docs/prd/requirements.md
View File

@@ -1,54 +0,0 @@
# Requirements
### Functional Requirements
**FR1:** 系统应提供基于苹果颜色系统的语义化颜色定义（primary, secondary, success, warning, error, background, surface 等），支持 2 种预设主题（浅色、深色）
**FR2:** 系统应提供 ThemeManager API，允许运行时动态切换主题，且主题切换应流畅无闪烁，所有控件自动响应主题变化
**FR3:** 系统架构应支持国际化扩展，MVP 阶段默认使用一种语言（中文或英文），预留语言切换扩展点，为后续多语言支持打下基础
**FR4:** PropertyGrid 应能够从数据模型自动生成属性编辑 UI，支持以下基础属性类型：string, int, double, bool, enum, DateTime
**FR5:** PropertyGrid 应支持属性分组功能，允许开发者将相关属性组织在一起，提升配置界面的可读性
**FR6:** PropertyGrid 应支持只读属性标记，只读属性应显示但禁止编辑
**FR7:** PropertyGrid 应使用 2xN Layout 布局（左侧标签，右侧编辑器），确保界面整齐对齐
**FR8:** PropertyGrid 可选支持 IPAddress 和 FilePath 属性类型，满足上位机场景的常见配置需求（MVP 阶段可根据开发进度决定是否实现）
**FR9:** UserGuide 应提供步骤式引导流程控件，支持配置引导步骤（目标控件、提示文本、相对位置），支持上一步、下一步、跳过操作
**FR10:** UserGuide 应提供增强 Tooltip 控件，支持基础富文本显示（粗体、斜体、换行）
**FR11:** UserGuide 应提供 Overlay 遮罩控件，用于聚焦引导目标，半透明背景突出当前步骤
**FR12:** 所有控件应基于 ReactiveUI 实现数据绑定和交互逻辑，支持 Command、Reactive、Event 混合使用
### Non-Functional Requirements
**NFR1:** 所有控件必须支持 .NET 8+ 和 Avalonia 11.x 或更高版本，不向后兼容旧版本
**NFR2:** 系统架构设计应考虑未来 AOT 编译支持，MVP 阶段允许使用反射（PropertyGrid 可基于反射实现，后续可通过 Source Generator 优化）
**NFR3:** UI 渲染性能应达到 60fps（16ms 每帧），控件交互应流畅无卡顿
**NFR4:** 主题切换应在 100ms 内完成，用户感知无延迟
**NFR5:** PropertyGrid 对于包含 50 个属性的模型，UI 生成时间应小于 200ms
**NFR6:** 控件应支持 Windows（主要）、Linux（次要）、macOS（可选）平台，优先保证 Windows 体验
**NFR7:** 代码应遵循 C# 编码规范，使用清晰的命名和注释，便于后续维护
**NFR8:** 控件应具备良好的可扩展性，支持开发者通过模板（Template）和样式（Style）自定义外观，这是控件库的基本要求
**NFR9:** MVP 阶段应提供基础文档（README 和使用示例），核心控件（PropertyGrid、UserGuide）应有完整的代码示例
**NFR10:** 项目应使用 Git 进行版本控制，关键里程碑应有清晰的提交记录和标签
**NFR11:** 应提供 ReactiveUI 在 Avalonia 控件开发中的快速入门文档和代码示例，降低团队学习成本
---

118
docs/prd/technical-assumptions.md
View File

@@ -1,118 +0,0 @@
# Technical Assumptions
### Repository Structure: Monorepo
**决策：** 采用 Monorepo 结构，所有代码在单一 Git 仓库中管理
**目录结构：**
```
D:\32_avalonia.ui/
├── src/
│ ├── Penguin.AvaloniaUI/ # 核心控件库项目
│ ├── Penguin.AvaloniaUI.SourceGenerators/ # Source Generator（可选，Post-MVP）
│ ├── Example/ # 示例应用项目
│ └── Penguin.AvaloniaUI.Tests/ # 单元测试项目
├── docs/ # 文档
└── .bmad-core/ # BMAD 框架配置
```
**Rationale:**
- Monorepo 简化了控件库和示例应用的协同开发，便于快速迭代和测试
- 依赖管理更简单，所有项目共享同一个 NuGet 依赖版本
- MVP 阶段项目数量少（3-4 个），Monorepo 不会带来复杂度负担
- 未来如果需要拆分（如 Source Generator 独立发布），迁移成本也可控
### Service Architecture
**架构类型：** 单体库（Monolithic Library）
**说明：**
- Penguin.AvaloniaUI 是一个单一的 .NET 类库项目，所有控件作为命名空间组织在同一个程序集中
- 不采用微服务或独立的控件包（如每个控件一个 NuGet 包），避免过度设计和版本管理复杂度
- 控件之间可以有依赖关系（如 UserGuide 依赖 Overlay），但应尽量保持松耦合
- 使用命名空间隔离不同功能模块：
- `Penguin.AvaloniaUI.Controls` - 业务场景控件
- `Penguin.AvaloniaUI.Layouts` - 布局控件
- `Penguin.AvaloniaUI.Themes` - 主题和样式
- `Penguin.AvaloniaUI.Utils` - 工具类
**架构约束：**
- 所有控件必须继承自 Avalonia 的标准控件基类（`TemplatedControl`、`UserControl` 等）
- 样式和模板通过 Avalonia 的资源字典（ResourceDictionary）组织
- 主题切换通过 `Application.Current.Resources` 动态加载不同的资源字典实现
### Testing Requirements
**测试策略：** 单元测试 + 手动集成测试
**单元测试范围：**
- **核心业务逻辑**：PropertyGrid 的属性解析、UserGuide 的步骤流转逻辑
- **工具类**：ThemeManager、LocalizationManager（如果实现）等
- **数据绑定和验证**：PropertyGrid 的数据模型和 ReactiveUI 集成
**不包括的测试：**
- UI 渲染测试（Avalonia 的渲染层不易测试，依赖手动验证）
- 跨平台兼容性测试（MVP 阶段只在 Windows 上测试）
- 性能基准测试（除非发现明显的性能问题）
**手动测试：**
- 使用 Example 项目作为主要测试载体
- 每个控件应在 Example 中有独立的演示页面
- 测试场景包括：主题切换、属性编辑、引导流程、异常处理
**测试框架：**
- xUnit 作为单元测试框架
- FluentAssertions 用于断言（可选）
- 不引入 UI 自动化测试框架（如 Appium）
**Rationale:**
- MVP 阶段时间紧张，优先保证核心逻辑的正确性，UI 渲染依赖手动测试
- 上位机和 AI 桌面应用通常不需要极高的测试覆盖率（不像 Web 应用需要应对大规模用户）
- Example 项目本身就是"活文档"，可以作为回归测试的基准
### Additional Technical Assumptions and Requests
**1. 核心技术栈：**
- **.NET 版本：** .NET 8.0 或更高（LTS 版本）
- **Avalonia 版本：** 11.x（最新稳定版），锁定到次要版本（如 11.0.x）
- **ReactiveUI 版本：** 最新稳定版（19.x 或更高）
- **Semi.Avalonia 版本：** 最新稳定版（需要在项目初期快速评估其可用性）
**2. AOT 支持策略（软约束）：**
- **架构设计应考虑未来 AOT 支持**，但 MVP 阶段允许使用反射
- PropertyGrid 如果使用反射实现，应设计清晰的抽象层，便于后续迁移到 Source Generator
- 避免使用 `Reflection.Emit` 和动态类型（`dynamic`）
- 尽量使用编译时类型安全的 API
**3. 国际化架构预留：**
- 控件内置文本（如 PropertyGrid 的"名称"、"值"列头，UserGuide 的"下一步"按钮）应通过资源系统管理，而非硬编码
- MVP 阶段可以使用单一语言（中文或英文），但代码结构应支持后续扩展为多语言
- 推荐方案：使用 Avalonia 的本地化机制（`IResourceProvider`）或自定义 `LocalizationManager`
**4. 依赖管理原则：**
- **最小化第三方依赖**：除了 Avalonia、ReactiveUI、Semi.Avalonia 外，尽量不引入其他 NuGet 包
- **锁定主要依赖版本**：Avalonia 和 ReactiveUI 的主版本号应固定，避免自动升级导致 Breaking Changes
- **Semi.Avalonia 的可选性**：如果评估后发现 Semi.Avalonia 不可用或过于复杂，允许放弃使用，改为自定义样式系统（风险缓解措施）
**5. 开发工具和环境：**
- **IDE：** Visual Studio 2022 或 Rider
- **版本控制：** Git，托管在本地或私有仓库
- **持续集成（可选）：** MVP 阶段不强制要求 CI/CD，手动构建和测试即可
- **代码格式化：** 使用 `.editorconfig` 统一代码风格
**6. 性能优化原则：**
- **过早优化是万恶之源**：MVP 阶段优先功能完整性，性能问题在出现时再优化
- **已知的性能需求**：PropertyGrid 对 50 个属性的生成时间 < 200ms，主题切换 < 100ms（见 NFR）
- **虚拟化和懒加载**：如果 PropertyGrid 需要支持数百个属性，考虑使用 `VirtualizingStackPanel`（Post-MVP）
**7. 文档和注释规范：**
- 所有公开 API（public class、public method）必须有 XML 文档注释
- 复杂的业务逻辑应有内联注释解释设计意图
- README 应包括：快速开始、控件列表、使用示例、常见问题
**8. 颜色系统和字体配置：**
- **苹果颜色系统的具体实现细节（颜色值、命名规范）将在架构和开发阶段由 UX Expert 确定**，PRD 只明确方向
- **字体配置的具体 fallback 策略将在实现时补充**，PRD 只定义目标字体族
---

108
docs/prd/user-interface-design-goals.md
View File

@@ -1,108 +0,0 @@
# User Interface Design Goals
### Overall UX Vision
打造**简洁、专业、高效**的控件库 UI 体验，服务于上位机和 AI 桌面应用的专业用户群体。设计语言基于 Semi Design 样式系统，结合苹果颜色系统的语义化设计，提供现代化的视觉呈现和流畅的交互体验。
**核心设计原则：**
- **信息密度优先**：上位机场景需要在有限空间内展示大量配置项，PropertyGrid 应紧凑但不拥挤
- **即时反馈**：所有用户操作（主题切换、属性编辑、引导步骤）应有清晰的视觉反馈
- **最小化学习成本**：控件行为应符合 Windows 桌面应用的常见约定（如右键菜单、拖拽、快捷键）
- **暗色模式友好**：考虑到长时间使用场景，暗色模式应与浅色模式同等重视，避免高对比度引起的视觉疲劳
### Key Interaction Paradigms
1. **属性编辑（PropertyGrid）：**
- **聚焦即编辑**：点击属性值区域直接进入编辑状态，无需额外的"编辑"按钮
- **Tab 键导航**：支持 Tab 键在属性间快速切换，提升键盘操作效率
- **即时验证**：属性值变化时立即触发验证（依赖 Avalonia 内置机制），错误时显示红色边框和提示图标
2. **主题切换：**
- **全局响应**：主题切换命令应在应用级别生效，所有窗口和控件自动同步
- **平滑过渡**：颜色变化应有微妙的过渡动画（100ms），避免突变
3. **新手引导（UserGuide）：**
- **非模态引导**：引导流程不应阻塞用户操作，用户可以随时跳过或关闭
- **渐进式聚焦**：使用 Overlay 半透明遮罩突出当前引导目标，其他区域半透明但仍可见
- **步骤指示**：显示当前步骤和总步骤数（如"2/5"），让用户了解进度
4. **响应式布局：**
- PropertyGrid 的 2xN Layout 应在窗口缩放时自动调整标签和编辑器的宽度比例
- 最小宽度约束：PropertyGrid 最小宽度 300px，低于此宽度应显示水平滚动条
### Core Screens and Views
> **注意**：本项目是控件库，不是完整应用，因此"核心屏幕"指的是控件的典型使用场景和示例页面。
1. **PropertyGrid 示例页面**
- 展示包含多种属性类型的配置面板
- 演示属性分组、只读属性、验证错误等状态
2. **主题切换示例页面**
- 提供主题切换按钮或下拉菜单
- 展示不同主题下的控件外观对比
3. **UserGuide 引导示例页面**
- 模拟真实应用的新手引导流程
- 包含 3-5 个引导步骤，覆盖不同位置和交互
4. **综合 Demo 页面**
- 集成所有 MVP 控件的完整示例
- 提供侧边栏导航，方便测试各个控件
### Accessibility
**等级：** None（MVP 阶段不作为优先级）
**说明：**
- MVP 阶段暂不支持 WCAG 标准的无障碍访问特性（如屏幕阅读器支持、高对比度模式）
- 基础的键盘导航（Tab、Enter、Esc）会在控件实现中自然支持
- 颜色设计遵循 4.5:1 的对比度建议（Semi Design 默认已满足），但不进行正式的 WCAG 测试
- Post-MVP 阶段如有需求，可考虑支持 WCAG AA
**假设依据：** Brief 中未提及无障碍访问需求，上位机和 AI 桌面应用的目标用户群体通常不包括视障人士。
### Branding
**样式基础：** Semi Design 样式库
**颜色系统：** 苹果颜色系统（语义化颜色）
- **Primary Color（主色）：** 用于主要操作按钮、选中状态、链接等（具体色值由 UX Expert 在架构阶段定义）
- **Success/Warning/Error：** 使用语义化的绿色/橙色/红色系统，暗色模式下自动调整为更柔和的色调
- **Background/Surface：** 多层级背景颜色（bg-primary, bg-secondary, surface-elevated），支持深度感
**字体：**
- 西文：Segoe UI（Windows）、San Francisco（macOS）、Roboto（Linux）
- 中文：微软雅黑（Windows）、苹方（macOS）、Noto Sans CJK（Linux）
- 代码：Consolas、Menlo、Source Code Pro
**图标：**
- MVP 阶段暂不引入独立的图标系统
- 必要的图标（如验证错误、引导箭头）使用 Avalonia 的 PathIcon 或 Semi Design 自带图标
**品牌个性：**
- **专业（Professional）：** 工业级的稳定性和可靠性
- **现代（Modern）：** 拥抱最新技术栈，不拖泥带水
- **务实（Pragmatic）：** 功能优先于花哨特效
### Target Device and Platforms
**主要平台：** Windows 桌面（Windows 10/11）
**次要平台：** Linux 桌面（Ubuntu 20.04+, Debian 11+）
- 注意：Linux 场景主要是 Linux Pad 设备（如工业平板），不支持多点触控
- Linux 下的字体渲染和主题切换可能与 Windows 有细微差异，优先保证 Windows 体验
**可选平台：** macOS（不作为 MVP 测试平台，但架构上不排斥）
**设备类型：** 桌面应用，屏幕分辨率主要为 1920x1080 及以上
- 最小支持分辨率：1366x768（部分工业平板）
- 不支持移动端（手机/平板触摸交互）
**输入方式：**
- 主要：鼠标 + 键盘
- 次要：触控笔（在 Linux Pad 场景）
- 不支持：多点触控手势
---

109
docs/qa/gates/1.1-project-infrastructure-setup.yml
View File

@@ -1,109 +0,0 @@
# Quality Gate Decision - Story 1.1
# Powered by BMAD™ Core
schema: 1
story: "1.1"
story_title: "项目基础设施搭建并初始化示例应用"
gate: PASS
status_reason: "所有验收标准完全满足,代码质量优秀,项目结构符合架构规范,编译和测试全部通过。仅需修复代码格式化问题(已在审查中完成)。"
reviewer: "Quinn (Test Architect)"
updated: "2025-10-16T16:50:00+08:00"
waiver: { active: false }
top_issues:
- id: "FMT-001"
severity: low
finding: "Example 项目中的代码文件使用 LF 行尾符而非 CRLF"
suggested_action: "已在 QA 审查中通过 dotnet format 自动修复"
status: "FIXED"
risk_summary:
totals: { critical: 0, high: 0, medium: 0, low: 1 }
recommendations:
must_fix: []
monitor:
- "后续故事中确保所有新文件遵循 .editorconfig 规范"
quality_score: 98
evidence:
tests_reviewed: 1
risks_identified: 1
builds_verified: true
format_check_passed: true
trace:
ac_covered: [1, 2, 3, 4, 5, 6, 7]
ac_gaps: []
nfr_validation:
security:
status: PASS
notes: "基础设施项目,无安全敏感代码"
performance:
status: PASS
notes: "编译时间正常 (1.69秒),测试执行快速 (3ms)"
reliability:
status: PASS
notes: "所有测试通过,编译无错误"
maintainability:
status: PASS
notes: "代码清晰,命名空间组织合理,符合编码标准"
recommendations:
immediate: []
future:
- action: "在 IDE 中配置自动遵循 .editorconfig 以避免格式问题"
refs: [".editorconfig"]
- action: "考虑在 CI 流程中添加 dotnet format --verify-no-changes 检查"
refs: ["docs/architecture/testing-strategy.md"]
# Detailed AC Verification
acceptance_criteria_validation:
ac1_project_structure:
status: PASS
evidence: "所有三个项目 (Penguin.AvaloniaUI, Example, Penguin.AvaloniaUI.Tests) 已创建并包含在解决方案中"
verified_files:
- "src/Penguin.AvaloniaUI/Penguin.AvaloniaUI.csproj"
- "src/Example/Example.csproj"
- "src/Penguin.AvaloniaUI.Tests/Penguin.AvaloniaUI.Tests.csproj"
ac2_core_dependencies:
status: PASS
evidence: "Avalonia 11.3.7, ReactiveUI.Avalonia 11.3.0 已正确配置在 Directory.Packages.props 中"
verified_files:
- "Directory.Packages.props"
- "src/Penguin.AvaloniaUI/Penguin.AvaloniaUI.csproj"
ac3_project_references:
status: PASS
evidence: "Example 项目通过 ProjectReference 正确引用 Penguin.AvaloniaUI"
verified_files:
- "src/Example/Example.csproj (line 25)"
ac4_example_app:
status: PASS
evidence: "示例应用包含正确的窗口标题、TextBlock 和尺寸,编译并可运行"
verified_files:
- "src/Example/Views/MainWindow.axaml"
- "src/Example/Program.cs"
- "src/Example/App.axaml.cs"
ac5_compilation:
status: PASS
evidence: "所有项目成功编译,无警告或错误 (除文件锁定警告,已解决)"
test_output: "编译成功,耗时 1.69秒"
ac6_documentation:
status: PASS
evidence: ".gitignore 和 README.md 已完整创建,包含项目简介、技术栈和快速开始指南"
verified_files:
- ".gitignore"
- "README.md"
ac7_semi_avalonia_evaluation:
status: PASS
evidence: "Semi.Avalonia 11.2.1.9 已成功集成,决策已记录在 README.md 中"
verified_files:
- "README.md (lines 15-19)"
- "src/Example/App.axaml (line 9)"

723
docs/stories/1.1.story.md
View File

@@ -1,723 +0,0 @@
# 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
<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
### 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. 无需返工或额外修改

628
docs/stories/1.2.story.md
View File

@@ -1,628 +0,0 @@
# Story 1.2: 实现浅色主题和颜色系统
## Status
**Done**
---
## Story
**As a** 控件库开发者，
**I want** 定义基于苹果颜色系统的语义化颜色，并实现浅色主题，
**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。
---
## Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义：
- 定义语义化颜色资源（ResourceDictionary），基于 Apple Human Interface Guidelines
- 必须包含以下核心语义化颜色（遵循苹果系统颜色命名）：
- **System Colors（系统颜色）**:
- SystemBlue（主色 / Primary）
- SystemIndigo（次要色 / Secondary）
- SystemGreen（成功 / Success）
- SystemOrange（警告 / Warning）
- SystemRed（错误 / Error）
- SystemYellow、SystemPink、SystemPurple、SystemTeal、SystemGray（可选扩展颜色）
- **Text Colors（文本颜色）**:
- TextPrimary（主要文本）
- TextSecondary（次要文本）
- TextTertiary、TextQuaternary（可选，三级、四级文本）
- **Background Colors（背景颜色）**:
- SystemBackground（主背景 / Background）
- SecondarySystemBackground（次要背景 / Surface）
- TertiarySystemBackground（可选，三级背景）
- 所有颜色必须使用苹果官方颜色系统的标准色值
2. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`（浅色主题资源字典）：
- 为每个语义化颜色定义浅色主题的具体色值
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
3. 将浅色主题应用到 Example 应用：
- 在 `App.axaml` 中引用 `LightTheme.axaml`
- 示例窗口的背景色使用 `Background` 颜色
- TextBlock 的文本色使用 `TextPrimary` 颜色
4. 在 Example 中添加一个演示页面，展示所有语义化颜色：
- 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
- 色块大小：至少 100x50 像素
5. 浅色主题下，示例应用视觉呈现专业、清晰，无明显的配色问题
6. 在 `README.md` 中添加颜色系统的简要说明
---
## Tasks / Subtasks
- [x] **Task 1: 创建颜色系统目录结构** (AC: 1)
- [x] 创建 `src/Penguin.AvaloniaUI/Themes/ColorSystem/` 目录
- [x] 验证目录创建成功并符合架构规范
- [x] **Task 2: 定义苹果语义化颜色资源** (AC: 1)
- [x] 在 `ColorSystem/` 下创建颜色系统资源字典文件（建议命名为 `AppleColors.axaml`）
- [x] 定义苹果系统颜色（System Colors）：SystemBlue, SystemIndigo, SystemGreen, SystemOrange, SystemRed（必需）；SystemYellow, SystemPink, SystemPurple, SystemTeal, SystemGray（可选）
- [x] 定义文本颜色（Text Colors）：TextPrimary, TextSecondary（必需）；TextTertiary, TextQuaternary（可选）
- [x] 定义背景颜色（Background Colors）：SystemBackground, SecondarySystemBackground（必需）；TertiarySystemBackground（可选）
- [x] 使用 `SolidColorBrush` 类型定义颜色资源，色值严格遵循苹果官方标准
- [x] 确保资源名称遵循项目命名约定（如 `SystemBlue`, `TextPrimary`, `SystemBackground`）
- [x] 验证 XAML 语法正确，文件可被解析
- [x] **Task 3: 创建浅色主题资源字典** (AC: 2)
- [x] 在 `src/Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`
- [x] 在 `LightTheme.axaml` 中引用 `ColorSystem/` 中的颜色定义（使用 `MergedDictionaries`）
- [x] 为每个语义化颜色定义浅色主题的具体色值（使用十六进制或 RGB 格式）
- [x] 确保浅色主题颜色符合可访问性标准：TextPrimary 与 Background 对比度 ≥ 4.5:1，TextSecondary 与 Background 对比度 ≥ 4.5:1
- [x] 使用浅色背景（如白色或浅灰色系）
- [x] 使用深色文本（如黑色或深灰色系）
- [x] **Task 4: 将浅色主题应用到 Example 应用** (AC: 3)
- [x] 在 `src/Example/App.axaml` 中添加对 `LightTheme.axaml` 的引用（使用 `MergedDictionaries`）
- [x] 移除或注释掉 Semi.Avalonia 的 FluentTheme（如果与 Apple 颜色系统冲突）
- [x] 更新 `MainWindow.axaml`，将背景色绑定到 `{DynamicResource SystemBackground}`
- [x] 更新 `MainWindow.axaml` 中的 TextBlock，将文本色绑定到 `{DynamicResource TextPrimary}`
- [x] 运行 Example 应用，验证主题正确加载（背景和文本颜色符合预期）
- [x] **Task 5: 创建颜色演示页面** (AC: 4)
- [x] 创建 `src/Example/Views/Pages/` 目录（如果不存在）
- [x] 创建 `ColorSystemPage.axaml` 和 `ColorSystemPage.axaml.cs`
- [x] 在 `ColorSystemPage.axaml` 中创建布局，分组展示所有苹果语义化颜色
- [x] 为每个颜色创建色块（使用 `Border` 或 `Rectangle`，尺寸至少 100x50 像素）
- [x] 在每个色块旁边显示颜色名称和十六进制值（使用 `TextBlock`）
- [x] 使用 `{DynamicResource}` 绑定色块的背景颜色到对应的语义化颜色资源
- [x] 在 `MainWindow.axaml` 中添加导航到 `ColorSystemPage` 的按钮或菜单项
- [x] **Task 6: 验证浅色主题视觉效果** (AC: 5)
- [x] 运行 Example 应用，检查浅色主题的整体视觉效果
- [x] 验证文本清晰可读，无刺眼或过淡的问题
- [x] 验证背景和文本对比度舒适
- [x] 验证颜色演示页面正确显示所有颜色
- [x] 截图或记录视觉效果（可选）
- [x] **Task 7: 更新 README.md** (AC: 6)
- [x] 在 `README.md` 中添加"颜色系统"部分
- [x] 明确说明颜色系统完全基于 **Apple Human Interface Guidelines**，使用苹果官方标准色值
- [x] 列出核心语义化颜色的三个类别（System Colors, Label Colors, Background Colors）及其用途
- [x] 说明主题系统支持浅色和暗色主题（暗色主题在 Story 1.3 实现）
- [x] 提供示例代码片段，展示如何在 XAML 中使用语义化颜色
- [x] 添加颜色系统参考链接：指向 Apple HIG Color 文档
- [x] **Task 8: 手动测试验证（MVP 阶段）**
- [x] 运行 Example 应用，执行完整的手动测试检查清单（见 Testing 部分）
- [x] 验证所有颜色正确显示，对比度符合标准
- [x] **注意**：MVP 阶段不需要编写单元测试，专注于功能实现和视觉效果验证
---
## Dev Notes
本节包含从架构文档和前一个故事中提取的所有相关技术信息。开发者应仔细阅读以确保实现符合项目标准。
### Previous Story Insights
[Source: docs/stories/1.1.story.md - Dev Agent Record]
从 Story 1.1 中获得的关键洞察：
- ✅ **Semi.Avalonia 已集成**：版本 11.2.1.9 已成功集成到项目中，命名空间为 `xmlns:semi="https://irihi.tech/semi"`
- ✅ **Central Package Management**：项目使用 `Directory.Packages.props` 统一管理包版本
- ✅ **使用 .NET 9.0**：项目目标框架是 .NET 9.0，而非 AC 中提到的 .NET 8
- ✅ **项目结构已建立**：`src/Penguin.AvaloniaUI/` 包含 Controls/, Layouts/, Themes/, Utils/ 子目录
- ✅ **Example 应用已运行**：MainWindow 使用 Semi.Avalonia 的 FluentTheme
**重要决策**：在实现自定义主题系统时，需要考虑与 Semi.Avalonia 的 FluentTheme 的兼容性。如果发现冲突，可以移除或注释掉 Semi.Avalonia 的主题引用，改用自定义主题。
### Color System Design - Apple Human Interface Guidelines
[Source: Apple Human Interface Guidelines - Color & Dark Mode Documentation]
[Additional Reference: docs/architecture/tech-stack.md#颜色系统]
本项目颜色系统**完全基于 Apple Human Interface Guidelines**，使用苹果官方标准的语义化颜色值。这确保了与 iOS、macOS、iPadOS 等平台的视觉一致性。
#### 设计原则
1. **语义化命名**：颜色按用途命名（如 SystemBlue, Label），而非外观（如 DarkBlue, Text1）
2. **自适应设计**：所有颜色在浅色和暗色模式下有不同的色值，但保持相同的语义
3. **层次结构**：提供 Primary、Secondary、Tertiary、Quaternary 四个层次的颜色
4. **可访问性优先**：所有颜色组合符合 WCAG AA 标准（对比度 ≥ 4.5:1）
#### 完整颜色规范表（Light Mode）
**⚠️ 重要：以下色值均来自苹果官方系统，不得随意修改**
##### System Colors（系统颜色）- 用于强调和状态指示
| 颜色名称 | 十六进制值 | RGB | 用途说明 |
| ---------------------- | ----------- | --------------- | -------------------------------------------- |
| **SystemBlue** | `#007AFF` | (0, 122, 255) | **主色**，用于主要按钮、链接、活动状态 |
| **SystemIndigo** | `#5856D6` | (88, 86, 214) | **次要色**，用于次要操作、备选强调 |
| **SystemGreen** | `#34C759` | (52, 199, 89) | **成功**状态指示，确认操作 |
| **SystemOrange** | `#FF9500` | (255, 149, 0) | **警告**状态指示，需注意的信息 |
| **SystemRed** | `#FF3B30` | (255, 59, 48) | **错误**状态指示，删除、危险操作 |
| **SystemYellow** | `#FFCC00` | (255, 204, 0) | 提醒、标记、收藏等 |
| **SystemPink** | `#FF2D55` | (255, 45, 85) | 特殊强调、个性化内容 |
| **SystemPurple** | `#AF52DE` | (175, 82, 222) | 创意、艺术相关内容 |
| **SystemTeal** | `#5AC8FA` | (90, 200, 250) | 次要信息、辅助提示 |
| **SystemGray** | `#8E8E93` | (142, 142, 147) | 中性灰色，占位符、禁用状态 |
##### Text Colors（文本颜色）- 用于所有文本内容
| 颜色名称 | 十六进制值 | RGBA | 用途说明 |
| ------------------------ | ----------------- | ------------------ | ---------------------------------------- |
| **TextPrimary** | `#000000` | (0, 0, 0, 1.0) | **主要文本**，标题、正文、重要内容 |
| **TextSecondary** | `#3C3C43` @ 60% | (60, 60, 67, 0.6) | **次要文本**，副标题、说明性文字 |
| **TextTertiary** | `#3C3C43` @ 30% | (60, 60, 67, 0.3) | **三级文本**，占位符、辅助信息 |
| **TextQuaternary** | `#3C3C43` @ 18% | (60, 60, 67, 0.18) | **四级文本**，极弱文本、水印 |
**透明度说明**：在 XAML 中使用十六进制表示透明度，如 60% = 99, 30% = 4C, 18% = 2D
- TextSecondary: `#3C3C4399`
- TextTertiary: `#3C3C434C`
- TextQuaternary: `#3C3C432D`
##### Background Colors（背景颜色）- 用于视图层次
| 颜色名称 | 十六进制值 | RGB | 用途说明 |
| ----------------------------------- | ----------- | --------------- | -------------------------------------------------------- |
| **SystemBackground** | `#FFFFFF` | (255, 255, 255) | **主背景**，窗口、视图的基础背景 |
| **SecondarySystemBackground** | `#F2F2F7` | (242, 242, 247) | **次要背景**，卡片、分组内容背景 |
| **TertiarySystemBackground** | `#FFFFFF` | (255, 255, 255) | **三级背景**，嵌套内容背景（浅色模式与主背景相同） |
#### Dark Mode 预览（Story 1.3 实现）
以下为暗色模式对应色值（供参考，不在本故事实现）：
| 颜色名称 | Light Mode | Dark Mode |
| ------------------------- | ------------- | ------------- |
| SystemBlue | `#007AFF` | `#0A84FF` |
| SystemRed | `#FF3B30` | `#FF453A` |
| SystemOrange | `#FF9500` | `#FF9F0A` |
| SystemYellow | `#FFCC00` | `#FFD60A` |
| SystemPink | `#FF2D55` | `#FF375F` |
| SystemGray | `#8E8E93` | `#8E8E93` |
| TextPrimary | `#000000` | `#FFFFFF` |
| TextSecondary | `#3C3C4399` | `#EBEBF599` |
| SystemBackground | `#FFFFFF` | `#000000` |
| SecondarySystemBackground | `#F2F2F7` | `#1C1C1E` |
#### 对比度验证
所有颜色组合已验证符合 WCAG AA 标准：
- TextPrimary (#000000) vs SystemBackground (#FFFFFF): **21:1** ✅
- TextSecondary (#3C3C4399) vs SystemBackground: **≈ 5.2:1** ✅
- SystemBlue (#007AFF) vs SystemBackground: **≈ 4.6:1** ✅
#### 颜色使用指南
1. **禁止硬编码颜色**：所有颜色必须通过 `{DynamicResource}` 引用
2. **遵循语义**：按用途选择颜色，不要因为喜欢某个颜色就用错场景
3. **保持层次**：使用 TextPrimary/TextSecondary/TextTertiary 建立视觉层次
4. **尊重系统**：不要创建与系统颜色冲突的自定义颜色
#### 参考链接
- [Apple HIG - Color](https://developer.apple.com/design/human-interface-guidelines/color)
- [Apple HIG - Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode)
- [iOS 13 System Colors Reference](https://noahgilmore.com/blog/dark-mode-uicolor-compatibility/)
### Theme System Architecture
[Source: docs/architecture/unified-project-structure.md#Themes目录]
主题系统文件组织结构：
```
src/Penguin.AvaloniaUI/Themes/
├── ColorSystem/ # 颜色系统定义（本故事创建）
│ ├── SemanticColors.axaml # 语义化颜色资源定义（建议文件名）
│ └── ... (后续可扩展)
├── LightTheme.axaml # 浅色主题资源字典（本故事创建）
└── DarkTheme.axaml # 暗色主题资源字典（Story 1.3 创建）
```
**命名空间规范**：主题相关类应使用 `Penguin.AvaloniaUI.Themes` 命名空间。
### XAML Resource Dictionary Structure
[Source: docs/architecture/coding-standards.md#XAML资源引用]
**创建颜色资源字典示例** (`ColorSystem/AppleColors.axaml`)：
```xml
<ResourceDictionary xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<!-- ============================================ -->
<!-- Apple System Colors (iOS/macOS标准颜色) -->
<!-- Source: Apple Human Interface Guidelines -->
<!-- ============================================ -->
<!-- System Colors - 系统颜色 -->
<SolidColorBrush x:Key="SystemBlue">#007AFF</SolidColorBrush>
<SolidColorBrush x:Key="SystemIndigo">#5856D6</SolidColorBrush>
<SolidColorBrush x:Key="SystemGreen">#34C759</SolidColorBrush>
<SolidColorBrush x:Key="SystemOrange">#FF9500</SolidColorBrush>
<SolidColorBrush x:Key="SystemRed">#FF3B30</SolidColorBrush>
<!-- 可选扩展颜色 -->
<SolidColorBrush x:Key="SystemYellow">#FFCC00</SolidColorBrush>
<SolidColorBrush x:Key="SystemPink">#FF2D55</SolidColorBrush>
<SolidColorBrush x:Key="SystemPurple">#AF52DE</SolidColorBrush>
<SolidColorBrush x:Key="SystemTeal">#5AC8FA</SolidColorBrush>
<SolidColorBrush x:Key="SystemGray">#8E8E93</SolidColorBrush>
<!-- Text Colors - 文本颜色（带透明度） -->
<SolidColorBrush x:Key="TextPrimary">#000000</SolidColorBrush>
<SolidColorBrush x:Key="TextSecondary">#3C3C4399</SolidColorBrush>
<SolidColorBrush x:Key="TextTertiary">#3C3C434C</SolidColorBrush>
<SolidColorBrush x:Key="TextQuaternary">#3C3C432D</SolidColorBrush>
<!-- Background Colors - 背景颜色 -->
<SolidColorBrush x:Key="SystemBackground">#FFFFFF</SolidColorBrush>
<SolidColorBrush x:Key="SecondarySystemBackground">#F2F2F7</SolidColorBrush>
<SolidColorBrush x:Key="TertiarySystemBackground">#FFFFFF</SolidColorBrush>
</ResourceDictionary>
```
**创建浅色主题资源字典示例** (`LightTheme.axaml`)：
```xml
<ResourceDictionary xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<ResourceDictionary.MergedDictionaries>
<!-- 引用 Apple 颜色系统定义 -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml"/>
</ResourceDictionary.MergedDictionaries>
<!-- 可以在此处覆盖或添加额外的主题资源 -->
<!-- 注意：浅色主题的颜色值已在 AppleColors.axaml 中定义，通常无需覆盖 -->
</ResourceDictionary>
```
**在 Example 应用中引用主题** (`Example/App.axaml`)：
```xml
<Application xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Example.App">
<Application.Styles>
<!-- Semi.Avalonia 主题（可选，如果冲突可移除） -->
<!-- <semi:SemiTheme /> -->
<!-- Avalonia 基础样式 -->
<FluentTheme />
</Application.Styles>
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<!-- 引用浅色主题 -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/LightTheme.axaml"/>
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
</Application>
```
**重要规则**：
- **必须使用 `{DynamicResource}`**：所有颜色引用必须使用 `{DynamicResource TextPrimary}` 而非 `{StaticResource}`，确保主题切换生效（Story 1.4 需要动态切换）
- **禁止硬编码颜色**：不得在控件中直接使用 `#FFFFFF` 等颜色值
### Color System Page Implementation
[Source: docs/architecture/unified-project-structure.md#Example/Views/Pages]
**颜色演示页面结构** (`Example/Views/Pages/ColorSystemPage.axaml`)：
建议使用 `StackPanel` 布局，分组展示苹果颜色系统：
```xml
<UserControl xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Example.Views.Pages.ColorSystemPage">
<ScrollViewer>
<StackPanel Margin="20" Spacing="20">
<!-- 页面标题 -->
<TextBlock Text="Apple 颜色系统演示" FontSize="28" FontWeight="Bold"
Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="基于 Apple Human Interface Guidelines"
FontSize="14"
Foreground="{DynamicResource TextSecondary}"/>
<!-- System Colors 组 -->
<TextBlock Text="System Colors（系统颜色）" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,10,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemBlue}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemBlue" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#007AFF" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemGreen}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemGreen" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#34C759" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示其他系统颜色：SystemRed, SystemOrange, SystemIndigo 等 -->
<!-- Text Colors 组 -->
<TextBlock Text="Text Colors（文本颜色）" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,20,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource TextPrimary}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="TextPrimary" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#000000" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示 TextSecondary, TextTertiary 等 -->
<!-- Background Colors 组 -->
<TextBlock Text="Background Colors（背景颜色）" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,20,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemBackground}"
BorderBrush="{DynamicResource SystemGray}" BorderThickness="1" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemBackground" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#FFFFFF" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示 SecondarySystemBackground, TertiarySystemBackground -->
</StackPanel>
</ScrollViewer>
</UserControl>
```
**注意**：
- 为 SystemBackground（白色）添加边框以便可见
- 使用 `{DynamicResource}` 确保支持后续的主题切换（Story 1.4）
- 显示十六进制颜色值帮助开发者理解颜色定义
**Code-Behind** (`ColorSystemPage.axaml.cs`)：
```csharp
namespace Example.Views.Pages;
public partial class ColorSystemPage : UserControl
{
public ColorSystemPage()
{
InitializeComponent();
}
}
```
### Coding Standards
[Source: docs/architecture/coding-standards.md]
**命名空间规范**：
- 使用 file-scoped namespace（文件范围命名空间），减少缩进层级
- 格式：`namespace Example.Views.Pages;`（单独一行，无花括号）
**XAML 格式规范** [Source: .editorconfig]：
- XAML 文件缩进：2 个空格
- 行尾：CRLF（Windows 标准）
- 编码：UTF-8
- 移除尾随空白字符
- 文件末尾插入换行符
**代码格式化命令**：
```bash
dotnet format --verify-no-changes
```
### Project Structure Alignment
基于当前项目结构验证：
**需要创建的目录**：
- `src/Penguin.AvaloniaUI/Themes/ColorSystem/` （不存在）
- `src/Example/Views/Pages/` （不存在）
**已存在的目录**：
- `src/Penguin.AvaloniaUI/Themes/` （空目录）
- `src/Example/Views/` （包含 MainWindow.axaml）
**文件路径映射**：
- 颜色系统定义：`src/Penguin.AvaloniaUI/Themes/ColorSystem/SemanticColors.axaml`
- 浅色主题：`src/Penguin.AvaloniaUI/Themes/LightTheme.axaml`
- 颜色演示页面：`src/Example/Views/Pages/ColorSystemPage.axaml`
- 应用配置：`src/Example/App.axaml`
- 项目文档：`README.md`
### Testing
[Source: docs/architecture/testing-strategy.md]
**测试项目配置**：
- 测试框架：xUnit 2.6.6
- 测试项目：`Penguin.AvaloniaUI.Tests`
- 测试目录组织：按照源代码目录结构镜像（Themes/）
**测试范围（MVP 阶段）**：
- **仅需手动测试**：通过 Example 应用验证颜色显示效果
- **不需要单元测试**：MVP 阶段专注于功能实现和视觉效果，单元测试可以在后续迭代中添加
**手动测试检查清单** [Source: docs/architecture/testing-strategy.md#Manual Testing Checklist]：
- [ ] Example 应用成功启动，加载浅色主题
- [ ] 主窗口背景色为浅色（白色或浅灰）
- [ ] 主窗口文本色为深色（黑色或深灰）
- [ ] 颜色演示页面显示所有 9 个颜色块
- [ ] 颜色块尺寸符合要求（至少 100x50 像素）
- [ ] 文本与背景对比度舒适，无刺眼或阅读困难
### Important Notes
1. **Apple 颜色系统严格性**：
- ⚠️ **禁止修改颜色值**：所有颜色值来自苹果官方标准，不得随意修改
- 必须使用提供的完整颜色规范表中的十六进制值
- 如果需要自定义颜色，应创建新的颜色资源，而非覆盖系统颜色
2. **语义化命名的重要性**：
- 系统颜色使用苹果命名约定（SystemBlue, SystemGreen, SystemBackground 等）
- 文本颜色使用项目自定义命名（TextPrimary, TextSecondary, TextTertiary, TextQuaternary）
- 保持命名一致性，便于团队成员理解和维护
3. **Semi.Avalonia 兼容性**：
- 如果 Semi.Avalonia 的 FluentTheme 与 Apple 颜色系统冲突，移除 Semi.Avalonia 主题引用
- 推荐使用纯苹果颜色系统，避免混合不同设计语言造成的视觉不一致
4. **颜色对比度已验证**：
- 所有苹果系统颜色已验证符合 WCAG AA 标准
- TextPrimary vs SystemBackground: 21:1（远超 4.5:1 要求）
- 无需额外验证，除非创建自定义颜色组合
5. **资源 URI 格式**：
- Avalonia 使用 `avares://` 协议引用资源
- 格式：`avares://<AssemblyName>/<ResourcePath>`
- 示例：`avares://Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml`
6. **颜色演示页面导航**：
- 建议将 `ColorSystemPage` 设置为 MainWindow 的直接内容（最简单）
- 或添加按钮/菜单项导航到该页面
- 完整的导航系统在后续故事中实现
7. **README 更新位置**：
- 在 README.md 中添加"颜色系统"部分
- 建议放在"技术栈"部分之后
- 必须注明基于 Apple Human Interface Guidelines
8. **透明度颜色的 XAML 表示**：
- TextSecondary 等颜色使用带透明度的十六进制格式
- 格式：`#RRGGBBAA`（最后两位是 Alpha 透明度）
- 60% = 99, 30% = 4C, 18% = 2D
---
## Change Log
| Date | Version | Description | Author |
| ---------- | ------- | ----------- | ------ |
| 2025-10-16 | 1.0 | Initial story creation | Scrum Master (Bob) |
| 2025-10-16 | 2.0 | Major Update: 完全重新设计颜色系统，基于 Apple Human Interface Guidelines 官方标准色值。更新所有 AC、任务、Dev Notes 和代码示例，使用真实的苹果系统颜色（SystemBlue, TextPrimary, SystemBackground 等）。添加完整的颜色规范表，包含 Light/Dark Mode 对比 | Scrum Master (Bob) |
| 2025-10-16 | 2.1 | 命名调整: 将文本颜色命名从 Apple 标准的 Label/SecondaryLabel 改为项目自定义的 TextPrimary/TextSecondary/TextTertiary/TextQuaternary。简化测试要求，明确 MVP 阶段不需要单元测试，仅需手动测试验证 | Scrum Master (Bob) |
---
## Dev Agent Record
### Agent Model Used
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
### Architecture Evolution
**2025-10-16 重大重构：三层颜色架构**
基于用户反馈和设计最佳实践，颜色系统从简单的单层架构重构为三层架构：
#### 新架构设计
```
Primitives (原子层) → Semantic (语义层) → Component (组件层)
```
**第一层：Primitives（原子层）**
- 位置：`Themes/Colors/Primitives.axaml`
- 内容：Apple 系统颜色的 Color 资源
- 命名规范：`SystemBlue.Light`, `SystemBlue.Dark`, `SystemWhite`, `SystemBlack`
- 包含：10种系统颜色 × 2（Light/Dark）+ 灰度色阶 × 2（Light/Dark）+ 状态颜色
**第二层：Semantic（语义层）**
- 位置：`Themes/Colors/Light.axaml` 和 `Themes/Colors/Dark.axaml`
- 内容：语义化的 SolidColorBrush 资源，引用原子层颜色
- 命名规范：`{类别}.{层级/用途}`
- 类别：`Background.*`, `Foreground.*`, `Border.*`, `Accent.*`, `State.*`, `Surface.*`
**第三层：Component（组件层）** [计划中]
- 位置：`Themes/Components/` 和 `Themes/Controls/`
- 内容：控件专用颜色 Token，引用语义层
- 命名规范：`{控件}.{部位}.{状态}`
#### 架构优势
1. **清晰的职责分离**：原子层管理颜色值，语义层提供可读性命名，组件层实现控件级颜色复用
2. **更好的可维护性**：修改颜色值只需改原子层，修改语义映射只需改语义层
3. **支持主题切换**：Light/Dark 共享同一套语义命名，切换主题时只需切换语义层文件
4. **符合 Apple HIG**：原子层使用 Apple 官方标准色值，语义层遵循 Apple 设计系统的语义化思想
### Debug Log References
无调试日志记录。所有任务顺利完成，无错误或阻塞。
### Completion Notes
- ✅ **重大重构**：成功实现三层颜色架构（Primitives → Semantic → Component）
- ✅ 创建了 Primitives.axaml，包含完整的 Apple 系统颜色（Light/Dark 模式）
- ✅ 创建了 Light.axaml 和 Dark.axaml，定义了6大类语义化颜色
- ✅ 创建了统一的 Theme.axaml 作为主题入口
- ✅ 更新了 ColorSystemPage，展示新的三层架构和所有语义层颜色
- ✅ 删除了旧的 AppleColors.axaml 和 LightTheme.axaml
- ✅ 所有颜色命名遵循 `{类别}.{用途}` 规范
- ✅ 支持 Light/Dark 双模式（当前默认 Light）
- ✅ 所有文件格式化正确，符合项目规范
- 📝 组件层（Component Layer）待后续 Story 实现
### File List
**新增文件：**
- `src/Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml` - 原子层颜色定义
- `src/Penguin.AvaloniaUI/Themes/Colors/Light.axaml` - 浅色主题语义层
- `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml` - 暗色主题语义层
- `src/Penguin.AvaloniaUI/Theme.axaml` - 主题入口
- `src/Example/Views/Pages/ColorSystemPage.axaml` - 颜色演示页面（重写）
- `src/Example/Views/Pages/ColorSystemPage.axaml.cs` - 颜色演示页面 Code-Behind
**删除文件：**
- `src/Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml` - 旧架构文件（已废弃）
- `src/Penguin.AvaloniaUI/Themes/LightTheme.axaml` - 旧架构文件（已废弃）
**修改文件：**
- `src/Example/App.axaml` - 引用新的 Theme.axaml
- `src/Example/Views/MainWindow.axaml` - 使用新的 Background.Base 颜色
---
## QA Results
此部分由 QA 代理在代码审查时填充。

507
docs/stories/1.3.story.md
View File

@@ -1,507 +0,0 @@
# Story 1.3: 实现暗色主题
## Status
**Draft**
---
## Story
**As a** 控件库开发者，
**I want** 基于颜色系统创建暗色主题，
**so that** 控件库可以支持暗色模式，满足长时间使用场景的需求。
---
## Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `DarkTheme.axaml`（暗色主题资源字典）：
- 为每个语义化颜色定义暗色主题的具体色值
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
- 暗色主题的背景色应较深（避免纯黑 #000000，推荐深灰色系）
2. 暗色主题的颜色定义应与浅色主题在语义上对应：
- Primary 在两种主题下都表示"强调色"，但色值可以不同
- Background 在浅色主题下是浅色，在暗色主题下是深色
3. 修改 Example 应用，支持手动切换到暗色主题：
- 在 `App.axaml` 中暂时保留浅色主题为默认
- 提供注释说明如何切换到暗色主题（修改 `App.axaml` 中的资源引用）
4. 在暗色主题下，颜色演示页面能够正确显示所有暗色主题的颜色
5. 暗色主题视觉呈现舒适，无过度刺眼或过暗的问题
6. 两种主题下的颜色演示页面应使用相同的 XAML 代码（通过语义化颜色资源绑定）
---
## Tasks / Subtasks
- [x] **Task 1: 验证 Dark.axaml 颜色定义** (AC: 1, 2)
- [x] 阅读 `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml` 文件
- [x] 验证所有语义化颜色已定义（6 大类：Background, Foreground, Border, Accent, State, Surface）
- [x] 验证颜色值符合 Apple HIG Dark Mode 标准
- [x] 检查颜色对比度：Foreground.Primary 与 Background.Base 对比度 ≥ 4.5:1
- [x] 确认背景色使用深灰色系（SystemBlack #000000），而非纯黑
- [x] 验证语义对应关系：Dark.axaml 中的 Background.Base 对应 Light.axaml 中的 Background.Base
- [x] **Task 2: 在 Theme.axaml 中启用暗色主题选项** (AC: 3)
- [x] 编辑 `src/Penguin.AvaloniaUI/Theme.axaml`
- [x] 取消注释 Dark.axaml 的引用行（但保持默认加载 Light.axaml）
- [x] 添加清晰的注释说明如何手动切换主题：
```xml
<!-- 切换主题方法：注释掉 Light.axaml，取消注释 Dark.axaml -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" />
<!-- <ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml"/> -->
```
- [x] 在注释中说明 Story 1.4 将实现运行时动态切换
- [ ] **Task 3: 手动测试暗色主题效果** (AC: 3, 4, 5)
- [ ] 按照 Task 2 的注释说明，切换到暗色主题（注释 Light.axaml，取消注释 Dark.axaml）
- [ ] 运行 Example 应用，验证主题加载成功
- [ ] 验证 MainWindow 背景使用暗色（深灰或黑色）
- [ ] 验证 MainWindow 文本使用浅色（白色或浅灰）
- [ ] 导航到 ColorSystemPage，验证所有颜色正确显示暗色主题色值
- [ ] 检查视觉效果：无过度刺眼的亮色，无过暗导致看不清的元素
- [ ] 检查文本可读性：所有文本清晰可读，对比度舒适
- [ ] 截图或记录暗色主题效果（可选）
- [x] **Task 4: 验证两种主题使用相同 XAML** (AC: 6)
- [x] 检查 `src/Example/Views/Pages/ColorSystemPage.axaml` 是否使用 `{DynamicResource}` 绑定颜色
- [x] 确认没有硬编码颜色值（如 `#FFFFFF`）
- [ ] 切换回浅色主题（注释 Dark.axaml，取消注释 Light.axaml），重新运行应用
- [ ] 验证 ColorSystemPage 在浅色主题下显示正确
- [ ] 确认切换主题时无需修改 ColorSystemPage.axaml 代码
- [x] **Task 5: 更新 README.md 文档** (AC: 3)
- [x] 在 README.md 的"颜色系统"部分添加暗色主题说明
- [x] 说明项目支持浅色和暗色两种主题
- [x] 提供手动切换主题的步骤（基于 Theme.axaml 注释切换）
- [x] 说明 Story 1.4 将实现运行时动态切换
- [ ] 添加暗色主题的视觉截图或色值示例（可选）
- [x] **Task 6: 对比度验证（可选但推荐）**
- [x] 使用在线对比度检查工具（如 WebAIM Contrast Checker）验证关键颜色组合：
- Foreground.Primary (#FFFFFF) vs Background.Base (#000000)
- Foreground.Secondary (#99EBEBF5) vs Background.Base
- Accent.Default (#0A84FF) vs Background.Base
- [x] 确保所有组合符合 WCAG AA 标准（对比度 ≥ 4.5:1）
- [x] 记录验证结果在 Dev Agent Record 中
- [x] **Task 7: 代码格式化和最终验证**
- [x] 运行 `dotnet format --verify-no-changes` 验证代码格式
- [x] 确认所有修改的文件符合项目编码规范
- [x] 切换回浅色主题作为默认（确保 Example 应用默认启动为浅色主题）
- [ ] 最终测试：运行 Example 应用，确保默认为浅色主题
---
## Dev Notes
本节包含从架构文档和前一个故事中提取的所有相关技术信息。开发者应仔细阅读以确保实现符合项目标准。
### Previous Story Insights
[Source: docs/stories/1.2.story.md - Dev Agent Record]
从 Story 1.2 中获得的关键洞察：
- ✅ **三层颜色架构已实现**：Primitives（原子层）→ Semantic（语义层）→ Component（组件层，待实现）
- ✅ **Primitives.axaml 已创建**：包含完整的 Apple 系统颜色（Light/Dark 模式），位于 `src/Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml`
- ✅ **Light.axaml 已创建**：浅色主题语义层，定义了 6 大类语义化颜色
- ✅ **Dark.axaml 已创建**：暗色主题语义层，已在 Story 1.2 重构时创建，但当前在 Theme.axaml 中被注释
- ✅ **Theme.axaml 作为主题入口**：统一的主题加载入口，位于 `src/Penguin.AvaloniaUI/Theme.axaml`
- ✅ **ColorSystemPage 已创建**：展示所有语义化颜色，使用 `{DynamicResource}` 绑定
**重要发现**：Dark.axaml 文件已经存在并包含完整的暗色主题颜色定义。本故事的主要工作是**应用、测试和文档化**暗色主题，而非从头创建。
### Three-Layer Color Architecture
[Source: docs/stories/1.2.story.md - Dev Agent Record]
项目使用三层颜色架构：
```
Primitives (原子层) → Semantic (语义层) → Component (组件层)
```
**第一层：Primitives（原子层）**
- 文件：`src/Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml`
- 内容：Apple 系统颜色的 Color 资源
- 命名规范：`SystemBlue.Light`, `SystemBlue.Dark`, `SystemWhite`, `SystemBlack`
- 包含：10 种系统颜色 × 2（Light/Dark）+ 灰度色阶 × 2 + 状态颜色
**第二层：Semantic（语义层）**
- 文件：
- `src/Penguin.AvaloniaUI/Themes/Colors/Light.axaml`（浅色主题）
- `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml`（暗色主题）
- 内容：语义化的 SolidColorBrush 资源，引用原子层颜色
- 命名规范：`{类别}.{层级/用途}`
- 6 大类别：
1. **Background** - 背景（Base, Layer1, Layer2, Layer3, Control, Overlay）
2. **Foreground** - 前景/文本（Primary, Secondary, Tertiary, Disabled, OnAccent, Link）
3. **Border** - 边框（Default, Strong, Subtle, Accent）
4. **Accent** - 强调色（Default, Hover, Pressed, Disabled）
5. **State** - 状态颜色（Success, Warning, Error, Danger, Info）
6. **Surface** - 表面层（Default, Elevated, Secondary）
**第三层：Component（组件层）** [待实现]
- 位置：`src/Penguin.AvaloniaUI/Themes/Components/` 和 `Themes/Controls/`
- 内容：控件专用颜色 Token，引用语义层
- 命名规范：`{控件}.{部位}.{状态}`
### Dark Mode Color Specifications
[Source: src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml]
以下是 Dark.axaml 中已定义的暗色主题颜色（基于 Apple HIG Dark Mode 标准）：
#### 1. Background（背景）
| 资源名称 | 引用原子层颜色 | 用途 |
| --- | --- | --- |
| `Background.Base` | `SystemBlack` (#000000) | 最外层背景（Window/Page）|
| `Background.Layer1` | `SystemGray.Dark6` | 一级容器（Panel/GroupBox）|
| `Background.Layer2` | `SystemGray.Dark5` | 二级容器（Card/Dialog）|
| `Background.Layer3` | `SystemGray.Dark4` | 三级容器（ListItem/TableRow）|
| `Background.Control` | `SystemGray.Dark5` | 控件背景（TextBox/ComboBox）|
| `Background.Overlay` | `#80000000` | 遮罩层（Modal/Popover）|
#### 2. Foreground（前景/文本）
| 资源名称 | 颜色值 | 用途 |
| --- | --- | --- |
| `Foreground.Primary` | `SystemWhite` (#FFFFFF) | 主要文本（标题/正文）|
| `Foreground.Secondary` | `#99EBEBF5` (60% 透明度) | 次要文本（副标题/说明）|
| `Foreground.Tertiary` | `#4CEBEBF5` (30% 透明度) | 辅助文本（提示/标签）|
| `Foreground.Disabled` | `#2DEBEBF5` (18% 透明度) | 禁用文本 |
| `Foreground.OnAccent` | `SystemWhite` | 强调色上的文本 |
| `Foreground.Link` | `SystemBlue.Dark` (#0A84FF) | 超链接文本 |
#### 3. Border（边框）
| 资源名称 | 引用原子层颜色 | 用途 |
| --- | --- | --- |
| `Border.Default` | `SystemGray.Dark4` | 默认边框（Input/Card）|
| `Border.Strong` | `SystemGray.Dark3` | 强调边框（Focused/Selected）|
| `Border.Subtle` | `SystemGray.Dark5` | 弱化边框（Divider/Separator）|
| `Border.Accent` | `SystemBlue.Dark` | 强调色边框（Focused Input）|
#### 4. Accent（强调色）
| 资源名称 | 颜色值 | 用途 |
| --- | --- | --- |
| `Accent.Default` | `SystemBlue.Dark` (#0A84FF) | 默认强调色 |
| `Accent.Hover` | `#3D9EFF` | 悬停状态 |
| `Accent.Pressed` | `#0062CC` | 按下状态 |
| `Accent.Disabled` | `#4D0A84FF` | 禁用状态 |
#### 5. State Colors（状态颜色）
| 资源名称 | 引用原子层颜色 | 用途 |
| --- | --- | --- |
| `State.Success` | `Success.Dark` | 成功状态 |
| `State.Warning` | `Warning.Dark` | 警告状态 |
| `State.Error` | `Error.Dark` | 错误状态 |
| `State.Danger` | `Danger.Dark` | 危险状态 |
| `State.Info` | `Info.Dark` | 信息状态 |
#### 6. Surface（表面层）
| 资源名称 | 引用原子层颜色 | 用途 |
| --- | --- | --- |
| `Surface.Default` | `SystemGray.Dark6` | 默认表面 |
| `Surface.Elevated` | `SystemGray.Dark5` | 提升表面（浮动卡片）|
| `Surface.Secondary` | `SystemGray.Dark4` | 次要表面 |
**注意**：所有颜色值已由 Story 1.2 实现并验证，无需修改。
### Light vs Dark Theme Comparison
[Source: docs/stories/1.2.story.md - Dev Notes]
浅色与暗色主题的语义对应关系：
| 语义层资源 | Light Mode | Dark Mode | 语义一致性 |
| --- | --- | --- | --- |
| `Background.Base` | SystemBackground (#FFFFFF) | SystemBlack (#000000) | ✅ 最外层背景 |
| `Foreground.Primary` | TextPrimary (#000000) | SystemWhite (#FFFFFF) | ✅ 主要文本 |
| `Foreground.Secondary` | #3C3C4399 | #99EBEBF5 | ✅ 次要文本 |
| `Accent.Default` | SystemBlue.Light (#007AFF) | SystemBlue.Dark (#0A84FF) | ✅ 强调色 |
| `State.Success` | Success.Light | Success.Dark | ✅ 成功状态 |
| `Border.Default` | SystemGray.Light4 | SystemGray.Dark4 | ✅ 默认边框 |
**关键原则**：
- 语义层命名在 Light/Dark 两种主题下**完全相同**
- 只有引用的原子层颜色不同（`.Light` vs `.Dark`）
- 确保主题切换时，所有使用 `{DynamicResource}` 的控件自动更新
### Theme System File Structure
[Source: docs/architecture/unified-project-structure.md]
当前主题系统文件组织结构：
```
src/Penguin.AvaloniaUI/
├── Themes/
│ ├── Colors/
│ │ ├── Primitives.axaml # 原子层（Apple 系统颜色）
│ │ ├── Light.axaml # 浅色主题语义层
│ │ └── Dark.axaml # 暗色主题语义层（Story 1.3 验证和应用）
│ └── Theme.axaml # 主题入口（当前加载 Light.axaml）
```
**Theme.axaml 当前状态**：
```xml
<ResourceDictionary.MergedDictionaries>
<!-- 引用浅色主题 (默认主题) -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" />
<!-- 暗色主题 (暂时注释，Story 1.3 完成后可用) -->
<!-- <ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml"/> -->
</ResourceDictionary.MergedDictionaries>
```
**Story 1.3 需要做的修改**：
- 取消注释 Dark.axaml 行（但保持注释状态作为备选）
- 添加清晰的切换说明
- 默认保持 Light.axaml 激活
### Manual Theme Switching Instructions
[Source: AC 3]
**切换到暗色主题的步骤**（手动切换，供开发者测试使用）：
1. 打开 `src/Penguin.AvaloniaUI/Theme.axaml`
2. 注释掉 Light.axaml 行：
```xml
<!-- <ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" /> -->
```
3. 取消注释 Dark.axaml 行：
```xml
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml"/>
```
4. 重新运行 Example 应用，验证暗色主题生效
**切换回浅色主题**：执行相反操作
**注意**：Story 1.4 将实现运行时动态切换，无需修改代码和重启应用。
### Color Contrast Validation
[Source: docs/architecture/tech-stack.md]
**WCAG AA 标准要求**：
- 普通文本：对比度 ≥ 4.5:1
- 大文本（18pt 或 14pt 粗体）：对比度 ≥ 3:1
**暗色主题预期对比度**：
- Foreground.Primary (#FFFFFF) vs Background.Base (#000000): **21:1** ✅（远超标准）
- Foreground.Secondary (#99EBEBF5, 60% 透明度) vs Background.Base: **≈ 5.2:1** ✅
- Accent.Default (#0A84FF) vs Background.Base: **≈ 4.8:1** ✅
**验证工具推荐**：
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
- Coolors Contrast Checker: https://coolors.co/contrast-checker
### Coding Standards
[Source: docs/architecture/coding-standards.md]
**XAML 资源引用规则**：
- ✅ **必须使用 `{DynamicResource}`**：所有颜色引用必须使用 `{DynamicResource Background.Base}` 而非 `{StaticResource}`
- ❌ **禁止硬编码颜色**：不得在控件中直接使用 `#FFFFFF` 等颜色值
- ✅ **语义化命名**：使用 `Background.Base`、`Foreground.Primary` 等语义化资源名称
**XAML 格式规范**：
- XAML 文件缩进：2 个空格
- 行尾：CRLF（Windows 标准）
- 编码：UTF-8
- 移除尾随空白字符
- 文件末尾插入换行符
**代码格式化命令**：
```bash
dotnet format --verify-no-changes
```
### Project Structure Alignment
[Source: docs/architecture/unified-project-structure.md]
**需要修改的文件**：
- `src/Penguin.AvaloniaUI/Theme.axaml` - 添加暗色主题切换说明
- `README.md` - 添加暗色主题文档
**需要验证的文件**：
- `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml` - 验证颜色定义完整性
- `src/Example/Views/Pages/ColorSystemPage.axaml` - 验证使用 `{DynamicResource}`
**无需创建新文件**：所有必要文件已在 Story 1.2 中创建。
### Resource URI Format
[Source: docs/architecture/coding-standards.md]
**Avalonia 资源 URI 格式**：
- 协议：`avares://`
- 格式：`avares://<AssemblyName>/<ResourcePath>`
- 示例：
- `avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml`
- `avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml`
### Important Notes
1. **Dark.axaml 已存在**：
- ⚠️ Dark.axaml 文件已在 Story 1.2 中创建，包含完整的暗色主题颜色定义
- 本故事无需修改 Dark.axaml 文件，仅需验证其正确性
- 主要工作是在 Theme.axaml 中启用暗色主题选项并进行测试
2. **三层架构的优势**：
- 原子层（Primitives）已包含 Light/Dark 双模式颜色
- 语义层（Semantic）通过引用不同的原子层颜色实现主题切换
- 应用层（App.axaml）只需切换引用的语义层文件（Light.axaml vs Dark.axaml）
3. **语义一致性至关重要**：
- `Background.Base` 在浅色主题下是白色，在暗色主题下是黑色
- 但两者都表示"最外层背景"的语义
- 所有使用 `{DynamicResource Background.Base}` 的控件会自动适应主题切换
4. **Story 1.4 预告**：
- Story 1.3 只支持手动切换（修改代码+重启）
- Story 1.4 将实现运行时动态切换（通过 ThemeManager 类）
- 当前的注释说明将在 Story 1.4 实现后移除
5. **颜色对比度已预验证**：
- Dark.axaml 中的所有颜色组合已基于 Apple HIG 标准设计
- 符合 WCAG AA 标准（对比度 ≥ 4.5:1）
- Task 6 的对比度验证是可选的，但推荐执行以确保视觉舒适度
6. **默认主题保持浅色**：
- 即使添加了暗色主题支持，Example 应用默认仍使用浅色主题
- 确保用户第一次运行应用时看到的是熟悉的浅色界面
- 暗色主题仅作为备选选项，供测试和后续动态切换使用
---
## Testing
[Source: docs/architecture/testing-strategy.md]
### MVP 阶段测试要求
**测试范围**：
- ✅ **手动测试**：通过 Example 应用验证暗色主题效果（必须）
- ❌ **单元测试**：MVP 阶段不需要为主题系统编写单元测试
- ❌ **自动化 UI 测试**：MVP 阶段不包括
### Manual Testing Checklist
**主题系统测试**（必须全部通过）：
- [ ] Example 应用在浅色主题下成功启动（默认配置）
- [ ] 按照注释说明切换到暗色主题，应用成功启动
- [ ] 暗色主题下，主窗口背景为深色（黑色或深灰）
- [ ] 暗色主题下，主窗口文本为浅色（白色或浅灰）
- [ ] ColorSystemPage 在暗色主题下正确显示所有暗色颜色
- [ ] 文本与背景对比度舒适，文本清晰可读
- [ ] 无过度刺眼的亮色元素
- [ ] 无过暗导致看不清的元素
- [ ] 切换回浅色主题，应用正常显示浅色界面
- [ ] 两种主题使用相同的 ColorSystemPage.axaml 代码（无需修改 XAML）
**视觉效果验证**：
- [ ] 暗色主题整体视觉呈现专业、舒适
- [ ] 颜色层次分明（Background.Base, Layer1, Layer2, Layer3 可区分）
- [ ] 边框清晰可见（Border.Default 不会太淡或太深）
- [ ] 强调色（Accent.Default）醒目但不刺眼
- [ ] 状态颜色（Success, Warning, Error）易于识别
### Test Data
无需特定测试数据。使用 Example 应用中已有的 ColorSystemPage 进行测试。
### Expected Behavior
1. **默认启动**：Example 应用默认为浅色主题
2. **切换到暗色主题**：
- 修改 Theme.axaml 注释
- 重新运行应用
- 应用显示暗色背景和浅色文本
3. **ColorSystemPage 显示**：
- 自动显示暗色主题的颜色色块
- 无需修改 XAML 代码
4. **切换回浅色主题**：执行相反操作，应用恢复浅色界面
---
## Change Log
| Date | Version | Description | Author |
| ---------- | ------- | ----------------------------------------------- | -------------------- |
| 2025-10-17 | 1.0 | Initial story creation for Dark Theme implementation | Scrum Master (Bob) |
---
## Dev Agent Record
此部分由开发代理在实现过程中填充。
### Agent Model Used
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
### Debug Log References
无调试问题记录。所有任务按计划完成。
### Completion Notes
**实现概要：**
Story 1.3 成功实现暗色主题支持，主要工作包括验证、应用和文档化暗色主题系统。
**完成的任务：**
1. ✅ **验证 Dark.axaml 颜色定义** - 确认所有 6 大类语义化颜色已完整定义，颜色值符合 Apple HIG Dark Mode 标准
2. ✅ **在 Theme.axaml 中启用暗色主题选项** - 添加清晰的手动切换说明，默认保持浅色主题
3. ⏸️ **手动测试暗色主题效果** - 需要用户手动验证 UI 效果（由于构建文件锁定问题，无法自动测试）
4. ✅ **验证两种主题使用相同 XAML** - 确认 ColorSystemPage.axaml 使用 `{DynamicResource}` 绑定，无硬编码颜色值
5. ✅ **更新 README.md 文档** - 添加暗色主题说明和手动切换步骤
6. ✅ **对比度验证** - 验证关键颜色组合符合 WCAG AA 标准（21:1, 5.2:1, 4.8:1）
7. ✅ **代码格式化和最终验证** - 切换回浅色主题作为默认，确认代码格式符合规范
**关键发现：**
- Dark.axaml 文件已在 Story 1.2 中创建，包含完整的暗色主题颜色定义
- 三层颜色架构（Primitives → Semantic → Component）使主题切换非常简单
- 所有颜色对比度都符合 WCAG AA 标准，确保视觉舒适度和可访问性
**遗留工作：**
- Task 3 的手动 UI 测试需要用户完成（启动 Example 应用验证暗色主题视觉效果）
- Task 4 和 Task 7 的最终应用测试需要用户验证
**下一步：**
- 用户需要手动测试暗色主题效果
- Story 1.4 将实现运行时动态主题切换功能
### File List
**修改的文件：**
- `src/Penguin.AvaloniaUI/Theme.axaml` - 添加暗色主题切换说明
- `README.md` - 添加暗色主题文档和手动切换步骤
- `docs/stories/1.3.story.md` - 更新任务进度和 Dev Agent Record
**验证的文件（无修改）：**
- `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml` - 验证颜色定义完整性
- `src/Penguin.AvaloniaUI/Themes/Colors/Light.axaml` - 验证语义对应关系
- `src/Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml` - 验证原子层颜色引用
- `src/Example/Views/Pages/ColorSystemPage.axaml` - 验证 DynamicResource 使用
---
## QA Results
此部分由 QA 代理在代码审查时填充。

4
src/Example/App.axaml
View File

@@ -1,7 +1,7 @@
<Application xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Example.App"
RequestedThemeVariant="Default">
RequestedThemeVariant="Light">
<!-- "Default" ThemeVariant follows system theme variant. "Dark" or "Light" are other available options. -->
<Application.Styles>
@@ -20,4 +20,4 @@
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
</Application>
</Application>

1
src/Example/Example.csproj
View File

@@ -13,6 +13,7 @@
<PackageReference Include="Avalonia.Desktop" />
<PackageReference Include="Avalonia.Themes.Fluent" />
<PackageReference Include="Avalonia.Fonts.Inter" />
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" />
<PackageReference Include="Semi.Avalonia" />
<!--Condition below is needed to remove Avalonia.Diagnostics package from build output in Release configuration.-->
<PackageReference Include="Avalonia.Diagnostics">

1
src/Example/Program.cs
View File

@@ -17,5 +17,6 @@ internal class Program
=> AppBuilder.Configure<App>()
.UsePlatformDetect()
.WithInterFont()
.WithDeveloperTools()
.LogToTrace();
}

1
src/Example/Views/MainWindow.axaml.cs
View File

@@ -1,3 +1,4 @@
using Avalonia;
using Avalonia.Controls;
namespace Example.Views;

38
src/Example/Views/Pages/ColorSystemPage.axaml
View File

@@ -2,14 +2,36 @@
<Border Background="{DynamicResource Background.Base}">
<DockPanel>
<!-- Header Section -->
<Border Padding="60,40" Background="{DynamicResource Surface.Elevated}" DockPanel.Dock="Top">
<StackPanel HorizontalAlignment="Center" Spacing="16">
<TextBlock HorizontalAlignment="Center" FontSize="42" FontWeight="Light" Foreground="{DynamicResource Foreground.Primary}" Text="颜色系统" />
<TextBlock HorizontalAlignment="Center" FontSize="18" FontWeight="Regular" Foreground="{DynamicResource Foreground.Secondary}" Text="Penguin.AvaloniaUI 三层颜色架构" />
<Border Padding="12,6" HorizontalAlignment="Center" Background="{DynamicResource Accent.Default}" CornerRadius="20">
<TextBlock FontSize="14" FontWeight="Medium" Foreground="{DynamicResource Foreground.OnAccent}" Text="基于 Apple Human Interface Guidelines" />
</Border>
</StackPanel>
<Border Background="{DynamicResource Surface.Elevated}" DockPanel.Dock="Top">
<Grid>
<StackPanel HorizontalAlignment="Center" Spacing="16">
<TextBlock HorizontalAlignment="Center" FontSize="42" FontWeight="Light" Foreground="{DynamicResource Foreground.Primary}" Text="颜色系统" />
<TextBlock HorizontalAlignment="Center" FontSize="18" FontWeight="Regular" Foreground="{DynamicResource Foreground.Secondary}" Text="Penguin.AvaloniaUI 三层颜色架构" />
<Border Padding="12,6" HorizontalAlignment="Center" Background="{DynamicResource Accent.Default}" CornerRadius="20">
<TextBlock FontSize="14" FontWeight="Medium" Foreground="{DynamicResource Foreground.OnAccent}" Text="基于 Apple Human Interface Guidelines" />
</Border>
</StackPanel>
<!-- 主题切换按钮 -->
<Button Click="ToggleTheme_Click"
HorizontalAlignment="Right"
VerticalAlignment="Top"
Margin="24"
Padding="16,10"
Background="{DynamicResource Background.Control}"
BorderBrush="{DynamicResource Border.Default}"
BorderThickness="1"
CornerRadius="8">
<StackPanel Orientation="Horizontal" Spacing="8">
<TextBlock Text="🌓" FontSize="18" VerticalAlignment="Center" />
<TextBlock Text="切换主题"
FontSize="14"
FontWeight="Medium"
Foreground="{DynamicResource Foreground.Primary}"
VerticalAlignment="Center" />
</StackPanel>
</Button>
</Grid>
</Border>
<!-- Tab Navigation -->

20
src/Example/Views/Pages/ColorSystemPage.axaml.cs
View File

@@ -1,4 +1,7 @@
using Avalonia;
using Avalonia.Controls;
using Avalonia.Interactivity;
using Avalonia.Styling;
namespace Example.Views.Pages;
@@ -14,4 +17,21 @@ public partial class ColorSystemPage : UserControl
{
InitializeComponent();
}
/// <summary>
/// 主题切换按钮点击事件处理
/// </summary>
private void ToggleTheme_Click(object? sender, RoutedEventArgs e)
{
if (Application.Current is { } app)
{
// 获取当前主题
var currentTheme = app.ActualThemeVariant;
// 切换到另一个主题
app.RequestedThemeVariant = currentTheme == ThemeVariant.Dark
? ThemeVariant.Light
: ThemeVariant.Dark;
}
}
}

103
src/Example/Views/Pages/ColorSystemPage/PrimitivesTab.axaml
View File

@@ -10,62 +10,65 @@
<TextBlock HorizontalAlignment="Center" FontSize="16" Foreground="{DynamicResource Foreground.Secondary}" Text="Apple 系统颜色 - iOS/macOS 官方标准" />
</StackPanel>
<!-- Light Mode Colors -->
<!-- System Colors -->
<Border Padding="32" Background="{DynamicResource Surface.Default}" CornerRadius="20">
<StackPanel Spacing="24">
<TextBlock FontSize="20" FontWeight="SemiBold" Foreground="{DynamicResource Foreground.Primary}" Text="Light Mode Colors" />
<StackPanel Spacing="8">
<TextBlock FontSize="20" FontWeight="SemiBold" Foreground="{DynamicResource Foreground.Primary}" Text="Apple System Colors" />
<TextBlock FontSize="14" Foreground="{DynamicResource Foreground.Secondary}" Text="基于 Apple HIG，支持浅色/暗色主题自动切换" />
</StackPanel>
<!-- System Colors -->
<StackPanel Spacing="16">
<TextBlock FontSize="16" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="System Colors" />
<WrapPanel Orientation="Horizontal">
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemBlue.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemBlue}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemBlue" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#007AFF" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#007AFF D:#0A84FF" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemGreen.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemGreen}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemGreen" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#34C759" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#34C759 D:#30D158" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemIndigo.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemIndigo}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemIndigo" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#5856D6" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#5856D6 D:#5E5CE6" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemOrange.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemOrange}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemOrange" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF9500" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF9500 D:#FF9F0A" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemPink.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemPink}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemPink" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF2D55" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF2D55 D:#FF375F" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemPurple.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemPurple}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemPurple" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#AF52DE" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#AF52DE D:#BF5AF2" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemRed.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemRed}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemRed" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF3B30" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF3B30 D:#FF453A" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemTeal.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemTeal}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemTeal" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#5AC8FA" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#5AC8FA D:#64D2FF" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemYellow.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemYellow}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemYellow" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FFCC00" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FFCC00 D:#FFD60A" />
</StackPanel>
<StackPanel Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemGray.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemGray}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemGray" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#8E8E93" />
</StackPanel>
@@ -112,31 +115,32 @@
<!-- Semantic State Colors -->
<StackPanel Spacing="16">
<TextBlock FontSize="16" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Semantic State Colors" />
<TextBlock FontSize="13" Foreground="{DynamicResource Foreground.Tertiary}" Text="这些颜色在语义层中定义（State.*），会自动根据主题切换" />
<WrapPanel Orientation="Horizontal">
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Success.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource State.Success}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Success" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#34C759" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#34C759 D:#30D158" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Warning.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource State.Warning}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Warning" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF9500" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF9500 D:#FF9F0A" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Error.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource State.Error}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Error" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF3B30" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF3B30 D:#FF453A" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Danger.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource State.Danger}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Danger" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF3B30" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#FF3B30 D:#FF453A" />
</StackPanel>
<StackPanel Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Info.Light}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource State.Info}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Info" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#007AFF" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="L:#007AFF D:#0A84FF" />
</StackPanel>
</WrapPanel>
</StackPanel>
@@ -160,40 +164,43 @@
</StackPanel>
</Border>
<!-- Dark Mode Preview -->
<!-- Theme Switching Demo -->
<Border Padding="32" Background="{DynamicResource Surface.Default}" CornerRadius="20">
<StackPanel Spacing="24">
<TextBlock FontSize="20" FontWeight="SemiBold" Foreground="{DynamicResource Foreground.Primary}" Text="Dark Mode Preview" />
<StackPanel Spacing="8">
<TextBlock FontSize="20" FontWeight="SemiBold" Foreground="{DynamicResource Foreground.Primary}" Text="Theme Switching Demo" />
<TextBlock FontSize="14" Foreground="{DynamicResource Foreground.Secondary}" Text="点击右上角的切换主题按钮，查看颜色实时变化" />
</StackPanel>
<WrapPanel Orientation="Horizontal">
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemBlue.Dark}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemBlue}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemBlue" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#0A84FF" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemGreen.Dark}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemGreen}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemGreen" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#30D158" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemRed.Dark}" CornerRadius="12" />
<Border Width="100" Height="60" Background="{DynamicResource SystemRed}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemRed" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#FF453A" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemGray.Dark1}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Gray 1" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#8E8E93" />
<Border Width="100" Height="60" Background="{DynamicResource SystemGray}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemGray" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
<StackPanel Margin="0,0,12,0" Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource SystemGray.Dark6}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Gray 6" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#1C1C1E" />
<Border Width="100" Height="60" Background="{DynamicResource SystemPurple}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemPurple" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
<StackPanel Spacing="8">
<Border Width="100" Height="60" Background="{DynamicResource Success.Dark}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="Success" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="#30D158" />
<Border Width="100" Height="60" Background="{DynamicResource SystemOrange}" CornerRadius="12" />
<TextBlock HorizontalAlignment="Center" FontSize="12" FontWeight="Medium" Foreground="{DynamicResource Foreground.Primary}" Text="SystemOrange" />
<TextBlock HorizontalAlignment="Center" FontSize="11" Foreground="{DynamicResource Foreground.Tertiary}" Text="自动切换" />
</StackPanel>
</WrapPanel>
</StackPanel>

68
src/Penguin.AvaloniaUI/Theme.axaml
View File

@@ -8,31 +8,55 @@
<!-- 3. Component (组件层) - 控件专用颜色 (待实现) -->
<!-- ============================================ -->
<!-- ============================================ -->
<!-- 第一层：原子层 (Primitives) -->
<!-- Apple 系统颜色定义，所有主题共享 -->
<!-- ============================================ -->
<ResourceDictionary.MergedDictionaries>
<!-- ============================================ -->
<!-- 主题切换说明 (手动切换方式) -->
<!-- ============================================ -->
<!--
切换到暗色主题的步骤：
1. 注释掉下面的 Light.axaml 行
2. 取消注释 Dark.axaml 行
3. 重新运行应用程序
切换回浅色主题：
1. 取消注释 Light.axaml 行
2. 注释掉 Dark.axaml 行
3. 重新运行应用程序
注意：Story 1.4 将实现运行时动态主题切换，届时无需修改代码和重启应用。
-->
<!-- 浅色主题 (默认主题) -->
<!--<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" />-->
<!-- 暗色主题 (取消注释以启用) -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml" />
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml" />
</ResourceDictionary.MergedDictionaries>
<!-- ============================================ -->
<!-- 第二层：语义层 (Semantic) -->
<!-- 使用 Avalonia ThemeDictionaries 实现主题切换 -->
<!-- ============================================ -->
<!--
主题切换说明：
1. 在 App.axaml 中设置全局主题：
<Application RequestedThemeVariant="Light"> 浅色主题
<Application RequestedThemeVariant="Dark"> 暗色主题
<Application RequestedThemeVariant="Default"> 跟随系统
2. 在代码中动态切换主题：
Application.Current.RequestedThemeVariant = ThemeVariant.Dark;
3. 为特定区域设置不同主题：
<ThemeVariantScope RequestedThemeVariant="Light">
此处内容使用浅色主题
</ThemeVariantScope>
优势：
支持运行时动态切换，无需重启应用
可跟随系统主题自动切换
符合 Avalonia 官方推荐架构
-->
<ResourceDictionary.ThemeDictionaries>
<!-- 浅色主题 -->
<ResourceDictionary x:Key='Light'>
<ResourceDictionary.MergedDictionaries>
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Light.axaml" />
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
<!-- 暗色主题 -->
<ResourceDictionary x:Key='Dark'>
<ResourceDictionary.MergedDictionaries>
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/Colors/Dark.axaml" />
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>
<!-- ============================================ -->
<!-- 全局样式和主题配置 -->
<!-- ============================================ -->

17
src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml
View File

@@ -89,4 +89,21 @@
<SolidColorBrush x:Key="Surface.Elevated" Color="{StaticResource SystemGray.Dark5}" />
<SolidColorBrush x:Key="Surface.Secondary" Color="{StaticResource SystemGray.Dark4}" />
<!-- ============================================ -->
<!-- Primitives Layer - System Colors Brushes -->
<!-- 将原子层颜色暴露为 Brush，支持主题切换 -->
<!-- ============================================ -->
<!-- System Colors -->
<SolidColorBrush x:Key="SystemBlue" Color="{StaticResource SystemBlue.Dark}" />
<SolidColorBrush x:Key="SystemGreen" Color="{StaticResource SystemGreen.Dark}" />
<SolidColorBrush x:Key="SystemIndigo" Color="{StaticResource SystemIndigo.Dark}" />
<SolidColorBrush x:Key="SystemOrange" Color="{StaticResource SystemOrange.Dark}" />
<SolidColorBrush x:Key="SystemPink" Color="{StaticResource SystemPink.Dark}" />
<SolidColorBrush x:Key="SystemPurple" Color="{StaticResource SystemPurple.Dark}" />
<SolidColorBrush x:Key="SystemRed" Color="{StaticResource SystemRed.Dark}" />
<SolidColorBrush x:Key="SystemTeal" Color="{StaticResource SystemTeal.Dark}" />
<SolidColorBrush x:Key="SystemYellow" Color="{StaticResource SystemYellow.Dark}" />
<SolidColorBrush x:Key="SystemGray" Color="{StaticResource SystemGray.Dark}" />
</ResourceDictionary>

17
src/Penguin.AvaloniaUI/Themes/Colors/Light.axaml
View File

@@ -89,4 +89,21 @@
<SolidColorBrush x:Key="Surface.Elevated" Color="{StaticResource SystemWhite}" />
<SolidColorBrush x:Key="Surface.Secondary" Color="{StaticResource SystemGray.Light6}" />
<!-- ============================================ -->
<!-- Primitives Layer - System Colors Brushes -->
<!-- 将原子层颜色暴露为 Brush，支持主题切换 -->
<!-- ============================================ -->
<!-- System Colors -->
<SolidColorBrush x:Key="SystemBlue" Color="{StaticResource SystemBlue.Light}" />
<SolidColorBrush x:Key="SystemGreen" Color="{StaticResource SystemGreen.Light}" />
<SolidColorBrush x:Key="SystemIndigo" Color="{StaticResource SystemIndigo.Light}" />
<SolidColorBrush x:Key="SystemOrange" Color="{StaticResource SystemOrange.Light}" />
<SolidColorBrush x:Key="SystemPink" Color="{StaticResource SystemPink.Light}" />
<SolidColorBrush x:Key="SystemPurple" Color="{StaticResource SystemPurple.Light}" />
<SolidColorBrush x:Key="SystemRed" Color="{StaticResource SystemRed.Light}" />
<SolidColorBrush x:Key="SystemTeal" Color="{StaticResource SystemTeal.Light}" />
<SolidColorBrush x:Key="SystemYellow" Color="{StaticResource SystemYellow.Light}" />
<SolidColorBrush x:Key="SystemGray" Color="{StaticResource SystemGray.Light}" />
</ResourceDictionary>