# App Update Check Protocol

本文档定义移动端应用更新检查协议，适用于 Android/iOS。

## 1. Endpoint

- Method: `GET`
- Path: `/api/v1/app/check-updates`

## 2. Request Query

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `platform` | `android` \| `ios` | 否 | 默认 `ios` |
| `channel` | `string` | 否 | 发布渠道，默认 `release` |
| `current_version_code` | `int` | 是 | 当前构建号（Android versionCode / iOS buildNumber） |
| `current_version_name` | `string` | 否 | 当前展示版本号（如 `0.1.1`） |

## 3. Response

```json
{
  "has_update": true,
  "update_type": "optional",
  "latest_version_name": "0.1.1",
  "latest_version_code": 2,
  "min_supported_version_code": 1,
  "download_url": "https://example.com/releases/social-app-android-v0.1.1+2-release.apk",
  "release_notes": "问题修复和体验优化",
  "file_name": "social-app-android-v0.1.1+2-release.apk",
  "file_size": 59768832,
  "sha256": "<sha256>"
}
```

## 4. Update Decision Algorithm

后端必须按以下顺序判定：

1. `current_version_code >= latest_version_code` -> `update_type = none`
2. `current_version_code < min_supported_version_code` -> `update_type = required`
3. 其他且 `< latest_version_code` -> `update_type = optional`

`has_update = (update_type != "none")`

## 5. Release Manifest

发布清单文件位置：`deploy/static/releases/manifest.json`

```json
{
  "releases": [
    {
      "platform": "android",
      "channel": "release",
      "version_name": "0.1.1",
      "version_code": 2,
      "min_supported_version_code": 1,
      "file_name": "social-app-android-v0.1.1+2-release.apk",
      "release_notes": "问题修复和体验优化",
      "file_size": 59768832,
      "sha256": "<sha256>"
    }
  ]
}
```

同一 `platform + channel` 可存在多条记录，服务端按 `version_code` 最大值选最新版。

## 6. Package Naming Convention

Android 安装包命名规范：

`social-app-android-v{versionName}+{versionCode}-{channel}.apk`

示例：

- `social-app-android-v0.1.1+2-release.apk`
- `social-app-android-v0.1.2+3-beta.apk`

规则：

- `versionName` 给用户展示（如 `0.1.1`）
- `versionCode` 必须严格递增
- `channel` 建议使用 `release` / `beta`

推荐打包命令：

```bash
./deploy/build-android-release.sh \
  --backend-host 115.190.63.157 \
  --channel release \
  --release-notes "问题修复和体验优化"
```

该脚本会：

- 按命名规范生成 APK 文件到 `deploy/static/releases/`
- 每次打包自动将 `apps/pubspec.yaml` 的 `buildNumber` 递增 1 并写回
- 自动更新 `deploy/static/releases/manifest.json`
- 输出版本号、文件路径和 SHA256

注意：

- `versionName`（如 `0.1.0`）由开发者手动维护
- `buildNumber`（如 `+2`）由打包脚本自动递增