feat(api-water): 支持上传水印图片

2026-09-04 14:27:59 +08:00
parent c2523fe349
commit 009082d0f4
15 changed files with 6484 additions and 6089 deletions
@@ -22,7 +22,7 @@ Headers：`Idempotency-Key` 必填。
 }
 ```

-首期允许 `image/png`、`image/jpeg`、`image/webp`。服务端按用途校验大小/尺寸策略，生成随机 `object_key` 和短时预签名上传地址。返回 `201 Created`：
+首期允许 `image/png`、`image/jpeg`、`image/webp`，最大 5 MiB，图片宽高须为 1–8192 px。服务端按用途校验大小/尺寸策略，生成随机 `object_key` 和 10 分钟有效的预签名上传地址。返回 `201 Created`：

 ```json
 {
@@ -50,7 +50,7 @@ Headers：`Idempotency-Key` 必填。
 { "checksum_sha256": "hex-sha256" }
 ```

-服务端检查对象存在、文件大小、MIME/魔数、哈希和图片尺寸；校验通过后创建/复用 `media_asset` 并返回 `201 Created`。图片解码或安全扫描耗时时可先返回 `202` 与 `media_processing` operation。
+服务端检查对象存在、文件大小、声明 MIME、文件魔数、哈希和图片尺寸；校验通过后创建/复用 `media_asset` 并返回 `201 Created`。校验失败时上传意图标记为失败，不能被水印模板引用。

 ```json
 {
@@ -67,7 +67,7 @@ Headers：`Idempotency-Key` 必填。
 }
 ```

-`object_key` 是服务端内部字段，不放在普通客户端响应。上传意图、完成状态和对象清理需要在实现时增加持久化记录；它不能只存在于 Redis 或预签名 token 中。
+`object_key` 是服务端内部字段，不放在普通客户端响应。上传意图和完成状态均持久化在数据库，不能只存在于 Redis 或预签名 token 中；过期和失败对象由后续清理任务回收。

 ### 1.3 临时预览 URL

@@ -77,7 +77,7 @@ Headers：`Idempotency-Key` 必填。
 { "purpose": "preview" }
 ```

-返回短时 `url` 与 `expires_at`。仅当前工作空间的素材可签发；前端在 URL 过期后重新请求，不能把 URL 写回业务表或长期缓存。
+返回 10 分钟有效的短时 `url` 与 `expires_at`。仅当前工作空间的素材可签发；前端在 URL 过期后重新请求，不能把 URL 写回业务表或长期缓存。

 ## 2. 可用字体