diff --git a/.gitignore b/.gitignore index 7d81d66..cea7839 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ /bmad .claude/commands/bmad docs-ai/ +.bmad-core/ + ## Ignore Visual Studio temporary files, build results, and ## files generated by popular Visual Studio add-ons. ## diff --git a/docs/brainstorming-session-results.md b/docs/brainstorming-session-results.md new file mode 100644 index 0000000..757adb1 --- /dev/null +++ b/docs/brainstorming-session-results.md @@ -0,0 +1,487 @@ +# Brainstorming Session Results + +**Session Date:** 2025-10-15 +**Facilitator:** Business Analyst Mary +**Participant:** Project Lead + +--- + +## Executive Summary + +**Topic:** Avalonia UI 库开发 - 基于 Semi 样式库的业务场景控件库 + +**Session Goals:** + +- 明确项目战略定位和核心价值 +- 系统化梳理控件清单和优先级 +- 识别技术挑战和解决方案 +- 制定渐进式开发路线图 + +**Techniques Used:** + +1. First Principles Thinking（第一性原理） +2. Morphological Analysis（形态分析） +3. SCAMPER Method（SCAMPER 方法） +4. What If Scenarios（假设情景） + +**Total Ideas Generated:** 50+ + +### Key Themes Identified: + +- **市场定位**：填补"业务场景集成控件"的市场空白 +- **技术栈**：.NET 8+ / Avalonia 最新版 / ReactiveUI / AOT / 苹果颜色系统 +- **开发策略**：自顶向下、MVP 优先、渐进式替换 +- **目标场景**：上位机开发 + AI 桌面应用 + +--- + +## Technique Sessions + +### First Principles Thinking（第一性原理）- 40 分钟 + +**Description:** 回归基本原理，重新思考项目的核心价值和根本问题 + +#### Ideas Generated: + +1. **核心问题识别** + + - 市面上的 UI 库都是"基础控件库"（Button、TextBox 等通用组件） + - 真正加速开发的应该是"业务场景集成控件"（PropertyGrid、LoggingControl 等） + - 每个开发者业务需求不同，所以没有人做这些集成控件 + - 对于固定场景（上位机 + AI 桌面），可以打造专用工具集 +2. **业务控件的共同特征** + + - 与数据模型耦合（追求"合适的通用性"而非"极致通用性"） + - 由多个基础控件组合而成，但代表通用业务场景 + - 例如：PropertyGrid = 自动化 UI 生成；LoggingControl = 领域数据的完整交互 +3. **市场空白的原因** + + - 商业逻辑：开源作者倾向做"影响面广"的基础控件 + - 需求差异：每个人的业务定义不同 + - 技术障碍：AOT、反射限制等 + - 对于固定场景（上位机 + AI 桌面），这些限制不存在 + +#### Insights Discovered: + +- 项目定位：私有生产力工具 > 开源通用库 +- 允许高度场景化，不追求过度通用性 +- PropertyGrid 可以只支持常用类型，不需要覆盖所有边缘情况 + +#### Notable Connections: + +- Source Generator 可以解决 AOT 反射限制 +- 对接系统接口（ILogger 等）而非重新发明轮子 + +--- + +### Morphological Analysis（形态分析）- 25 分钟 + +**Description:** 系统化识别项目维度，探索不同选项的组合 + +#### Ideas Generated: + +1. **控件数据模式维度** + + - 选择：带数据模型的 UserControl（自包含业务单元） + - 允许 CustomControl 和 UserControl 混合存在 +2. **主题系统维度** + + - 选择：多主题，与 Avalonia 原生集成 + - 采用苹果颜色系统（语义化、自适应暗色模式） +3. **样式定制维度** + + - 选择：Style Class（通过 ClassName 切换主题） + - 利用 Avalonia 的样式扩展特性 +4. **交互模式维度** + + - 选择：ReactiveUI 作为核心交互数据流 + - Command / Reactive / Event 混合使用 + +#### Insights Discovered: + +- 控件类型不需要过度分类，实用性优先 +- 抽象维度对固定场景项目价值有限 +- 应聚焦具体控件清单和功能特性 + +--- + +### SCAMPER Method（SCAMPER 方法）- 30 分钟 + +**Description:** 基于 Semi/Ursa 进行系统化创新改造 + +#### Ideas Generated: + +**S - Substitute（替代）:** + +1. 颜色系统 → 苹果颜色系统（统一规范、语义化） +2. 传统样式 → Style Class 系统（灵活主题切换） + +**C - Combine（组合）:** + +1. 战略调整：只用 Semi（样式库），不用 Ursa（控件库） +2. 部署方式：NuGet 安装依赖，逐步替换而非 Copy 源码 + +**A - Adapt（调整适配）:** + +1. Semi/Ursa 已原生支持 AOT，无需额外适配 +2. ReactiveUI 只需适配自己的代码，标准库无需特殊集成 + +**M - Modify/Magnify（修改/放大）:** + +1. LoggingControl 需要处理百万级日志流（唯一性能焦点） +2. 虚拟化 + 过滤策略 + +**E - Eliminate（消除简化）:** + +1. Semi 中可删除大量不需要的样式代码 +2. Ursa 完全不使用，减少依赖 + +**R - Reverse/Rearrange（逆向/重组）:** + +1. **开发顺序逆转**：自顶向下，先定义复杂控件，再分解基础控件 +2. **控件依赖设计**：先指定基础控件目标，适时插入复杂控件 + +#### Insights Discovered: + +- 自顶向下避免"不知道要做什么基础控件"的困境 +- 需求驱动：只做真正用到的 +- 符合"快速渐进开发"目标 + +--- + +### What If Scenarios（假设情景）- 25 分钟 + +**Description:** 通过挑衅性情景探索边界和潜在问题 + +#### Ideas Generated: + +**情景：极端性能挑战（百万级日志流）** + +- 虚拟化性能应该可以支撑 +- 过滤策略：每次只显示部分，上下卸载 +- 需要编写性能测试 + +**情景：跨平台扩展（桌面 + Pad）** + +- 当前场景：Windows 桌面 + Linux Pad（无多点触控） +- 通过 ClassName 切换桌面/Pad 模式（核心显示不变） + +**情景：开源化路径** + +- 策略：先私有实现大量功能，再开源 +- 不影响当前设计决策 + +**情景：AOT 兼容性踩坑** + +- PropertyGrid 如果 AOT 不可用，可以妥协 +- 其他控件必须支持 AOT +- Source Generator 作为主要解决方案 + +**情景：依赖替换风险** + +- 最差情况：不替换，可接受 +- 策略：逐步替换，可回退 + +**情景：团队协作与学习曲线** + +- 技术栈统一：ReactiveUI 为唯一方案 +- 不会的就学，不提供多套 API + +**情景：快速迭代 vs 质量** + +- 策略：MVP + 迭代开发 +- 控件库天然适合增量开发（每个控件相对独立） +- 慢慢替换到现有项目，降低风险 + +#### Insights Discovered: + +- 职责边界明确：UI 库只负责展示，不管数据持久化 +- 风险可控：允许妥协（PropertyGrid AOT）、允许不替换（Semi） +- MVP + 渐进式验证设计合理性 + +--- + +## Idea Categorization + +### Immediate Opportunities + +*Ideas ready to implement now* + +#### 1. **依赖策略：只用 Semi，不用 Ursa** + +- Description: 安装 Semi NuGet 包作为样式基础，删除 Ursa 依赖 +- Why immediate: 简化依赖，减少不必要的代码 +- Resources needed: 评估 Semi 样式完整性，确定需要自定义的部分 + +#### 2. **采用苹果颜色系统** + +- Description: 建立语义化颜色规范（primary, secondary, accent, success, warning, error 等） +- Why immediate: 是所有控件样式的基础，必须先定义 +- Resources needed: 研究 Apple Human Interface Guidelines 颜色系统，制定规范文档 + +#### 3. **开发顺序：自顶向下** + +- Description: 先定义复杂控件需求，再从中分解基础控件 +- Why immediate: 避免过度设计，需求驱动开发 +- Resources needed: 完成控件清单优先级排序 + +#### 4. **MVP 第一阶段：PropertyGrid** + +- Description: 最高优先级控件，自动从数据模型生成 UI +- Why immediate: 是最常用、价值最高的控件 +- Resources needed: Source Generator 技术预研（AOT 支持） + +#### 5. **建立项目结构** + +- Description: 设置 .NET 8+、Avalonia 最新版、ReactiveUI 的项目模板 +- Why immediate: 基础设施 +- Resources needed: 项目脚手架、CI/CD 配置 + +--- + +### Future Innovations + +*Ideas requiring development/research* + +#### 1. **控件开发路线图（分阶段）** + +- Description: 按优先级逐步实现完整控件库 +- Development needed: + - Phase 1: PropertyGrid + - Phase 2: UserGuide 系列控件 + - Phase 3: TextEditor + - Phase 4: MarkdownRender + - Phase 5: ImageEx + - Phase 6: LoggingControl + - Phase 7: Icon + 2xN Layout + - Phase 8: CodeEditor + - Phase 9: PathSelector（接口 + 实现） +- Timeline estimate: 6-12 个月（根据实际项目需求调整） + +#### 2. **Chart 控件项目** + +- Description: 调研 Avalonia 现有 Chart 库，进行二次开发 +- Development needed: 独立项目，包含在当前大项目下 +- Timeline estimate: 单独规划 + +#### 3. **布局/容器优化系列** + +- Description: 专注性能优化的布局控件 +- Development needed: + - 先实现 2xN Layout（PropertyGrid 专用） + - 后续根据需要扩展其他布局 +- Timeline estimate: 按需迭代 + +#### 4. **Avalonia 工具类库** + +- Description: 开发效率提升工具集 +- Development needed: + - VisualTreeHelper/LogicalTreeHelper（视觉树/逻辑树查找） + - ControlLocator（定位控件） + - AOT Binding Helpers（AOT 绑定辅助） + - ThemeManager Commands（主题切换命令） + - LocalizationManager Commands（语言切换命令） + - 其他工具类按需添加 +- Timeline estimate: 伴随控件开发逐步完善 + +#### 5. **桌面/Pad 双模式支持** + +- Description: 通过 ClassName 切换不同平台的样式微调 +- Development needed: 样式定义、响应式布局策略 +- Timeline estimate: 第二阶段 + +#### 6. **开源准备** + +- Description: 在私有功能完善后，准备开源 +- Development needed: 文档、示例、License、贡献指南 +- Timeline estimate: 长期目标 + +--- + +### Moonshots + +*Ambitious, transformative concepts* + +#### 1. **LoggingControl 百万级日志流处理** + +- Description: 支持每秒数万条日志的实时显示和过滤 +- Transformative potential: 成为 Avalonia 生态中性能最强的日志控件 +- Challenges to overcome: + - 虚拟化渲染优化 + - 内存管理策略 + - 高效的过滤算法 + - 性能测试和压力测试 + +#### 2. **PropertyGrid 的 AOT 完全支持** + +- Description: 在 AOT 模式下实现完整的动态 UI 生成 +- Transformative potential: 证明 Source Generator 可以完美替代反射 +- Challenges to overcome: + - Source Generator 复杂度 + - 类型推断和代码生成 + - 编译时元数据收集 + - 可能需要妥协某些高级特性 + +#### 3. **渐进式替换现有项目** + +- Description: 在不影响稳定性的前提下，将新控件逐步替换到生产项目 +- Transformative potential: 在真实场景中验证控件设计，快速迭代 +- Challenges to overcome: + - 兼容性保障 + - 回退机制 + - 性能对比验证 + - 团队培训 + +--- + +### Insights & Learnings + +*Key realizations from the session* + +- **战略定位清晰**: 私有生产力工具定位允许高度场景化，不追求过度通用性，可以大胆做取舍 +- **需求驱动设计**: 上位机 + AI 桌面应用的固定场景，填补"业务场景集成控件"的市场空白 +- **技术栈统一**: .NET 8+ / Avalonia 最新版 / ReactiveUI / AOT，不向后兼容，换取开发效率 +- **职责边界明确**: UI 库只负责展示，不管数据持久化；对接系统接口（ILogger 等），不重新发明轮子 +- **快速迭代哲学**: 功能优先，测试缓缓（除非必要如性能测试）；MVP + 渐进式开发，在真实项目中验证 +- **自顶向下优势**: 先定义复杂控件，再分解基础控件，避免过度设计，需求驱动 +- **风险可控策略**: PropertyGrid 可以妥协 AOT；依赖替换最差不替换；控件独立可回退 +- **苹果颜色系统的价值**: 语义化颜色、自适应暗色模式、动态颜色支持、设计一致性 +- **ReactiveUI 的核心优势**: 统一的数据流处理模型、天然支持异步操作、便于组合复杂交互逻辑 + +--- + +## Action Planning + +### Top 3 Priority Ideas + +#### #1 Priority: 建立项目基础设施和颜色系统 + +**Rationale:** + +- 所有后续开发的基础 +- 颜色系统是样式定义的核心 +- 项目结构影响长期可维护性 + +**Next steps:** + +1. 创建 .NET 8+ 解决方案，配置 Avalonia 最新版 + ReactiveUI +2. 安装 Semi NuGet 包，评估样式完整性 +3. 制定苹果颜色系统规范文档（语义颜色、浅色/深色主题） +4. 建立 Style Class 命名规范 +5. 搭建 CI/CD 基础（构建、测试、AOT 兼容性检查） + +**Resources needed:** + +- Apple Human Interface Guidelines 文档 +- Semi 源码分析 +- Avalonia 样式系统文档 + +**Timeline:** 1-2 周 + +--- + +#### #2 Priority: PropertyGrid MVP 开发 + +**Rationale:** + +- 最高价值控件 +- 验证自顶向下开发策略 +- 验证 AOT + Source Generator 技术路线 + +**Next steps:** + +1. 定义 PropertyGrid 的核心功能范围（MVP） + - 支持的属性类型（string, int, bool, enum, 等） + - 基础布局（2xN Layout） + - 数据绑定方式 +2. 设计 Source Generator 方案（AOT 支持） +3. 实现 2xN Layout 基础控件 +4. 开发 PropertyGrid 核心逻辑 +5. 在一个小型测试项目中验证 + +**Resources needed:** + +- Source Generator 技术预研 +- Roslyn API 文档 +- 测试项目（上位机场景） + +**Timeline:** 3-4 周 + +--- + +#### #3 Priority: 制定完整控件开发路线图 + +**Rationale:** + +- 明确长期目标和里程碑 +- 合理分配开发资源 +- 识别控件间的依赖关系 + +**Next steps:** + +1. 完成完整控件清单（包括工具类） +2. 为每个控件制定功能规格（简要） +3. 识别控件间的依赖关系（例如：UserGuide 依赖 Overlay） +4. 制定分阶段开发计划（6 个月、1 年、长期） +5. 定义 MVP 范围和"可选特性" +6. 建立控件开发模板和最佳实践文档 + +**Resources needed:** + +- 现有项目需求分析 +- 竞品控件库调研（Semi、Ursa、Material Design） + +**Timeline:** 1 周 + +--- + +## Reflection & Follow-up + +### What Worked Well + +- 第一性原理帮助明确了项目的核心价值和市场定位 +- SCAMPER 方法发现了"自顶向下开发"这一关键策略调整 +- What If Scenarios 识别了潜在风险和应对方案 +- 讨论过程中不断澄清边界，避免了过度设计 + +### Areas for Further Exploration + +- **Source Generator 技术深度**: 需要专门的技术预研，验证 PropertyGrid 的 AOT 可行性 +- **性能基准测试**: LoggingControl 的百万级日志场景需要建立性能基准 +- **Semi 样式分析**: 详细分析 Semi 的样式结构，确定哪些需要保留、哪些需要删除 +- **控件功能规格**: 每个控件需要更详细的功能设计文档 +- **跨平台测试**: 验证 Windows 桌面和 Linux Pad 的样式差异 + +### Recommended Follow-up Techniques + +- **SWOT 分析**: 评估项目的优势、劣势、机会、威胁 +- **用户故事映射**: 从用户角度设计控件功能 +- **技术尖峰（Spike）**: 对 Source Generator、LoggingControl 性能等关键技术进行原型验证 + +### Questions That Emerged + +- Source Generator 能否支持 PropertyGrid 的所有预期功能？ +- Semi 的样式系统如何与苹果颜色系统集成？ +- LoggingControl 的虚拟化策略具体实现方案？ +- 如何设计控件的可扩展性（模板、样式、行为）？ +- Chart 控件选择哪个现有库进行二次开发？ +- 如何平衡"快速开发"和"代码质量"？ + +### Next Session Planning + +- **Suggested topics:** + + - PropertyGrid 详细设计会议 + - Source Generator 技术预研总结 + - 苹果颜色系统规范制定 + - 控件模板和最佳实践 +- **Recommended timeframe:** PropertyGrid MVP 完成后（4-6 周后） +- **Preparation needed:** + + - 完成项目基础设施搭建 + - 完成 Source Generator 技术预研 + - 收集现有项目中的实际使用场景 + +--- + +*Session facilitated using the BMAD-METHOD™ brainstorming framework* diff --git a/docs/brief.md b/docs/brief.md new file mode 100644 index 0000000..d4a2ecc --- /dev/null +++ b/docs/brief.md @@ -0,0 +1,671 @@ +# 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 的头脑风暴会议成果。* diff --git a/docs/prd.md b/docs/prd.md new file mode 100644 index 0000000..6ee915a --- /dev/null +++ b/docs/prd.md @@ -0,0 +1,1129 @@ +# 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:** 系统应提供基于苹果颜色系统的语义化颜色定义（primary, secondary, success, warning, error, background, surface 等），支持 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** 定义基于苹果颜色系统的语义化颜色，并实现浅色主题， +**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。 + +#### Acceptance Criteria + +1. 在 `Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义： + - 定义语义化颜色资源（ResourceDictionary），包含至少以下颜色： + - Primary（主色） + - Secondary（次要色） + - Success（成功） + - Warning（警告） + - Error（错误） + - Background（背景） + - Surface（表面） + - TextPrimary（主要文本） + - TextSecondary（次要文本） + +2. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`（浅色主题资源字典）： + - 为每个语义化颜色定义浅色主题的具体色值 + - 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1） + +3. 将浅色主题应用到 Example 应用： + - 在 `App.axaml` 中引用 `LightTheme.axaml` + - 示例窗口的背景色使用 `Background` 颜色 + - TextBlock 的文本色使用 `TextPrimary` 颜色 + +4. 在 Example 中添加一个演示页面，展示所有语义化颜色： + - 显示每个颜色的名称和色块（使用 Border 或 Rectangle） + - 色块大小：至少 100x50 像素 + +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. 支持基础富文本格式： + - **粗体**: 使用 `` 标签或支持 Markdown 的 `**text**` 语法（选其一） + - **斜体**: 使用 `` 标签或 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** diff --git a/docs/prd/checklist-results-report.md b/docs/prd/checklist-results-report.md new file mode 100644 index 0000000..f078f9c --- /dev/null +++ b/docs/prd/checklist-results-report.md @@ -0,0 +1,57 @@ +# 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 小时） + +--- + \ No newline at end of file diff --git a/docs/prd/epic-1-details-foundation-theme-infrastructure.md b/docs/prd/epic-1-details-foundation-theme-infrastructure.md new file mode 100644 index 0000000..08b7a5a --- /dev/null +++ b/docs/prd/epic-1-details-foundation-theme-infrastructure.md @@ -0,0 +1,145 @@ +# 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** 定义基于苹果颜色系统的语义化颜色，并实现浅色主题， +**so that** 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。 + +#### Acceptance Criteria + +1. 在 `Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义： + - 定义语义化颜色资源（ResourceDictionary），包含至少以下颜色： + - Primary（主色） + - Secondary（次要色） + - Success（成功） + - Warning（警告） + - Error（错误） + - Background（背景） + - Surface（表面） + - TextPrimary（主要文本） + - TextSecondary（次要文本） + +2. 在 `Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`（浅色主题资源字典）： + - 为每个语义化颜色定义浅色主题的具体色值 + - 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1） + +3. 将浅色主题应用到 Example 应用： + - 在 `App.axaml` 中引用 `LightTheme.axaml` + - 示例窗口的背景色使用 `Background` 颜色 + - TextBlock 的文本色使用 `TextPrimary` 颜色 + +4. 在 Example 中添加一个演示页面，展示所有语义化颜色： + - 显示每个颜色的名称和色块（使用 Border 或 Rectangle） + - 色块大小：至少 100x50 像素 + +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），验证主题切换对不同控件的影响 + +--- + \ No newline at end of file diff --git a/docs/prd/epic-2-details-propertygrid-auto-generated-configuration-ui.md b/docs/prd/epic-2-details-propertygrid-auto-generated-configuration-ui.md new file mode 100644 index 0000000..13f0b0d --- /dev/null +++ b/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 + - 已知限制（如暂不支持嵌套对象） + +--- + \ No newline at end of file diff --git a/docs/prd/epic-3-details-userguide-onboarding-user-assistance.md b/docs/prd/epic-3-details-userguide-onboarding-user-assistance.md new file mode 100644 index 0000000..f1e04b4 --- /dev/null +++ b/docs/prd/epic-3-details-userguide-onboarding-user-assistance.md @@ -0,0 +1,265 @@ +# 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. 支持基础富文本格式： + - **粗体**: 使用 `` 标签或支持 Markdown 的 `**text**` 语法（选其一） + - **斜体**: 使用 `` 标签或 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 提交记录清晰 + +--- + \ No newline at end of file diff --git a/docs/prd/epic-list.md b/docs/prd/epic-list.md new file mode 100644 index 0000000..7d410b4 --- /dev/null +++ b/docs/prd/epic-list.md @@ -0,0 +1,16 @@ +# 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 遮罩，交付完整的新手引导和应用内帮助系统 + +--- + \ No newline at end of file diff --git a/docs/prd/goals-and-background-context.md b/docs/prd/goals-and-background-context.md new file mode 100644 index 0000000..7e7993a --- /dev/null +++ b/docs/prd/goals-and-background-context.md @@ -0,0 +1,27 @@ +# 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 | + +--- + \ No newline at end of file diff --git a/docs/prd/index.md b/docs/prd/index.md new file mode 100644 index 0000000..f59a74e --- /dev/null +++ b/docs/prd/index.md @@ -0,0 +1,15 @@ +# Penguin.AvaloniaUI Product Requirements Document (PRD) + +## Table of Contents + +- [Penguin.AvaloniaUI Product Requirements Document (PRD)](#table-of-contents) + - [Goals and Background Context](#goals-and-background-context) + - [Requirements](#requirements) + - [User Interface Design Goals](#user-interface-design-goals) + - [Technical Assumptions](#technical-assumptions) + - [Epic List](#epic-list) + - [Epic 1 Details: Foundation & Theme Infrastructure](#epic-1-details-foundation-theme-infrastructure) + - [Epic 2 Details: PropertyGrid - Auto-Generated Configuration UI](#epic-2-details-propertygrid-auto-generated-configuration-ui) + - [Epic 3 Details: UserGuide - Onboarding & User Assistance](#epic-3-details-userguide-onboarding-user-assistance) + - [Checklist Results Report](#checklist-results-report) + - [Next Steps](#next-steps) diff --git a/docs/prd/next-steps.md b/docs/prd/next-steps.md new file mode 100644 index 0000000..56a0ad9 --- /dev/null +++ b/docs/prd/next-steps.md @@ -0,0 +1,102 @@ +# 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** diff --git a/docs/prd/requirements.md b/docs/prd/requirements.md new file mode 100644 index 0000000..1f32f6d --- /dev/null +++ b/docs/prd/requirements.md @@ -0,0 +1,54 @@ +# Requirements + +### Functional Requirements + +**FR1:** 系统应提供基于苹果颜色系统的语义化颜色定义（primary, secondary, success, warning, error, background, surface 等），支持 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 控件开发中的快速入门文档和代码示例，降低团队学习成本 + +--- + \ No newline at end of file diff --git a/docs/prd/technical-assumptions.md b/docs/prd/technical-assumptions.md new file mode 100644 index 0000000..1dacdcf --- /dev/null +++ b/docs/prd/technical-assumptions.md @@ -0,0 +1,118 @@ +# 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 只定义目标字体族 + +--- + \ No newline at end of file diff --git a/docs/prd/user-interface-design-goals.md b/docs/prd/user-interface-design-goals.md new file mode 100644 index 0000000..5cd3792 --- /dev/null +++ b/docs/prd/user-interface-design-goals.md @@ -0,0 +1,108 @@ +# 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 场景） +- 不支持：多点触控手势 + +--- + \ No newline at end of file