# 版本强更接口 App 对接

## 接口地址

`GET /api/v1/app/version`

公开接口，不需要 `Authorization`。

## Header

| Header | 必填 | 说明 |
| --- | --- | --- |
| `X-App-Code` | 否 | App 编码，默认 `lalu`。 |
| `X-App-Package` | 否 | App 包名；当前 `com.org.laluparty` 可解析为 `lalu`。 |
| `X-App-Platform` | 条件必填 | `android` 或 `ios`；query `platform` 为空时读取该 header。 |
| `X-App-Build-Number` | 条件必填 | 当前客户端编译版本号；query `build_number` 为空时读取该 header。 |
| `X-App-Version` | 否 | 当前客户端展示版本号，只用于日志排查。 |

## Query 参数

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `platform` | 条件必填 | string | `android` 或 `ios`；优先级高于 `X-App-Platform`。 |
| `build_number` | 条件必填 | int64 | 当前客户端编译版本号；优先级高于 `X-App-Build-Number`。 |

`platform` 必须通过 query 或 header 传入。`build_number` 对 App 端必须传；服务端缺省时按 `0` 处理，会导致已配置版本都被判定为有更新。

请求示例：

```http
GET /api/v1/app/version?platform=android&build_number=100
X-App-Code: lalu
X-App-Platform: android
X-App-Build-Number: 100
X-App-Version: 1.1.0
```

## 成功返回

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "app_code": "lalu",
    "platform": "android",
    "version": "1.2.0",
    "build_number": 120,
    "force_update": true,
    "download_url": "https://example.com/lalu.apk",
    "description": "修复已知问题",
    "has_update": true,
    "current_build_number": 100,
    "updated_at_ms": 1710000000000,
    "server_time_ms": 1710000001234
  }
}
```

返回字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `app_code` | string | 服务端解析后的 App 编码。 |
| `platform` | string | `android` 或 `ios`。 |
| `version` | string | 后台配置的最新展示版本号，只用于展示。 |
| `build_number` | int64 | 后台当前最高编译版本号。 |
| `current_build_number` | int64 | 服务端收到的客户端编译版本号。 |
| `has_update` | bool | `build_number > current_build_number` 时为 `true`。 |
| `force_update` | bool | 当前客户端落后且后台最新版本标记强更时为 `true`。 |
| `download_url` | string | 更新跳转地址；Android 通常是 APK 下载页，iOS 通常是 App Store 链接。 |
| `description` | string | 更新说明，可为空。 |
| `updated_at_ms` | int64 | 后台版本配置更新时间，Unix epoch milliseconds。 |
| `server_time_ms` | int64 | gateway 返回时间，Unix epoch milliseconds。 |

## 错误码

| HTTP 状态码 | `code` | 触发条件 |
| --- | --- | --- |
| `400` | `INVALID_ARGUMENT` | `platform` 为空或不是 `android` / `ios`。 |
| `502` | `UPSTREAM_ERROR` | gateway 读取后台版本配置失败。 |

错误返回仍使用统一 envelope：

```json
{
  "code": "INVALID_ARGUMENT",
  "message": "platform is invalid",
  "request_id": "req_abc"
}
```