用户手册详情页设计规格

概述

当前访客端首页通过弹窗展示工具详情，适合快速浏览，但不适合作为稳定的用户手册阅读入口。现有工具数据中的 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 查询的公开详情接口，避免影响既有逻辑，并为长期公开链接提供稳定入口。

详情页信息结构分为三层：

页面顶部：返回列表、工具名称、分类、更新时间、主操作按钮
信息摘要区：评分、访问方式、下载/访问次数、版本、标签、核心能力
手册正文区：将 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

数据流

首页进入详情页的数据流如下：

首页加载工具列表，列表项已带有 id 和 slug
用户点击“详情”按钮
前端通过路由跳转到 /tools/:slug
详情页组件从路由参数读取 slug
前端调用新的公开接口，例如 GET /api/v1/tools/slug/:slug
后端按 slug + status=published + isDeleted=false 查询工具
查询成功后返回详情数据，包括 description、features、分类、评分、访问方式、访问量/下载量、版本等
前端渲染详情页摘要区和 Markdown 正文；若正文存在标题，则生成目录锚点或章节导航
用户可从详情页返回首页，或继续点击“打开网页/下载”执行现有 launch 流程

长文阅读的数据处理建议如下：

详情页获取 Markdown 原文
使用现有 Markdown 解析能力渲染 HTML
在渲染前或渲染时提取标题层级，生成页面内目录
为标题生成稳定锚点，支持目录点击跳转
若正文无标题，则不显示目录，保留清晰的文章排版和回顶能力

错误处理

错误类型	处理方式
详情接口加载中	展示页面级骨架或加载态，不显示旧弹窗
`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` 接口	兼容已有内部调用，减少回归风险	后端存在两个公开详情查询入口，但职责清晰

7.3 KiB Raw Blame History Unescape Escape