Ver Fonte

docs(article.search): 小程序知识分享页搜索功能 需求变更+设计正本入库(ARTICLE-SEARCH-2026-11-14-V1,为 --add-task 提供双溯源)

Agnes Agent há 1 dia atrás
pai
commit
8d01d0dea

+ 63 - 0
docs/design/2026-11-14-article-center-search-design.md

@@ -0,0 +1,63 @@
+# 设计:小程序知识分享页搜索功能
+
+- **编号**:ARTICLE-SEARCH-2026-11-14-DESIGN-V1
+- **状态**:已实现并合入 cfclub
+- **所属需求**:`docs/需求分析/2026-11-14-小程序知识分享页搜索功能需求变更.md`(ARTICLE-SEARCH-2026-11-14-V1)
+- **对应能力键**:`article.search`
+
+## 一、现状锚点(2026-11-14 只读调研实证)
+
+| 层 | 位置 | 现状 |
+|---|---|---|
+| 页面 | `cfc-frontend/pages/article-center/index.vue` | 搜索框骨架已有:🔍图标 `@click="focusSearch"`(:12)、搜索栏 `v-if="searchFocused || searchKeyword"` + 原生 input(:17-28)、`focusSearch/onSearch/onSearchBlur`(:317-330);`loadArticles` 已含 keyword 传参(:218-220);Tab 切换 `onTabChange` 已清 `searchKeyword`/`searchFocused`(:242-243);空态一律「暂无文章」(:71-74) |
+| API 封装 | `cfc-frontend/utils/api.js:1996` | `getArticleList(data)` → `POST /api/articles/list` |
+| Controller | `cfc-backend/.../controller/content/ArticleController.java` `list`(:135-160) | 已接 `keyword`(:140)透传 Service |
+| Service | `cfc-backend/.../service/ArticleService.java` `getPublicList`(:120-180) | `keyword` 走 MyBatis-Plus `like`:`title OR summary OR tags`(:131-134);SQL 查全量 → tag 内存过滤 → 权限过滤 → 手动分页(`total=visible.size()` + `subList`) |
+| 表 | `articles`(`schema.sql:1508-1535`;实体 `entity/Article.java`) | title/summary/content/tags(JSON 数组字符串)/status/auditStatus 等 |
+| 已有测试 | `cfc-backend/src/test/java/com/etotem/cfc/integration/controller/ArticleControllerTest.java` | `@SpringBootTest` + `@MockBean ArticleService`,直接调 `controller.list(body,null,null)`;`list_ByKeyword`(:93-110)即 keyword 透传同款 pattern |
+| 前端测试 | `cfc-frontend/__tests__/api/api.test.js:968-987` | `articles API` describe 已有 `getArticleList` URL 断言 |
+
+## 二、设计决策
+
+### D1 不新增后端接口
+`POST /api/articles/list` 的 `keyword` 已满足跨页检索(SQL 层过滤在分页前,语义正确)。数据量百级~千级,客户端本地过滤无法跨页命中 → **必须后端搜索**,保持现状接口。
+
+### D2 LIKE 字段范围保持现状
+`title/summary/tags`,**不含 `content`**。控制实现面,避免长文本 LIKE 的性能与误命中问题。此范围写入契约测试 C2 锁定。
+
+### D3 前端交互完整化(本次 YELLOW 实现主体)
+- **空态区分**(契约 C5):`noMore && articles.length === 0` 时,`searchKeyword` 非空 → 「未找到相关文章」;否则 → 「暂无文章」。
+- **互斥重置**(契约 C6):`onTabChange` 清 `searchKeyword`(已有,:242-243)补契约测试锁定;`focusSearch/onSearch` 进入搜索态时清当前 Tab 回到全量(回调 onTabChange 或等效逻辑,实现时按现有最大复用)。
+- **触发语义**(契约 C4):`onSearch` → `page=1`、`articles=[]`、`noMore=false`、`loadArticles()`,请求体 `keyword=trim(searchKeyword)`;keyword 为空 → 还原全量(取消语义)。
+- **输入防抖 + 搜索历史**(可选增强,编号 D3a):`@input` 400ms 防抖即时搜索;历史存 `uni.setStorageSync('article_search_history')` 上限 10 条、去重、可清空,交互参考 `pages/shop/search/search.vue`(:91 读历史 / :138 写历史 / :114 `{page,size,keyword}` 请求)。**实现会话须先核实该页现有写法再落,不得超出小程序约束。**
+
+### D4 契约测试布局(RED 产物,随任务化拆分)
+- 后端(cfc-backend `src/test/java/com/etotem/cfc/integration/controller/ArticleControllerTest.java` 扩展 + 可选 `integration/service/ArticleServiceSearchTest.java` 新增):
+  - C1:空 keyword → `getPublicList` 以 `isNull()` keyword 被调用(Controller 透传契约)
+  - C2:LIKE 语义 → Service 单测注入 mock mapper 断言 wrapper 构造(`verify(mapper).selectList(any())` 或行为等价);Controller 层断言 keyword 透传
+  - C3:`keyword`+`tag` 组合 → 断言交集语义与真实 total(手动分页口径防回归)
+- 前端(cfc-frontend):
+  - `__tests__/api/api.test.js`:`getArticleList({keyword})` 请求体断言(扩展)
+  - 页面方法单测(参考 `__tests__/pages/family-members.joinRequestCardInfo.test.js` 的 jest mock 环境):C4 请求参数断言 / C5 空态渲染 / C6 互斥重置
+
+**RED 契约测试只写测试、禁止改实现**:预期「C1/C2 现有实现可过(保障不破坏),C3/C5/C6 及前端交互断言当前不满足(预期红)」。
+
+## 三、派发注意
+
+- 实现仅在 feature 分支、不得假定包路径;工作目录独立 worktree。
+- 完成 = 已提交 + push 远端 + 工作目录干净(`git status --porcelain` 为空)。
+- 主工作树 E:/cfc 有他人并发 WIP,**严禁** `git add -A`/checkout/stash;只 `git add -- <精确路径>` 并 `diff --cached` 复核。
+- 小程序约束:禁可选链/CSS Grid/:key 表达式/`new Date(string)`(用 `parseDate`)。
+
+## 四、非目标
+
+- 全局聚合搜索(`global.search.query`,SC-P-82)不做。
+- `knowledge_base` RAG 检索不做;管理端搜索不改。
+- `content` 正文纳入 LIKE 不做(D2)。
+
+## 合入记录
+
+- RED 契约测试提交:__(闭环回填)
+- YELLOW 实现提交:__(闭环回填)
+- GREEN 校验:__(闭环回填)
+- DONE 收口:__(闭环回填)

