tools-show/design/plans/2026-04-14-tool-display-version-none-mode-plan.md

# 工具展示版本与无访问模式实施计划

**目标**：为工具站新增 `Tool.versionOverride` 与 `AccessMode.none`，由服务端统一计算 `displayVersion`，并让后台工具管理、公开列表、公开详情和 launch 语义全部兼容新模型。

**架构**：采用“数据契约先行”的增量改造。先在 Prisma 和服务端建立稳定的数据模型与返回字段，再分别更新公开站和管理端消费 `displayVersion`，最后用单元测试与 e2e 回归把 `none` 模式的行为闭合。

**技术栈**：Prisma、SQLite、NestJS、Jest、Supertest、Vue 3、Element Plus、Vitest

---

## 文件结构

### 新建文件

- `server/prisma/migrations/*_tool-display-version-none-mode/migration.sql` - 由 Prisma 生成 `AccessMode.none` 和 `Tool.versionOverride` 的迁移脚本。注释需求：低。复杂度：低。
- `server/src/modules/admin-tools/admin-tools.service.spec.ts` - 覆盖后台工具列表/详情的 `displayVersion` 映射、`versionOverride` 归一化和 `none` 模式输入。注释需求：低。复杂度：中。
- `server/src/modules/access/access.service.spec.ts` - 覆盖 `none` 模式 launch 被拒绝、`web/download` 既有行为不回归。注释需求：低。复杂度：中。
- `server/src/modules/admin-overview/admin-overview.service.spec.ts` - 覆盖概览统计对 `none` 模式的计数与文案数据。注释需求：低。复杂度：中。
- `server/test/tool-launch-none.e2e-spec.ts` - 覆盖公开 launch 接口对 `none` 模式返回 `409`。注释需求：低。复杂度：中。
- `client/src/admin/components/ToolFormDialog.spec.js` - 覆盖工具表单展示版本输入项和 `none` 模式可见性。注释需求：低。复杂度：中。
- `client/src/admin/components/AccessModeDialog.spec.js` - 覆盖快速切换访问方式时 `none` 模式隐藏 URL 输入。注释需求：低。复杂度：中。
- `client/src/admin/components/AdminToolsSection.spec.js` - 覆盖后台工具列表版本列和 `none` 模式标签渲染。注释需求：低。复杂度：中。
- `client/src/admin/components/AdminOverviewSection.spec.js` - 覆盖后台概览的 `none` 模式统计展示。注释需求：低。复杂度：中。

### 修改文件

