feat(#1714): 前端 prepare 短路（后端 skip_transfer 命中时跳过 OSS 直传） #1729

Merged

auto-approve-bot merged 1 commits from feat/1714-prepare-skip-transfer into develop 2026-09-06 11:43:59 +08:00

Conversation 5 Commits 1 Files Changed 5

+170

xiaoxia commented 2026-09-06 11:38:33 +08:00

Owner

Copy Link

Copy Source

背景

Issue #1714 后续——后端 prepare_direct_upload 已支持 skip_transfer / duplicated 字段：当 file_hash 命中素材库已有相同文件时，返回这两个字段为 true，前端应识别并跳过 OSS 直传 + complete 阶段。

改动

api/assets/types.ts

• DirectUploadPrepareResult 扩展：duplicated?: boolean + skip_transfer?: boolean，兼容新旧后端（旧后端不返回则走老流程）

pages/assets/hooks/useAssetUpload.ts（队列链路）

• runUpload：prepare 返回后、transfer 前检查 h.prepared.skip_transfer || h.prepared.duplicated
  • 命中 → 立即 updateItem(tempId, { status: "done", duplicated: true, assetId })
  • toast 提示「与素材库已有内容相同，已跳过」
  • 调 refreshList（让已存在的 asset 立即显示），不调 transfer、不调 complete
  • 清理 handlesRef

api/assets/upload.ts（非队列链路：配音/封面/克隆）

• uploadAssetDirect prepare 后同样判断 skip_transfer/duplicated
  • 命中 → 直接返回 { storage_key, ingest_job_id: "", url: "", duplicated: true, asset_id }
  • 不调 transfer、不调 complete

测试

• useAssetUpload.test.tsx：新增 prepare 返回 skip_transfer=true 用例（队列场景），断言 transfer/complete 不被调用、标记 done+duplicated
• assets.test.ts：新增 uploadAssetDirect skip_transfer 短路 describe 两个用例
  • skip_transfer=true → 直接返回 duplicated，complete 不被调用
  • skip_transfer 缺失 → 走老流程，complete 被调用

验证

• 全量 668 passed（141 文件）；tsc / eslint --max-warnings 0 / prettier / build 全绿

说明

• 本 PR 只改前端短路逻辑，后端 prepare_direct_upload 返回 skip_transfer/duplicated 字段已由 #1719 系列合入 develop
• 旧后端不返回这两个字段时前端降级走老流程，无兼容性风险

## 背景 Issue #1714 后续——后端 `prepare_direct_upload` 已支持 `skip_transfer` / `duplicated` 字段：当 file_hash 命中素材库已有相同文件时，返回这两个字段为 true，前端应识别并跳过 OSS 直传 + complete 阶段。 ## 改动 ### `api/assets/types.ts` - `DirectUploadPrepareResult` 扩展：`duplicated?: boolean` + `skip_transfer?: boolean`，兼容新旧后端（旧后端不返回则走老流程） ### `pages/assets/hooks/useAssetUpload.ts`（队列链路） - runUpload：prepare 返回后、transfer 前检查 `h.prepared.skip_transfer || h.prepared.duplicated` - 命中 → 立即 `updateItem(tempId, { status: "done", duplicated: true, assetId })` - toast 提示「与素材库已有内容相同，已跳过」 - 调 refreshList（让已存在的 asset 立即显示），不调 transfer、不调 complete - 清理 handlesRef ### `api/assets/upload.ts`（非队列链路：配音/封面/克隆） - `uploadAssetDirect` prepare 后同样判断 skip_transfer/duplicated - 命中 → 直接返回 `{ storage_key, ingest_job_id: "", url: "", duplicated: true, asset_id }` - 不调 transfer、不调 complete ## 测试 - `useAssetUpload.test.tsx`：新增 prepare 返回 skip_transfer=true 用例（队列场景），断言 transfer/complete 不被调用、标记 done+duplicated - `assets.test.ts`：新增 `uploadAssetDirect skip_transfer 短路` describe 两个用例 - skip_transfer=true → 直接返回 duplicated，complete 不被调用 - skip_transfer 缺失 → 走老流程，complete 被调用 ## 验证 - 全量 **668 passed**（141 文件）；tsc / eslint --max-warnings 0 / prettier / build 全绿 ## 说明 - 本 PR 只改前端短路逻辑，后端 `prepare_direct_upload` 返回 skip_transfer/duplicated 字段已由 #1719 系列合入 develop - 旧后端不返回这两个字段时前端降级走老流程，无兼容性风险

xiaoxia added 1 commit 2026-09-06 11:38:34 +08:00

feat(#1714): 前端 prepare 短路（识别后端 skip_transfer/duplicated 跳过 OSS 直传 + complete） 4b10dc800e

auto-approve-bot commented 2026-09-06 11:40:02 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：1 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [apps/web/src/pages/assets/hooks/useAssetUpload.ts] 批量上传逻辑中断
   • 问题类型：逻辑bug
   • 问题描述：在 enqueueUploads 函数的 for 循环中，当检测到文件去重（skip_transfer 或 duplicated 为 true）时，代码执行了 return 语句。这将导致函数提前退出，循环终止，队列中当前文件之后的所有文件将无法被处理和上传。
   • 修改建议：将 return 改为 continue，确保跳过当前去重文件后，继续处理队列中的后续文件。

💡 改进建议（不阻塞合并）

1. [apps/web/src/pages/assets/hooks/useAssetUpload.ts] 列表刷新性能优化

   • 具体内容：当前逻辑在每次遇到去重文件时都会调用 refreshList()。如果用户一次性上传多个重复文件，会触发多次列表刷新请求，造成不必要的性能开销和网络压力。建议在循环结束后统一刷新，或者使用防抖机制控制刷新频率。

2. [apps/web/src/api/assets/upload.ts] 返回值健壮性检查

   • 具体内容：在短路返回逻辑中，asset_id 直接取自 handle.prepared.asset_id，该字段在接口定义中是可选的。虽然根据业务逻辑后端应该会返回，但如果后端接口异常或数据不一致，前端将返回 undefined。建议增加对该字段存在性的校验或注释说明依赖后端强契约。

✅ 良好实践

• TypeScript 类型定义清晰，注释详细解释了新旧字段的兼容性逻辑。
• 单元测试覆盖全面，同时测试了 skip_transfer 为 true 和 false 的场景，确保了核心逻辑的可靠性。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-09-06 03:40:00 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：1 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[apps/web/src/pages/assets/hooks/useAssetUpload.ts] 批量上传逻辑中断** - 问题类型：逻辑bug - 问题描述：在 `enqueueUploads` 函数的 `for` 循环中，当检测到文件去重（`skip_transfer` 或 `duplicated` 为 true）时，代码执行了 `return` 语句。这将导致函数提前退出，循环终止，队列中当前文件之后的所有文件将无法被处理和上传。 - 修改建议：将 `return` 改为 `continue`，确保跳过当前去重文件后，继续处理队列中的后续文件。 ### 💡 改进建议（不阻塞合并） 1. **[apps/web/src/pages/assets/hooks/useAssetUpload.ts] 列表刷新性能优化** - 具体内容：当前逻辑在每次遇到去重文件时都会调用 `refreshList()`。如果用户一次性上传多个重复文件，会触发多次列表刷新请求，造成不必要的性能开销和网络压力。建议在循环结束后统一刷新，或者使用防抖机制控制刷新频率。 2. **[apps/web/src/api/assets/upload.ts] 返回值健壮性检查** - 具体内容：在短路返回逻辑中，`asset_id` 直接取自 `handle.prepared.asset_id`，该字段在接口定义中是可选的。虽然根据业务逻辑后端应该会返回，但如果后端接口异常或数据不一致，前端将返回 `undefined`。建议增加对该字段存在性的校验或注释说明依赖后端强契约。 ### ✅ 良好实践 - TypeScript 类型定义清晰，注释详细解释了新旧字段的兼容性逻辑。 - 单元测试覆盖全面，同时测试了 `skip_transfer` 为 true 和 false 的场景，确保了核心逻辑的可靠性。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-09-06 03:40:00 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

gitea-actions bot commented 2026-09-06 11:40:55 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1729
预览链接	https://pr-1729.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1729 | | 预览链接 | [https://pr-1729.preview.xiaoxiajianji.com](https://pr-1729.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot approved these changes 2026-09-06 11:41:04 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-09-06 11:41:04 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit ff60fdf956 into develop 2026-09-06 11:43:59 +08:00

auto-approve-bot deleted branch feat/1714-prepare-skip-transfer 2026-09-06 11:43:59 +08:00

gitea-actions bot commented 2026-09-06 11:44:22 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1729 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1729 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1729