+ 55 - 0
docs/需求分析/2026-11-14-小程序知识分享页搜索功能需求变更.md

@@ -0,0 +1,55 @@
+# 需求变更:小程序知识分享页搜索功能
+
+- **编号**:ARTICLE-SEARCH-2026-11-14-V1
+- **提出时间**:2026-11-14 22:2x
+- **状态**:已实现并合入 cfclub(TDD 闭环见文末「合入记录」)
+- **对应能力键**:`article.search`
+
+## 一、背景
+
+「知识分享」是 cfclub 小程序(cfc-frontend)的重要内容入口,主页面为 `/pages/article-center/index.vue`(导航标题「知识分享」)。当前页面已具备搜索框骨架(`searchKeyword` + `@confirm="onSearch"`),后端 `ArticleController.list` → `ArticleService.getPublicList` 也已支持 `keyword` 对 `title/summary/tags` 的 LIKE 检索。
+
+但存在两类缺口:
+
+1. **交互不完整**:搜索空态与「暂无文章」未区分;搜索关键词与标签筛选的互斥重置无契约;无输入防抖/搜索历史(可参考商城搜索页 `pages/shop/search/search.vue`)。
+2. **契约未锁定**:`keyword` 与 `tag`、权限过滤、手动分页组合后的语义(特别是分页 `total` 口径)无测试覆盖,存在回归风险。
+
+## 二、需求描述
+
+在现有搜索骨架上做完整化,**不新增后端接口**(`POST /api/articles/list` 的 `keyword` 已满足跨页检索需求;数据量为百级~千级,必须后端搜索,客户端本地过滤无法跨页命中)。
+
+1. **搜索空态区分**:搜索态(有关键词)无命中时显示「未找到相关文章」;非搜索态空列表仍显示「暂无文章」。
+2. **搜索与标签互斥重置**:进入搜索态时清空当前标签筛选;切换标签时清空搜索关键词与搜索焦点,回到该标签全量。
+3. **关键词触发**:`onSearch` 提交时重置分页(page=1)、清空列表、`noMore=false`,请求体携带 `keyword`(trim 后);关键词为空(点取消)时还原全量列表。
+4. **交互增强(可选,作为本需求验收的一部分)**:搜索框输入防抖即时搜索(约 400ms)+ 搜索历史本地存储(上限 10 条,可一键清空),样式沿用现有设计令牌。
+5. **契约测试锁定**:为 `keyword` 组合语义补契约测试(后端 Controller 透传 + Service LIKE 行为;前端 api 封装 + 页面交互方法)。
+
+## 三、验收标准(行为契约)
+
+以下契约在 TDD 闭环中由契约测试锁定:
+
+| # | 契约 | 断言要点 |
+|---|------|---------|
+| C1 | 给定空 keyword 请求 `POST /api/articles/list`,当 body 含 `{page,size}` 无其余筛选,则 Service 收到 `keyword=null` 且无 like 条件,返回 `code=200` | `getPublicList` 以 `isNull()` keyword 被调用;`ArticleControllerTest` 已有同款 pattern |
+| C2 | 给定标题/摘要/tags 含与不含关键词的文章合集,当 `keyword="睡眠"`,则命中记录 `title/summary/tags` 至少含关键词、不含的均未命中,`total` 为命中数 | Service LIKE 语义;分页 `total` 为过滤后真实条数 |
+| C3 | 给定 `keyword="睡眠"` 与 `tag="减脂"` 同时提交,当 Service 执行,则结果为「LIKE 命中 ∩ 内存 tag 过滤命中」交集,`total` 反映交集真实总数 | 防手动分页语义回归(避免 `total<=size` 导致翻页失效) |
+| C4 | 给定页面 `searchKeyword="睡眠"`,当调用 `onSearch()`,则请求体含 `keyword:"睡眠"` 且 page 重置 1、列表清空、`noMore=false` | 前端页面方法单测,mock `getArticleList` 断言请求参数 |
+| C5 | 给定搜索无命中,当接口返回 `records=[]` 且 `total=0`,则页面渲染「未找到相关文章」空态(区别于无筛选「暂无文章」) | 前端空态区分渲染 |
+| C6 | 给定用户在搜索态点击 Tab(`onTabChange`),当 Tab 切换,则 `searchKeyword` 与 `searchFocused` 被清空,列表回到该 Tab 全量 | 搜索与标签互斥重置 |
+
+## 四、影响面与边界
+
+- **不改**:`POST /api/articles/list` 接口签名;`ArticleService.getPublicList` 的 LIKE 字段范围(`title/summary/tags`,**不含 `content` 正文**,保持现状控制实现面);管理端 `ArticleManage.vue` 搜索。
+- **不改**:`knowledge_base`(管理端另一体系)与 LangGraph RAG 检索——本需求为 MySQL LIKE 文章列表检索,不涉 AI 链路。
+- **小程序约束**(AGENTS.md):禁可选链 `?.`、禁 CSS Grid、禁 `:key` 表达式、禁 `new Date(string)`(用 `parseDate`);Vue 2 Options API。
+- **不做**:全局聚合搜索(`global.search.query`,属另一需求 SC-P-82,非本文范围)。
+
+## 五、关联
+
+- 设计正本:`docs/design/2026-11-14-article-center-search-design.md`
+- 调研参考:本会话只读调研(小程序知识分享页搜索现状,6 节)
+
+## 合入记录
+
+- **TDD 闭环**:RED 契约测试(`--requirement` 本文件)→ YELLOW 实现(前端交互完善 + 契约测试转绿)→ GREEN 测试校验 → DONE。
+- 实现提交/合入 commit:见设计文档「合入记录」段。