# 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 的头脑风暴会议成果。*