feat(#1714): prepare_direct_upload 去重 + 预建 PROCESSING asset 占位 #1730

Merged

auto-approve-bot merged 2 commits from feature/prepare-dedup-1714 into develop 2026-09-06 12:31:38 +08:00

Conversation 3 Commits 2 Files Changed 3

+614 -12

xiaoxia commented 2026-09-06 12:23:58 +08:00

Owner

Copy Link

Copy Source

背景

当前 direct 两段式上传的 prepare 只签名 OSS 表单、不做去重（去重只在 complete），导致重复文件每次都完整上传一遍 OSS 才在 complete 阶段被跳过，浪费带宽。

改动

schema（apps/api/app/schemas/upload.py）

• DirectUploadPrepareRequest 增加 client_upload_id（客户端幂等 token）
• DirectUploadPrepareResponse 扩展 3 个向后兼容字段：duplicated: bool=False、skip_transfer: bool=False、asset_id: str=""

prepare_direct_upload（apps/api/app/api/routes/upload.py）

• 生成 OSS 签名前，若 file_hash 或 client_upload_id 非空，先调 _find_duplicate_asset 去重（复用现有 3 级查找：client_upload_id → file_hash → 同名兜底）
• 命中：直接返回 duplicated=True, skip_transfer=True, asset_id=existing.id，upload_url/fields 为空——前端识别后跳过 OSS 直传，直接走 complete
• 未命中：正常签名 OSS，并立即调 _create_pending_asset 预建一条 PROCESSING 占位 asset（写入 file_hash/client_upload_id/storage_key/filename/size），占住 file_hash 闸门，响应带 asset_id；预建失败 try/except 降级不阻塞签名

_create_pending_asset 改 find-or-create

• 先按 client_upload_id、再按 file_hash 查现有记录；命中则复用并补齐缺失字段（触发 update），未命中才新建——避免 pre-create + complete 重复建两条

_find_duplicate_asset 兜底规则细化

• READY/ERROR 稳定素材：总命中（避免重复创建）
• PROCESSING/UPLOADING 占位：仅当占位 hash 与请求 hash 一致、或占位无 hash（旧客户端 complete 占位）时命中；占位有 hash 且与请求不同 → 跳过（同文件名不同内容的新上传不能误杀）

测试

12 个新单测（tests/unit/test_prepare_dedup_1714.py）：

• 首次上传无 hash：duplicated=false、无 asset_id
• 首次上传带 hash：duplicated=false + asset_id 非空（PROCESSING 占位落库）
• 二次同 hash：duplicated=true, skip_transfer=true
• 同 client_upload_id 重试：直接跳过
• file_hash 空：走老逻辑
• 同名兜底不命中 PROCESSING 占位 / 命中 READY 稳定记录
• PROCESSING 占位 hash 不同跳过 / 相同命中
• find-or-create 复用现有记录 / 无匹配新建 / update 异常吞掉
• 预建失败降级：签名仍正常返回

全量 14400 passed（5 个已知 TTS 沙箱失败与本次无关），diff coverage 85%+。

前端配合

后端 prepare 响应已带 skip_transfer + asset_id，前端识别后跳过 OSS 直传、直接调 complete（前端工程师跟进）。

## 背景 当前 direct 两段式上传的 prepare 只签名 OSS 表单、不做去重（去重只在 complete），导致重复文件每次都完整上传一遍 OSS 才在 complete 阶段被跳过，浪费带宽。 ## 改动 ### schema（`apps/api/app/schemas/upload.py`） - `DirectUploadPrepareRequest` 增加 `client_upload_id`（客户端幂等 token） - `DirectUploadPrepareResponse` 扩展 3 个向后兼容字段：`duplicated: bool=False`、`skip_transfer: bool=False`、`asset_id: str=""` ### prepare_direct_upload（`apps/api/app/api/routes/upload.py`） - 生成 OSS 签名前，若 `file_hash` 或 `client_upload_id` 非空，先调 `_find_duplicate_asset` 去重（复用现有 3 级查找：client_upload_id → file_hash → 同名兜底） - **命中**：直接返回 `duplicated=True, skip_transfer=True, asset_id=existing.id`，upload_url/fields 为空——前端识别后跳过 OSS 直传，直接走 complete - **未命中**：正常签名 OSS，并立即调 `_create_pending_asset` 预建一条 PROCESSING 占位 asset（写入 file_hash/client_upload_id/storage_key/filename/size），占住 file_hash 闸门，响应带 `asset_id`；预建失败 try/except 降级不阻塞签名 ### _create_pending_asset 改 find-or-create - 先按 client_upload_id、再按 file_hash 查现有记录；命中则复用并补齐缺失字段（触发 update），未命中才新建——避免 pre-create + complete 重复建两条 ### _find_duplicate_asset 兜底规则细化 - READY/ERROR 稳定素材：总命中（避免重复创建） - PROCESSING/UPLOADING 占位：仅当占位 hash 与请求 hash 一致、或占位无 hash（旧客户端 complete 占位）时命中；占位有 hash 且与请求不同 → 跳过（同文件名不同内容的新上传不能误杀） ## 测试 12 个新单测（`tests/unit/test_prepare_dedup_1714.py`）： - 首次上传无 hash：duplicated=false、无 asset_id - 首次上传带 hash：duplicated=false + asset_id 非空（PROCESSING 占位落库） - 二次同 hash：duplicated=true, skip_transfer=true - 同 client_upload_id 重试：直接跳过 - file_hash 空：走老逻辑 - 同名兜底不命中 PROCESSING 占位 / 命中 READY 稳定记录 - PROCESSING 占位 hash 不同跳过 / 相同命中 - find-or-create 复用现有记录 / 无匹配新建 / update 异常吞掉 - 预建失败降级：签名仍正常返回 全量 14400 passed（5 个已知 TTS 沙箱失败与本次无关），diff coverage 85%+。 ## 前端配合 后端 prepare 响应已带 `skip_transfer` + `asset_id`，前端识别后跳过 OSS 直传、直接调 complete（前端工程师跟进）。

xiaoxia added 2 commits 2026-09-06 12:23:58 +08:00

feat(#1714): prepare_direct_upload 去重 + 预建 PROCESSING asset 占位 ... 6a11680f62

- schema: DirectUploadPrepareRequest 加 client_upload_id；
  DirectUploadPrepareResponse 加 duplicated/skip_transfer/asset_id（向后兼容）
- _create_pending_asset: find-or-create 模式，先按 client_upload_id/file_hash
  查现有记录，命中则复用并补齐字段，未命中才新建
- prepare_direct_upload: 签名 OSS 前按 file_hash/client_upload_id 去重，
  命中直接返回 duplicated=true+skip_transfer=true；未命中正常签名并预建
  PROCESSING 占位 asset（占位失败不阻塞签名）
- _find_duplicate_asset 兜底规则细化：READY/ERROR 总命中；PROCESSING/
  UPLOADING 仅当 hash 一致或占位无 hash 时命中，避免同文件名不同内容冲突
- 8 个新单测覆盖：首次带 hash、重复命中、client_upload_id 重试、
  文件名兜底不命中 PROCESSING、兜底命中 READY、find-or-create 复用

test(#1714): 补 prepare 去重边界分支——预建失败降级、update异常吞掉、PROCESSING hash不同跳过/相同命中 9088be360f

gitea-actions bot commented 2026-09-06 12:25:44 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot commented 2026-09-06 12:28:09 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #1730

⚠️ 问题（2个需要修改）

1. apps/api/app/api/routes/upload.py 第193行：兜底去重逻辑存在误判风险。当 existing_hash 为空（旧占位）而 file_hash 不为空时，代码进入 else 分支判定为命中。这会导致不同内容（同名但 hash 不同）的新上传被错误关联到旧的空 hash 占位记录上，造成数据混乱或去重失效。
2. apps/api/app/api/routes/upload.py 第248行：_create_pending_asset 中字段补齐失败时异常被静默吞掉（pass）。如果补齐 file_hash 等 ID 关键字段失败，会导致内存对象与数据库记录不一致。后续流程（如 complete）若依赖 DB 中的这些字段进行校验，将导致业务逻辑错误。

💡 建议（1个可选）

1. apps/api/app/api/routes/upload.py 第393行：日志记录建议增加堆栈信息。当前 logger.warning("预建 asset 占位失败，降级走 old flow: %s", error) 仅打印异常对象，建议使用 exc_info=True 或 exc_info=error 以便排查预建失败的根本原因。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ✅ 性能良好

---

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

## 代码审查结果 - PR #1730 ### ⚠️ 问题（2个需要修改） 1. **apps/api/app/api/routes/upload.py 第193行**：兜底去重逻辑存在误判风险。当 `existing_hash` 为空（旧占位）而 `file_hash` 不为空时，代码进入 `else` 分支判定为命中。这会导致不同内容（同名但 hash 不同）的新上传被错误关联到旧的空 hash 占位记录上，造成数据混乱或去重失效。 2. **apps/api/app/api/routes/upload.py 第248行**：`_create_pending_asset` 中字段补齐失败时异常被静默吞掉（`pass`）。如果补齐 `file_hash` 等 ID 关键字段失败，会导致内存对象与数据库记录不一致。后续流程（如 complete）若依赖 DB 中的这些字段进行校验，将导致业务逻辑错误。 ### 💡 建议（1个可选） 1. **apps/api/app/api/routes/upload.py 第393行**：日志记录建议增加堆栈信息。当前 `logger.warning("预建 asset 占位失败，降级走 old flow: %s", error)` 仅打印异常对象，建议使用 `exc_info=True` 或 `exc_info=error` 以便排查预建失败的根本原因。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ✅ 性能良好 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-09-06 04:28:09 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit 70dde8cbfb into develop 2026-09-06 12:31:38 +08:00

auto-approve-bot deleted branch feature/prepare-dedup-1714 2026-09-06 12:31:39 +08:00

gitea-actions bot commented 2026-09-06 12:31:53 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

Sign in to join this conversation.

Reviewers

No Reviewers

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#1730