docs: brainstorm,brief and prd

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. 支持基础富文本格式：
+   - **粗体**: 使用 `<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 提交记录清晰
+
+---
+