# Mobile Upgrade Admin - API 文档

## 概述

本文档描述 Mobile Upgrade Admin 前端与 Admin Service 后端的 API 交互。

## 基础配置

### 环境变量

```bash
# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000
```

### API 客户端配置

```typescript
// src/infrastructure/http/api-client.ts
export const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
})
```

## API 端点

### 版本管理 API

Base URL: `/api/v1/versions`

---

### 1. 获取版本列表

**端点**: `GET /api/v1/versions`

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| platform | string | 否 | 平台筛选：`android` 或 `ios` |
| includeDisabled | boolean | 否 | 是否包含已禁用版本，默认 `true` |

**请求示例**:

```typescript
// 获取所有版本
const response = await apiClient.get('/api/v1/versions')

// 获取 Android 版本
const response = await apiClient.get('/api/v1/versions?platform=android')

// 只获取已启用版本
const response = await apiClient.get('/api/v1/versions?includeDisabled=false')
```

**响应示例**:

```json
[
  {
    "id": "uuid-1234",
    "platform": "android",
    "versionCode": 100,
    "versionName": "1.0.0",
    "buildNumber": "100",
    "downloadUrl": "https://example.com/app-1.0.0.apk",
    "fileSize": "52428800",
    "fileSha256": "abc123...",
    "changelog": "1. 新增功能A\n2. 修复问题B",
    "isForceUpdate": false,
    "isEnabled": true,
    "minOsVersion": "8.0",
    "releaseDate": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

---

### 2. 获取单个版本

**端点**: `GET /api/v1/versions/:id`

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 版本 ID (UUID) |

**请求示例**:

```typescript
const response = await apiClient.get('/api/v1/versions/uuid-1234')
```

**响应**: 单个 `AppVersion` 对象

---

### 3. 创建版本

**端点**: `POST /api/v1/versions`

**请求体**:

```typescript
interface CreateVersionInput {
  platform: 'android' | 'ios'
  versionCode: number
  versionName: string
  buildNumber: string
  downloadUrl: string
  fileSize: string
  fileSha256: string
  changelog: string
  isForceUpdate: boolean
  minOsVersion?: string
  releaseDate?: string
}
```

**请求示例**:

```typescript
const response = await apiClient.post('/api/v1/versions', {
  platform: 'android',
  versionCode: 101,
  versionName: '1.0.1',
  buildNumber: '101',
  downloadUrl: 'https://example.com/app-1.0.1.apk',
  fileSize: '52428800',
  fileSha256: 'sha256hash...',
  changelog: '修复已知问题',
  isForceUpdate: false,
  minOsVersion: '8.0'
})
```

**响应**: 创建的 `AppVersion` 对象

---

### 4. 更新版本

**端点**: `PUT /api/v1/versions/:id`

**请求体**:

```typescript
interface UpdateVersionInput {
  downloadUrl?: string
  fileSize?: string
  fileSha256?: string
  changelog?: string
  isForceUpdate?: boolean
  isEnabled?: boolean
  minOsVersion?: string | null
  releaseDate?: string | null
}
```

**请求示例**:

```typescript
const response = await apiClient.put('/api/v1/versions/uuid-1234', {
  changelog: '更新的更新日志',
  isForceUpdate: true
})
```

**响应**: 更新后的 `AppVersion` 对象

---

### 5. 删除版本

**端点**: `DELETE /api/v1/versions/:id`

**请求示例**:

```typescript
await apiClient.delete('/api/v1/versions/uuid-1234')
```

**响应**: 无内容 (204)

---

### 6. 切换版本状态

**端点**: `PATCH /api/v1/versions/:id/toggle`

**请求体**:

```json
{
  "isEnabled": true
}
```

**请求示例**:

```typescript
await apiClient.patch('/api/v1/versions/uuid-1234/toggle', {
  isEnabled: false
})
```

**响应**: 无内容 (204)

---

### 7. 上传版本文件

**端点**: `POST /api/v1/versions/upload`

**请求类型**: `multipart/form-data`

**表单字段**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | 是 | APK 或 IPA 文件 |
| platform | string | 是 | `android` 或 `ios` |
| versionName | string | 是 | 版本号，如 `1.0.0` |
| buildNumber | string | 是 | 构建号，如 `100` |
| changelog | string | 否 | 更新日志 |
| isForceUpdate | boolean | 否 | 是否强制更新，默认 `false` |
| minOsVersion | string | 否 | 最低系统版本 |
| releaseDate | string | 否 | 发布日期 (ISO 8601) |

**请求示例**:

```typescript
const formData = new FormData()
formData.append('file', file)
formData.append('platform', 'android')
formData.append('versionName', '1.0.0')
formData.append('buildNumber', '100')
formData.append('changelog', '首次发布')
formData.append('isForceUpdate', 'false')

