docs: brainstorm,brief and prd

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

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