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

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：提高代码复用性，避免深层继承带来的维护问题

5.5 KiB Raw Blame History Unescape Escape