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

---