# 相册管理 API 文档

本文档描述相册管理查询接口规范。

## 1. 全局响应结构

所有接口返回值均由统一响应结构包装，格式如下：

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {},
  "timestamp": 1709628736123
}
```

---

## 2. 相册列表查询

*   **URL**: `/v2/ai/album/list`
*   **Method**: `GET`
*   **描述**: 分页查询相册列表，关联用户信息（昵称、邮箱、苹果用户ID、平台、语言）。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `page` | integer | 否 | 页码，默认 1 |
| `size` | integer | 否 | 每页大小，默认 10 |
| `id` | long | 否 | 相册ID（精确匹配） |
| `userId` | long | 否 | 用户ID |
| `title` | string | 否 | 标题（模糊匹配） |
| `taskId` | string | 否 | 任务ID（精确匹配） |
| `orderId` | string | 否 | 订单ID（精确匹配） |
| `status` | integer | 否 | 写真状态（1:处理中 2:生成中 3:已完成） |
| `startTime` | string | 否 | 开始时间（yyyy-MM-dd HH:mm:ss） |
| `endTime` | string | 否 | 结束时间（yyyy-MM-dd HH:mm:ss） |

### 响应参数（`data` 字段）

返回 Mybatis-Plus 分页对象，包含 `records`、`total`、`size`、`current`、`pages` 等字段。

`records` 中每条数据（`AiAlbumVO`）结构如下：

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `id` | long | 相册ID |
| `title` | string | 标题 |
| `userId` | long | 用户ID |
| `styleId` | integer | 风格ID |
| `taskId` | string | 任务ID |
| `status` | integer | 写真状态（1:处理中 2:生成中 3:已完成） |
| `pictures` | string | 写真照片 |
| `videos` | string | 视频 |
| `accelerate` | integer | 是否加速（0:否 1:是） |
| `timestamp` | long | 预计花费时间（秒） |
| `createTime` | string | 创建时间 |
| `updateTime` | string | 最后更新时间 |
| `orderId` | string | 订单ID |
| `type` | integer | 类型（1:分身相册 2:普通相册） |
| `expectTime` | string | 预计完成时间 |
| `videoImage` | string | 视频的原始图片 |
| `nickname` | string | 用户昵称 |
| `email` | string | 用户邮箱 |
| `appleUserId` | string | 苹果用户ID |
| `platform` | string | 平台 |
| `language` | string | 语言 |

### 示例请求

```http
GET /v2/ai/album/list?page=1&size=10&userId=10001&status=3
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "id": 90001,
        "title": "春日写真集",
        "userId": 10001,
        "styleId": 301,
        "taskId": "TASK_998877",
        "status": 3,
        "pictures": "[\"https://cdn.example.com/p1.jpg\"]",
        "videos": "[\"https://cdn.example.com/v1.mp4\"]",
        "accelerate": 1,
        "timestamp": 300,
        "createTime": "2026-03-10 09:30:00",
        "updateTime": "2026-03-10 09:36:20",
        "orderId": "ORD_202603100001",
        "type": 2,
        "expectTime": "2026-03-10 09:40:00",
        "videoImage": "[\"https://cdn.example.com/raw1.jpg\"]",
        "nickname": "Tom",
        "email": "tom@example.com",
        "appleUserId": "apple_user_001",
        "platform": "ios",
        "language": "zh-CN"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "timestamp": 1773033000000
}
```

---

## 3. 相册详情查询

*   **URL**: `/v2/ai/album/get/{id}`
*   **Method**: `GET`
*   **描述**: 根据相册ID获取相册详情（返回结构同 `AiAlbumVO`）。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | long | 是 | 相册ID |

### 响应参数（`data` 字段）

返回 `AiAlbumVO`，字段定义同上。

### 示例请求

```http
GET /v2/ai/album/get/90001
```

### 示例响应

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "id": 90001,
    "title": "春日写真集",
    "userId": 10001,
    "styleId": 301,
    "taskId": "TASK_998877",
    "status": 3,
    "pictures": "[\"https://cdn.example.com/p1.jpg\"]",
    "videos": "[\"https://cdn.example.com/v1.mp4\"]",
    "accelerate": 1,
    "timestamp": 300,
    "createTime": "2026-03-10 09:30:00",
    "updateTime": "2026-03-10 09:36:20",
    "orderId": "ORD_202603100001",
    "type": 2,
    "expectTime": "2026-03-10 09:40:00",
    "videoImage": "[\"https://cdn.example.com/raw1.jpg\"]",
    "nickname": "Tom",
    "email": "tom@example.com",
    "appleUserId": "apple_user_001",
    "platform": "ios",
    "language": "zh-CN"
  },
  "timestamp": 1773033000000
}
```