# Admin Service API 文档

## 目录

- [1. API 概述](#1-api-概述)
- [2. 认证](#2-认证)
- [3. 通用响应格式](#3-通用响应格式)
- [4. 错误处理](#4-错误处理)
- [5. API 端点](#5-api-端点)
- [6. 数据模型](#6-数据模型)
- [7. 使用示例](#7-使用示例)

---

## 1. API 概述

### 1.1 基本信息

| 项目 | 值 |
|-----|---|
| **Base URL** | `http://localhost:3005/api/v1` |
| **协议** | HTTP/HTTPS |
| **数据格式** | JSON |
| **字符编码** | UTF-8 |
| **API 版本** | v1 |

### 1.2 API 分类

| 分类 | 端点数 | 说明 |
|-----|-------|------|
| 版本管理 | 5 | 创建、启用、禁用、查询版本 |
| 版本检查 | 1 | 移动端检查更新 |

---

## 2. 认证

### 2.1 认证方式 (待实现)

当前版本 API **未实现认证机制**，生产环境需要添加 JWT 认证。

**计划认证方案**:
```http
Authorization: Bearer <JWT_TOKEN>
```

**获取 Token** (待实现):
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password123"
}
```

**响应**:
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 7200
}
```

### 2.2 权限级别 (待实现)

| 角色 | 权限 |
|-----|------|
| **admin** | 完全权限：创建、启用、禁用、删除版本 |
| **developer** | 创建、查询版本 |
| **public** | 仅检查更新 (无需认证) |

---

## 3. 通用响应格式

### 3.1 成功响应

**200 OK** - 查询成功:
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "android",
  "versionCode": 100,
  "versionName": "1.0.0",
  "buildNumber": "1",
  "downloadUrl": "https://cdn.example.com/app-v1.0.0.apk",
  "fileSize": 52428800,
  "fileSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "changelog": "Initial release",
  "isEnabled": true,
  "isForceUpdate": false,
  "createdBy": "admin",
  "createdAt": "2025-01-02T10:00:00.000Z",
  "updatedBy": "admin",
  "updatedAt": "2025-01-02T10:00:00.000Z"
}
```

**201 Created** - 创建成功:
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "android",
  "versionCode": 101,
  ...
}
```

**204 No Content** - 操作成功无返回内容

### 3.2 分页响应 (待实现)

```json
{
  "data": [...],
  "meta": {
    "total": 50,
    "page": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}
```

---

## 4. 错误处理

### 4.1 错误响应格式

```json
{
  "statusCode": 400,
  "message": "Invalid version code",
  "error": "Bad Request",
  "timestamp": "2025-01-02T10:00:00.000Z",
  "path": "/api/v1/version"
}
```

### 4.2 HTTP 状态码

| 状态码 | 说明 | 常见场景 |
|-------|------|---------|
| **200** | 成功 | 查询成功 |
| **201** | 已创建 | 创建版本成功 |
| **204** | 无内容 | 启用/禁用成功 |
| **400** | 请求错误 | 参数验证失败 |
| **401** | 未认证 | Token 缺失或无效 |
| **403** | 禁止访问 | 权限不足 |
| **404** | 未找到 | 版本不存在 |
| **409** | 冲突 | 版本号重复 |
| **500** | 服务器错误 | 内部异常 |

### 4.3 业务错误码 (待实现)

| 错误码 | 说明 |
|-------|------|
| `VERSION_ALREADY_EXISTS` | 版本已存在 |
| `INVALID_VERSION_CODE` | 版本号格式错误 |
| `INVALID_VERSION_NAME` | 版本名称格式错误 |
| `INVALID_SHA256` | SHA256 格式错误 |
| `VERSION_NOT_FOUND` | 版本不存在 |
| `FILE_SIZE_INVALID` | 文件大小无效 |

---

## 5. API 端点

### 5.1 创建版本

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

**权限**: 需要认证 (待实现)

**请求体**:
```json
{
  "platform": "android",
  "versionCode": 100,
  "versionName": "1.0.0",
  "buildNumber": "1",
  "downloadUrl": "https://cdn.example.com/app-v1.0.0.apk",
  "fileSize": 52428800,
  "fileSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "changelog": "Initial release",
  "isEnabled": true,
  "isForceUpdate": false,
  "createdBy": "admin"
}
```

**字段说明**:

| 字段 | 类型 | 必填 | 说明 | 验证规则 |
|-----|------|-----|------|---------|
| `platform` | string | ✅ | 平台 | `android` 或 `ios` |
| `versionCode` | number | ✅ | 版本号 | 正整数 |
| `versionName` | string | ✅ | 版本名称 | 语义化版本 (x.y.z) |
| `buildNumber` | string | ✅ | 构建号 | 非空字符串 |
| `downloadUrl` | string | ✅ | 下载链接 | 有效 URL |
| `fileSize` | number | ✅ | 文件大小 (字节) | > 0 |
| `fileSha256` | string | ✅ | SHA256 哈希 | 64 位十六进制 |
| `changelog` | string | ✅ | 更新日志 | 非空字符串 |
| `isEnabled` | boolean | ❌ | 是否启用 | 默认 `true` |
| `isForceUpdate` | boolean | ❌ | 是否强制更新 | 默认 `false` |
| `createdBy` | string | ✅ | 创建者 | 非空字符串 |

**响应**: `201 Created`
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "android",
  "versionCode": 100,
  "versionName": "1.0.0",
  "buildNumber": "1",
  "downloadUrl": "https://cdn.example.com/app-v1.0.0.apk",
  "fileSize": 52428800,
  "fileSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "changelog": "Initial release",
  "isEnabled": true,
  "isForceUpdate": false,
  "createdBy": "admin",
  "createdAt": "2025-01-02T10:00:00.000Z",
  "updatedBy": "admin",
  "updatedAt": "2025-01-02T10:00:00.000Z"
}
```

**错误响应**:
```json
// 400 Bad Request - 版本号无效
{
  "statusCode": 400,
  "message": "Version code must be a positive integer",
  "error": "Bad Request"
}

// 409 Conflict - 版本已存在
{
  "statusCode": 409,
  "message": "Version already exists for this platform",
  "error": "Conflict"
}
```

**cURL 示例**:
```bash
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "android",
    "versionCode": 100,
    "versionName": "1.0.0",
    "buildNumber": "1",
    "downloadUrl": "https://cdn.example.com/app-v1.0.0.apk",
    "fileSize": 52428800,
    "fileSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "changelog": "Initial release",
    "isEnabled": true,
    "isForceUpdate": false,
    "createdBy": "admin"
  }'
```

---

### 5.2 查询所有版本

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

**权限**: 需要认证 (待实现)

**查询参数**:

| 参数 | 类型 | 必填 | 说明 | 示例 |
|-----|------|-----|------|------|
| `platform` | string | ❌ | 过滤平台 | `android` |
| `isEnabled` | boolean | ❌ | 过滤启用状态 | `true` |
| `page` | number | ❌ | 页码 (待实现) | `1` |
| `pageSize` | number | ❌ | 每页数量 (待实现) | `10` |

**请求示例**:
```http
GET /api/v1/version?platform=android&isEnabled=true
```

**响应**: `200 OK`
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "platform": "android",
    "versionCode": 101,
    "versionName": "1.0.1",
    ...
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "platform": "android",
    "versionCode": 100,
    "versionName": "1.0.0",
    ...
  }
]
```

**cURL 示例**:
```bash
curl -X GET "http://localhost:3005/api/v1/version?platform=android&isEnabled=true"
```

---

### 5.3 查询单个版本

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

**权限**: 需要认证 (待实现)

**路径参数**:

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

**请求示例**:
```http
GET /api/v1/version/550e8400-e29b-41d4-a716-446655440000
```

**响应**: `200 OK`
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "android",
  "versionCode": 100,
  "versionName": "1.0.0",
  ...
}
```

**错误响应**:
```json
// 404 Not Found
{
  "statusCode": 404,
  "message": "Version not found",
  "error": "Not Found"
}
```

**cURL 示例**:
```bash
curl -X GET http://localhost:3005/api/v1/version/550e8400-e29b-41d4-a716-446655440000
```

---

### 5.4 启用版本

**端点**: `PATCH /api/v1/version/:id/enable`

**权限**: 需要认证 (待实现)

**路径参数**:

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

**请求体**:
```json
{
  "updatedBy": "admin"
}
```

**请求示例**:
```http
PATCH /api/v1/version/550e8400-e29b-41d4-a716-446655440000/enable
Content-Type: application/json

{
  "updatedBy": "admin"
}
```

**响应**: `204 No Content`

**错误响应**:
```json
// 404 Not Found
{
  "statusCode": 404,
  "message": "Version not found",
  "error": "Not Found"
}
```

**cURL 示例**:
```bash
curl -X PATCH http://localhost:3005/api/v1/version/550e8400-e29b-41d4-a716-446655440000/enable \
  -H "Content-Type: application/json" \
  -d '{"updatedBy": "admin"}'
```

---

### 5.5 禁用版本

**端点**: `PATCH /api/v1/version/:id/disable`

**权限**: 需要认证 (待实现)

**路径参数**:

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

**请求体**:
```json
{
  "updatedBy": "admin"
}
```

**请求示例**:
```http
PATCH /api/v1/version/550e8400-e29b-41d4-a716-446655440000/disable
Content-Type: application/json

{
  "updatedBy": "admin"
}
```

**响应**: `204 No Content`

**业务逻辑**:
- 禁用版本时，会自动将 `isForceUpdate` 设置为 `false`
- 禁用后的版本不会出现在 "检查更新" 结果中

**cURL 示例**:
```bash
curl -X PATCH http://localhost:3005/api/v1/version/550e8400-e29b-41d4-a716-446655440000/disable \
  -H "Content-Type: application/json" \
  -d '{"updatedBy": "admin"}'
```

---

### 5.6 检查更新 (移动端)

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

**权限**: 公开 (无需认证)

**查询参数**:

| 参数 | 类型 | 必填 | 说明 | 示例 |
|-----|------|-----|------|------|
| `platform` | string | ✅ | 平台 | `android` |
| `versionCode` | number | ✅ | 当前版本号 | `100` |

**请求示例**:
```http
GET /api/v1/version/check?platform=android&versionCode=100
```

**响应 1**: `200 OK` - 有更新
```json
{
  "hasUpdate": true,
  "latestVersion": "1.0.1",
  "downloadUrl": "https://cdn.example.com/app-v1.0.1.apk",
  "isForceUpdate": false,
  "changelog": "Bug fixes and performance improvements"
}
```

**响应 2**: `200 OK` - 无更新
```json
{
  "hasUpdate": false
}
```

**响应 3**: `200 OK` - 强制更新
```json
{
  "hasUpdate": true,
  "latestVersion": "2.0.0",
  "downloadUrl": "https://cdn.example.com/app-v2.0.0.apk",
  "isForceUpdate": true,
  "changelog": "Major security update. Please update immediately!"
}
```

**错误响应**:
```json
// 400 Bad Request - 参数缺失
{
  "statusCode": 400,
  "message": ["platform should not be empty", "versionCode must be a number"],
  "error": "Bad Request"
}
```

**业务逻辑**:
1. 查询指定平台的所有启用版本 (`isEnabled = true`)
2. 按 `versionCode` 降序排序，取第一个作为最新版本
3. 如果最新版本的 `versionCode` > 当前版本号，返回更新信息
4. 否则返回 `hasUpdate: false`

**移动端处理逻辑**:
```typescript
// Flutter 示例
async function checkForUpdate() {
  const response = await fetch(
    `${API_BASE}/version/check?platform=android&versionCode=100`
  );
  const data = await response.json();

  if (data.hasUpdate) {
    if (data.isForceUpdate) {
      // 显示强制更新对话框（无法关闭）
      showForceUpdateDialog({
        version: data.latestVersion,
        downloadUrl: data.downloadUrl,
        changelog: data.changelog,
      });
    } else {
      // 显示普通更新对话框（可以关闭）
      showUpdateDialog({
        version: data.latestVersion,
        downloadUrl: data.downloadUrl,
        changelog: data.changelog,
      });
    }
  }
}
```

**cURL 示例**:
```bash
curl -X GET "http://localhost:3005/api/v1/version/check?platform=android&versionCode=100"
```

---

## 6. 数据模型

### 6.1 AppVersion (应用版本)

```typescript
interface AppVersion {
  id: string;                 // UUID
  platform: 'android' | 'ios';// 平台
  versionCode: number;        // 版本号（整数）
  versionName: string;        // 版本名称（x.y.z）
  buildNumber: string;        // 构建号
  downloadUrl: string;        // 下载链接
  fileSize: number;           // 文件大小（字节）
  fileSha256: string;         // SHA256 哈希
  changelog: string;          // 更新日志
  isEnabled: boolean;         // 是否启用
  isForceUpdate: boolean;     // 是否强制更新
  createdBy: string;          // 创建者
  createdAt: string;          // 创建时间（ISO 8601）
  updatedBy: string;          // 更新者
  updatedAt: string;          // 更新时间（ISO 8601）
}
```

### 6.2 Platform (平台枚举)

```typescript
enum Platform {
  ANDROID = 'android',
  IOS = 'ios',
}
```

### 6.3 VersionCheckResult (版本检查结果)

```typescript
interface VersionCheckResult {
  hasUpdate: boolean;         // 是否有更新
  latestVersion?: string;     // 最新版本名称
  downloadUrl?: string;       // 下载链接
  isForceUpdate?: boolean;    // 是否强制更新
  changelog?: string;         // 更新日志
}
```

---

## 7. 使用示例

### 7.1 完整发版流程

#### 步骤 1: 创建 Android 新版本

```bash
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "android",
    "versionCode": 101,
    "versionName": "1.0.1",
    "buildNumber": "20250102001",
    "downloadUrl": "https://cdn.rwadurian.com/android/app-v1.0.1.apk",
    "fileSize": 54525952,
    "fileSha256": "a3c5d7e9f1b2c4d6e8f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "changelog": "1. Fixed mining reward calculation bug\n2. Improved UI performance\n3. Added dark mode support",
    "isEnabled": true,
    "isForceUpdate": false,
    "createdBy": "admin"
  }'
```

#### 步骤 2: 验证版本已创建

```bash
curl -X GET "http://localhost:3005/api/v1/version?platform=android&isEnabled=true"
```

#### 步骤 3: 移动端检查更新

```bash
# 用户当前版本号 100
curl -X GET "http://localhost:3005/api/v1/version/check?platform=android&versionCode=100"

# 响应：
{
  "hasUpdate": true,
  "latestVersion": "1.0.1",
  "downloadUrl": "https://cdn.rwadurian.com/android/app-v1.0.1.apk",
  "isForceUpdate": false,
  "changelog": "1. Fixed mining reward calculation bug\n2. Improved UI performance\n3. Added dark mode support"
}
```

#### 步骤 4: 发现问题，紧急禁用版本

```bash
curl -X PATCH http://localhost:3005/api/v1/version/550e8400-e29b-41d4-a716-446655440001/disable \
  -H "Content-Type: application/json" \
  -d '{"updatedBy": "admin"}'
```

#### 步骤 5: 创建修复版本

```bash
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "android",
    "versionCode": 102,
    "versionName": "1.0.2",
    "buildNumber": "20250102002",
    "downloadUrl": "https://cdn.rwadurian.com/android/app-v1.0.2.apk",
    "fileSize": 54530048,
    "fileSha256": "b4d6e8f0a2c3d5e7f9a1b3c4d6e8f0a2b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1",
    "changelog": "Hotfix: Fixed critical security vulnerability",
    "isEnabled": true,
    "isForceUpdate": true,
    "createdBy": "admin"
  }'
