# 资产铸造（AI 生成版）流程设计文档

## 📋 文档信息

- **版本**: v1.0
- **创建日期**: 2026-01-20
- **状态**: 待确认
- **作者**: 开发团队

---

## 📊 文档状态总结

### ✅ 已确认的设计
- ✅ 采用异步处理机制（AI 生成耗时，不阻塞用户请求）
- ✅ AI 生成的图片必须存储到 OSS（确保持久性）
- ✅ 使用预签名 URL 机制访问私有 OSS 资源
- ✅ 复用现有的 `Asset` 和 `MintOrder` 数据模型
- ✅ **AI 服务先使用 Mock 版本**，实现完整的前后端对接流程
- ✅ **铸造订单失败时自动退回水晶费用**（无论 AI 问题还是链问题）
- ✅ **所有图片 URL 自动生成预签名 URL**（在查询接口中）
- ✅ **前端轮询频率为 3 秒**
- ✅ **AI 生成失败时，前端查询返回失败消息**
- ✅ **暂不支持 WebSocket、进度提示、批量铸造**

### ⚠️ 后续优化项（暂不实现）
1. WebSocket 实时通知（当前使用轮询）
2. AI 生成进度百分比显示
3. 批量铸造功能（一次提交多个素材）

---

## 1. 业务概述

### 1.1 功能描述
用户通过上传原始图片（素材）并填写元数据信息，发起“铸造”请求。系统将：
1. 扣除用户的水晶余额作为铸造费用
2. 异步调用 AI 服务，基于原始素材生成一张新的艺术图片
3. 将 AI 生成的图片上传到 OSS 存储
4. 模拟区块链上链过程（生成交易哈希和模拟地址）
5. 更新资产状态为“已激活”，用户可在“我的藏品”中查看

### 1.2 核心特点
- **异步处理**：AI 生成耗时较长（通常 10-60 秒），采用后台异步处理，不阻塞用户请求
- **持久化存储**：AI 生成的图片必须转存到自己的 OSS，避免临时链接失效
- **状态可追踪**：用户可通过 `order_id` 实时查询铸造进度
- **安全访问**：私有 OSS 资源通过预签名 URL 机制访问

---

## 2. 系统架构

### 2.1 参与角色
| 角色 | 职责 |
| :--- | :--- |
| **前端 (FE)** | 用户交互、图片上传、状态展示、结果呈现 |
| **网关 (GW)** | 鉴权、限流、请求转发 |
| **资产服务 (AssetService)** | 订单管理、资产状态更新、异步任务调度 |
| **用户服务 (UserService)** | 水晶余额校验与扣减 |
| **AI 代理层 (AI Task)** | 对接 AI 接口、图片转存 OSS、模拟上链 |
| **阿里云 OSS** | 存储原始素材图和 AI 生成的目标图 |

### 2.2 数据流向
```
用户上传素材 → OSS (material_url)
     ↓
创建铸造订单 → 数据库 (Asset + MintOrder)
     ↓
异步 AI 处理 → AI 服务 → 下载图片 → 上传 OSS (cover_url)
     ↓
更新数据库 → 状态变更 (Pending → Active)
     ↓
前端轮询查询 → 返回结果（含预签名 URL）
```

---

## 3. 详细交互流程

### 3.1 完整流程图

