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

目标：为工具站新增 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，预期前后端关键回归全部通过。

14 KiB Raw Permalink Blame History Unescape Escape