audio_codebuddy/.qoder/repowiki/zh/content/数据库设计/交互数据模型/搜索历史数据模型.md

搜索历史数据模型

本文档引用的文件

• schema.prisma
• search.service.ts
• search.controller.ts
• index.vue
• history.controller.ts
• history-batch.controller.ts
• API.md

目录

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

简介

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

项目结构

搜索历史功能涉及以下关键文件：

• 数据库模型定义：Prisma Schema
• 业务逻辑层：SearchService
• API接口层：SearchController
• 前端交互：Vue页面组件

• 历史记录管理：历史控制器与批量删除控制器

  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
• search.service.ts:1-144
• history.controller.ts:1-67
• history-batch.controller.ts:1-105
• schema.prisma:220-240

章节来源

• search.controller.ts:1-170
• search.service.ts:1-144
• schema.prisma:220-240

核心组件

搜索历史功能的核心由以下组件构成：

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

章节来源

• schema.prisma:220-240
• search.service.ts:1-144
• search.controller.ts:1-170

架构概览

搜索历史功能采用分层架构：

• 表现层：Vue页面组件负责用户交互与数据展示
• 控制器层：Koa路由控制器处理HTTP请求与响应
• 服务层：SearchService封装业务逻辑与数据操作

• 数据层：Prisma ORM连接MySQL数据库

  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
• search.service.ts:52-119
• schema.prisma:220-240

详细组件分析

SearchHistory模型设计

SearchHistory模型是搜索历史功能的数据基础，包含以下字段：

• id：自增主键
• userId：用户标识，关联User模型
• keyword：搜索关键词
• createdAt：记录创建时间戳

该模型通过索引优化查询性能：

• 对(userId, createdAt)建立复合索引

• 对(userId)建立单独索引

  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
• schema.prisma:220-240

章节来源

• schema.prisma:220-228

搜索历史与用户的关系

SearchHistory与User模型建立一对多关系：

• User模型通过comments、drafts、favorites、orders等字段关联其他实体
• SearchHistory通过userId外键关联User
• 查询时可通过userId高效筛选特定用户的搜索历史

章节来源

• schema.prisma:10-38
• schema.prisma:220-228

存储策略与清理机制

SearchService实现了完善的存储策略：

• 去重规则：同一用户对同一关键词仅保留最新记录
• 时间限制：用户历史记录上限为20条，超出部分按时间顺序删除最旧记录

• 热门统计：每次新增搜索历史时更新HotSearch表的count字段

  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

章节来源

• search.service.ts:72-119

热门搜索统计

热门搜索统计通过HotSearch模型实现：

• count字段记录关键词被搜索的次数
• sort字段用于排序权重
• getHotSearches方法按sort降序、count降序返回热门词

章节来源

• schema.prisma:230-240
• search.service.ts:41-49

API使用示例

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

获取搜索历史

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

保存搜索历史

// 前端调用示例
await post('/search/history', { userId: 1, keyword: 'AI有声书' });

删除单条搜索历史

// 前端调用示例
await get('/search/history', { userId: 1, keyword: 'AI有声书' });

清空搜索历史

// 前端调用示例
await get('/search/history/all', { userId: 1 });

章节来源

• search.controller.ts:60-167
• index.vue:166-222

前端交互实现

前端Vue组件实现了搜索历史的展示与交互：

• 展示搜索历史标签与热门推荐
• 支持点击历史标签直接搜索
• 支持删除单条历史与清空历史
• 使用缓存机制提升用户体验

章节来源

• index.vue:46-89
• index.vue:166-250

依赖关系分析

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

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
• search.service.ts
• schema.prisma:220-240

章节来源

• search.controller.ts:1-5
• search.service.ts

性能考量

搜索历史功能的性能优化措施：

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

故障排除指南

常见问题及解决方案：

• 关键词为空：API会返回400错误，需确保keyword参数有效
• 用户ID无效：默认使用测试用户ID进行开发环境测试
• 查询超时：检查数据库索引是否正确创建
• 热门统计异常：确认HotSearch表数据完整性

章节来源

• search.controller.ts:92-98
• history.controller.ts:6-13

结论

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