ui/docs/prd.md

# Penguin.AvaloniaUI Product Requirements Document (PRD)

**Project Name:** Penguin.AvaloniaUI
**Version:** 1.0
**Date:** 2025-10-15
**Status:** Ready for Architecture
**PRD Completeness:** 88%

---

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

---

## Requirements

### Functional Requirements

**FR1:** 系统应提供基于苹果颜色系统的三层架构颜色定义（Primitives → Semantic → Component），包含完整的 Apple 官方色值，支持 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 控件开发中的快速入门文档和代码示例，降低团队学习成本

---

## 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 场景）
- 不支持：多点触控手势

---

## 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 只定义目标字体族

---

## 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 遮罩，交付完整的新手引导和应用内帮助系统

---

## 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** 实现基于苹果颜色系统的三层架构颜色系统（Primitives → Semantic → Component），并完成浅色主题，
**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。

#### Acceptance Criteria

1. 在 `Penguin.AvaloniaUI/Themes/Colors/` 下实现三层颜色架构：
   - **Primitives.axaml**（原子层）：定义 Apple 官方系统颜色的 Color 资源
   - **Light.axaml**（语义层）：定义浅色主题的语义化颜色（Background.*, Foreground.*, Border.*, Accent.*, State.*, Surface.*）
   - **Theme.axaml**（主题入口）：统一的主题加载入口，默认加载 Light.axaml

2. 实现完整的语义化颜色体系（6 大类）：
   - **Background**：Base, Layer1, Layer2, Layer3, Control, Overlay
   - **Foreground**：Primary, Secondary, Tertiary, Disabled, OnAccent, Link
   - **Border**：Default, Strong, Subtle, Accent
   - **Accent**：Default, Hover, Pressed, Disabled
   - **State**：Success, Warning, Error, Danger, Info
   - **Surface**：Default, Elevated, Secondary

3. 将浅色主题应用到 Example 应用：
   - 在 `App.axaml` 中引用 `Theme.axaml`
   - 示例窗口的背景色使用 `{DynamicResource Background.Base}`
   - TextBlock 的文本色使用 `{DynamicResource Foreground.Primary}`

4. 在 Example 中添加一个演示页面，展示所有语义化颜色：
   - 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
   - 色块大小：至少 100x50 像素
   - 按类别分组展示 6 大类颜色

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），验证主题切换对不同控件的影响

---

## 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
   - 已知限制（如暂不支持嵌套对象）

---

## 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 提交记录清晰

---

## 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 小时）

---

## 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**