crush-level-web/docs/AiReplySuggestions-Refactor.md

# AI 建议回复功能重构说明

## 重构日期
2025-11-17

## 最新更新
2025-11-17 - 优化请求逻辑，确保每次只发送 3 次 API 请求

## 问题描述

重构前的 AI 建议功能存在以下问题：

1. **状态管理复杂**：维护了大量状态（`allSuggestions`、`loadedPages`、`batchNo`、`excContentList`、`isPageLoading`、`isRequesting` 等）
2. **页面切换逻辑复杂**：需要跟踪哪些页面已加载，切换时判断是否显示骨架屏
3. **显示逻辑不清晰**：`isLoading` 只在首次加载时为 true，分页切换时骨架屏显示不正确
4. **用户体验问题**：会出现 AI 辅助提示为空的情况（如图所示）

## 重构目标

1. **简化状态管理**：只保留必要的状态
2. **统一交互逻辑**：每次打开建议面板时，重置到第1页并重新获取数据
3. **清晰的骨架屏显示**：数据未加载完成时始终显示骨架屏

## 重构内容

### 1. `useAiReplySuggestions` Hook 重构

#### 状态简化

**重构前：**
```typescript
const [allSuggestions, setAllSuggestions] = useState<ReplySuggestion[]>([]);
const [loadedPages, setLoadedPages] = useState<Set<number>>(new Set([1]));
const [isPageLoading, setIsPageLoading] = useState(false);
const [isRequesting, setIsRequesting] = useState(false);
// ... 其他状态
```

**重构后：**
```typescript
const [pageData, setPageData] = useState<Map<number, ReplySuggestion[]>>(new Map());
const [loadingPages, setLoadingPages] = useState<Set<number>>(new Set());
// ... 其他必要状态
```

#### 核心逻辑变化

**重构前：**
- `showSuggestions` 函数会根据多种条件判断是否需要获取数据
- 首次获取第1页数据，然后静默获取第2、3页
- 页面切换时复杂的加载状态判断

**重构后：**
- **每次调用 `showSuggestions` 都重置到第1页并重新获取所有数据**
- 按页存储数据到 `Map` 中，逻辑更清晰
- 页面切换时自动检查并加载缺失的页面数据

### 2. 数据获取流程优化

#### 重构前流程
1. 获取第1页 → 立即展示
2. 静默获取第2页 → 更新 `loadedPages`
3. 静默获取第3页 → 更新 `loadedPages`
4. 用户切换页面时检查 `loadedPages`

#### 重构后流程
1. 清空旧数据
2. 获取第1页 → 存入 `pageData.set(1, ...)`
3. 获取第2页 → 存入 `pageData.set(2, ...)`
4. 获取第3页 → 存入 `pageData.set(3, ...)`
5. 用户切换页面时从 `pageData` 读取，无数据则显示骨架屏

### 3. 骨架屏显示逻辑

**重构前：**
```typescript
const displaySuggestions = isCurrentPageLoaded ? suggestions : Array.from({ length: 3 }, ...);
```

**重构后：**
```typescript
const suggestions = isCurrentPageLoading || !currentPageSuggestions
  ? Array.from({ length: 3 }, (_, index) => ({
      id: `skeleton-${currentPage}-${index}`,
      text: '',
      isSkeleton: true
    }))
  : currentPageSuggestions;
```

UI 组件根据 `isSkeleton` 标志渲染骨架屏或真实内容。

### 4. UI 组件更新

`AiReplySuggestions.tsx` 更新：
- 添加 `isSkeleton` 字段到 `ReplySuggestion` 接口
- 检查 `suggestions.some(s => s.isSkeleton)` 决定是否显示骨架屏
- 骨架屏添加 `animate-pulse` 动画效果

## 重构优势

### 1. **简化的状态管理**
- 使用 `Map<number, ReplySuggestion[]>` 按页存储数据，结构清晰
- 移除了 `isRequesting`、`isPageLoading`、`isCurrentPageLoaded` 等冗余状态
- 只需维护 `loadingPages: Set<number>` 来跟踪正在加载的页面

### 2. **智能的数据管理**
- **有新 AI 消息时**：重置到第1页并重新获取数据
- **没有新消息时**：保留之前的建议内容和当前页面位置
- 避免了"空白建议"的问题
- 数据加载状态清晰可见（骨架屏动画）

### 3. **更可靠的数据加载**
- 智能判断是否需要重新获取数据（基于最后一条 AI 消息 ID）
- 首次打开或数据为空时自动获取
- 减少了因状态不同步导致的 bug

### 4. **更好的代码可维护性**
- 代码从 312 行减少到 200 行
- 逻辑流程更清晰直观
- 减少了状态依赖和副作用

## 使用示例

### 场景1：首次打开建议面板（渐进式加载）

