用户手册详情页实施计划

目标：将访客端原有详情弹窗替换为基于 slug 的独立详情页，使 description 可以长期作为 Markdown 用户手册展示，并补齐直达访问、空内容、404 和长文阅读体验。

架构：本次为单一功能子系统改造，不创建纲领文件。后端先补齐按 slug 查询已发布工具的公开详情能力，再由前端新增公开详情页路由和页面组件，最后替换首页详情入口并完善长文阅读样式与测试。前端测试基建当前缺失，因此计划第一步先补齐 Vitest + Vue Test Utils + jsdom，确保后续页面改造遵循测试优先。

技术栈：Vue 3、vue-router、Vite、Vitest、Vue Test Utils、NestJS、Prisma、Jest、Supertest、marked、DOMPurify

文件结构

新建文件

client/vitest.config.js - 前端测试配置，提供 Vue SFC 和 jsdom 运行环境
注释需求：低优先级，配置项仅在非直观处补简短说明
复杂度：低
client/src/test/setup.js - 前端测试初始化，挂载全局匹配器、滚动和路由相关基础 mock
注释需求：中优先级，需要说明全局 mock 的用途
复杂度：中
client/src/utils/markdown-outline.js - 提取 Markdown 标题、生成稳定锚点和目录结构
注释需求：高优先级，需要为重复标题去重和锚点规范化逻辑添加说明
复杂度：中
client/src/utils/markdown-outline.spec.js - 验证目录提取、标题去重和无标题场景
注释需求：低优先级
复杂度：中
client/src/pages/ToolDetailPage.vue - 公开详情页，负责按 slug 拉取详情、渲染摘要和 Markdown 手册、处理空状态/404/返回入口
注释需求：高优先级，需要在状态流转和 launch 复用入口处补说明
复杂度：高
client/src/pages/ToolDetailPage.spec.js - 详情页组件测试，覆盖加载态、404、空内容、目录和主操作按钮
注释需求：低优先级
复杂度：高
client/src/App.spec.js - 首页交互测试，覆盖详情按钮跳转和旧弹窗移除
注释需求：低优先级
复杂度：中
server/src/modules/tools/tools.service.spec.ts - 后端服务单测，覆盖按 slug 查询详情的业务规则
注释需求：低优先级
复杂度：中
server/test/tools-detail.e2e-spec.ts - 公开详情接口 e2e，覆盖成功命中和 404
注释需求：中优先级，需要说明测试数据准备和清理
复杂度：中

修改文件

client/package.json - 增加前端测试脚本和测试依赖声明
注释需求：低优先级
复杂度：低
client/package-lock.json - 锁定前端测试依赖版本
注释需求：无
复杂度：低
client/src/api.js - 新增按 slug 获取详情的方法，复用现有错误和 launch 行为
注释需求：中优先级，需要说明新接口和旧按 id 接口的职责差异
复杂度：中
client/src/admin/router.js - 增加公开详情页路由 /tools/:slug
注释需求：低优先级
复杂度：低
client/src/App.vue - 移除详情弹窗状态和模板，将详情入口改为路由跳转
注释需求：中优先级，需要说明首页仅负责列表和跳转，不再持有详情状态
复杂度：高
client/src/style.scss - 增加详情页布局、目录、空状态、404 和长文阅读样式
注释需求：低优先级
复杂度：高
client/src/admin/components/ToolFormDialog.vue - 微调“工具简介”提示文案，明确其可承载 Markdown 手册内容
注释需求：低优先级
复杂度：低
server/src/modules/tools/tools.service.ts - 抽出详情映射逻辑，新增按 slug 查询已发布工具详情的方法
注释需求：高优先级，需要说明 id 与 slug 两套公开查询入口的职责分层
复杂度：中
server/src/modules/tools/tools.controller.ts - 新增按 slug 获取公开详情的接口
注释需求：低优先级
复杂度：低

测试文件