- `server/prisma/schema.prisma` - 为 `AccessMode` 增加 `none`，为 `Tool` 增加 `versionOverride`。注释需求：低。复杂度：中。
- `server/prisma/seed.ts` - 为种子工具补充展示版本样例，并加入至少一个 `none` 模式工具。注释需求：低。复杂度：中。
- `server/src/modules/tools/tools.service.ts` - 公开列表和详情统一输出 `displayVersion`，保留下载工具 `latestVersion` 兼容字段。注释需求：中，新增版本解析 helper 需说明回退顺序。复杂度：高。
- `server/src/modules/tools/tools.service.spec.ts` - 增加 `displayVersion` 与 `none` 模式回归断言。注释需求：低。复杂度：中。
- `server/test/tools-detail.e2e-spec.ts` - 扩展详情接口断言，验证 `displayVersion` 和 `accessMode=none` 可被公开读取。注释需求：低。复杂度：中。
- `server/src/modules/admin-tools/dto/create-tool.dto.ts` - 接收 `versionOverride`，并让 `accessMode` 接受 `none`。注释需求：低。复杂度：中。
- `server/src/modules/admin-tools/dto/update-tool.dto.ts` - 继承新增展示版本字段。注释需求：低。复杂度：低。
- `server/src/modules/admin-tools/dto/update-access-mode.dto.ts` - 允许切换到 `none`，并明确 URL 仅在 `web/download` 下有意义。注释需求：低。复杂度：中。
- `server/src/modules/admin-tools/admin-tools.service.ts` - 统一归一化 `versionOverride`，后台接口输出 `displayVersion` 和 `versionOverride`。注释需求：中，新增映射 helper 需要解释字段语义。复杂度：高。
- `server/src/modules/access/access.service.ts` - 对 `none` 模式 launch 返回冲突错误，不生成 ticket，也不返回 actionUrl。注释需求：中。复杂度：中。
- `server/src/modules/admin-overview/admin-overview.service.ts` - 新增 `noneToolTotal` 统计，并让模式分布闭合。注释需求：低。复杂度：中。
- `client/src/App.vue` - 首页卡片改为展示 `displayVersion`，`none` 模式主按钮跳详情并显示“查看详情”。注释需求：低。复杂度：中。
- `client/src/App.spec.js` - 增加 `displayVersion` 与 `none` 模式交互回归。注释需求：低。复杂度：中。
- `client/src/pages/ToolDetailPage.vue` - 详情页展示 `displayVersion`，`none` 模式不渲染主操作按钮。注释需求：低。复杂度：中。
- `client/src/pages/ToolDetailPage.spec.js` - 增加 `displayVersion` 渲染和 `none` 模式无主按钮断言。注释需求：低。复杂度：中。
- `client/src/admin/AdminApp.vue` - 表单状态新增 `versionOverride`，访问方式选项新增“无”，构造 payload 和标签样式兼容 `none`。注释需求：中，构造 payload 的归一化逻辑需要简短说明。复杂度：高。
- `client/src/admin/components/ToolFormDialog.vue` - 新增展示版本输入项，按模式调整文案。注释需求：低。复杂度：中。
- `client/src/admin/components/AccessModeDialog.vue` - `none` 模式隐藏 URL 输入和无意义的新标签页控制。注释需求：低。复杂度：中。
- `client/src/admin/components/AdminToolsSection.vue` - 增加版本列并渲染 `none` 标签文案。注释需求：低。复杂度：中。
- `client/src/admin/components/AdminOverviewSection.vue` - 新增或调整模式分布项，显示“无”模式。注释需求：低。复杂度：中。
- `client/src/admin/stores/console.js` - 为概览 summary 默认值补充 `noneToolTotal`。注释需求：低。复杂度：低。

### 测试文件

- `server/src/modules/tools/tools.service.spec.ts` - 公开服务的 `displayVersion` 计算与详情映射回归。
- `server/src/modules/admin-tools/admin-tools.service.spec.ts` - 后台服务的版本覆盖与访问方式回归。
- `server/src/modules/access/access.service.spec.ts` - `none` 模式 launch 约束回归。
- `server/src/modules/admin-overview/admin-overview.service.spec.ts` - 概览模式分布回归。
- `server/test/tools-detail.e2e-spec.ts` - 公开详情接口契约回归。
- `server/test/tool-launch-none.e2e-spec.ts` - 公开 launch 接口 `none` 模式回归。
- `client/src/App.spec.js` - 首页卡片版本展示和 `none` 模式路由回归。
- `client/src/pages/ToolDetailPage.spec.js` - 详情页版本展示和无主按钮回归。
- `client/src/admin/components/ToolFormDialog.spec.js` - 后台工具表单版本输入与 `none` 模式渲染回归。
- `client/src/admin/components/AccessModeDialog.spec.js` - 后台访问方式对话框 `none` 模式回归。
- `client/src/admin/components/AdminToolsSection.spec.js` - 后台列表版本列和模式标签回归。
- `client/src/admin/components/AdminOverviewSection.spec.js` - 后台概览模式分布回归。

---

## 任务列表

### 任务 1：先锁定 Prisma 契约和公开接口版本映射

**文件**：
- 修改：`server/prisma/schema.prisma`
- 修改：`server/src/modules/tools/tools.service.ts`
- 修改：`server/src/modules/tools/tools.service.spec.ts`
- 修改：`server/test/tools-detail.e2e-spec.ts`
- 创建：`server/prisma/migrations/*_tool-display-version-none-mode/migration.sql`

