# Flutter App 配置与内购对接

本文只描述当前 App 端需要直接调用的 gateway HTTP 接口。所有业务接口都返回统一外壳：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "server-generated-request-id",
  "data": {}
}
```

## 1. 检查 App 更新

`GET /api/v1/app/version`

公开接口，不需要登录。客户端必须传平台，建议同时传当前编译版本号。

请求头：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `X-App-Code` | 否 | App 编码，默认 `lalu`。 |
| `X-App-Platform` | 是 | `android` 或 `ios`。也可以用 query `platform` 覆盖。 |
| `X-App-Build-Number` | 建议 | 当前客户端编译版本号。也可以用 query `build_number` 覆盖。 |
| `X-App-Version` | 否 | 当前客户端展示版本号，只用于客户端侧日志排查。 |

示例：

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

响应：

```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
  }
}
```

Flutter 处理规则：

- `has_update=false`：不展示升级弹窗。
- `has_update=true && force_update=false`：展示普通升级弹窗，允许关闭。
- `has_update=true && force_update=true`：展示强更弹窗，不允许进入主流程。
- `download_url` 由后台配置。Android 通常打开 APK 下载页；iOS 通常打开 App Store 链接。
- 服务端只用 `build_number` 判断新旧，不解析 `version` 语义版本。

## 2. 获取内购商品列表

`GET /api/v1/wallet/recharge/products`

登录接口，需要 `Authorization: Bearer <access_token>`。gateway 会用当前登录用户资料里的 `region_id` 筛选商品，客户端不要自己传区域。

请求头：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | App 登录 access token。 |
| `X-App-Platform` | 是 | `android` 或 `ios`。也可以用 query `platform` 覆盖。 |

示例：

```http
GET /api/v1/wallet/recharge/products
Authorization: Bearer <access_token>
X-App-Platform: ios
```

响应：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "channels": ["apple"],
    "products": [
      {
        "product_id": 11,
        "product_code": "iap_ios_1500",
        "product_name": "1500 Coins",
        "description": "coin pack",
        "platform": "ios",
        "channel": "apple",
        "currency_code": "USDT",
        "coin_amount": 1500,
        "amount_micro": 1500000,
        "region_ids": [2002],
        "resource_asset_type": "COIN",
        "status": "active",
        "enabled": true
      }
    ]
  }
}
```

Flutter 处理规则：

- 只展示 `products` 里的商品；后台已经按平台、用户区域、上架状态过滤。
- `amount_micro` 是 USDT 微单位，`1 USDT = 1000000`。
- 当前资源类型固定是 `COIN`，后续如果后台新增资源类型，客户端应按 `resource_asset_type` 分支处理。
- Android 使用 `channel=google` 的商品对接 Google Play Billing；iOS 使用 `channel=apple` 的商品对接 StoreKit。