# 智能推荐系统文档

## 一、系统概述

智能推荐系统基于用户行为数据，为用户提供个性化的商品推荐。系统综合分析用户的搜索历史、浏览历史，结合全站热销商品数据，生成智能推荐列表。

## 二、推荐逻辑架构

```
┌─────────────────────────────────────────────────────────────┐
│                    智能推荐系统                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 用户搜索历史 │  │ 用户浏览历史 │  │ 全站热销商品 │         │
│  │   (权重高)   │  │   (权重中)   │  │   (权重低)   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         ▼                ▼                ▼                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 关键词匹配  │  │ 分类匹配    │  │ 销量排序    │         │
│  │ 相关商品    │  │ 相似商品    │  │ 热门商品    │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          ▼                                  │
│              ┌─────────────────────┐                       │
│              │   去重 & 合并结果   │                       │
│              └──────────┬──────────┘                       │
│                         ▼                                  │
│              ┌─────────────────────┐                       │
│              │   返回推荐商品列表   │                       │
│              └─────────────────────┘                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 三、权重分配策略

### 3.1 数据源权重

| 数据源 | 权重 | 说明 |
|--------|------|------|
| 用户搜索历史 | 50% | 用户主动搜索的关键词最能反映购买意向 |
| 用户浏览历史 | 30% | 用户浏览过的商品分类反映兴趣偏好 |
| 热销商品 | 20% | 全站热销商品作为兜底和补充 |

### 3.2 推荐优先级

```
优先级 1: 用户搜索历史匹配的商品（最多占推荐列表的50%）
优先级 2: 用户浏览过的分类下的商品（最多占推荐列表的30%）
优先级 3: 全站热销商品（填充剩余位置）
```

## 四、核心算法详解

### 4.1 智能推荐主流程

```typescript
async getSmartRecommendations(limit: number): Promise<Product[]> {
  const products: Product[] = []
  const addedIds = new Set<string>()  // 用于去重
  
  // 步骤1: 根据用户搜索历史推荐（权重最高）
  const searchHistory = await getUserSearchHistory(5)
  if (searchHistory.length > 0) {
    const keywordProducts = await searchProductsByKeywords(searchHistory, limit)
    // 添加到结果列表，去重
  }
  
  // 步骤2: 根据用户浏览历史推荐（权重中）
  if (products.length < limit) {
    const browseCategories = await getUserBrowseCategories(3)
    if (browseCategories.length > 0) {
      const categoryProducts = await getProductsByCategories(browseCategories, limit - products.length)
      // 添加到结果列表，去重
    }
  }
  
  // 步骤3: 补充热销商品（权重低）
  if (products.length < limit) {
    const hotProducts = await getHotProducts(limit - products.length + 5)
    // 添加到结果列表，去重
  }
  
  return products.slice(0, limit)
}
```

### 4.2 搜索历史匹配算法

```typescript
// 根据用户搜索关键词匹配商品
async searchProductsByKeywords(keywords: string[], limit: number): Promise<Product[]> {
  // 1. 获取商品数据
  // 2. 遍历商品，检查名称和描述是否包含关键词
  // 3. 匹配成功的商品加入推荐列表
  
  for (product in products) {
    for (keyword in keywords) {
      if (product.name.contains(keyword) || product.description.contains(keyword)) {
        matched = true
        break
      }
    }
  }
}
```

### 4.3 浏览历史分类匹配算法

```typescript
// 根据用户浏览过的商品分类推荐
async getProductsByCategories(categoryIds: string[], limit: number): Promise<Product[]> {
  // 1. 获取用户浏览过的商品分类ID列表
  // 2. 查询这些分类下的商品
  // 3. 按销量排序返回
}
```

## 五、热搜词系统

### 5.1 热搜词计算

```typescript
async getHotKeywords(limit: number): Promise<string[]> {
  // 1. 获取最近100条搜索记录
  // 2. 统计每个关键词的出现频率
  // 3. 按频率降序排序
  // 4. 返回前N个高频关键词
}
```

### 5.2 热搜词展示规则

| 排名 | 样式 | 说明 |
|------|------|------|
| 1-3名 | 红色背景 | 热度最高，突出显示 |
| 4-10名 | 灰色背景 | 普通热度 |

## 六、用户行为记录

### 6.1 搜索行为记录

```typescript
// 在用户执行搜索时调用
async recordSearch(keyword: string, resultCount: number): Promise<void> {
  // 记录字段：
  // - user_id: 用户ID（可选，支持匿名）
  // - keyword: 搜索关键词
  // - result_count: 搜索结果数量
  // - created_at: 搜索时间
}
```

### 6.2 浏览行为记录

```typescript
// 在用户查看商品详情时调用
async recordBrowse(productId: string, duration: number): Promise<void> {
  // 记录字段：
  // - user_id: 用户ID
  // - product_id: 商品ID
  // - browse_duration: 浏览时长（秒）
  // - created_at/updated_at: 时间戳
}
```

## 七、数据表结构

### 7.1 搜索历史表 (ml_search_history)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| user_id | UUID | 用户ID（可空） |
| keyword | VARCHAR(200) | 搜索关键词 |
| result_count | INTEGER | 搜索结果数量 |
| created_at | TIMESTAMP | 搜索时间 |

### 7.2 浏览历史表 (ml_browse_history)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| user_id | UUID | 用户ID |
| product_id | UUID | 商品ID |
| browse_duration | INTEGER | 浏览时长（秒） |
| created_at | TIMESTAMP | 首次浏览时间 |
| updated_at | TIMESTAMP | 最近浏览时间 |

## 八、API接口列表

| API | 方法 | 说明 |
|-----|------|------|
| getSmartRecommendations | GET | 获取智能推荐商品 |
| getHotKeywords | GET | 获取热搜词列表 |
| getUserSearchHistory | GET | 获取用户搜索历史 |
| getUserBrowseCategories | GET | 获取用户浏览分类 |
| recordSearch | POST | 记录搜索行为 |
| recordBrowse | POST | 记录浏览行为 |

## 九、性能优化建议

### 9.1 缓存策略

- 热搜词列表：缓存5分钟，减少数据库查询
- 用户搜索历史：缓存10分钟
- 推荐结果：缓存3分钟

### 9.2 数据量控制

- 搜索历史：每个用户最多保留100条
- 浏览历史：每个用户最多保留50条
- 热搜词统计：只统计最近30天的数据

## 十、扩展方向

### 10.1 短期优化

1. **时间衰减因子**：近期行为权重更高
2. **购买行为加权**：已购买商品的相关商品权重提升
3. **收藏行为加权**：收藏商品的相关商品权重提升

### 10.2 长期规划

1. **协同过滤**：基于相似用户的行为推荐
2. **商品相似度**：基于商品属性计算相似度
3. **机器学习**：使用推荐算法模型

---

*文档版本：1.0*
*最后更新：2024年*