```

### 7.2 iOS 版本发布

```bash
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "versionCode": 1,
    "versionName": "1.0.0",
    "buildNumber": "1",
    "downloadUrl": "https://apps.apple.com/app/rwa-durian/id123456789",
    "fileSize": 67108864,
    "fileSha256": "c5e7f9a1b3c4d6e8f0a2b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2",
    "changelog": "Initial iOS release",
    "isEnabled": true,
    "isForceUpdate": false,
    "createdBy": "admin"
  }'
```

### 7.3 Postman Collection (部分示例)

```json
{
  "info": {
    "name": "Admin Service API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create Android Version",
      "request": {
        "method": "POST",
        "header": [{"key": "Content-Type", "value": "application/json"}],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"platform\": \"android\",\n  \"versionCode\": 100,\n  \"versionName\": \"1.0.0\",\n  \"buildNumber\": \"1\",\n  \"downloadUrl\": \"https://cdn.example.com/app-v1.0.0.apk\",\n  \"fileSize\": 52428800,\n  \"fileSha256\": \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\n  \"changelog\": \"Initial release\",\n  \"isEnabled\": true,\n  \"isForceUpdate\": false,\n  \"createdBy\": \"admin\"\n}"
        },
        "url": {
          "raw": "http://localhost:3005/api/v1/version",
          "protocol": "http",
          "host": ["localhost"],
          "port": "3005",
          "path": ["api", "v1", "version"]
        }
      }
    },
    {
      "name": "Check For Update",
      "request": {
        "method": "GET",
        "url": {
          "raw": "http://localhost:3005/api/v1/version/check?platform=android&versionCode=100",
          "protocol": "http",
          "host": ["localhost"],
          "port": "3005",
          "path": ["api", "v1", "version", "check"],
          "query": [
            {"key": "platform", "value": "android"},
            {"key": "versionCode", "value": "100"}
          ]
        }
      }
    }
  ]
}
```

---

## 8. 版本控制策略

### 8.1 版本号规则

**VersionCode** (数字版本号):
- 每次发布递增 1
- Android: 从 1 开始
- iOS: 从 1 开始
- 用于版本比较 (机器识别)

**VersionName** (语义化版本):
- 格式: `MAJOR.MINOR.PATCH` (例如: `1.2.3`)
- 用于用户展示 (人类可读)

**BuildNumber** (构建号):
- 格式: 自定义 (建议: `YYYYMMDDXXX`)
- 例如: `20250102001` = 2025年1月2日第1次构建

### 8.2 更新策略

| 场景 | isForceUpdate | 说明 |
|-----|---------------|------|
| 功能更新 | `false` | 用户可选择更新时机 |
| Bug 修复 | `false` | 建议更新，但不强制 |
| 安全漏洞 | `true` | 必须更新才能继续使用 |
| API 破坏性变更 | `true` | 旧版本无法正常工作 |

---

## 9. 最佳实践

### 9.1 文件托管建议

1. **使用 CDN**: 加速全球用户下载
2. **HTTPS**: 确保传输安全
3. **文件命名**: `app-{platform}-v{versionName}.{ext}`
   - Android: `app-android-v1.0.0.apk`
   - iOS: `app-ios-v1.0.0.ipa`

### 9.2 SHA256 校验流程

**服务端计算** (发版时):
```bash
# Linux/macOS
sha256sum app-android-v1.0.0.apk

