84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# 项目上下文
|
|
|
|
## 基本信息
|
|
|
|
| 字段 | 内容 |
|
|
|------|------|
|
|
| **项目名称** | 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 完成 |
|