# 全站搜索功能设计文档

## 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**