# Windows
certutil -hashfile app-android-v1.0.0.apk SHA256
```

**移动端校验** (下载后):
```dart
// Flutter 示例
import 'package:crypto/crypto.dart';
import 'dart:io';

Future<bool> verifyApkIntegrity(String filePath, String expectedSha256) async {
  final file = File(filePath);
  final bytes = await file.readAsBytes();
  final digest = sha256.convert(bytes);
  return digest.toString() == expectedSha256.toLowerCase();
}

// 使用
final isValid = await verifyApkIntegrity(
  '/storage/emulated/0/Download/app.apk',
  'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
);

if (!isValid) {
  throw Exception('File integrity check failed! Possible tampering detected.');
}
```

### 9.3 更新日志编写规范

**推荐格式**:
```
1. 新功能：添加暗黑模式支持
2. 优化：挖矿页面性能提升 30%
3. 修复：交易历史加载失败问题
4. 安全：修复账户导入漏洞
```

**避免**:
- ❌ "Bug fixes and improvements" (太笼统)
- ❌ 技术术语 (普通用户不理解)
- ✅ 简洁明了，面向用户

---

## 10. 常见问题

### Q1: 如何回滚版本？

**方案 1**: 禁用问题版本，启用旧版本
```bash
# 禁用 v1.0.1
curl -X PATCH http://localhost:3005/api/v1/version/{v1.0.1-id}/disable \
  -H "Content-Type: application/json" \
  -d '{"updatedBy": "admin"}'

