# 图片资产生命周期

> 状态：已实施（2026-08-30）  
> 适用范围：采集图、手动上传图、AI 套图、单张 AI 图生图，以及图片水印。

## 1. 核心模型

每个 `product_assets` 图片素材只维护两个逻辑版本：

```text
original：无水印原图，始终保留
current：页面预览、单图下载、ZIP 导出使用的当前版本
```

| 状态 | original | current | 七牛对象数 |
|---|---|---|---|
| 未加水印 | 同一个对象 | 指向 original | 1 |
| 已加水印 | 无水印对象 | 指向水印对象 | 2 |

系统**不保留历史水印版**。修改水印时，先上传新的水印版并切换 current，再删除旧水印版。

采集图、上传图、AI 图的区别只在 original 的来源：采集源站、用户上传文件、模型输出。后续水印、下载、删除均走同一套流程。

## 2. 数据字段

`product_assets` 继续保留 `stored_url` 兼容既有前端接口；其语义为 current URL。新增字段：

| 字段 | 含义 |
|---|---|
| `original_url` | 无水印原图公开 URL |
| `original_storage_key` | 无水印原图对象 Key |
| `current_storage_key` | 当前展示对象 Key |
| `watermark_enabled` | current 是否为水印版 |
| `watermark_config` | 当前水印配置快照 |

删除对象必须使用 `storage_key`，不应由 URL 反推；`storage_key_from_url()` 仅用于兼容旧数据迁移。

迁移：`a41e8c7f4b20_add_asset_image_lifecycle.py`。`start.command` 会在启动服务前执行 `alembic upgrade head`。

## 3. 对象路径

新图片统一使用：

```text
products/{product_id}/assets/{asset_id}/original.{ext}
products/{product_id}/assets/{asset_id}/watermark-{uuid}.{ext}
```

路径前缀不仅便于单图精准删除，也允许删除商品时按 `products/{product_id}/` 兜底清理所有对象，包括异常中断留下的孤儿文件。

## 4. 创建与水印流程

### 采集、上传、无水印 AI 图

```text
写入 original
→ current 指向 original
→ watermark_enabled = false
```

### 添加或修改水印

```text
读取 original
→ 合成新水印图
→ 上传新 current
→ 提交数据库切换 current
→ 删除旧 current（水印版）
```

因此不会叠加水印。AI 生图参考图也优先使用 `original_url`，避免把水印带进下一次生成。

### 移除水印

```text
current 切回 original
→ 提交数据库
→ 删除旧水印对象
```

## 5. 删除流程

### 删除单张素材

```text
删除 products/{product_id}/assets/{asset_id}/ 前缀
→ 删除旧格式路径中的 original/current 对象（兼容迁移前数据）
→ 删除 product_assets 记录
```

若对象存储删除失败，接口返回失败并保留数据库素材记录，避免出现“数据库已删、文件未删”的静默状态。

### 硬删除商品

```text
查询商品所有素材
→ 清理每个素材目录和旧格式对象
→ 清理 products/{product_id}/ 前缀（孤儿兜底）
→ 删除商品，数据库级联删除素材记录
```

归档商品只改变商品状态，不删除图片。

## 6. 服务职责

| 模块 | 职责 |
|---|---|
| `services/image_assets.py` | original/current 生命周期、加/移水印、迁入正式路径、单图/整商品回收 |
| `services/storage.py` | 本地/七牛上传、下载、按 Key 删除、按前缀删除、URL→Key 兼容解析 |
| `services/watermark.py` | 纯图片字节合成；不操作数据库或对象存储 |
| API 路由 | 参数校验、数据库提交、调用生命周期服务 |

## 7. 前端入口

试算页“采集图片”和“生成结果”均可打开水印设置：

- 为已选采集图添加水印；
- 为已选生成图添加水印；
- 移除已选采集图或生成图水印；
- 新的一键生图和单张 AI 生图按当前设置自动加水印。

预览、下载与 ZIP 导出始终使用 `stored_url`（current）；AI 生成参考图使用 `original_url`。

## 8. 旧数据兼容

旧素材首次加/移水印时会迁入新的商品/素材路径，并补齐 original/current 字段。迁移前已经产生但数据库无记录的旧七牛对象无法可靠识别；后续可按运营需要增加七牛前缀扫描与人工确认清理工具。