client/src/utils/markdown-outline.spec.js - 验证 Markdown 目录提取和锚点生成规则
client/src/pages/ToolDetailPage.spec.js - 验证详情页数据状态和长文阅读体验
client/src/App.spec.js - 验证首页详情入口从弹窗切为路由跳转
server/src/modules/tools/tools.service.spec.ts - 验证按 slug 查询的业务规则
server/test/tools-detail.e2e-spec.ts - 验证公开详情接口路由行为

任务列表

任务 1：建立前端测试基建和 Markdown 目录工具

文件：

创建：client/vitest.config.js
创建：client/src/test/setup.js
创建：client/src/utils/markdown-outline.js
测试：client/src/utils/markdown-outline.spec.js
修改：client/package.json
修改：client/package-lock.json
步骤 1：在 client/package.json 中增加 test、test:run 脚本和 vitest、@vue/test-utils、jsdom 等依赖声明；创建 client/vitest.config.js、client/src/test/setup.js；编写 client/src/utils/markdown-outline.spec.js，先描述标题提取、重复标题去重、无标题返回空目录的失败用例。
步骤 2：运行 npm --prefix client install；随后运行 npm --prefix client run test:run -- client/src/utils/markdown-outline.spec.js，预期输出为测试失败，原因是 markdown-outline.js 尚未实现或断言不满足。
步骤 3：创建 client/src/utils/markdown-outline.js，实现 extractMarkdownOutline 和稳定锚点生成逻辑，保证只提取正文标题并对重复标题追加序号。
步骤 4：再次运行 npm --prefix client run test:run -- client/src/utils/markdown-outline.spec.js，预期输出 1 passed，前端测试基建可用。

任务 2：实现后端按 `slug` 查询详情的服务层能力

文件：

创建：server/src/modules/tools/tools.service.spec.ts
修改：server/src/modules/tools/tools.service.ts
步骤 1：编写 server/src/modules/tools/tools.service.spec.ts，覆盖已发布工具可按 slug 查询、未发布工具不可见、缺失工具抛出 404、详情映射字段与现有按 id 详情保持一致的失败测试。
步骤 2：运行 npm --prefix server test -- --runTestsByPath src/modules/tools/tools.service.spec.ts，预期输出为编译失败或测试失败，因为 getToolDetailBySlug 及共享映射尚未存在。
步骤 3：在 server/src/modules/tools/tools.service.ts 中抽出详情映射方法，新增 getToolDetailBySlug(slug: string)，查询条件限定为 status=published、isDeleted=false，并复用现有详情返回结构。
步骤 4：再次运行 npm --prefix server test -- --runTestsByPath src/modules/tools/tools.service.spec.ts，预期输出 Test Suites: 1 passed。

任务 3：补齐公开详情 `slug` 接口和后端 e2e

文件：

创建：server/test/tools-detail.e2e-spec.ts
修改：server/src/modules/tools/tools.controller.ts
步骤 1：编写 server/test/tools-detail.e2e-spec.ts，准备一条已发布工具测试数据，定义 GET /tools/slug/:slug 成功返回详情和未知 slug 返回 404 的失败测试。
步骤 2：运行 npm --prefix server run test:e2e -- --runTestsByPath test/tools-detail.e2e-spec.ts，预期输出为 404 或断言失败，因为控制器路由尚未暴露该接口。
步骤 3：在 server/src/modules/tools/tools.controller.ts 中新增 GET /tools/slug/:slug 路由，调用 toolsService.getToolDetailBySlug；按需要调整 e2e 中的测试数据清理，避免污染现有数据。
步骤 4：再次运行 npm --prefix server run test:e2e -- --runTestsByPath test/tools-detail.e2e-spec.ts，预期输出 1 passed 或 2 passed，接口直达行为稳定。

任务 4：新增公开详情页路由、API 接入和页面状态

文件：

