360 lines
11 KiB
Markdown
360 lines
11 KiB
Markdown
# 全站搜索功能设计文档
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 功能说明
|
||
|
||
为碳信网（txw-mhzc-web）提供全站统一的搜索功能，支持搜索全站内容（碳证中心、服务中心、行业专题等），提供搜索建议、搜索历史、热门搜索等辅助功能。
|
||
|
||
### 1.2 项目背景
|
||
|
||
- 碳信网各子系统（供需大厅、绿色金融、绿色交易等）目前分散独立
|
||
- 用户需要在全站范围内快速查找内容
|
||
- 需要为后续子系统迁移到 txw-mhzc 做准备
|
||
|
||
### 1.3 设计原则
|
||
|
||
- 前端聚合在 txw-mhzc-web
|
||
- 后端聚合在 txw-mhzc
|
||
- 搜索服务架构先搭好，后期快速对接迁移后的子系统
|
||
|
||
---
|
||
|
||
## 2. 前端设计
|
||
|
||
### 2.1 路由
|
||
|
||
| 路径 | 组件 | 说明 |
|
||
|------|------|------|
|
||
| `/search` | SearchView | 搜索结果页 |
|
||
|
||
### 2.2 页面结构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Header (复用现有) - Logo + 网站名 + 登录/注册 + 工作台 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 搜索区域 (灰色背景 #F5F5F5) │
|
||
│ [分类 ▼] [搜索输入框........................] [搜索] │
|
||
│ 热门搜索：江苏电厂配额 | 林业碳汇开发 | CBAM 报告... │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ [全部] [碳证中心] [服务中心] ← 分类Tab (左侧) │
|
||
│ ───────────── (绿色下划线指示选中) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 搜索结果列表 (单列) │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ [行业专题] 构建新型碳排放数据治理框架 │ │
|
||
│ │ 2025年5月29日 核算技术双轨并行发展... │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ [碳减排服务] 碳排放... │ │
|
||
│ │ 2025年5月29日 ... │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ ... │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ [1] [2] [3] [4] [5] [下一页] ← 分页 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 版权信息等 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**说明：**
|
||
- 搜索区域包含：分类下拉、搜索输入框、搜索按钮、热门搜索词
|
||
- 搜索历史在搜索区域下方显示（横向排列，右侧有"清除全部"）
|
||
- 分类Tab在分隔线下方，左对齐
|
||
- 结果列表单列展示，包含分类标签、标题、日期、摘要
|
||
- 无左侧边栏
|
||
|
||
### 2.3 组件列表
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| SearchView | 搜索结果页主组件（外层使用现有 Nav 组件） |
|
||
| SearchArea | 搜索区域（输入框+下拉+按钮+热门词） |
|
||
| SearchSuggestion | 搜索建议下拉 |
|
||
| SearchHistoryBar | 搜索历史横条（历史词+清除按钮） |
|
||
| SearchCategoryTabs | 分类Tab（全部/碳证中心/服务中心） |
|
||
| SearchResultList | 结果列表 |
|
||
| SearchResultItem | 结果项 |
|
||
| SearchPagination | 分页组件（复用 TDesign） |
|
||
| SearchEmpty | 空状态 |
|
||
| SearchLoading | 加载状态 |
|
||
|
||
> **Header/Nav 复用项目现有 `Nav` 组件**，搜索页只需开发 SearchArea 及以下部分
|
||
|
||
### 2.4 分类筛选
|
||
|
||
| 分类 | categoryType | 说明 |
|
||
|------|--------------|------|
|
||
| 全部 | all | 所有内容 |
|
||
| 碳证中心 | carbon_cert | 碳证相关 |
|
||
| 服务中心 | service | 服务市场、金融市场、需求市场、数据市场 |
|
||
| 行业专题 | news | 新闻资讯 |
|
||
|
||
### 2.5 搜索建议
|
||
|
||
触发方式：用户输入时，延迟 300ms 后请求（前端防抖）
|
||
限流：接口级别限流，相同关键词 1 分钟内不重复请求
|
||
数据来源：
|
||
- 用户输入匹配（模糊匹配标题/内容）
|
||
- 历史搜索词（取当前用户最近 10 条）
|
||
- 运营配置的热门词
|
||
|
||
---
|
||
|
||
## 3. 后端设计
|
||
|
||
### 3.1 技术栈
|
||
|
||
- Spring Boot
|
||
- MyBatis Plus
|
||
- Redis（缓存搜索历史、热门词）
|
||
|
||
### 3.2 接口设计
|
||
|
||
#### 3.2.1 搜索
|
||
|
||
```
|
||
GET /search?keyword=碳排放&categoryType=all&page=1&pageSize=10
|
||
|
||
参数说明：
|
||
- keyword: 搜索关键词（必填，最大 50 字符，需 XSS 过滤）
|
||
- categoryType: 分类筛选（all, carbon_cert, service, news）
|
||
- page: 页码（默认 1）
|
||
- pageSize: 每页条数（默认 10，最大 50）
|
||
|
||
Response:
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"total": 18,
|
||
"categoryCount": {
|
||
"all": 18,
|
||
"carbon_cert": 2,
|
||
"service": 16,
|
||
"news": 0
|
||
},
|
||
"list": [
|
||
{
|
||
"id": "xxx",
|
||
"title": "构建新型<em>碳排放</em>数据治理框架",
|
||
"summary": "核算技术双轨并行发展...",
|
||
"category": "行业专题",
|
||
"categoryType": "news",
|
||
"source": "碳证中心",
|
||
"sourceType": "carbon_cert",
|
||
"publishTime": "2025-05-29",
|
||
"url": "/gxzx/detail/xxx"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.2.2 搜索建议
|
||
|
||
```
|
||
GET /search/suggest?keyword=碳排
|
||
|
||
参数说明：
|
||
- keyword: 搜索关键词（必填，最大 50 字符）
|
||
|
||
Response:
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"suggestions": [
|
||
"碳排放",
|
||
"碳排放权",
|
||
"碳排放核算"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.2.3 热门搜索
|
||
|
||
```
|
||
GET /search/hot
|
||
|
||
Response:
|
||
{
|
||
"code": 0,
|
||
"data": [
|
||
"江苏电厂配额",
|
||
"林业碳汇开发",
|
||
"CBAM 报告",
|
||
"零碳展会"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3.2.4 搜索历史
|
||
|
||
```
|
||
GET /search/history
|
||
|
||
Response:
|
||
{
|
||
"code": 0,
|
||
"data": [
|
||
"碳排放",
|
||
"林业碳汇",
|
||
"CBAM"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3.2.5 清除搜索历史
|
||
|
||
```
|
||
DELETE /search/history
|
||
|
||
Response:
|
||
{
|
||
"code": 0,
|
||
"msg": ""
|
||
}
|
||
```
|
||
|
||
### 3.3 数据模型
|
||
|
||
#### 3.3.1 搜索结果（SearchResultVO）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String | 内容ID |
|
||
| title | String | 标题（关键词高亮，使用 `<em>` 标签） |
|
||
| summary | String | 摘要（截取前 200 字符） |
|
||
| thumbnail | String | 缩略图URL（可为空） |
|
||
| category | String | 分类标签（展示用，如"行业专题"） |
|
||
| categoryType | String | 分类类型（筛选用，如"news"） |
|
||
| source | String | 来源名称 |
|
||
| sourceType | String | 来源类型 |
|
||
| publishTime | String | 发布时间 |
|
||
| url | String | 跳转链接 |
|
||
|
||
#### 3.3.2 热门搜索配置（HotSearchConfig）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Long | 主键 |
|
||
| keyword | String | 关键词 |
|
||
| sort | Integer | 排序 |
|
||
| status | Integer | 状态（0禁用1启用） |
|
||
| startTime | LocalDateTime | 生效开始时间（可选） |
|
||
| endTime | LocalDateTime | 生效结束时间（可选） |
|
||
|
||
> 注：支持临时活动配置热门词，通过生效时间控制
|
||
|
||
#### 3.3.3 搜索历史（SearchHistory）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Long | 主键 |
|
||
| userId | String | 用户ID（登录用户） |
|
||
| deviceId | String | 设备ID（游客，用于关联未登录用户） |
|
||
| keyword | String | 搜索词 |
|
||
| searchTime | LocalDateTime | 搜索时间 |
|
||
|
||
> 注：搜索历史最多存储 20 条，超出后删除最早的记录
|
||
|
||
### 3.4 搜索聚合服务
|
||
|
||
由于目前各子系统还没有迁移，搜索聚合服务采用以下策略：
|
||
|
||
**阶段一（当前）**：
|
||
- 只搜索资讯中心 `/sy/zxxx` 的内容
|
||
- 数据直接存储在 txw-mhzc 中
|
||
|
||
**阶段二（子系统迁移后）**：
|
||
- 各子系统迁移到 txw-mhzc 后
|
||
- SearchAggregatorService 并行调用各子系统的搜索方法
|
||
- 聚合去重后返回
|
||
|
||
---
|
||
|
||
## 4. 文件结构
|
||
|
||
### 4.1 前端（txw-mhzc-web）
|
||
|
||
```
|
||
txw-mhzc-web/src/pages/index/
|
||
├── views/
|
||
│ └── search/
|
||
│ └── index.vue # 搜索结果页
|
||
├── components/
|
||
│ └── search/
|
||
│ ├── SearchArea.vue # 搜索区域
|
||
│ ├── SearchSuggestion.vue # 搜索建议下拉
|
||
│ ├── SearchHistoryBar.vue # 搜索历史横条
|
||
│ ├── SearchCategoryTabs.vue # 分类Tab
|
||
│ ├── SearchResultList.vue
|
||
│ └── SearchResultItem.vue
|
||
└── api/
|
||
└── search.js # 搜索接口
|
||
```
|
||
|
||
### 4.2 后端（txw-mhzc）
|
||
|
||
```
|
||
txw-mhzc/txw-mhzc-service-biz/src/main/java/com/css/txw/mhzc/
|
||
├── controller/
|
||
│ └── SearchController.java
|
||
├── service/
|
||
│ ├── SearchService.java
|
||
│ └── impl/
|
||
│ └── SearchServiceImpl.java
|
||
├── mapper/
|
||
│ └── SearchMapper.java
|
||
└── pojo/
|
||
├── dto/
|
||
│ └── SearchDTO.java
|
||
└── vo/
|
||
├── SearchReqVO.java
|
||
├── SearchResultVO.java
|
||
├── HotSearchConfig.java
|
||
└── SearchHistory.java
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 开发计划
|
||
|
||
### 5.1 第一阶段（预计 3 天）
|
||
|
||
| 任务 | 优先级 | 预估工时 |
|
||
|------|--------|----------|
|
||
| 前端：搜索页面基础结构 | P0 | 0.5d |
|
||
| 前端：搜索框组件 + 搜索建议 | P0 | 0.5d |
|
||
| 前端：左侧边栏（历史+热门+分类） | P0 | 0.5d |
|
||
| 前端：结果列表展示 | P0 | 0.5d |
|
||
| 前端：分类筛选 + 分页 | P0 | 0.5d |
|
||
| 后端：搜索接口（资讯中心）| P0 | 1d |
|
||
| 后端：搜索建议接口 | P1 | 0.5d |
|
||
| 后端：热门搜索接口 | P1 | 0.5d |
|
||
| 后端：搜索历史接口 | P1 | 0.5d |
|
||
| **前后端联调 + 测试** | P0 | 1d |
|
||
|
||
### 5.2 第二阶段（子系统迁移后）
|
||
|
||
- [ ] 后端：聚合其他子系统搜索
|
||
- [ ] 搜索结果去重优化
|
||
- [ ] 搜索权重配置
|
||
|
||
### 5.3 数据埋点（可后续迭代）
|
||
|
||
- 搜索关键词上报
|
||
- 搜索结果点击上报
|
||
- 热门词曝光点击统计
|
||
|
||
---
|
||
|
||
## 6. 待确认
|
||
|
||
1. ~~ 搜索结果高亮标签使用 `<em>` 还是其他？~~ → **使用 `<em>`**
|
||
2. ~~每个分类的数量是否需要实时从后端获取？~~ → **随搜索结果一起返回，在 data.categoryCount 中**
|
||
3. 搜索结果点击后跳转到原详情页，详情页是否需要开发？ → **由各子系统详情页处理，搜索只提供 URL**
|