- [ ] **步骤 1**：在 `server/src/modules/tools/tools.service.spec.ts` 先补 3 个失败测试，分别覆盖“下载工具无覆盖版本时回退 `latestArtifact.version`”“网页工具使用 `versionOverride`”“`none` 模式详情返回 `displayVersion` 和 `accessMode=none`”。
- [ ] **步骤 2**：在 `server/test/tools-detail.e2e-spec.ts` 先补失败断言，执行 `cd server && npm run test -- src/modules/tools/tools.service.spec.ts` 与 `cd server && npm run test:e2e -- test/tools-detail.e2e-spec.ts`，预期出现缺少 `displayVersion`、`none` 枚举未生效或断言失败。
- [ ] **步骤 3**：更新 `server/prisma/schema.prisma`，执行 `cd server && npx prisma migrate dev --name tool-display-version-none-mode` 与 `cd server && npm run prisma:generate`，然后在 `server/src/modules/tools/tools.service.ts` 加入统一的 `displayVersion` 解析 helper，并保留下载工具 `latestVersion` 兼容字段。
- [ ] **步骤 4**：重新执行 `cd server && npm run test -- src/modules/tools/tools.service.spec.ts` 与 `cd server && npm run test:e2e -- test/tools-detail.e2e-spec.ts`，预期 Jest 与 e2e 通过，公开接口开始稳定返回 `displayVersion`。

### 任务 2：补齐后台工具服务对 `versionOverride` 和 `none` 的支持

**文件**：
- 修改：`server/prisma/seed.ts`
- 修改：`server/src/modules/admin-tools/dto/create-tool.dto.ts`
- 修改：`server/src/modules/admin-tools/dto/update-tool.dto.ts`
- 修改：`server/src/modules/admin-tools/dto/update-access-mode.dto.ts`
- 修改：`server/src/modules/admin-tools/admin-tools.service.ts`
- 创建：`server/src/modules/admin-tools/admin-tools.service.spec.ts`

- [ ] **步骤 1**：创建 `server/src/modules/admin-tools/admin-tools.service.spec.ts`，先写失败测试，覆盖“后台列表/详情同时返回 `displayVersion` 和 `versionOverride`”“下载工具覆盖版本优先于安装包版本”“`none` 模式允许空 `openUrl` 保存”。
- [ ] **步骤 2**：执行 `cd server && npm run test -- src/modules/admin-tools/admin-tools.service.spec.ts`，预期因 DTO、服务映射或归一化逻辑缺失而失败。
- [ ] **步骤 3**：更新后台 DTO 与 `server/src/modules/admin-tools/admin-tools.service.ts`，为 `versionOverride` 做 trim/null 归一化、为 `none` 模式放开 URL 约束，并在 `server/prisma/seed.ts` 加入带版本覆盖值的 `web`/`none` 示例工具，便于本地人工验证。
- [ ] **步骤 4**：执行 `cd server && npm run test -- src/modules/admin-tools/admin-tools.service.spec.ts src/modules/tools/tools.service.spec.ts`，预期后台和公开服务映射同时通过。

### 任务 3：封闭 `none` 模式的 launch 语义并补齐概览统计

**文件**：
- 修改：`server/src/modules/access/access.service.ts`
- 修改：`server/src/modules/admin-overview/admin-overview.service.ts`
- 创建：`server/src/modules/access/access.service.spec.ts`
- 创建：`server/src/modules/admin-overview/admin-overview.service.spec.ts`
- 创建：`server/test/tool-launch-none.e2e-spec.ts`

- [ ] **步骤 1**：先创建 `server/src/modules/access/access.service.spec.ts` 与 `server/src/modules/admin-overview/admin-overview.service.spec.ts`，分别写失败测试，覆盖“`none` 模式 launch 抛 `409`”“概览 summary 返回 `noneToolTotal` 且模式分布不把 `none` 算进下载模式”；同时创建 `server/test/tool-launch-none.e2e-spec.ts` 作为接口级失败测试。
- [ ] **步骤 2**：执行 `cd server && npm run test -- src/modules/access/access.service.spec.ts src/modules/admin-overview/admin-overview.service.spec.ts` 与 `cd server && npm run test:e2e -- test/tool-launch-none.e2e-spec.ts`，预期 launch 与概览相关断言失败。
- [ ] **步骤 3**：在 `server/src/modules/access/access.service.ts` 拒绝 `none` 模式 launch，在 `server/src/modules/admin-overview/admin-overview.service.ts` 增加 `noneToolTotal` 和 `none` 统计分支；若复用现有错误码，则统一错误消息语义。
- [ ] **步骤 4**：重新执行上述测试命令，预期单元测试和 e2e 都通过，`none` 模式行为在服务端完全闭合。