# 启用 v1.0.0
curl -X PATCH http://localhost:3005/api/v1/version/{v1.0.0-id}/enable \
  -H "Content-Type: application/json" \
  -d '{"updatedBy": "admin"}'
```

**方案 2**: 创建新版本，使用更高的 versionCode
```bash
# 创建 v1.0.0-hotfix (versionCode = 103)
curl -X POST http://localhost:3005/api/v1/version \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "android",
    "versionCode": 103,
    "versionName": "1.0.0",
    "buildNumber": "20250102003",
    ...
  }'
```

### Q2: 如何处理多渠道包 (Google Play, 自建服务器)?

当前版本不支持，建议通过 `buildNumber` 区分：

```bash
# Google Play 渠道
{
  "versionCode": 100,
  "versionName": "1.0.0",
  "buildNumber": "100-gplay",
  "downloadUrl": "https://play.google.com/store/apps/details?id=com.rwa.durian",
  ...
}

# 自建渠道
{
  "versionCode": 100,
  "versionName": "1.0.0",
  "buildNumber": "100-self",
  "downloadUrl": "https://cdn.rwadurian.com/android/app-v1.0.0.apk",
  ...
}
```

### Q3: 如何实现灰度发布？

当前版本不支持，未来可扩展：

```typescript
// 计划实现
interface AppVersion {
  ...
  releaseType: 'full' | 'gray'; // 发布类型
  grayRatio?: number;           // 灰度比例 (0-100)
  grayUserIds?: string[];       // 灰度用户列表
}
```

---

**最后更新**: 2025-12-03
**版本**: 1.0.0
**维护者**: RWA Durian Team