```mermaid
sequenceDiagram
    autonumber
    participant 用户
    participant 前端
    participant 网关
    participant 资产服务
    participant 用户服务
    participant 异步任务(AI+OSS)
    participant AI服务
    participant OSS存储

    Note over 用户, OSS存储: 第一阶段：素材准备
    用户->>前端: 选择图片并填写信息
    前端->>网关: GET /api/v1/assets/oss/upload-signature?type=asset
    网关-->>前端: 返回STS临时凭证 + 目录路径
    前端->>OSS存储: 直传素材图 (POST Object)
    OSS存储-->>前端: 上传成功，返回 material_url

    Note over 用户, OSS存储: 第二阶段：发起铸造 (同步，立即返回)
    前端->>网关: POST /api/v1/assets/mints
    Note right of 前端: {<br/>  "name": "资产名称",<br/>  "material_url": "...",<br/>  "description": "描述"<br/>}
    网关->>资产服务: CreateMintOrder (RPC)
    资产服务->>用户服务: 扣除铸造费用 (UpdateCrystalBalance)
    用户服务-->>资产服务: 扣费成功
    资产服务->>资产服务: DB事务：创建 Asset (Status=0) + Order (Status=PROCESSING)
    资产服务-->>网关: 返回 order_id
    网关-->>前端: 返回 200 OK { order_id, status: "PROCESSING" }
    前端->>用户: 界面显示 "AI创作中，请稍候..."

    Note over 用户, OSS存储: 第三阶段：异步生成 (后台处理)
    rect rgb(240, 240, 240)
    资产服务->>异步任务(AI+OSS): 启动 Goroutine 处理
    alt AI处理成功
        异步任务(AI+OSS)->>AI服务: 调用AI接口 (输入: material_url) [Mock版本]
        AI服务-->>异步任务(AI+OSS): 返回AI生成图片 (临时URL或Base64)
        异步任务(AI+OSS)->>异步任务(AI+OSS): 下载AI图片到内存
        异步任务(AI+OSS)->>OSS存储: 上传到 OSS (asset/{user_id}/{star_id}/covers/{asset_id}.png)
        OSS存储-->>异步任务(AI+OSS): 返回 cover_url
        异步任务(AI+OSS)->>异步任务(AI+OSS): 生成模拟 TxHash (0x...)
        异步任务(AI+OSS)->>资产服务: 更新 DB: Asset (Status=1, CoverURL, TxHash)
        资产服务->>资产服务: 更新 Order 为 SUCCESS
    else AI处理失败
        异步任务(AI+OSS)->>资产服务: 更新 Order 为 FAILED + error_message
        资产服务->>用户服务: 退回水晶费用 (UpdateCrystalBalance)
        用户服务-->>资产服务: 退费成功
    end
    end

    Note over 用户, OSS存储: 第四阶段：结果获取 (轮询/展示)
    loop 状态轮询 (每3秒)
        前端->>网关: GET /api/v1/assets/mints/:order_id
        网关->>资产服务: 查询订单状态 (GetMintOrder)
        资产服务-->>前端: 返回 Status=SUCCESS, cover_url=...
    end
    alt 状态为SUCCESS
        资产服务-->>前端: 返回 Status=SUCCESS, cover_url_signed=... (已自动生成预签名URL)
        前端->>用户: 动画展示生成的藏品 & 模拟链上地址
    else 状态为FAILED
        资产服务-->>前端: 返回 Status=FAILED, error_message="AI生成失败，已退回费用"
        前端->>用户: 显示失败提示 & 费用已退回消息
    end
```

### 3.2 阶段说明

#### 阶段一：素材准备（前端完成）
1. 用户在前端选择图片并填写元数据（名称、描述等）
2. 前端调用 `GET /api/v1/assets/oss/upload-signature?type=asset` 获取 OSS 上传凭证
3. 前端使用临时凭证直接上传图片到 OSS（路径：`asset/{user_id}/{star_id}/materials/{filename}`）
4. 前端获得 `material_url`（原始素材的 OSS 地址）

#### 阶段二：发起铸造（同步，立即返回）
1. 前端调用 `POST /api/v1/assets/mints`，传入 `material_url` 和元数据
2. 后端在事务中完成：
   - 扣除用户水晶余额（调用 UserService）
   - 创建 `Asset` 记录（`Status = 0 (Pending)`，`MaterialURL` 已设置，`CoverURL` 为空）
   - 创建 `MintOrder` 记录（`Status = PROCESSING`）
3. 立即返回 `order_id`，不等待 AI 处理

#### 阶段三：异步 AI 处理（后台 Goroutine）
1. 启动独立的 Goroutine 处理 AI 生成任务
2. 调用 AI 服务接口（输入：`material_url`）
   - **Mock 版本**：随机选择预设图片或直接复制 `material_url` 的图片
3. AI 服务返回生成的图片（可能是临时 URL 或 Base64）
4. 下载 AI 生成的图片到内存
5. 上传到 OSS（路径：`asset/{user_id}/{star_id}/covers/{asset_id}_{timestamp}.png`）
6. 生成模拟链上信息：
   - `TxHash`: `0x` + 64位随机16进制字符串
   - `BlockNumber`: 随机生成
   - `MintedAt`: 当前时间戳