### 任务 4：更新公开站首页与详情页，统一消费 `displayVersion`

**文件**：
- 修改：`client/src/App.vue`
- 修改：`client/src/App.spec.js`
- 修改：`client/src/pages/ToolDetailPage.vue`
- 修改：`client/src/pages/ToolDetailPage.spec.js`

- [ ] **步骤 1**：先在 `client/src/App.spec.js` 与 `client/src/pages/ToolDetailPage.spec.js` 增加失败用例，覆盖“首页优先展示 `displayVersion`”“`none` 模式主按钮文案为‘查看详情’并跳转详情页”“详情页展示 `displayVersion` 且 `none` 模式不渲染主按钮”。
- [ ] **步骤 2**：执行 `cd client && npm run test:run -- src/App.spec.js src/pages/ToolDetailPage.spec.js`，预期 Vitest 因页面仍依赖 `latestVersion` 或仍渲染打开/下载按钮而失败。
- [ ] **步骤 3**：更新 `client/src/App.vue` 与 `client/src/pages/ToolDetailPage.vue`，将版本展示切换到 `displayVersion`，为 `none` 模式增加详情跳转分支，并移除详情页无意义的主操作按钮。
- [ ] **步骤 4**：重新执行 `cd client && npm run test:run -- src/App.spec.js src/pages/ToolDetailPage.spec.js`，预期公开站回归通过。

### 任务 5：补齐后台表单、列表和概览对新字段的 UI 支持

**文件**：
- 修改：`client/src/admin/AdminApp.vue`
- 修改：`client/src/admin/components/ToolFormDialog.vue`
- 修改：`client/src/admin/components/AccessModeDialog.vue`
- 修改：`client/src/admin/components/AdminToolsSection.vue`
- 修改：`client/src/admin/components/AdminOverviewSection.vue`
- 修改：`client/src/admin/stores/console.js`
- 创建：`client/src/admin/components/ToolFormDialog.spec.js`
- 创建：`client/src/admin/components/AccessModeDialog.spec.js`
- 创建：`client/src/admin/components/AdminToolsSection.spec.js`
- 创建：`client/src/admin/components/AdminOverviewSection.spec.js`

- [ ] **步骤 1**：先创建 4 个后台组件测试文件，分别写失败测试，覆盖“工具表单存在展示版本输入项并可选择‘无’”“访问方式对话框切换到 `none` 时隐藏 URL 输入”“工具列表显示版本列和 `none` 标签”“概览模式分布显示 `none` 模式统计”。
- [ ] **步骤 2**：执行 `cd client && npm run test:run -- src/admin/components/ToolFormDialog.spec.js src/admin/components/AccessModeDialog.spec.js src/admin/components/AdminToolsSection.spec.js src/admin/components/AdminOverviewSection.spec.js`，预期后台组件测试失败。
- [ ] **步骤 3**：更新 `client/src/admin/AdminApp.vue`、`ToolFormDialog.vue`、`AccessModeDialog.vue`、`AdminToolsSection.vue`、`AdminOverviewSection.vue` 和 `client/src/admin/stores/console.js`，让后台表单、快速切换、列表和概览统一识别 `versionOverride`、`displayVersion` 与 `noneToolTotal`。
- [ ] **步骤 4**：重新执行上面的后台组件测试，并追加执行 `cd client && npm run test:run -- src/App.spec.js src/pages/ToolDetailPage.spec.js` 与 `cd server && npm run test -- src/modules/tools/tools.service.spec.ts src/modules/admin-tools/admin-tools.service.spec.ts src/modules/access/access.service.spec.ts src/modules/admin-overview/admin-overview.service.spec.ts`，预期前后端关键回归全部通过。