265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
# 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 提交记录清晰
|
||
|
||
---
|
||
|