# 用户引导功能实现文档

## 功能概述

用户引导功能用于在用户首次进入特定页面时，提供功能说明和操作指导，帮助用户更好地理解和使用应用功能。

## 已实现的引导

### 1. Goals页面 - 全面功能引导

**位置**: `app/(tabs)/goals.tsx`

**引导内容**:
- 欢迎介绍：介绍目标页面的整体功能
- 任务进度统计：说明任务进度卡片显示当天任务的完成情况
- 目标管理：说明如何查看和管理目标
- 创建新目标：说明如何快速创建新目标
- 任务筛选：说明如何使用标签筛选任务
- 任务列表：说明任务列表的功能和操作

**组件**: `GoalsPageGuide`

## 技术实现

### 核心组件

1. **GoalsPageGuide** (`components/GoalsPageGuide.tsx`)
   - 引导弹窗组件
   - 支持多步骤引导
   - 动态高亮不同功能区域
   - 平滑动画效果
   - 回顾功能支持

2. **引导状态管理** (`utils/guideHelpers.ts`)
   - 使用AsyncStorage存储引导完成状态
   - 提供检查、标记、重置功能

### 引导状态键

```typescript
const GUIDE_KEYS = {
  GOALS_PAGE: '@guide_goals_page_completed',
} as const;
```

## 使用方法

### 在页面中集成引导

1. **导入必要组件和工具**:
```typescript
import { GoalsPageGuide } from '@/components/GoalsPageGuide';
import { checkGuideCompleted, markGuideCompleted } from '@/utils/guideHelpers';
```

2. **添加状态管理**:
```typescript
const [showGuide, setShowGuide] = useState(false);
```

3. **检查引导状态**:
```typescript
const checkAndShowGuide = async () => {
  try {
    const hasCompletedGuide = await checkGuideCompleted('GOALS_PAGE');
    if (!hasCompletedGuide) {
      setTimeout(() => {
        setShowGuide(true);
      }, 1000);
    }
  } catch (error) {
    console.error('检查引导状态失败:', error);
  }
};
```

4. **处理引导完成**:
```typescript
const handleGuideComplete = async () => {
  try {
    await markGuideCompleted('GOALS_PAGE');
    setShowGuide(false);
  } catch (error) {
    console.error('保存引导状态失败:', error);
    setShowGuide(false);
  }
};
```

5. **在页面中渲染组件**:
```typescript
<GoalsPageGuide
  visible={showGuide}
  onComplete={handleGuideComplete}
/>
```

## 开发测试

### 测试按钮

在开发模式下，Goals页面右上角会显示"重置引导"按钮，用于测试引导功能。

### 手动重置引导状态

```typescript
import { resetGuideStates } from '@/utils/devTools';

// 重置所有引导状态
await resetGuideStates();
```

### 检查引导状态

```typescript
import { getAllGuideStatus } from '@/utils/guideHelpers';

// 获取所有引导状态
const status = await getAllGuideStatus();
console.log('引导状态:', status);
```

## 添加新的引导

### 1. 创建引导组件

参考 `TaskProgressCardGuide` 的结构创建新的引导组件。

### 2. 添加状态键

在 `utils/guideHelpers.ts` 中添加新的引导键：

```typescript
const GUIDE_KEYS = {
  GOALS_PAGE: '@guide_goals_page_completed',
  NEW_GUIDE: '@guide_new_guide_completed', // 新增
} as const;
```

### 3. 在页面中集成

按照上述使用方法在目标页面中集成引导功能。

## 设计原则

1. **用户友好**: 引导内容简洁明了，避免信息过载
2. **可跳过**: 用户可以选择跳过引导
3. **可回顾**: 用户可以回顾之前的步骤
4. **一次性**: 引导只显示一次，避免重复打扰
5. **响应式**: 引导内容适应不同屏幕尺寸
6. **可测试**: 提供开发测试工具

## 注意事项

1. 引导应该在页面完全加载后显示，避免布局问题
2. 引导状态应该持久化存储，避免重复显示
3. 引导内容应该与页面功能紧密相关
4. 测试时注意重置引导状态，确保功能正常