7. 更新数据库：
   - `Asset.Status = 1 (Active)`
   - `Asset.CoverURL = <OSS地址>`
   - `Asset.TxHash = <模拟哈希>`
   - `MintOrder.Status = SUCCESS`

**失败处理**（AI 超时、AI 调用失败、OSS 上传失败等）：
1. 记录错误信息到 `MintOrder.error_message`
2. 更新订单状态为 `FAILED`
3. **自动退回水晶费用**：调用 `UserService.UpdateCrystalBalance`，退回 `cost_crystal` 金额
4. 记录日志，便于后续排查

#### 阶段四：结果获取（前端轮询）
1. 前端每 3 秒轮询一次 `GET /api/v1/assets/mints/:order_id`
2. **成功场景**：当 `status = SUCCESS` 时
   - 前端获取到 `cover_url_signed`（后端已自动生成预签名 URL）
   - 展示生成的藏品图片和模拟链上地址
3. **失败场景**：当 `status = FAILED` 时
   - 前端获取到 `error_message` 字段
   - 展示失败提示："AI生成失败，已退回水晶费用"
   - 用户可重新提交订单

---

## 4. API 接口定义

### 4.1 创建铸造订单

**Endpoint**: `POST /api/v1/assets/mints`

**认证**: 需要 JWT Token（从 Header 中获取 `user_id` 和 `star_id`）

**Request Body**:
```json
{
  "name": "我的数字艺术藏品",
  "material_url": "https://top-fans-test.oss-cn-shanghai.aliyuncs.com/asset/7/87/materials/original.jpg",
  "description": "这是由AI生成的数字艺术品",
  "rarity": 1,
  "tags": ["AI", "Art", "Digital"]
}
```

**字段说明**:
| 字段 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `name` | string | ✅ | 资产名称 |
| `material_url` | string | ✅ | 原始素材的 OSS URL（前端已上传到 `asset/{user_id}/{star_id}/materials/` 目录） |
| `description` | string | ❌ | 资产描述 |
| `rarity` | int32 | ❌ | 稀有度（预留字段） |
| `tags` | string[] | ❌ | 标签数组 |

**重要说明**:
- ✅ `material_url` 是必填字段，前端必须在调用此接口前完成素材上传
- ✅ `cover_url` 不需要前端传入，由后端 AI 处理完成后自动生成
- ✅ 创建订单时，`Asset.CoverURL` 字段为空，等待异步任务完成后回填

**Response (200 OK)**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset_id": 12345,
    "status": "PROCESSING",
    "created_at": 1705747200000
  }
}
```

**错误响应**:
- `400 Bad Request`: 参数错误（缺少必填字段、URL 格式错误等）
- `401 Unauthorized`: 未授权（Token 无效）
- `402 Payment Required`: 水晶余额不足
- `500 Internal Server Error`: 服务器内部错误

---

### 4.2 查询铸造订单状态

**Endpoint**: `GET /api/v1/assets/mints/:order_id`

**认证**: 需要 JWT Token（只能查询自己的订单）

**URL 参数**:
- `order_id`: 订单 ID（UUID 格式）

**Response (200 OK) - 成功状态**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset_id": 12345,
    "status": "SUCCESS",
    "cover_url": "https://top-fans-test.oss-cn-shanghai.aliyuncs.com/asset/7/87/covers/12345_1705747200.png",
    "cover_url_signed": "https://top-fans-test.oss-cn-shanghai.aliyuncs.com/asset/7/87/covers/12345_1705747200.png?Expires=...&Signature=...",
    "tx_hash": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "minted_at": 1705747260000,
    "created_at": 1705747200000,
    "updated_at": 1705747260000
  }
}
```

**Response (200 OK) - 处理中状态**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset_id": 12345,
    "status": "PROCESSING",
    "cover_url": null,
    "cover_url_signed": null,
    "tx_hash": null,
    "minted_at": null,
    "created_at": 1705747200000,
    "updated_at": 1705747200000
  }
}
```

**Response (200 OK) - 失败状态**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset_id": 12345,
    "status": "FAILED",
    "error_message": "AI生成超时，已自动退回水晶费用",
    "cover_url": null,
    "cover_url_signed": null,
    "tx_hash": null,
    "minted_at": null,
    "created_at": 1705747200000,
    "updated_at": 1705747300000
  }
}
```

