ui/docs/prd/epic-3-details-userguide-onboarding-user-assistance.md

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 提交记录清晰

---