1. **点击建议按钮** → 面板打开，重置到第1页，显示骨架屏
2. **~500ms 后第1页数据返回** → ✨ **立即展示第1页的3条建议**（用户可以开始浏览）
3. **后台继续获取第2、3页** → 不阻塞用户交互
4. **点击下一页** → 切换到第2页
   - 如果第2页数据已加载 → 立即显示
   - 如果第2页数据未加载 → 显示骨架屏（通常第2页已在后台加载完成）

### 场景2：关闭后再次打开（无新消息）

1. **关闭建议面板**
2. **再次点击建议按钮** → 面板打开
3. **保留上次的内容和页面位置**（比如之前在第2页，现在仍在第2页）
4. **无需重新加载数据**，立即显示缓存的建议

### 场景3：收到新 AI 消息后打开

1. **用户发送消息，AI 回复**
2. **点击建议按钮** → 面板打开
3. **检测到新的 AI 消息** → 重置到第1页，显示骨架屏
4. **重新获取所有建议数据**（基于最新的对话内容）

### 场景4：面板已打开时收到新 AI 消息

1. **建议面板已打开**（比如用户正在浏览第2页）
2. **用户发送消息，AI 回复**
3. **自动刷新建议数据** → **保持在当前页面**（第2页），不强制切回第1页
4. **渐进式加载新数据**，用户可以继续浏览当前页

## API 返回值变化

Hook 返回的接口保持不变，确保向后兼容：

```typescript
return {
  suggestions,        // ReplySuggestion[] (包含 isSkeleton 标志)
  currentPage,        // number
  totalPages,         // number
  isLoading,          // boolean (只要有页面在加载就为 true)
  isVisible,          // boolean
  showSuggestions,    // () => void
  hideSuggestions,    // () => void
  handlePageChange,   // (page: number) => void
};
```

移除的返回值：
- `isPageLoading`
- `isCurrentPageLoaded`
- `refreshSuggestions`

## 关键优化点

### 避免多次请求的设计

**问题**：原始实现会触发多次重复请求

**解决方案**：
1. **统一的 `fetchAllData` 函数**：一次性顺序获取3页数据，使用局部变量传递 `batchNo` 和 `excContentList`
2. **防重复调用保护**：在 `fetchAllData` 开始时检查 `loadingPages.size > 0`，如果已有加载则跳过
3. **移除分页独立加载**：删除了 `fetchPageData` 函数和 `handlePageChange` 中的数据获取逻辑
4. **简化页面切换**：`handlePageChange` 只负责切换 `currentPage`，不触发数据加载

### 渐进式加载流程

采用**渐进式加载**策略，让用户尽早看到数据，提升体验：

```typescript
fetchAllData() {
  // 1. 检查防重复
  if (loadingPages.size > 0) return;
  
  // 2. 标记所有页面为加载中
  setLoadingPages(new Set([1, 2, 3]));
  
  // 3. 获取第1页 → 立即展示
  const response1 = await genSupContentV2({ aiId, excContentList: [] });
  setPageData(new Map([[1, response1]]));  // ✨ 立即展示第1页
  setLoadingPages(new Set([2, 3]));        // 标记第1页已完成
  
  // 4. 获取第2页 → 追加展示
  const response2 = await genSupContentV2({ aiId, batchNo, excContentList: [response1] });
  setPageData(prev => prev.set(2, response2));  // ✨ 追加第2页
  setLoadingPages(new Set([3]));                // 标记第2页已完成
  
  // 5. 获取第3页 → 追加展示
  const response3 = await genSupContentV2({ aiId, batchNo, excContentList: [response1, response2] });
  setPageData(prev => prev.set(3, response3));  // ✨ 追加第3页
  setLoadingPages(new Set());                   // 全部完成
}
```

**关键优势**：
- 🚀 **第1页数据到达后立即展示**，用户无需等待所有数据
- 📊 **后续页面数据追加展示**，不影响用户浏览第1页
- ⏱️ **感知加载时间更短**，提升用户体验
- 🔄 **页面2、3可以并行渲染**，用户切换时自动显示骨架屏

## 注意事项

1. **精确的请求次数**：每次调用 `fetchAllData` 只会发送 **3 次** API 请求（第1、2、3页）
2. **智能缓存策略**：没有新 AI 消息时，复用已有数据，不发送请求
3. **网络失败处理**：任一页面加载失败会中断整个流程并清空数据
4. **Coin 不足处理**：任何页面触发 Coin 不足错误都会关闭整个建议面板
5. **防重复保护**：通过 `loadingPages.size` 检查防止并发调用

## 测试建议

1. 测试正常流程：打开建议 → 浏览3页 → 关闭 → 再次打开
2. 测试网络慢场景：确认骨架屏正确显示
3. 测试 Coin 不足场景：确认面板正确关闭
4. 测试新消息场景：发送消息后面板已打开时自动刷新