**状态值说明**:
- `PROCESSING`: AI 生成中（前端继续轮询）
- `SUCCESS`: 生成成功（前端展示结果）
- `FAILED`: 生成失败（前端显示 `error_message`，提示用户费用已退回）

**关键设计点**:
- ✅ **自动预签名**：`status = SUCCESS` 时，自动返回 `cover_url_signed` 预签名 URL
- ✅ **失败信息返回**：`status = FAILED` 时，返回 `error_message` 字段，前端直接展示
- ✅ **费用已退回**：失败时，后端已自动退回水晶费用，前端无需额外处理

**错误响应**:
- `404 Not Found`: 订单不存在或不属于当前用户
- `401 Unauthorized`: 未授权

---

### 4.3 获取我的藏品列表

**Endpoint**: `GET /api/v1/assets/me`

**认证**: 需要 JWT Token

**Query 参数**:
- `page`: 页码（默认 1）
- `page_size`: 每页数量（默认 20，最大 100）
- `status`: 筛选状态（可选：`pending`, `active`，默认返回全部）

**Response (200 OK)**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "asset_id": 12345,
        "name": "我的数字艺术藏品",
        "cover_url": "https://top-fans-test.oss-cn-shanghai.aliyuncs.com/asset/7/87/covers/12345_1705747200.png",
        "cover_url_signed": "https://top-fans-test.oss-cn-shanghai.aliyuncs.com/asset/7/87/covers/12345_1705747200.png?Expires=...&Signature=...",
        "status": "active",
        "tx_hash": "0x1a2b3c4d...",
        "minted_at": 1705747260000,
        "like_count": 10,
        "created_at": 1705747200000
      },
      {
        "asset_id": 12346,
        "name": "另一个藏品",
        "cover_url": null,
        "cover_url_signed": null,
        "status": "pending",
        "tx_hash": null,
        "minted_at": null,
        "like_count": 0,
        "created_at": 1705747300000
      }
    ]
  }
}
```

**关键设计点**:
- ✅ **自动预签名**：后端在返回数据前，自动为所有 `cover_url` 和 `material_url` 生成预签名 URL，放入 `*_signed` 字段
- ✅ **状态区分**：`status = pending` 时，`cover_url` 为 `null`，前端显示“生成中”占位图
- ✅ **状态筛选**：支持按状态筛选，方便用户查看“进行中”或“已完成”的藏品
- ✅ **失败状态展示**：`status = failed` 的藏品也会出现在列表中，`cover_url` 为 `null`，前端可显示“生成失败”提示

---

### 4.4 获取藏品详情

**Endpoint**: `GET /api/v1/assets/:asset_id`

**认证**: 需要 JWT Token（只能查看自己的藏品或公开藏品）

**Response (200 OK)**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "asset_id": 12345,
    "name": "我的数字艺术藏品",
    "description": "这是由AI生成的数字艺术品",
    "material_url": "https://.../materials/original.jpg",
    "material_url_signed": "https://...?Expires=...&Signature=...",
    "cover_url": "https://.../covers/12345_1705747200.png",
    "cover_url_signed": "https://...?Expires=...&Signature=...",
    "status": "active",
    "tx_hash": "0x1a2b3c4d...",
    "block_number": 12345678,
    "minted_at": 1705747260000,
    "like_count": 10,
    "is_liked": false,
    "created_at": 1705747200000
  }
}
```

---

## 5. 数据模型设计

### 5.1 Asset 表（资产表）

