# 用户手册详情页设计规格

## 概述

当前访客端首页通过弹窗展示工具详情，适合快速浏览，但不适合作为稳定的用户手册阅读入口。现有工具数据中的 `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` 接口 | 兼容已有内部调用，减少回归风险 | 后端存在两个公开详情查询入口，但职责清晰 |