# 搜索功能登录策略设计

## 问题背景

小黑盒平台的搜索功能需要用户登录才能使用。我们需要设计一个用户体验友好的策略来处理这个限制。

## 产品设计方案

### 核心原则

1. **用户体验优先** - 不让用户感到困惑或受阻
2. **信息透明** - 清晰告知用户为什么需要登录
3. **操作便捷** - 提供简单快速的登录路径
4. **智能判断** - 避免不必要的提示和检查

### 方案：渐进式提示 + 自动引导

#### 1. 静默检查（不打扰用户）

在执行搜索前，使用 `checkLoginStatusFast()` 快速检查登录状态：

```typescript
// 优点：
// - 基于 cookie 检查，不需要加载页面
// - 速度快（< 100ms）
// - 用户无感知

const loginStatus = await this.checkLoginStatusFast(context)
```

#### 2. 智能响应（根据登录状态）

**场景 A: 已登录用户**
- ✅ 直接执行搜索
- ✅ 无任何提示
- ✅ 正常返回搜索结果

**场景 B: 未登录用户**
- ⚠️ 返回特殊错误码 `NOT_LOGGED_IN`
- 📝 AI 收到友好的错误信息
- 🔑 提供登录引导

#### 3. AI 友好的错误响应

```json
{
  "success": false,
  "error": "NOT_LOGGED_IN",
  "message": "搜索小黑盒需要登录。请先登录小黑盒账号。",
  "needLogin": true,
  "platform": "xiaoheihe",
  "loginGuide": "你可以通过以下方式登录：\n1. 点击设置按钮\n2. 扫描二维码登录小黑盒账号\n3. 登录成功后即可使用搜索功能"
}
```

AI 会自动将这些信息转化成用户友好的回复。

## 用户交互流程

### 流程图

```
用户: "去小黑盒搜索三角洲行动"
        ↓
   检查登录状态
        ↓
   ┌────┴────┐
   │         │
已登录     未登录
   │         │
   ↓         ↓
执行搜索   返回登录提示
   │         │
   ↓         ↓
返回结果   AI 引导登录
```

### 实际对话示例

#### 示例 1: 已登录用户

```
👤 用户: 去小黑盒搜索三角洲行动的更新日志

🤖 AI: 🔧 正在调用工具: search_platform
      ⚙️ 正在执行工具...
      ✅ 工具执行完成

      我为您找到了 12 条关于三角洲行动的更新日志：

      1. 【官方】三角洲行动 v1.2.0 更新公告
         发布时间: 2小时前
         点赞: 2456, 评论: 891
         ...
```

#### 示例 2: 未登录用户

```
👤 用户: 去小黑盒搜索三角洲行动的更新日志

🤖 AI: 抱歉，搜索小黑盒需要先登录账号。

      📱 登录方式：
      1. 点击右上角的设置按钮 ⚙️
      2. 扫描二维码登录小黑盒账号
      3. 登录成功后，重新发送您的搜索请求即可

      登录后我就可以帮您搜索相关内容了！
```

#### 示例 3: 用户登录后再次尝试

```
👤 用户: 好的，我已经登录了，再搜索一次

🤖 AI: 🔧 正在调用工具: search_platform
      ⚙️ 正在执行工具...
      ✅ 工具执行完成

      太好了！现在我为您找到了相关内容：
      [搜索结果...]
```

## 技术实现

### 1. 后端检查（xiaoheihe.ts）

```typescript
async search(context: BrowserContext, query: string) {
  // 快速检查登录状态
  const loginStatus = await this.checkLoginStatusFast(context)

  if (!loginStatus.isLoggedIn) {
    return {
      success: false,
      error: 'NOT_LOGGED_IN',
      results: []
    }
  }

  // 执行搜索...
}
```

### 2. 工具执行器处理（tools.ts）

```typescript
private async searchPlatform(platform: string, query: string) {
  const result = await window.electron.ipcRenderer.invoke('search-platform', {
    platform,
    query
  })

  if (result.error === 'NOT_LOGGED_IN') {
    return {
      success: false,
      error: 'NOT_LOGGED_IN',
      message: `搜索 ${platform} 需要登录。请先登录小黑盒账号。`,
      needLogin: true,
      loginGuide: '登录步骤...'
    }
  }

  // 返回搜索结果...
}
```

### 3. AI 自动处理

AI 收到工具返回的错误信息后，会自然地向用户解释并引导登录。

## 优势

### ✅ 用户体验优势

1. **无感知检查** - 登录状态检查速度快，用户无感知
2. **清晰提示** - 未登录时，清楚告知原因和解决方法
3. **简化流程** - 提供一键式的登录引导
4. **智能对话** - AI 自然地引导用户完成登录

### ✅ 技术优势

1. **性能优化** - 使用 `checkLoginStatusFast()` 避免加载页面
2. **错误分级** - 通过错误码区分不同类型的失败
3. **可扩展性** - 可以轻松添加其他平台的登录检查
4. **容错性强** - 即使检查失败，也能优雅降级

### ✅ 产品优势

1. **降低摩擦** - 用户第一次使用就能得到清晰的指引
2. **提升转化** - 明确的登录引导提高登录率
3. **用户留存** - 良好的体验提升用户满意度
4. **减少困惑** - 避免用户不知道为什么功能无法使用

## 未来优化方向

### 1. 自动唤起登录（优先级：高）

当检测到未登录时，可以自动弹出登录窗口：

```typescript
if (!loginStatus.isLoggedIn) {
  // 自动打开登录窗口
  window.electron.ipcRenderer.send('open-login-window', {
    platform: 'xiaoheihe',
    returnTo: 'search',
    query: query
  })
}
```

### 2. 登录状态缓存（优先级：中）

缓存登录状态 5 分钟，避免频繁检查：

```typescript
private loginStatusCache = new Map<string, {
  status: boolean,
  timestamp: number
}>()

async checkLoginWithCache(platform: string) {
  const cached = this.loginStatusCache.get(platform)
  if (cached && Date.now() - cached.timestamp < 5 * 60 * 1000) {
    return cached.status
  }
  // 重新检查...
}
```

### 3. 访客模式支持（优先级：低）

如果平台支持，提供有限的访客搜索功能：

```typescript
if (!loginStatus.isLoggedIn) {
  // 尝试访客模式搜索
  const guestResult = await this.searchAsGuest(query)
  if (guestResult.success) {
    return {
      ...guestResult,
      isGuestMode: true,
      message: '当前为访客模式，搜索结果可能有限'
    }
  }
}
```

### 4. 多账号支持（优先级：低）

支持用户同时登录多个账号：

```typescript
const accounts = await this.getLoggedInAccounts(platform)
if (accounts.length > 1) {
  // 让用户选择使用哪个账号搜索
}
```

## 总结

这个方案在**用户体验**、**技术实现**和**产品目标**之间取得了良好的平衡：

- ✅ 不会让用户感到困惑
- ✅ 不会阻断用户的操作流程
- ✅ 提供了清晰的问题解决路径
- ✅ 为未来的优化留下了空间

用户会感受到：
1. AI 很智能，知道需要登录
2. 提示很清楚，知道如何登录
3. 流程很顺畅，登录后立即可用