**现有字段复用**:
| 字段 | 类型 | 用途 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | int64 | 资产ID | 主键 |
| `owner_uid` | int64 | 所有者ID | 外键关联 users 表 |
| `star_id` | int64 | 明星ID | 用于数据隔离 |
| `name` | string | 资产名称 | 用户填写 |
| `cover_url` | string | **AI生成图URL** | 异步处理完成后回填 |
| `material_url` | string | **原始素材URL** | 前端上传时设置 |
| `description` | text | 描述 | 用户填写 |
| `status` | int32 | 状态 | `0=Pending`, `1=Active` |
| `tx_hash` | string | 交易哈希 | 模拟生成（0x...） |
| `block_number` | int64 | 区块号 | 模拟生成 |
| `minted_at` | int64 | 上链时间 | 毫秒时间戳 |
| `like_count` | int32 | 点赞数 | 默认 0 |
| `created_at` | int64 | 创建时间 | 毫秒时间戳 |
| `updated_at` | int64 | 更新时间 | 毫秒时间戳 |

**关键字段映射**:
- ✅ `MaterialURL` → 用户上传的原始素材（前端已上传到 OSS）
- ✅ `CoverURL` → AI 生成的最终图片（异步任务完成后回填）
- ✅ `Status` → `0` 表示处理中，`1` 表示已完成

### 5.2 MintOrder 表（铸造订单表）

**现有字段复用**:
| 字段 | 类型 | 用途 | 说明 |
| :--- | :--- | :--- | :--- |
| `order_id` | string | 订单ID | UUID，主键 |
| `user_id` | int64 | 用户ID | 外键关联 users 表 |
| `star_id` | int64 | 明星ID | 用于数据隔离 |
| `asset_id` | int64 | 资产ID | 外键关联 assets 表 |
| `status` | string | 订单状态 | `PROCESSING`, `SUCCESS`, `FAILED` |
| `cost_crystal` | int64 | 消耗水晶 | 铸造费用 |
| `error_message` | text | 错误信息 | 失败时记录原因 |
| `retry_count` | int32 | 重试次数 | 默认 0 |
| `created_at` | int64 | 创建时间 | 毫秒时间戳 |
| `updated_at` | int64 | 更新时间 | 毫秒时间戳 |
| `minted_at` | int64 | 完成时间 | 毫秒时间戳 |

---

## 6. 状态机设计

### 6.1 Asset 状态流转

```
[Pending (0)] ──AI处理成功──> [Active (1)]
     │                              │
     └──AI处理失败──> [Pending (0)] ──┘
     (保持Pending，记录错误信息)
```

**状态说明**:
- **Pending (0)**: 资产创建后，等待 AI 处理或处理失败
- **Active (1)**: AI 处理成功，资产可用（`CoverURL` 已设置）

### 6.2 MintOrder 状态流转

```
[PROCESSING] ──AI处理成功──> [SUCCESS]
     │                              │
     └──AI处理失败──> [FAILED] ────┘
     (记录 error_message)
```

**状态说明**:
- **PROCESSING**: 订单创建后，AI 处理中
- **SUCCESS**: AI 处理成功，资产已激活
- **FAILED**: AI 处理失败（超时、API 错误等）

---

## 7. 关键设计决策

### 7.1 异步处理机制

**决策**: 采用 Goroutine 异步处理 AI 生成任务，不阻塞用户请求。

**理由**:
- AI 生成通常需要 10-60 秒，同步等待会导致请求超时
- 用户体验更好：用户提交后立即获得 `order_id`，可继续其他操作
- 系统可扩展：后续可引入消息队列（如 RocketMQ）进行任务调度

**实现方式**:
```go
// 在 CreateMintOrder 中，创建订单后立即启动异步任务
go s.processAIGeneration(mintOrder.OrderID, asset.ID, req.MaterialUrl)
```

### 7.2 AI 图片必须存储到 OSS

**决策**: AI 服务返回的图片（临时 URL 或 Base64）必须下载并上传到自己的 OSS。

**理由**:
- AI 服务的临时 URL 通常有效期仅 1 小时，不转存会导致链接失效
- 统一管理：所有资产图片都在自己的 OSS 中，便于权限控制和 CDN 加速
- 数据安全：避免依赖第三方服务的稳定性

**实现方式**:
1. 调用 AI 服务，获取生成的图片（临时 URL 或 Base64）
2. 下载图片到内存（如果是 URL，使用 HTTP GET；如果是 Base64，解码）
3. 上传到 OSS（路径：`asset/{user_id}/{star_id}/covers/{asset_id}_{timestamp}.png`）
4. 将 OSS URL 回填到 `Asset.CoverURL`

