gongxiangp2/docs/upload-spec-from-decompiled.md

64 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 上传表单/处理对齐说明(基于反编译版 & 数据库字段)
> 目标:按反编译文件彻底还原各素材类型的字段、必填项、文件要求、预览/展示图规则,并与 `materials` 表字段一致,避免落库不匹配。
## 数据库字段(materials)
- 关键:`productModel`(SPU)、`categoryName`(店铺)、`sceneName`(场景)、`platformName`、`productCategoryName`、`materialType`、`renderer`、`previewUrl`
- 文件:`zipFileName`(视频/音频存 S3 URL;其它存文件名)、`zipFilePath`(本地路径)、`zipFileSize`
- 展示:`displayImages` 数组
- 视频:`videoSourceUrl`、`videoPreview540Url`、`videoPreviewClipUrl`、`videoCoverUrl`、`videoProcessingStatus`、`videoDuration`、`transcodeLastError`、`transcodeAttempts`
- 分片:`uploadId`
## 素材类型清单(反编译下拉)
3D场景、详情页、材质、模特、实拍图片、买家秀图片、小红书种草、主图模版、SKU模版、主图视频、安装视频、种草视频、音乐、C4D模型、标准饰品、标准模型、品牌VI灵感、矢量文件。
## 各类型必填/文件/预览规则
- **通用 SPU**:大多数类型必填 `productModel`。批量(音乐/视频/3D场景/买家秀/小红书/品牌VI)每条都要 SPU。
- **店铺/场景自动填充**:材质/音乐/种草视频 → `categoryName=通用`,`sceneName=通用`。
- **预览图必填**(反编译逻辑):
- 必填:除以下类型外都要预览图。
- 例外(可不填):详情页、模特、实拍图片、买家秀图片、小红书种草、主图模版、SKU模版、品牌VI灵感、主图视频、安装视频、种草视频、音乐、(3D场景批量且各文件已带预览)。
- 3D场景批量:每个文件必须有预览图。
- **展示图/切片**:
- 详情页:必须展示图(displayImages)。
- 模特/实拍/买家秀/小红书/主图模版/SKU模版/品牌VI:必须展示图或 PDF。展示图做压缩/切片。
- 买家秀批量:每批 ≥ 8 张图。
- 品牌VI:支持 PDF,自动从文件名生成 SPU 可手改。
- **主文件必填**:
- 除模特/标准模型外,其余类型需要主文件。
- 音乐、种草视频:文件必传。
- **批量上传**:
- 音乐(I[])、视频(D[])、3D场景(M[])、买家秀(A[])、小红书(L[])、品牌VI(O[]) 支持多批;每批含 productModel、文件/展示图。
## 文件格式与存储
- 视频/音频:直传 S3,`zipFileName` 保存 S3 URL,同时写 `videoSourceUrl`(视频类型),`videoProcessingStatus='pending'`。
- 其他:存本地 `zipFilePath`,文件名写 `zipFileName`。
- 展示图:`displayImages` 数组;预览图 `previewUrl`。
- 品牌VI PDF:走本地存储(zipFilePath/zipFileName/zipFileSize),允许展示图或 PDF。
## 前端处理要求(反编译)
- 图片压缩:预览/展示图压缩 `maxWidth≈800, maxHeight≈2000, quality≈0.85`,上传前压缩。
- 展示图切片:多图类型(模特/买家秀等)切片上传;买家秀批次 ≥ 8 图。
- 分片上传:主文件 >5MB 走 `chunkUpload` → `/api/materials/upload/complete` → 携 metadata 正式提交。
- 校验提示:SPU/预览/展示图/文件必填、买家秀≥8张、品牌VI PDF、标准模型需品类、通用店铺/场景填充等。
## 后端处理要点
- `/api/materials/upload`:
- 支持从分片合并文件 `existingFilePath` 读取。
- 视频/音频:S3 上传,写 `videoSourceUrl`、`zipFileName`=S3 URL,`videoProcessingStatus='pending'`。
- 品牌VI/PDF:存本地,写 `zipFilePath/zipFileName/zipFileSize`。
- 展示图数组写入 `displayImages`;预览图写 `previewUrl`。
- 分片阈值:反编译约 5MB(可按此恢复)。
## 待落地的主要差距
- 前端缺批量数据结构与批量校验(音乐/视频/3D场景/买家秀/小红书/品牌VI),买家秀≥8张、品牌VI PDF、通用店铺/场景自动填充未还原。
- 预览/展示图压缩与切片未还原;预览必填规则与异常类型需按上文实现。
- 分片阈值当前 50MB,需调 5MB 对齐反编译。
- 后端仍是单条创建路径,需确认批量是“多次请求”还是“批处理”;若多次请求,前端需循环调用;品牌VI/PDF分支需完善。
## 执行顺序建议
1) 前端:重建批量数据结构、校验、通用填充、压缩/切片、分片阈值 5MB。
2) 后端:补品牌VI/PDF、本地存储分支;确保视频/音频 S3 分支落库字段一致;确认批量调用策略。
3) 验证:按各类型场景上传,检查 DB 字段写入与转码/预览。