创建：client/src/pages/ToolDetailPage.vue
测试：client/src/pages/ToolDetailPage.spec.js
修改：client/src/api.js
修改：client/src/admin/router.js
步骤 1：编写 client/src/pages/ToolDetailPage.spec.js，覆盖按路由 slug 拉取详情、加载态、404 提示、空内容提示、返回首页入口以及主操作按钮展示的失败测试。
步骤 2：运行 npm --prefix client run test:run -- client/src/pages/ToolDetailPage.spec.js，预期输出为模块不存在或多个断言失败，因为详情页组件、路由和新 API 方法尚未实现。
步骤 3：在 client/src/api.js 中新增 fetchToolDetailBySlug(slug)；在 client/src/admin/router.js 中增加公开路由 /tools/:slug；创建 client/src/pages/ToolDetailPage.vue，完成按 slug 加载数据、页面级加载/错误/404/空内容状态和返回入口，并复用现有 launch 行为。
步骤 4：再次运行 npm --prefix client run test:run -- client/src/pages/ToolDetailPage.spec.js，预期输出 1 passed，详情页基础行为成立。

任务 5：替换首页详情弹窗为路由跳转

文件：

创建：client/src/App.spec.js
修改：client/src/App.vue
步骤 1：编写 client/src/App.spec.js，覆盖“详情”按钮改为跳转到 /tools/:slug、旧详情弹窗 DOM 不再渲染、首页仍保留概览弹窗的失败测试。
步骤 2：运行 npm --prefix client run test:run -- client/src/App.spec.js，预期输出为断言失败，因为首页仍然保留 openDetailModal 流程和旧弹窗模板。
步骤 3：修改 client/src/App.vue，移除 detailModalOpen/detailLoading/detailError/detail 等状态及弹窗模板，将详情按钮改为 router.push 或 RouterLink 跳转，并保留列表、筛选和概览弹窗逻辑不变。
步骤 4：再次运行 npm --prefix client run test:run -- client/src/App.spec.js client/src/pages/ToolDetailPage.spec.js，预期输出全部通过，首页到详情页的主链路打通。

任务 6：完善长文阅读体验、后台提示文案和整体验证

文件：

修改：client/src/style.scss
修改：client/src/pages/ToolDetailPage.vue
修改：client/src/pages/ToolDetailPage.spec.js
修改：client/src/admin/components/ToolFormDialog.vue
步骤 1：扩展 client/src/pages/ToolDetailPage.spec.js，新增目录渲染、无标题时不显示目录、长文时保留清晰段落层级和返回入口的失败测试。
步骤 2：运行 npm --prefix client run test:run -- client/src/pages/ToolDetailPage.spec.js，预期输出为目录相关断言失败，因为页面尚未接入目录工具和阅读态样式。
步骤 3：修改 client/src/pages/ToolDetailPage.vue 和 client/src/style.scss，接入 extractMarkdownOutline、渲染目录导航、优化正文宽度/标题层级/锚点区块；同步修改 client/src/admin/components/ToolFormDialog.vue 的简介提示文案，明确其支持 Markdown 手册内容。
步骤 4：依次运行 npm --prefix client run test:run -- client/src/utils/markdown-outline.spec.js client/src/pages/ToolDetailPage.spec.js client/src/App.spec.js、npm --prefix client run build、npm --prefix server test -- --runTestsByPath src/modules/tools/tools.service.spec.ts、npm --prefix server run test:e2e -- --runTestsByPath test/tools-detail.e2e-spec.ts，预期输出均为通过，且客户端构建成功无报错。

执行顺序说明

先补前端测试基建，否则后续页面任务无法按 TDD 执行。
后端先做服务层，再做控制器和 e2e，可减少路由级调试成本。
前端先完成详情页自身状态，再替换首页入口，避免“按钮先改了但页面未就绪”。
长文阅读体验放在最后收口，避免样式和目录逻辑反复返工。

风险提示

前端当前没有测试依赖，任务 1 会同时引入测试脚手架和锁文件变更。
App.vue 体量较大，任务 5 需要谨慎删除旧弹窗状态，避免误伤概览弹窗和列表筛选逻辑。
slug 接口与按 id 接口将同时存在，任务 2 和任务 3 需要确保两者返回结构一致，避免前端出现双标准。
e2e 测试需要自行准备和清理工具数据，避免依赖现有 seed 内容导致测试不稳定。

12 KiB Raw Blame History Unescape Escape