feat: 搜索实现spec技术方案

2026-04-10 16:24:32 +08:00 · 2026-04-10 16:24:32 +08:00 · 8423f61a3f
commit 8423f61a3f
parent 8fa426644f
4 changed files with 2068 additions and 37 deletions
--- a/README.md
+++ b/README.md
@ -32,8 +32,6 @@ yarn dev
 | `txw-gxzx-web` | 个人工作台 |
 | `txw-kxtfwzx-web` | 科学碳体重中心 |
 | `txw-mhzc-web` | 碳门户主页 |
-| `txw-tzzx-web` | 碳资讯 |
-| `txw-ytzx-web` | 碳云学堂 |
 | `txw-yygl-web` | 运营管理 |
 | `local-nodemodules` | 本地私有包（ggzc-web 组件库） |

--- a/docs/superpowers/plans/2026-04-10-search-plan.md
+++ b/docs/superpowers/plans/2026-04-10-search-plan.md
--- a/docs/superpowers/specs/2026-04-10-search-design.md
+++ b/docs/superpowers/specs/2026-04-10-search-design.md
@ -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**
--- a/script/copy-changed-files.sh
+++ b/script/copy-changed-files.sh
@ -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 目录"