xiaoyu/txw

Fork 0

liulujian 8423f61a3f feat: 搜索实现spec技术方案

2026-04-10 16:24:32 +08:00

11 KiB

Raw Blame History

全站搜索功能设计文档

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. 待确认

~~ 搜索结果高亮标签使用 <em> 还是其他？~~ → 使用 <em>
~~每个分类的数量是否需要实时从后端获取？~~ → 随搜索结果一起返回，在 data.categoryCount 中
搜索结果点击后跳转到原详情页，详情页是否需要开发？ → 由各子系统详情页处理，搜索只提供 URL

11 KiB Raw Blame History Unescape Escape