update:增加文档模式

design/specs/2026-04-14-tool-display-version-none-mode-design.md

@@ -0,0 +1,152 @@
+# 工具展示版本与无访问模式设计规格
+
+## 概述
+
+当前工具站只区分 `web` 和 `download` 两种访问方式。下载工具的版本来源于 `ToolArtifact.version`，因此访客端首页和详情页中的“版本”信息只对下载工具有效，网页工具长期显示“暂无版本”。与此同时，当前系统没有“仅展示详情、不提供打开或下载入口”的访问模式，无法承载预告型、资料型或人工分发型工具。
+
+本次设计目标是在现有 `Tool` 模型上补齐“展示版本”和“无访问模式”能力，保持下载包管理逻辑不变，同时让前台和后台统一拿到一个稳定的展示版本字段。具体策略为：数据库新增 `Tool.versionOverride` 作为人工维护的展示版本覆盖值；服务端统一计算 `displayVersion`；访问方式新增 `none`，用于“只展示详情，不执行 launch”的工具。
+
+## 目标定位
+
+- **主要用户**：后台管理员、公开站访客
+- **使用场景**：管理员在新增或编辑工具时维护展示版本，并可将工具设置为 `download`、`web` 或 `none`；访客在首页和详情页查看统一的版本信息，其中 `none` 模式工具只提供“查看详情”入口，不提供打开网页或下载操作
+
+## 约束条件
+
+- **技术限制**：前端基于 Vue 3 + Element Plus，服务端基于 NestJS + Prisma + SQLite；本次只做现有模型上的增量改造，不引入新的依赖或新的版本历史表
+- **时间限制**：本轮只实现版本展示和 `none` 访问模式，不扩展版本历史、发布日期、版本说明等二级能力
+- **资源限制**：继续复用现有下载包模型、公开列表/详情接口和后台工具管理流程；版本字段仅用于展示，不参与发布校验、不新增额外审核流程
+
+## 成功标准
+
+- [ ] Prisma 数据模型支持 `AccessMode.none` 和 `Tool.versionOverride`
+- [ ] 后台新增/编辑工具表单可以维护“展示版本”，访问方式下拉可选择“无”
+- [ ] 后台工具列表接口和公开工具列表/详情接口统一返回 `displayVersion`
+- [ ] 下载工具的 `displayVersion` 计算规则为 `versionOverride || latestArtifact.version || null`
+- [ ] 网页工具和无访问模式工具的 `displayVersion` 计算规则为 `versionOverride || null`
+- [ ] 访客端首页和详情页统一展示 `displayVersion`，不再依赖下载模式专属的 `latestVersion`
+- [ ] `none` 模式在首页主按钮显示“查看详情”，详情页不展示打开/下载主按钮
+- [ ] 直接调用 `launch` 接口访问 `none` 模式工具时返回明确错误，且不会产生打开/下载计数
+- [ ] 现有发布约束保持不变：`web` 仍要求 `openUrl`，`download` 仍要求安装包或下载地址，`none` 不因为缺少版本而被阻止发布
+- [ ] 后台概览和模式标签不再把 `none` 模式误显示为“下载模式”
+
+## 架构设计
+
+### 系统结构
+
+本次改造分为四层：
+
+1. **数据层**：在 `Tool` 模型中新增 `versionOverride` 字段；在 `AccessMode` 枚举中新增 `none`
+2. **映射层**：在后台服务和公开服务中统一计算 `displayVersion`，将“原始覆盖值”和“最终展示值”分离
+3. **行为层**：在 `AccessService` 中显式拒绝 `none` 模式的 launch 行为，保证服务端语义闭合
+4. **展示层**：后台编辑页维护 `versionOverride`，后台列表和访客端页面统一展示 `displayVersion`
+
+版本数据的核心原则如下：
+
+1. `versionOverride` 是管理员手工维护的原始字段，允许为空
+2. `displayVersion` 是接口返回给前端的最终展示值，不直接持久化
+3. 对下载工具，若 `versionOverride` 为空，则自动回退到当前 `latestArtifact.version`
+4. 对网页工具和无访问模式工具，`displayVersion` 只来自 `versionOverride`
+5. `latestArtifact.version` 继续用于安装包管理；`displayVersion` 用于页面展示
+
+访问模式的核心原则如下：
+
+1. 新增枚举值 `none`，内部值固定为 `none`，后台展示文案为“无”
+2. `none` 模式工具允许存在详情页和展示版本，但不允许执行 launch
+3. 访客端列表页对 `none` 模式的主按钮改为“查看详情”
+4. 访客端详情页对 `none` 模式不渲染打开/下载按钮
+5. 服务端若收到对 `none` 模式的 launch 请求，返回 `409 Conflict`
+
+### 组件划分
+
+| 组件 | 职责 | 依赖 |
+|------|------|------|
+| `server/prisma/schema.prisma` | 为 `AccessMode` 增加 `none`；为 `Tool` 增加 `versionOverride` 字段 | Prisma |
+| `server/prisma/seed.ts` | 补齐种子数据中的访问方式和展示版本样例，避免本地初始化后看不到新行为 | Prisma Seed |
+| `server/src/modules/admin-tools/dto/create-tool.dto.ts` | 接收 `versionOverride`，并允许 `accessMode=none` | `class-validator` |
+| `server/src/modules/admin-tools/dto/update-tool.dto.ts` | 继承新增字段，支持后台更新展示版本 | `CreateToolDto` |
+| `server/src/modules/admin-tools/dto/update-access-mode.dto.ts` | 接收 `none` 枚举值，兼容访问方式切换 | `class-validator` |
+| `server/src/modules/admin-tools/admin-tools.service.ts` | 规范化 `versionOverride`；列表和详情返回 `displayVersion` 与 `versionOverride`；保持发布校验逻辑不因版本字段变化 | Prisma |
+| `server/src/modules/tools/tools.service.ts` | 公开列表和详情统一返回 `displayVersion`；保留下载工具的 `latestVersion` 作为兼容字段 | Prisma |
+| `server/src/modules/access/access.service.ts` | 对 `none` 模式返回明确错误，禁止生成 launch 地址或下载票据 | Prisma, ConfigService |
+| `server/src/modules/admin-overview/admin-overview.service.ts` | 访问方式统计兼容 `none`，避免概览数据遗漏或模式显示错误 | Prisma |
+| `client/src/admin/components/ToolFormDialog.vue` | 新增“展示版本”输入项；访问方式下拉新增“无”；根据模式调整提示文案 | Element Plus |
+| `client/src/admin/components/AdminToolsSection.vue` | 列表增加版本列，访问方式标签兼容 `none` 文案 | Element Plus |
+| `client/src/admin/components/AccessModeDialog.vue` | 快速修改访问方式时允许选择“无”，并在 `none` 模式下隐藏 URL 输入项 | Element Plus |
+| `client/src/admin/AdminApp.vue` | 表单数据结构新增 `versionOverride`；构造创建/更新 payload；访问模式、标签颜色和模式文案兼容 `none` | Vue 3 |
+| `client/src/App.vue` | 工具卡片统一显示 `displayVersion`；`none` 模式主按钮改为“查看详情”并直接路由跳转 | `vue-router`, `client/src/api.js` |
+| `client/src/pages/ToolDetailPage.vue` | 摘要区展示 `displayVersion`；`none` 模式不显示主操作按钮 | `vue-router`, `client/src/api.js` |
+| `client/src/admin/components/AdminOverviewSection.vue` | 模式统计与 Top 工具模式文案兼容 `none` | Element Plus |
+
+## 数据流
+
+### 版本字段维护流
+
+1. 管理员在新增或编辑工具时填写“展示版本”
+2. 前端将该值作为 `versionOverride` 提交给后台；空字符串在提交前或服务端落库前统一归一化为 `null`
+3. 服务端保存 `Tool.versionOverride`
+4. 当后台列表、后台详情、公开列表或公开详情查询工具时，服务端统一计算 `displayVersion`
+5. 前端页面一律渲染 `displayVersion`，不再直接依赖下载工具专属的 `latestVersion`
+
+`displayVersion` 计算规则如下：
+
+1. 当 `tool.accessMode === 'download'` 时：`displayVersion = tool.versionOverride || tool.latestArtifact?.version || null`
+2. 当 `tool.accessMode === 'web'` 或 `tool.accessMode === 'none'` 时：`displayVersion = tool.versionOverride || null`
+
+为降低回归风险，下载工具响应中的 `latestVersion` 字段继续保留，其语义保持为“当前最新安装包版本”；页面展示逻辑统一切换为 `displayVersion`。
+
+### 访问模式切换流
+
+1. 管理员在新增/编辑表单或访问方式对话框中选择 `download`、`web` 或 `none`
+2. 当模式为 `web` 时，沿用现有规则，发布时仍要求 `openUrl`
+3. 当模式为 `download` 时，沿用现有规则，发布时仍要求活动安装包或外部下载地址
+4. 当模式为 `none` 时，不生成 launch 目标，不要求 `openUrl`，前端不展示打开/下载按钮
+5. 当公开站列表遇到 `none` 模式工具时，主按钮直接路由到详情页
+6. 当公开站详情页遇到 `none` 模式工具时，仅展示内容和版本，不发起 launch 请求
+7. 若外部调用者直接请求 `POST /api/v1/tools/:id/launch` 且目标工具为 `none` 模式，服务端返回 `409`
+
+### 前后台显示流
+
+1. 后台工具列表新增版本列，显示 `row.displayVersion || '-'`
+2. 公开首页卡片“版本”行显示 `tool.displayVersion || '暂无版本'`
+3. 公开详情页摘要区显示 `detail.displayVersion || '暂无版本'`
+4. `none` 模式的卡片副文案和详情摘要不再显示“下载/访问”动词，统一显示“仅详情”
+5. 概览和模式标签遇到 `none` 时显示“无”，不将其归并到下载模式
+
+## 错误处理
+
+| 错误类型 | 处理方式 |
+|----------|----------|
+| `versionOverride` 为空字符串 | 前端提交前或服务端保存前统一归一化为 `null`，避免空串污染数据 |
+| 下载工具没有覆盖版本且没有最新安装包版本 | `displayVersion` 返回 `null`，前端显示“暂无版本”，但不阻止发布之外的页面展示 |
+| `none` 模式被直接调用 launch 接口 | 服务端返回 `409 Conflict`，建议复用 `TOOL_ACCESS_MODE_MISMATCH` 并提供明确消息，如“tool is not launchable in none mode” |
+| 访问方式统计遇到 `none` | 后台概览必须显式处理该值，避免统计遗漏或错误文案 |
+| 旧前端代码仍读取 `latestVersion` | 下载工具继续保留该字段，版本展示迁移到 `displayVersion` 后逐步收敛消费端 |
+| 管理员把工具切换为 `none` | 页面行为以模式为准，版本仍可展示，但公开站不再允许打开/下载 |
+
+## 风险评估
+
+| 风险描述 | 类别 | 影响 | 概率 | 缓解策略 |
+|----------|------|------|------|----------|
+| 新增 `none` 枚举后，现有前端分支把未知模式错误地当成下载模式处理 | 集成风险 | 高 | 中 | 全量检查 `accessMode` 条件分支，补齐 `none` 的按钮文案、标签颜色和统计展示 |
+| 下载工具同时存在 `latestArtifact.version` 和 `versionOverride`，容易出现展示口径不一致 | 技术风险 | 中 | 中 | 服务端统一生成 `displayVersion`，前端禁止自行拼接版本来源 |
+| 旧接口调用方继续消费 `latestVersion`，导致 web/none 工具仍显示“暂无版本” | 范围风险 | 中 | 中 | 在页面和后台列表统一切到 `displayVersion`，同时短期保留 `latestVersion` 兼容下载工具 |
+| 增加 `none` 模式后，后台概览和模式统计遗漏该值 | 集成风险 | 中 | 中 | 同步更新概览服务、模式标签和概览页面文案，避免出现统计不闭合 |
+
+## 测试策略
+
+- **单元测试**：为服务端新增版本解析逻辑编写测试，覆盖三种场景：下载工具无覆盖值时回退安装包版本、下载工具有覆盖值时优先显示覆盖值、`web/none` 工具只使用覆盖值
+- **集成测试**：覆盖后台创建/更新工具时提交 `versionOverride` 和 `accessMode=none`；覆盖公开列表和详情接口返回 `displayVersion`；覆盖 `none` 模式 launch 接口返回 `409`
+- **前端组件测试**：覆盖首页卡片在 `none` 模式下显示“查看详情”；覆盖详情页在 `none` 模式下不渲染主操作按钮；覆盖版本展示优先使用 `displayVersion`
+- **验收标准**：管理员可维护展示版本；后台工具列表可看到版本；访客端列表与详情都能看到统一版本；下载工具默认继承安装包版本；`none` 模式只可查看详情、不可 launch；后台概览与模式文案不出现错误映射
+
+## 决策记录
+
+| 决策 | 理由 | 影响 |
+|------|------|------|
+| 使用 `Tool.versionOverride + displayVersion`，而不是为所有工具新建统一版本表 | 当前需求只需要单值展示和少量覆盖能力，不需要版本历史，增量成本最低 | 需要在服务端增加统一映射逻辑 |
+| `displayVersion` 由服务端计算，不在数据库落地 | 避免前端自行拼接版本来源，减少 download/web/none 三种模式的歧义 | 后台和公开接口都要增加该字段 |
+| 下载工具保留 `latestVersion`，但页面展示切到 `displayVersion` | 降低旧代码回归风险，同时给新页面一个统一字段 | 服务端响应短期内会同时存在两个版本相关字段 |
+| 访问方式新增 `none`，而不是用布尔开关控制是否可 launch | 与现有 `AccessMode` 模型保持一致，语义清晰，便于后台筛选和统计 | Prisma 枚举、前后端条件分支和概览统计都需要更新 |
+| `none` 模式首页主按钮跳详情页，详情页不展示主操作按钮 | 用户已明确选择详情引导型行为，比“禁用按钮”更可用 | 公开站首页和详情页都需增加 `none` 分支 |
+| 版本字段不参与发布校验 | 用户明确要求版本只作展示，不希望改变当前发布约束 | `assertPublishInput` 和状态流保持现状，只需兼容 `none` 模式 |