chuan/ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: brainstorm,brief and prd

Browse Source
This commit is contained in:
chuan
2025-10-15 23:40:13 +08:00
parent 28e620573c
commit 6b4c227d3c
15 changed files with 3423 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

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

487
docs/brainstorming-session-results.md Normal file
View File

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

671
docs/brief.md Normal file
View File

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

1129
docs/prd.md Normal file
View File

File diff suppressed because it is too large Load Diff

57
docs/prd/checklist-results-report.md Normal file
View File

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

145
docs/prd/epic-1-details-foundation-theme-infrastructure.md Normal file
View File

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

227
docs/prd/epic-2-details-propertygrid-auto-generated-configuration-ui.md Normal file
View File

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

265
docs/prd/epic-3-details-userguide-onboarding-user-assistance.md Normal file
View File

@@ -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. 支持基础富文本格式：
- **粗体**: 使用 `<Bold>` 标签或支持 Markdown 的 `**text**` 语法（选其一）
- **斜体**: 使用 `<Italic>` 标签或 Markdown 的 `*text*` 语法
- **换行**: 使用 `\n` 或自动换行
- 不支持链接、图片等复杂格式（符合 YAGNI 原则）
3. RichTooltip 应响应主题系统：
- 背景色使用 `Surface` 或 `Background`
- 文本颜色使用 `TextPrimary`
- 边框颜色使用 `Primary` 或 `Secondary`
4. 提供简单的 API 设置内容：
- 接受纯文本（自动解析格式标记）
- 或接受 `TextBlock`（手动设置格式）
5. 在 Example 中创建测试页面：
- 几个按钮，鼠标悬停时显示 RichTooltip
- 测试粗体、斜体、换行的组合效果
- 示例文本："**注意**: 这是一个重要的功能提示。\n请仔细阅读。"
6. RichTooltip 的显示位置应智能调整：
- 默认显示在目标控件下方
- 如果空间不足，自动调整到上方或左右侧
7. RichTooltip 的最大宽度应限制（如 300px），超出自动换行
---
### Story 3.3: 实现 UserGuide 引导流程数据模型和步骤管理
**As a** 控件库开发者，
**I want** 定义 UserGuide 的数据模型和步骤管理逻辑，
**so that** 开发者可以配置多步引导流程，UserGuide 控件可以管理步骤的流转。
#### Acceptance Criteria
1. 在 `Penguin.AvaloniaUI/Controls/UserGuide/` 下创建以下类：
- `UserGuide.cs`: UserGuide 主控件类
- `GuideStep.cs`: 表示单个引导步骤的数据模型，包含：
- `TargetControl`: 引导目标控件（Control 类型）
- `Title`: 步骤标题（string）
- `Content`: 步骤内容/提示文本（string，支持基础富文本）
- `Position`: 提示框相对于目标控件的位置（枚举：Bottom、Top、Left、Right）
- `Order`: 步骤顺序（int）
2. UserGuide 提供 `Steps` 属性（集合）：
- 接受 `GuideStep` 列表
- 支持在 XAML 或代码中配置
3. UserGuide 提供步骤管理功能：
- `CurrentStepIndex`: 当前步骤索引（int）
- `NextStepCommand`: 前进到下一步
- `PreviousStepCommand`: 返回上一步
- `SkipCommand`: 跳过引导
- `FinishCommand`: 完成引导
4. 步骤流转逻辑：
- 初始状态：CurrentStepIndex = 0（第一步）
- NextStep: CurrentStepIndex + 1，如果是最后一步则触发 Finish
- PreviousStep: CurrentStepIndex - 1，如果是第一步则禁用
- Skip/Finish: 隐藏 UserGuide，触发完成事件
5. 创建单元测试，验证步骤管理逻辑：
- 测试 NextStep、PreviousStep 的边界条件
- 测试步骤按 Order 排序
6. 在 Example 中创建测试页面：
- 定义包含 3-5 个 GuideStep 的引导流程
- 使用调试输出或 TextBlock 显示当前步骤信息（暂时不渲染 UI）
- 提供按钮手动触发 NextStep、PreviousStep，验证逻辑正确
---
### Story 3.4: 实现 UserGuide UI 呈现和引导交互
**As a** 应用用户，
**I want** 看到清晰的引导提示框，并通过"上一步"、"下一步"、"跳过"按钮控制引导流程，
**so that** 我可以快速了解应用的核心功能，而不会感到困惑。
#### Acceptance Criteria
1. UserGuide 开始引导时：
- 显示 Overlay 遮罩，遮挡除当前目标控件外的其他区域
- 在目标控件附近显示引导提示框（根据 GuideStep.Position）
2. 引导提示框的内容：
- 显示步骤标题（GuideStep.Title），使用稍大的字体或加粗
- 显示步骤内容（GuideStep.Content），支持基础富文本（调用 RichTooltip 逻辑）
- 显示步骤进度（如 "2/5"）
3. 引导提示框的按钮：
- "上一步"按钮（如果不是第一步）
- "下一步"按钮（如果不是最后一步）或"完成"按钮（如果是最后一步）
- "跳过"按钮（所有步骤都显示）
- 按钮绑定到 UserGuide 的 Command
4. 引导提示框应响应主题系统：
- 背景色使用 `Surface` 并带有阴影效果
- 按钮使用 `Primary` 颜色（"下一步"/"完成"）和 `Secondary` 颜色（"上一步"/"跳过"）
5. 步骤切换动画（可选）：
- 切换步骤时，提示框有淡入淡出或平移动画（200ms）
6. 在 Example 中创建完整的 UserGuide 演示：
- 定义一个包含 5 个步骤的引导流程
- 目标控件为页面上的不同按钮或区域
- 测试步骤：用户可以顺畅地前进、后退、跳过、完成引导
7. UserGuide 完成后，应触发事件或回调：
- 开发者可以监听完成事件，执行后续逻辑（如标记"引导已完成"）
---
### Story 3.5: UserGuide 边缘情况处理和集成测试
**As a** 控件库开发者，
**I want** 处理 UserGuide 的边缘情况并进行全面测试，
**so that** 确保 UserGuide 在各种场景下稳定可用，用户体验流畅。
#### Acceptance Criteria
1. 处理边缘情况：
- **目标控件不可见或已销毁**: UserGuide 应自动跳过该步骤或显示错误提示
- **窗口缩放**: 引导提示框应随窗口调整位置，不出现错位
- **多窗口场景**: UserGuide 应只在启动它的窗口内生效
- **用户点击 Overlay 遮罩**: 默认不响应（不关闭引导），或提供配置选项
2. 主题切换测试：
- 在引导进行中切换主题，UserGuide 应正确响应，无视觉错误
3. 性能测试：
- 引导流程包含 10 个步骤时，步骤切换应流畅（< 100ms）
- Overlay 和提示框的动画不应卡顿
4. 用户体验测试：
- 引导流程的视觉呈现清晰，提示框不会遮挡目标控件
- 按钮的位置和文本易于理解
- 进度指示清晰（如 "3/5"）
5. 在 Example 中创建综合测试页面：
- 模拟真实应用的引导场景（如"首次使用教程"）
- 包含至少 5 个步骤，覆盖不同位置（Top、Bottom、Left、Right）
- 测试跳过、返回、完成等所有操作
6. 修复测试中发现的所有 Bug
7. 在 README 中添加 UserGuide 的使用文档：
- 基础用法示例（XAML 和代码）
- 如何定义 GuideStep
- 如何监听完成事件
- 最佳实践建议（如引导步骤不宜过多、提示文本应简洁）
---
### Story 3.6: MVP 整体集成测试和文档完善
**As a** 控件库的用户（开发者），
**I want** 在 Example 应用中看到所有 MVP 功能的完整演示，并有清晰的文档指导，
**so that** 我可以快速学习如何使用控件库，并在自己的项目中集成。
#### Acceptance Criteria
1. 在 Example 中创建"综合 Demo"页面：
- 集成 PropertyGrid、UserGuide、主题切换功能
- 模拟一个真实的应用场景（如"AI 模型配置工具"）
- 页面包含：
- 主题切换按钮
- PropertyGrid 显示配置对象
- "开始引导"按钮，触发 UserGuide
- UserGuide 引导用户了解主题切换、PropertyGrid 使用等功能
2. 验证所有 MVP Success Criteria（来自 Brief）：
- ✅ 颜色系统和主题框架可用：至少 2 种主题，运行时流畅切换
- ✅ 国际化框架架构预留：代码结构支持后续扩展
- ✅ PropertyGrid 可在测试项目中使用：支持常用类型，基础数据绑定
- ✅ UserGuide 可在测试项目中使用：引导流程完整，Tooltip 增强功能可用
- ✅ 架构支持未来 AOT：MVP 阶段允许反射
- ✅ 产出 5+ 个可复用的基础控件/工具：TwoColumnLayout、Overlay、RichTooltip、ThemeManager 等
3. 测试跨功能集成：
- 在 PropertyGrid 编辑时触发主题切换，验证无冲突
- 在 UserGuide 进行中修改 PropertyGrid，验证无异常
4. 性能基准测试：
- PropertyGrid 50 属性生成 < 200ms（NFR5）
- 主题切换 < 100ms（NFR4）
- UI 渲染 60fps（NFR3）
5. 完善 README.md：
- 项目概述和目标
- 快速开始指南（如何运行 Example）
- 控件列表和功能概述
- 核心控件的使用示例（PropertyGrid、UserGuide）
- 已知限制和后续计划（Post-MVP）
6. 创建 CHANGELOG.md：
- 记录 MVP v1.0 的功能清单
- 标记已完成的 Epic 和 Story
7. 项目代码质量检查：
- 所有公开 API 有 XML 文档注释
- 代码符合 C# 编码规范
- 删除未使用的代码和注释
- 确保 Git 提交记录清晰
---

16
docs/prd/epic-list.md Normal file
View File

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

27
docs/prd/goals-and-background-context.md Normal file
View File

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

15
docs/prd/index.md Normal file
View File

@@ -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)

102
docs/prd/next-steps.md Normal file
View File

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

54
docs/prd/requirements.md Normal file
View File

@@ -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 控件开发中的快速入门文档和代码示例，降低团队学习成本
---

118
docs/prd/technical-assumptions.md Normal file
View File

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

108
docs/prd/user-interface-design-goals.md Normal file
View File

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