389 lines
8.1 KiB
Markdown
389 lines
8.1 KiB
Markdown
# 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¤tVersion=1.0.0¤tBuild=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)
|