### 7.3 预签名 URL 自动生成

**决策**: 在 `GetMyAssets`、`GetAssetDetail` 和 `GetMintOrder` 接口中，后端自动为**所有图片 URL** 生成预签名 URL。

**理由**:
- 减少前端请求次数：前端不需要为每张图片单独调用预签名接口
- 统一管理：后端统一控制访问权限和有效期
- 性能优化：批量生成预签名 URL，减少 OSS API 调用
- 用户体验：前端拿到数据即可直接展示图片，无需额外请求

**实现方式**:
```go
// 在 DTO 转换层，自动为所有图片 URL 生成预签名 URL
func ToAssetDTO(asset *models.Asset) *dto.AssetDTO {
    dto := &dto.AssetDTO{
        AssetID: asset.ID,
        CoverURL: asset.CoverURL,
        MaterialURL: asset.MaterialURL,
    }
    
    // 为 cover_url 生成预签名 URL（如果存在）
    if asset.CoverURL != "" {
        signedURL, _ := generatePresignedURL(asset.CoverURL, 3600)
        dto.CoverURLSigned = signedURL
    }
    
    // 为 material_url 生成预签名 URL（如果存在）
    if asset.MaterialURL != nil && *asset.MaterialURL != "" {
        signedURL, _ := generatePresignedURL(*asset.MaterialURL, 3600)
        dto.MaterialURLSigned = &signedURL
    }
    
    return dto
}
```

**适用范围**:
- ✅ `GET /api/v1/assets/me` - 藏品列表
- ✅ `GET /api/v1/assets/:asset_id` - 藏品详情
- ✅ `GET /api/v1/assets/mints/:order_id` - 订单状态查询（成功时）

### 7.4 模拟链上信息生成

**决策**: 在前期不引入链端 API 的情况下，后端模拟生成 `TxHash` 和 `BlockNumber`。

**实现方式**:
```go
// 生成模拟交易哈希
txHash := fmt.Sprintf("0x%x", rand.Int63()) // 0x + 64位16进制

// 生成模拟区块号
blockNumber := rand.Int63n(1000000) + 1000000

// 设置上链时间
mintedAt := time.Now().UnixMilli()
```

**后续扩展**: 当引入真实区块链时，只需替换此处的模拟逻辑为真实的链端 SDK 调用。

---

## 8. 错误处理与异常场景

### 8.1 AI 生成超时

**场景**: AI 服务响应时间超过 60 秒。

**处理**:
1. 设置超时时间（60 秒，可配置）
2. 超时后，将订单状态更新为 `FAILED`
3. 记录错误信息：`error_message = "AI生成超时"`
4. **✅ 自动回退水晶费用**：调用 `UserService.UpdateCrystalBalance`，退回 `cost_crystal` 金额
5. 记录日志，便于后续排查

### 8.2 AI 服务调用失败

**场景**: AI 服务返回错误（API 限流、服务不可用等）。

**处理**:
1. 记录错误信息到 `MintOrder.error_message`（如："AI服务调用失败: API限流"）
2. 更新订单状态为 `FAILED`
3. **✅ 自动回退水晶费用**：调用 `UserService.UpdateCrystalBalance`，退回 `cost_crystal` 金额
4. **暂不重试**：当前版本不自动重试，失败即退回费用（后续版本可考虑重试机制）

### 8.3 OSS 上传失败

**场景**: AI 图片下载成功，但上传到 OSS 失败。

**处理**:
1. 记录错误信息：`error_message = "OSS上传失败: <具体错误>"`
2. 订单状态更新为 `FAILED`
3. **✅ 自动回退水晶费用**：调用 `UserService.UpdateCrystalBalance`，退回 `cost_crystal` 金额
4. **建议**：保留 AI 服务的临时 URL（如果还在有效期内），记录到日志，便于后续手动重试

### 8.4 链上模拟失败（预留）

**场景**: 模拟链上信息生成失败（当前版本为模拟，此场景理论上不会发生，但预留处理逻辑）。

**处理**:
1. 记录错误信息
2. 订单状态更新为 `FAILED`
3. **✅ 自动回退水晶费用**：调用 `UserService.UpdateCrystalBalance`，退回 `cost_crystal` 金额

