# 项目上下文

## 基本信息

| 字段 | 内容 |
|------|------|
| **项目名称** | Tools Show |
| **技术栈** | Vue 3、vue-router、Vite、Vitest、NestJS、Prisma、Jest、SQLite |
| **创建日期** | 2026-04-11 |
| **最后更新** | 2026-04-11 |
| **项目阶段** | 开发中 |

## 已完成功能

| 功能 | 描述 | 完成日期 | 状态 |
|------|------|---------|------|
| 访客端工具列表与筛选 | 首页支持搜索、分类、排序、分页和站点概览弹窗 | 2026-04-11 | 稳定 |
| 工具用户手册详情页 | 新增基于 `slug` 的访客端详情页，支持 Markdown 手册、空状态、404、返回入口和长文目录导航 | 2026-04-11 | 稳定 |
| 公开详情 `slug` 接口 | 服务端新增按 `slug` 查询已发布工具详情的公开接口，并保留原有按 `id` 查询能力 | 2026-04-11 | 稳定 |
| 前端测试基建 | 客户端补充 `Vitest + Vue Test Utils + jsdom`，覆盖首页跳转、详情页和 Markdown 目录工具 | 2026-04-11 | 稳定 |

## 项目结构

### 目录结构

```text
/
├── client/          # Vue 前端与管理端
├── server/          # NestJS 后端
├── docs/            # 项目文档
├── design/          # 需求、规格、计划与上下文
└── docker/          # 运行环境脚本
```

### 模块划分

| 模块 | 职责 | 依赖关系 |
|------|------|---------|
| `client/src/App.vue` | 访客端工具列表、筛选和概览入口 | `client/src/api.js` |
| `client/src/pages/ToolDetailPage.vue` | 访客端工具详情与 Markdown 手册阅读 | `client/src/api.js`, `client/src/utils/markdown.js`, `client/src/utils/markdown-outline.js` |
| `client/src/admin/*` | 后台工具、分类和审计管理 | `client/src/admin/api.js` |
| `server/src/modules/tools/*` | 公开工具列表与详情查询 | Prisma |
| `server/src/modules/access/*` | 网页打开与下载行为 | `server/src/modules/tools/*` |

## 架构决策记录

| 日期 | 决策 | 理由 | 影响 |
|------|------|------|------|
| 2026-04-11 | 访客端详情页使用 `slug` 路由 | 链接可读、适合长期分享和直达访问 | 前后端同步支持 `/tools/:slug` |
| 2026-04-11 | 继续复用 `Tool.description` 作为用户手册源 | 避免新增数据模型和后台复杂度 | 后台只需优化说明文案 |
| 2026-04-11 | 保留按 `id` 获取详情接口，同时新增按 `slug` 接口 | 降低回归风险，兼容既有调用 | `ToolsService` 维护共享详情映射 |
| 2026-04-11 | 客户端引入 `Vitest + Vue Test Utils + jsdom` | 详情页和路由改造需要前端自动化回归 | `client/package.json` 和锁文件更新 |

## 依赖管理

### 项目依赖

| 依赖名称 | 版本 | 用途 | 来源 |
|---------|------|------|------|
| `vitest` | `^3.2.4` | 客户端单元测试 | npm |
| `@vue/test-utils` | `^2.4.6` | Vue 组件测试挂载 | npm |
| `jsdom` | `^26.1.0` | 客户端测试 DOM 环境 | npm |
| `marked` | `^17.0.5` | Markdown 解析 | npm |
| `dompurify` | `^3.3.3` | Markdown HTML 安全净化 | npm |

### 外部服务

| 服务 | 用途 | 配置位置 |
|------|------|---------|
| SQLite | 工具、分类与访问数据存储 | `server/prisma/schema.prisma` |

## 技术债务

| 债务 | 影响 | 优先级 | 备注 |
|------|------|-------|------|
| 客户端构建产物单 chunk 体积较大 | Vite 构建有 chunk size warning | 中 | 后续可考虑按公开页/管理页拆分 chunk |
| 首页与详情页存在重复的 launch 行为逻辑 | 后续维护动作文案或追踪逻辑时需双处同步 | 中 | 可考虑抽成共享 composable |

## 更新历史

| 日期 | 更新内容 | 触发来源 |
|------|---------|---------|
| 2026-04-11 | 初始创建，记录访客端详情页与前端测试基建落地情况 | executing-plans 完成 |