# 搜索历史数据模型

<cite>
**本文档引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [index.vue](file://my-uniapp-vue3/src/pages/search/index.vue)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)
- [history-batch.controller.ts](file://server/src/modules/history/history-batch.controller.ts)
- [API.md](file://docs/API.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
本文件详细阐述AI有声书生成平台的搜索历史数据模型设计与实现。搜索历史功能旨在记录用户的搜索行为，提供个性化搜索体验，并支持热门搜索统计与推荐。本文档将深入解析SearchHistory模型的设计理念、字段作用、存储策略、清理机制，以及与用户(User)模型的一对多关系。

## 项目结构
搜索历史功能涉及以下关键文件：
- 数据库模型定义：Prisma Schema
- 业务逻辑层：SearchService
- API接口层：SearchController
- 前端交互：Vue页面组件
- 历史记录管理：历史控制器与批量删除控制器

```mermaid
graph TB
subgraph "前端"
FE_Search["搜索页面<br/>index.vue"]
end
subgraph "后端"
SC["SearchController<br/>search.controller.ts"]
SS["SearchService<br/>search.service.ts"]
HC["HistoryController<br/>history.controller.ts"]
HBC["HistoryBatchController<br/>history-batch.controller.ts"]
end
subgraph "数据层"
PRISMA["Prisma Client"]
DB[("MySQL 数据库")]
end
FE_Search --> SC
SC --> SS
SS --> PRISMA
PRISMA --> DB
HC --> PRISMA
HBC --> PRISMA
```

**图表来源**
- [search.controller.ts:1-170](file://server/src/modules/search/search.controller.ts#L1-L170)
- [search.service.ts:1-144](file://server/src/modules/search/search.service.ts#L1-L144)
- [history.controller.ts:1-67](file://server/src/modules/history/history.controller.ts#L1-L67)
- [history-batch.controller.ts:1-105](file://server/src/modules/history/history-batch.controller.ts#L1-L105)
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)

**章节来源**
- [search.controller.ts:1-170](file://server/src/modules/search/search.controller.ts#L1-L170)
- [search.service.ts:1-144](file://server/src/modules/search/search.service.ts#L1-L144)
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)

## 核心组件
搜索历史功能的核心由以下组件构成：
- SearchHistory模型：存储用户搜索记录
- HotSearch模型：维护热门搜索词及其热度
- SearchService：提供搜索历史的增删改查与热门统计
- SearchController：暴露REST API接口
- 前端Vue组件：展示搜索历史与热门推荐

**章节来源**
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)
- [search.service.ts:1-144](file://server/src/modules/search/search.service.ts#L1-L144)
- [search.controller.ts:1-170](file://server/src/modules/search/search.controller.ts#L1-L170)

## 架构概览
搜索历史功能采用分层架构：
- 表现层：Vue页面组件负责用户交互与数据展示
- 控制器层：Koa路由控制器处理HTTP请求与响应
- 服务层：SearchService封装业务逻辑与数据操作
- 数据层：Prisma ORM连接MySQL数据库

```mermaid
sequenceDiagram
participant FE as "前端页面"
participant SC as "SearchController"
participant SS as "SearchService"
participant PRISMA as "Prisma Client"
participant DB as "MySQL数据库"
FE->>SC : GET /api/search/history?userId=1&limit=5
SC->>SS : getSearchHistory(userId, limit)
SS->>PRISMA : findMany(SearchHistory)
PRISMA->>DB : SELECT * FROM SearchHistory
DB-->>PRISMA : 历史记录
PRISMA-->>SS : 历史记录
SS-->>SC : 历史记录
SC-->>FE : JSON响应
Note over FE,DB : 用户点击搜索时
FE->>SC : POST /api/search/history {userId, keyword}
SC->>SS : saveSearchHistory(userId, keyword)
SS->>PRISMA : deleteMany(SearchHistory)
PRISMA->>DB : DELETE FROM SearchHistory WHERE userId AND keyword
SS->>PRISMA : create(SearchHistory)
PRISMA->>DB : INSERT INTO SearchHistory
SS->>PRISMA : findMany(SearchHistory)
PRISMA->>DB : SELECT * FROM SearchHistory ORDER BY createdAt DESC
SS->>PRISMA : deleteMany(SearchHistory)
PRISMA->>DB : DELETE old records (超过20条)
SS->>PRISMA : findFirst(HotSearch)
PRISMA->>DB : SELECT * FROM HotSearch WHERE keyword
SS->>PRISMA : update/create HotSearch
PRISMA->>DB : UPDATE/INSERT HotSearch
SS-->>SC : 完成
SC-->>FE : JSON响应
```

**图表来源**
- [search.controller.ts:60-113](file://server/src/modules/search/search.controller.ts#L60-L113)
- [search.service.ts:52-119](file://server/src/modules/search/search.service.ts#L52-L119)
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)

## 详细组件分析

### SearchHistory模型设计
SearchHistory模型是搜索历史功能的数据基础，包含以下字段：
- id：自增主键
- userId：用户标识，关联User模型
- keyword：搜索关键词
- createdAt：记录创建时间戳

该模型通过索引优化查询性能：
- 对(userId, createdAt)建立复合索引
- 对(userId)建立单独索引

```mermaid
erDiagram
USER {
int id PK
string phone UK
string openid UK
string nickname
string avatar
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
datetime createdAt
datetime updatedAt
}
SEARCH_HISTORY {
int id PK
int userId FK
string keyword
datetime createdAt
}
HOT_SEARCH {
int id PK
string keyword
int count
int sort
datetime createdAt
datetime updatedAt
}
USER ||--o{ SEARCH_HISTORY : "拥有多个"
USER ||--o{ HOT_SEARCH : "参与搜索"
```

**图表来源**
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)

**章节来源**
- [schema.prisma:220-228](file://server/prisma/schema.prisma#L220-L228)

### 搜索历史与用户的关系
SearchHistory与User模型建立一对多关系：
- User模型通过comments、drafts、favorites、orders等字段关联其他实体
- SearchHistory通过userId外键关联User
- 查询时可通过userId高效筛选特定用户的搜索历史

**章节来源**
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)
- [schema.prisma:220-228](file://server/prisma/schema.prisma#L220-L228)

### 存储策略与清理机制
SearchService实现了完善的存储策略：
- 去重规则：同一用户对同一关键词仅保留最新记录
- 时间限制：用户历史记录上限为20条，超出部分按时间顺序删除最旧记录
- 热门统计：每次新增搜索历史时更新HotSearch表的count字段

```mermaid
flowchart TD
Start(["保存搜索历史"]) --> Validate["验证关键词非空"]
Validate --> Trim["去除首尾空白"]
Trim --> DeleteOld["删除同用户同关键词的历史记录"]
DeleteOld --> CreateNew["创建新的历史记录"]
CreateNew --> FetchAll["获取用户所有历史记录"]
FetchAll --> CheckLimit{"是否超过20条?"}
CheckLimit --> |否| UpdateHot["更新热门搜索统计"]
CheckLimit --> |是| SliceOld["截取最旧的记录"]
SliceOld --> DeleteOldRecords["删除最旧记录"]
DeleteOldRecords --> UpdateHot
UpdateHot --> End(["完成"])
```

**图表来源**
- [search.service.ts:72-119](file://server/src/modules/search/search.service.ts#L72-L119)

**章节来源**
- [search.service.ts:72-119](file://server/src/modules/search/search.service.ts#L72-L119)

### 热门搜索统计
热门搜索统计通过HotSearch模型实现：
- count字段记录关键词被搜索的次数
- sort字段用于排序权重
- getHotSearches方法按sort降序、count降序返回热门词

**章节来源**
- [schema.prisma:230-240](file://server/prisma/schema.prisma#L230-L240)
- [search.service.ts:41-49](file://server/src/modules/search/search.service.ts#L41-L49)

### API使用示例
以下是搜索历史功能的API使用示例：

#### 获取搜索历史
```javascript
// 前端调用示例
const response = await get('/search/history', { userId: 1, limit: 5 });
console.log(response.data); // 搜索历史数组
```

#### 保存搜索历史
```javascript
// 前端调用示例
await post('/search/history', { userId: 1, keyword: 'AI有声书' });
```

#### 删除单条搜索历史
```javascript
// 前端调用示例
await get('/search/history', { userId: 1, keyword: 'AI有声书' });
```

#### 清空搜索历史
```javascript
// 前端调用示例
await get('/search/history/all', { userId: 1 });
```

**章节来源**
- [search.controller.ts:60-167](file://server/src/modules/search/search.controller.ts#L60-L167)
- [index.vue:166-222](file://my-uniapp-vue3/src/pages/search/index.vue#L166-L222)

### 前端交互实现
前端Vue组件实现了搜索历史的展示与交互：
- 展示搜索历史标签与热门推荐
- 支持点击历史标签直接搜索
- 支持删除单条历史与清空历史
- 使用缓存机制提升用户体验

**章节来源**
- [index.vue:46-89](file://my-uniapp-vue3/src/pages/search/index.vue#L46-L89)
- [index.vue:166-250](file://my-uniapp-vue3/src/pages/search/index.vue#L166-L250)

## 依赖关系分析
搜索历史功能的依赖关系如下：

```mermaid
graph TB
subgraph "外部依赖"
KOA["Koa Router"]
PRISMA["Prisma Client"]
MYSQL["MySQL"]
end
subgraph "内部模块"
SC["SearchController"]
SS["SearchService"]
SH["SearchHistory Model"]
HS["HotSearch Model"]
end
SC --> SS
SS --> SH
SS --> HS
SS --> PRISMA
PRISMA --> MYSQL
SC --> KOA
```

**图表来源**
- [search.controller.ts:1-5](file://server/src/modules/search/search.controller.ts#L1-L5)
- [search.service.ts](file://server/src/modules/search/search.service.ts#L1)
- [schema.prisma:220-240](file://server/prisma/schema.prisma#L220-L240)

**章节来源**
- [search.controller.ts:1-5](file://server/src/modules/search/search.controller.ts#L1-L5)
- [search.service.ts](file://server/src/modules/search/search.service.ts#L1)

## 性能考量
搜索历史功能的性能优化措施：
- 数据库索引：对(userId, createdAt)和(userId)建立索引，提升查询效率
- 去重策略：同一用户同一关键词仅保留最新记录，减少重复数据
- 记录限制：用户历史记录上限20条，控制存储空间
- 热门统计：异步更新热门搜索，不影响主流程性能

## 故障排除指南
常见问题及解决方案：
- 关键词为空：API会返回400错误，需确保keyword参数有效
- 用户ID无效：默认使用测试用户ID进行开发环境测试
- 查询超时：检查数据库索引是否正确创建
- 热门统计异常：确认HotSearch表数据完整性

**章节来源**
- [search.controller.ts:92-98](file://server/src/modules/search/search.controller.ts#L92-L98)
- [history.controller.ts:6-13](file://server/src/modules/history/history.controller.ts#L6-L13)

## 结论
搜索历史数据模型通过清晰的字段设计、合理的存储策略和完善的清理机制，为AI有声书生成平台提供了可靠的搜索行为追踪能力。结合前端友好的交互界面，用户可以便捷地管理自己的搜索历史，同时平台能够基于热门搜索统计优化搜索体验。该设计既保证了数据的准确性与时效性，又兼顾了系统的性能与可维护性。