update

design/specs/2026-04-11-tool-manual-detail-page-design.md

@@ -0,0 +1,100 @@
+# 用户手册详情页设计规格
+
+## 概述
+
+当前访客端首页通过弹窗展示工具详情，适合快速浏览，但不适合作为稳定的用户手册阅读入口。现有工具数据中的 `description` 字段已经支持 Markdown 渲染，因此可以直接复用它承载用户手册内容，无需新增数据库字段。
+
+本次设计目标是在现有公开站点中增加一个正式的详情页入口，替换原有弹窗。详情页使用工具的 `slug` 作为公开访问标识，支持站内路由直达、长篇 Markdown 阅读、空内容状态、404 状态和明确的返回入口，使其可以长期承担“工具介绍 + 用户手册”的双重职责。
+
+## 目标定位
+
+- **主要用户**：普通访客
+- **使用场景**：访客从工具列表点击“详情”进入独立页面，阅读工具说明、能力介绍和 Markdown 格式的用户手册；也支持用户直接访问详情页链接
+
+## 约束条件
+
+- **技术限制**：前端基于 Vue 3 + vue-router，主站与管理端共用同一路由实例；后端基于 NestJS + Prisma；Markdown 渲染复用现有 `marked + DOMPurify` 能力；用户手册内容先复用 `Tool.description`
+- **时间限制**：本轮以增量改造为主，不引入新的内容模型，不重做管理端工具编辑流程
+- **资源限制**：仅在现有项目代码结构内完成，避免增加新依赖或引入第二套公开站点入口
+
+## 成功标准
+
+- [ ] 访客在首页点击“详情”后进入新的站内详情页，不再弹出旧弹窗
+- [ ] 详情页路由使用 `slug`，可通过 URL 直达访问
+- [ ] 详情页能够稳定展示 `description` Markdown、基础元信息和功能点，适合作为长期手册页面
+- [ ] 当工具不存在时展示明确的 404 状态；当 `description` 为空时展示清晰的空内容提示
+- [ ] 对于较长 Markdown 内容，页面具备目录感和良好的阅读体验，用户可以快速回到列表或继续执行“打开网页/下载”操作
+
+## 架构设计
+
+### 系统结构
+
+本次改造保持单一公开站点结构不变，在现有 `vue-router` 中新增公开详情路由。前端首页仍负责列表、筛选和跳转；详情页负责根据 `slug` 拉取数据并渲染完整内容。后端在保留现有按 `id` 获取详情接口的前提下，新增按 `slug` 查询的公开详情接口，避免影响既有逻辑，并为长期公开链接提供稳定入口。
+
+详情页信息结构分为三层：
+
+1. 页面顶部：返回列表、工具名称、分类、更新时间、主操作按钮
+2. 信息摘要区：评分、访问方式、下载/访问次数、版本、标签、核心能力
+3. 手册正文区：将 `description` 作为 Markdown 正文渲染，并为长文提供标题导航或可跳转的章节锚点
+
+### 组件划分
+
+| 组件 | 职责 | 依赖 |
+|------|------|------|
+| `client/src/App.vue` | 保留首页列表、筛选和分页；将“详情”按钮改为路由跳转；移除旧详情弹窗状态与模板 | `vue-router`, `client/src/api.js` |
+| `client/src/pages/ToolDetailPage.vue` | 详情页容器；根据 `slug` 拉取详情数据；处理加载、404、空内容、长文阅读与返回入口 | `vue-router`, `client/src/api.js`, `client/src/utils/markdown.js` |
+| `client/src/api.js` | 新增按 `slug` 获取详情的方法；复用已有错误处理与启动行为 | Axios |
+| `client/src/utils/markdown.js` | 继续负责安全渲染 Markdown；可扩展标题提取或锚点处理，支持长文目录体验 | `marked`, `DOMPurify` |
+| `client/src/admin/components/ToolFormDialog.vue` | 保持数据录入入口不变；若实施时顺手优化文案，可将简介提示改为更明确的“支持手册 Markdown” | Element Plus |
+| `server/src/modules/tools/tools.controller.ts` | 新增按 `slug` 获取公开详情的接口 | `ToolsService` |
+| `server/src/modules/tools/tools.service.ts` | 新增按 `slug` 查询已发布工具详情的方法，并复用现有详情映射逻辑 | Prisma |
+
+## 数据流
+
+首页进入详情页的数据流如下：
+
+1. 首页加载工具列表，列表项已带有 `id` 和 `slug`
+2. 用户点击“详情”按钮
+3. 前端通过路由跳转到 `/tools/:slug`
+4. 详情页组件从路由参数读取 `slug`
+5. 前端调用新的公开接口，例如 `GET /api/v1/tools/slug/:slug`
+6. 后端按 `slug + status=published + isDeleted=false` 查询工具
+7. 查询成功后返回详情数据，包括 `description`、`features`、分类、评分、访问方式、访问量/下载量、版本等
+8. 前端渲染详情页摘要区和 Markdown 正文；若正文存在标题，则生成目录锚点或章节导航
+9. 用户可从详情页返回首页，或继续点击“打开网页/下载”执行现有 launch 流程
+
+长文阅读的数据处理建议如下：
+
+1. 详情页获取 Markdown 原文
+2. 使用现有 Markdown 解析能力渲染 HTML
+3. 在渲染前或渲染时提取标题层级，生成页面内目录
+4. 为标题生成稳定锚点，支持目录点击跳转
+5. 若正文无标题，则不显示目录，保留清晰的文章排版和回顶能力
+
+## 错误处理
+
+| 错误类型 | 处理方式 |
+|----------|----------|
+| 详情接口加载中 | 展示页面级骨架或加载态，不显示旧弹窗 |
+| `slug` 对应工具不存在 | 展示 404 状态页，包含返回首页入口 |
+| 工具存在但 `description` 为空 | 展示“暂未提供用户手册”空状态，同时仍保留工具摘要信息和主操作按钮 |
+| 接口请求失败 | 展示页面级错误提示，提供重试操作和返回首页入口 |
+| Markdown 内容很长 | 启用目录/锚点导航、限制正文宽度、保证标题层级和段落间距，避免整页难以浏览 |
+| 从详情页执行打开或下载失败 | 复用现有 `launchTool` 和错误提示逻辑，不在详情页定义第二套行为 |
+
+## 测试策略
+
+- **单元测试**：校验按 `slug` 查询详情的服务方法；校验 Markdown 标题提取或目录生成逻辑；校验空内容和 404 的状态判断
+- **集成测试**：覆盖公开详情接口按 `slug` 返回已发布工具；覆盖不存在 `slug` 时返回 404；覆盖详情页直达访问、列表跳转访问和返回行为
+- **验收标准**：从首页点击“详情”可稳定进入 `/tools/:slug`；直达链接可用；长篇 Markdown 有清晰阅读结构；空内容、404、请求失败均有明确页面反馈；旧详情弹窗已移除
+
+## 决策记录
+
+| 决策 | 理由 | 影响 |
+|------|------|------|
+| 详情页采用站内路由而不是新标签页 | 用户明确要求站内跳转，且可形成连续阅读路径 | 前端需新增公开详情路由 |
+| 详情页公开地址使用 `slug` | `slug` 已存在且唯一，适合长期公开链接和分享 | 后端需新增按 `slug` 查询接口，前端详情页按 `slug` 加载 |
+| 用户手册先复用 `description` 字段 | 当前已支持 Markdown，避免新增数据库字段和后台复杂度 | 本轮不做数据模型迁移 |
+| 旧弹窗详情被新详情页替换 | 用户希望详情入口统一，避免双入口维护 | 首页需移除弹窗模板和相关状态 |
+| 长文阅读加入目录感设计 | 用户明确要求处理超长 Markdown 的阅读体验 | 详情页和 Markdown 工具层需要支持标题导航或锚点 |
+| 现有按 `id` 的详情接口保留，新增长期用的 `slug` 接口 | 兼容已有内部调用，减少回归风险 | 后端存在两个公开详情查询入口，但职责清晰 |