const response = await apiClient.post('/api/v1/versions/upload', formData, {
  headers: {
    'Content-Type': 'multipart/form-data',
  },
  timeout: 300000, // 5分钟超时，适用于大文件
})
```

**响应**: 创建的 `AppVersion` 对象

---

## 移动端检查更新 API

### 检查版本更新

**端点**: `GET /api/app/version/check`

> 注意：此端点不使用 `/api/v1` 前缀

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| platform | string | 是 | `android` 或 `ios` |
| currentVersion | string | 是 | 当前版本号，如 `1.0.0` |
| currentBuild | string | 否 | 当前构建号 |

**请求示例**:

```bash
GET /api/app/version/check?platform=android&currentVersion=1.0.0&currentBuild=100
```

**响应示例**:

```json
{
  "hasUpdate": true,
  "isForceUpdate": false,
  "latestVersion": {
    "versionName": "1.1.0",
    "buildNumber": "110",
    "downloadUrl": "https://example.com/app-1.1.0.apk",
    "fileSize": "55000000",
    "changelog": "1. 新功能\n2. 性能优化",
    "minOsVersion": "8.0"
  }
}
```

---

## 错误处理

### 错误响应格式

```json
{
  "statusCode": 400,
  "message": "错误描述",
  "error": "Bad Request"
}
```

### 常见错误码

| 状态码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 409 | 资源冲突（如版本已存在） |
| 413 | 文件过大 |
| 500 | 服务器内部错误 |

### 前端错误处理

```typescript
// API 客户端拦截器
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    const message = error.response?.data?.message || '请求失败'
    return Promise.reject(new Error(message))
  }
)

// 组件中使用
try {
  await deleteVersion(id)
  toast.success('删除成功')
} catch (err) {
  toast.error(err.message || '操作失败')
}
```

---

## 数据类型定义

### AppVersion

```typescript
interface AppVersion {
  id: string                    // UUID
  platform: 'android' | 'ios'   // 平台
  versionCode: number           // 版本代码（用于比较）
  versionName: string           // 版本名称（显示用）
  buildNumber: string           // 构建号
  downloadUrl: string           // 下载地址
  fileSize: string              // 文件大小（字节）
  fileSha256: string            // 文件 SHA256 校验值
  changelog: string             // 更新日志
  isForceUpdate: boolean        // 是否强制更新
  isEnabled: boolean            // 是否启用
  minOsVersion: string | null   // 最低系统版本要求
  releaseDate: string | null    // 发布日期
  createdAt: string             // 创建时间
  updatedAt: string             // 更新时间
}
```

### VersionListFilter

```typescript
interface VersionListFilter {
  platform?: 'android' | 'ios'
  includeDisabled?: boolean
}
```

---

## 相关文档

- [架构文档](./ARCHITECTURE.md)
- [开发指南](./DEVELOPMENT.md)
- [测试指南](./TESTING.md)
- [部署指南](./DEPLOYMENT.md)