feat: 搜索实现spec技术方案
This commit is contained in:
parent
8fa426644f
commit
8423f61a3f
@ -32,8 +32,6 @@ yarn dev
|
|||||||
| `txw-gxzx-web` | 个人工作台 |
|
| `txw-gxzx-web` | 个人工作台 |
|
||||||
| `txw-kxtfwzx-web` | 科学碳体重中心 |
|
| `txw-kxtfwzx-web` | 科学碳体重中心 |
|
||||||
| `txw-mhzc-web` | 碳门户主页 |
|
| `txw-mhzc-web` | 碳门户主页 |
|
||||||
| `txw-tzzx-web` | 碳资讯 |
|
|
||||||
| `txw-ytzx-web` | 碳云学堂 |
|
|
||||||
| `txw-yygl-web` | 运营管理 |
|
| `txw-yygl-web` | 运营管理 |
|
||||||
| `local-nodemodules` | 本地私有包（ggzc-web 组件库） |
|
| `local-nodemodules` | 本地私有包（ggzc-web 组件库） |
|
||||||
|
|
||||||
|
|||||||
1709
docs/superpowers/plans/2026-04-10-search-plan.md
Normal file
1709
docs/superpowers/plans/2026-04-10-search-plan.md
Normal file
File diff suppressed because it is too large
Load Diff
359
docs/superpowers/specs/2026-04-10-search-design.md
Normal file
359
docs/superpowers/specs/2026-04-10-search-design.md
Normal file
@ -0,0 +1,359 @@
|
|||||||
|
# 全站搜索功能设计文档
|
||||||
|
|
||||||
|
## 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**
|
||||||
@ -1,35 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 复制 git 变更文件到 change 目录，保留原文件相对路径
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
TARGET_DIR="change"
|
|
||||||
|
|
||||||
# 创建目标目录
|
|
||||||
mkdir -p "$TARGET_DIR"
|
|
||||||
|
|
||||||
# 获取所有变更文件（包含未跟踪文件）
|
|
||||||
files=$(git status --porcelain | awk '{print $2}')
|
|
||||||
|
|
||||||
if [ -z "$files" ]; then
|
|
||||||
echo "没有变更文件"
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
count=0
|
|
||||||
for f in $files; do
|
|
||||||
# 跳过目录（如 docs/）
|
|
||||||
if [ -d "$f" ]; then
|
|
||||||
mkdir -p "$TARGET_DIR/$f"
|
|
||||||
cp -r "$f" "$TARGET_DIR/$f"
|
|
||||||
echo "✓ $f/"
|
|
||||||
elif [ -f "$f" ]; then
|
|
||||||
mkdir -p "$TARGET_DIR/$(dirname "$f")"
|
|
||||||
cp "$f" "$TARGET_DIR/$f"
|
|
||||||
echo "✓ $f"
|
|
||||||
((count++))
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
echo "已完成，复制了 $count 个文件到 $TARGET_DIR 目录"
|
|
||||||
Loading…
Reference in New Issue
Block a user