### 8.5 用户余额不足

**场景**: 创建订单时，用户水晶余额不足。

**处理**:
1. 在事务中先检查余额，不足则直接返回错误
2. 不创建 `Asset` 和 `MintOrder` 记录
3. 返回 HTTP 402 状态码，前端提示“余额不足”

### 8.6 费用回退统一处理

**决策**: 所有失败场景（AI 超时、AI 调用失败、OSS 上传失败、链上失败）都必须自动退回水晶费用。

**实现方式**:
```go
// 在异步任务失败时，统一调用费用回退
func (s *mintService) refundCrystalBalance(order *models.MintOrder) error {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    // 退回水晶费用
    _, err := s.userClient.UpdateCrystalBalance(ctx, order.UserID, order.StarID, order.CostCrystal)
    if err != nil {
        logger.Logger.Error("Failed to refund crystal balance",
            zap.String("order_id", order.OrderID),
            zap.Error(err),
        )
        return err
    }
    
    logger.Logger.Info("Crystal balance refunded",
        zap.String("order_id", order.OrderID),
        zap.Int64("amount", order.CostCrystal),
    )
    
    return nil
}
```

**注意事项**:
- 费用回退必须在订单状态更新为 `FAILED` 之前完成（确保原子性）
- 如果费用回退失败，需要记录告警日志，并可能需要人工介入

---

## 9. 性能优化建议

### 9.1 异步任务并发控制

**建议**: 限制同时处理的 AI 任务数量，避免过载。

**实现方式**:
```go
// 使用 channel 作为信号量，限制并发数
var semaphore = make(chan struct{}, 10) // 最多10个并发任务

func (s *mintService) processAIGeneration(...) {
    semaphore <- struct{}{} // 获取信号量
    defer func() { <-semaphore }() // 释放信号量
    
    // AI 处理逻辑
}
```

### 9.2 预签名 URL 批量生成

**建议**: 在 `GetMyAssets` 接口中，批量生成预签名 URL，减少 OSS API 调用。

**实现方式**:
```go
// 一次性为所有 cover_url 生成预签名 URL
for i := range assets {
    if assets[i].CoverURL != "" {
        signedURL, _ := generatePresignedURL(assets[i].CoverURL, 3600)
        assets[i].CoverURLSigned = signedURL
    }
}
```

### 9.3 数据库索引优化

**建议**: 确保以下字段已建立索引：
- `assets.owner_uid + star_id`（复合索引，用于查询用户藏品）
- `assets.status`（用于筛选状态）
- `mint_orders.user_id + star_id`（复合索引，用于查询用户订单）
- `mint_orders.status`（用于筛选订单状态）

---

## 10. 已确认问题清单

### ✅ 已确认的设计决策

1. **AI 服务选择** ✅
   - ✅ **先使用 Mock 版本**：实现完整的前后端对接流程，AI 服务暂时模拟（返回一张预设图片或随机选择）
   - ✅ **后续集成真实 AI 服务**：Phase 4 再集成真实的 AI 服务 API
   - ✅ **Mock 实现方式**：可以随机选择一张预设图片，或直接复制 `material_url` 作为 `cover_url`（仅用于测试）

2. **AI 生成超时与重试** ✅
   - ✅ **超时时间**：60 秒（可配置）
   - ✅ **失败处理**：不自动重试，失败即退回费用（后续版本可考虑重试机制）

3. **费用回退策略** ✅
   - ✅ **自动回退**：所有失败场景（AI 超时、AI 调用失败、OSS 上传失败、链上失败）都必须自动退回水晶费用
   - ✅ **回退时机**：在订单状态更新为 `FAILED` 时，立即调用 `UserService.UpdateCrystalBalance` 退回费用
   - ✅ **回退金额**：退回 `MintOrder.cost_crystal` 的完整金额

4. **藏品列表预签名** ✅
   - ✅ **自动生成**：在 `GetMyAssets`、`GetAssetDetail` 和 `GetMintOrder` 接口中，自动为所有图片 URL 生成预签名 URL
   - ✅ **有效期**：3600 秒（1 小时）
   - ✅ **适用范围**：`cover_url` 和 `material_url` 都需要生成预签名 URL

