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

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

---