From 4b0f508f70a3cd642fc4ce7d7535108b35a3b40d Mon Sep 17 00:00:00 2001 From: yun-zhi-ztl <66589705+yun-zhi-ztl@users.noreply.github.com> Date: Thu, 19 Mar 2026 22:16:56 +0800 Subject: [PATCH] Delete docs Signed-off-by: yun-zhi-ztl <66589705+yun-zhi-ztl@users.noreply.github.com> --- .../2026-03-19-review-skill-detail-design.md | 244 ------------------ 1 file changed, 244 deletions(-) delete mode 100644 docs/superpowers/specs/2026-03-19-review-skill-detail-design.md diff --git a/docs/superpowers/specs/2026-03-19-review-skill-detail-design.md b/docs/superpowers/specs/2026-03-19-review-skill-detail-design.md deleted file mode 100644 index 20ec8a72..00000000 --- a/docs/superpowers/specs/2026-03-19-review-skill-detail-design.md +++ /dev/null @@ -1,244 +0,0 @@ -# 审核详情页内嵌技能详情设计 - -## 背景 - -当前审核员进入技能审核详情页后，只能看到审核任务基础信息和审批动作，无法直接查看当前待审核版本的技能详情、文件结构和下载内容。这会迫使审核员离开审核上下文，降低审核效率，也容易混淆待审核版本和已发布版本。 - -本次改动目标是在审核详情页内直接展示“当前审核任务对应的待审核版本”详情，并严格沿用现有审核权限体系，避免普通技能详情链路发生越权泄漏。 - -## 目标 - -- 审核员在审核详情页内直接查看待审核版本的： - - 技能概览 - - 文件树 - - 版本列表 - - zip 下载入口 -- 所有展示都固定绑定到当前 review 对应的待审核版本，不切到已发布版本。 -- 仅拥有现有审核权限的用户可以访问这些内容。 -- 页面只提供只读信息和下载，不暴露收藏、评分、举报、隐藏、治理等无关操作。 - -## 非目标 - -- 不改普通技能详情页的访问规则。 -- 不新增二次登录、二次确认或额外身份验证流程。 -- 不在审核详情页增加额外的治理操作。 -- 不支持在审核详情页中切换审核对象到其他版本。 - -## 用户场景 - -### 场景 1：审核员查看待审核版本详情 - -审核员打开某个审核任务详情页后，可以在当前页下半区看到该任务绑定版本的概览、文件树、版本列表和下载按钮。 - -### 场景 2：技能已有公开版本 - -即使该技能已有一个已发布版本，审核详情页里看到的仍然是 review 绑定的待审核版本，而不是对外公开版本。 - -### 场景 3：无权限用户尝试访问 - -没有审核权限的用户无法通过审核详情接口或新增的审核专用技能详情接口读取待审核版本内容。 - -## 方案对比 - -### 方案 1：审核详情页内嵌审核专用只读技能详情 - -新增审核专用查询接口，前端在审核详情页内嵌只读技能详情展示。 - -优点： -- 权限边界最清楚 -- 待审核版本绑定最稳定 -- 对现有普通技能详情链路影响最小 - -缺点： -- 需要新增一组审核专用查询对象 - -### 方案 2：复用普通技能详情接口并增加审核模式参数 - -优点： -- 表面上复用更多 - -缺点： -- 容易把普通详情和审核详情权限耦合 -- 容易误用 headline/published 逻辑 - -### 方案 3：审核详情跳转到单独的审核预览页 - -优点： -- 页面职责清晰 - -缺点： -- 审核员需要在多个页面来回切换 -- 不符合“在审核详情中展示”的目标 - -本次采用方案 1。 - -## 后端设计 - -### 核心原则 - -- 所有查询以 `reviewId` 为入口。 -- 最终返回的数据必须绑定到该 review 对应的 `skillVersionId`。 -- 任何地方都不能根据普通技能详情的默认版本选择逻辑重新推导版本。 - -### 接口设计 - -保留现有： - -- `GET /api/v1/reviews/{id}` - -新增： - -- `GET /api/v1/reviews/{id}/skill-detail` - -返回内容包含： - -- 技能基础信息 - - namespace - - slug - - name - - author / owner - - description - - tags - - downloadCount 等只读元信息 -- 当前审核绑定版本信息 - - version - - status - - createdAt - - changelog / release note（若现有领域对象中有） -- 概览文档 - - 文档路径 - - 文档内容 -- 文件树 - - 当前待审核版本全部文件 -- 版本列表 - - 该技能相关版本列表 - - 当前审核中的版本要明确标识 -- 下载链接 - - 固定指向当前 review 对应版本下载地址 - -### 服务层 - -建议新增审核专用查询服务或 DTO 组装逻辑，例如： - -- `ReviewSkillDetailAppService` - -它负责： - -1. 根据 `reviewId` 读取审核任务 -2. 校验当前用户是否有该审核任务的查看权限 -3. 取出 review 绑定的 `skillVersionId` -4. 按该 version 聚合技能详情、文件列表、版本列表和下载链接 -5. 输出审核专用响应 DTO - -### 权限 - -沿用现有审核权限体系： - -- 只有本来能访问审核详情的管理员/审核员可以访问新增接口 -- 普通用户、提交者本人但无审核权限者，不得访问 - -### 数据选择规则 - -- 概览文档：来自 review 对应版本 -- 文件树：来自 review 对应版本 -- 下载链接：来自 review 对应版本 -- 版本列表：可展示整个技能的版本时间线，但页面主视图始终锚定当前待审核版本 - -## 前端设计 - -### 页面结构 - -页面仍是审核详情页，不新增独立审核预览页面。 - -建议结构： - -1. 顶部：审核任务基础信息 -2. 中部：审批意见与审批按钮 -3. 下部：技能详情只读区 - - 概览 - - 文件 - - 版本 - - 下载按钮 - -### 交互约束 - -- 审核详情区新增 tabs，尽量复用普通技能详情页现有视觉结构： - - 概览 - - 文件 - - 版本 -- 下载按钮直接下载 review 对应版本 zip -- 不展示以下无关动作： - - 收藏 - - 评分 - - 举报 - - 隐藏/取消隐藏 - - 重新发布 - - 撤销审核 - - 版本治理操作 - -### 复用策略 - -优先复用现有只读展示能力，而不是复制整页逻辑： - -- 概览展示逻辑 -- 文件树组件 -- 版本列表视觉元素 - -必要时抽离只读展示组件，供普通技能详情页与审核详情页共享。 - -## 错误处理 - -- 审核任务不存在：显示当前审核详情页已有的 not found 状态 -- 无权限：沿用现有审核路由权限处理 -- 审核详情存在但技能版本数据异常缺失： - - 页面保留审核任务信息 - - 技能详情区域显示局部错误态 - - 不影响审核员返回列表或处理任务 - -## 测试策略 - -### 后端测试 - -#### Controller / Service - -- 有审核权限时可获取审核专用技能详情 -- 无审核权限时拒绝访问 -- 当技能已有 published 版本时，返回内容仍绑定 pending review 版本 -- 下载链接固定指向 review 对应版本 -- 文件树和文档读取来自 review 对应版本 - -### 前端测试 - -- 审核详情页成功渲染技能概览、文件树、版本区块 -- 当前待审核版本标识正确 -- 下载按钮使用当前待审核版本链接 -- 无关操作按钮不渲染 -- 接口失败时仅技能详情区显示错误态，不影响审核主信息展示 - -## 实施步骤 - -1. 新增审核专用后端查询 DTO / service / controller 接口 -2. 补齐后端权限与版本绑定测试 -3. 抽离或复用只读技能详情展示组件 -4. 在审核详情页接入审核专用技能详情查询 -5. 补齐前端页面测试 -6. 跑全量验证 - -## 风险与规避 - -### 风险 1：错误复用普通技能详情版本选择逻辑 - -规避： -- 所有审核详情相关查询都从 `reviewId -> skillVersionId` 出发 - -### 风险 2：新增接口泄漏待审核版本内容 - -规避： -- 新接口只放在审核控制器下 -- 复用现有审核权限判断，不挂到普通 skill 详情链路 - -### 风险 3：前端复制技能详情页逻辑过多，后续难维护 - -规避： -- 尽量抽取只读展示组件，不复制整页行为和动作按钮逻辑 -