5. **状态轮询频率** ✅
   - ✅ **轮询频率**：3 秒（前端每 3 秒轮询一次 `GET /api/v1/assets/mints/:order_id`）

6. **错误信息展示** ✅
   - ✅ **失败消息返回**：AI 生成失败时，`GET /api/v1/assets/mints/:order_id` 接口返回 `status = FAILED` 和 `error_message` 字段
   - ✅ **前端展示**：前端直接展示 `error_message`，提示用户费用已退回
   - ✅ **暂不提供重新生成**：当前版本不提供“重新生成”功能，用户需要重新提交订单

### 🟢 暂不实现的功能（后续优化）

7. **WebSocket 实时通知** ❌
   - ❌ **暂不实现**：当前版本使用轮询机制，后续版本可考虑 WebSocket

8. **AI 生成进度** ❌
   - ❌ **暂不实现**：当前版本不显示进度百分比，后续版本可考虑（需要 AI 服务支持）

9. **批量铸造** ❌
   - ❌ **暂不实现**：当前版本不支持一次提交多个素材，后续版本可考虑

---

## 11. 实现计划

### Phase 1: 核心功能实现（预计 3-5 天）
- [ ] 修改 `CreateMintOrder` 接口，支持 `material_url` 参数（替换 `cover_url` 为必填）
- [ ] 实现异步 AI 处理 Goroutine（**Mock 版本**：随机选择预设图片或复制 `material_url`）
- [ ] 实现 AI 图片下载与 OSS 上传逻辑（Mock 版本：直接上传 `material_url` 的图片到 `covers` 目录）
- [ ] 实现模拟链上信息生成（`TxHash`、`BlockNumber`、`MintedAt`）
- [ ] 实现订单状态查询接口 `GET /api/v1/assets/mints/:order_id`
- [ ] 实现费用回退逻辑（所有失败场景自动退回水晶）

### Phase 2: 藏品查询优化（预计 1-2 天）
- [ ] 优化 `GetMyAssets` 接口，自动为所有图片 URL 生成预签名 URL
- [ ] 实现 `GetAssetDetail` 接口，自动生成预签名 URL
- [ ] 优化 `GetMintOrder` 接口，成功时自动生成 `cover_url_signed`
- [ ] 添加状态筛选功能（`status` 参数）

### Phase 3: 错误处理与测试（预计 2-3 天）
- [ ] 实现超时处理机制（60 秒超时）
- [ ] 实现失败场景的统一错误处理（AI 超时、AI 调用失败、OSS 上传失败）
- [ ] 实现费用回退的统一处理逻辑
- [ ] 编写单元测试和集成测试
- [ ] 编写 HTTP 完整测试流程文档

### Phase 4: 真实 AI 服务集成（预计 2-3 天，后续版本）
- [ ] 集成真实的 AI 服务 API（OpenAI DALL-E、Stable Diffusion 或其他）
- [ ] 配置 AI 服务的 API Key 和 Endpoint
- [ ] 实现真实 AI 图片下载与转存逻辑
- [ ] 测试真实场景下的性能与稳定性
- [ ] 替换 Mock 版本的 AI 处理逻辑

---

## 12. 参考文档

- [资产服务设计文档](./资产服务设计文档.md)
- [OSS 预签名 URL 指南](../gateway/OSS_PRESIGNED_URL_GUIDE.md)
- [OSS 批量预签名 URL 指南](../gateway/OSS_BATCH_PRESIGNED_URL_GUIDE.md)
- [API 测试快速指南](../gateway/API_TEST_QUICK.md)

---

## 13. 更新日志

| 版本 | 日期 | 更新内容 | 作者 |
| :--- | :--- | :--- | :--- |
| v1.0 | 2026-01-20 | 初始版本，包含完整流程设计和待确认问题 | 开发团队 |
| v1.1 | 2026-01-20 | 根据确认结果更新：AI Mock 版本、费用自动回退、预签名 URL 自动生成、轮询频率 3 秒、失败消息返回、暂不实现的功能 | 开发团队 |

---

**文档状态**: ✅ 已确认，可开始实现

**下一步**: 开始 Phase 1 的核心功能实现，优先完成前后端完整对接流程。