# Flutter H5 排行榜对接文档

本文说明 Flutter App 如何打开 H5 排行榜、向 H5 传递登录态，以及接收 H5 通过 JSBridge 发回的导航事件。

## 入口地址

本地开发：

```text
http://127.0.0.1:30000/rank/index.html?env=local&token={access_token}&app_code=lalu
```

测试环境：

```text
https://{h5-test-domain}/rank/index.html?env=test&token={access_token}&app_code=lalu
```

线上环境：

```text
https://{h5-domain}/rank/index.html?token={access_token}&app_code=lalu
```

`env` 规则：

| 参数 | 说明 |
| --- | --- |
| 不传 | H5 请求 `https://api.global-interaction.com/` |
| `env=test` | H5 请求 `https://api-test.global-interaction.com/` |
| `env=local` | H5 请求 `http://localhost:13000/`，用于本机 gateway 联调 |

## URL 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `token` | 是 | App 登录后拿到的 access token。H5 会作为 `Authorization: Bearer <token>` 调后端。 |
| `access_token` | 否 | `token` 的兼容别名。 |
| `accessToken` | 否 | `token` 的兼容别名。 |
| `app_code` | 是 | App 编码，当前传 `lalu`。H5 会作为 `X-App-Code` 请求头。 |
| `appCode` | 否 | `app_code` 的兼容别名。 |
| `env` | 否 | API 环境切换，见上表。 |

H5 启动后会调用：

```http
GET /api/v1/users/me/overview
Authorization: Bearer <token>
X-App-Code: lalu
```

这个接口用于确认登录态并缓存当前用户信息。排行榜数据使用同一个 token 和 app code 请求。

## H5 页面能力

排行榜页面地址：

```text
/rank/index.html
```

页面内包含三个榜单，通过 tab 切换：

| H5 Tab | 后端 `board_type` | 说明 |
| --- | --- | --- |
| `Wealth` | `sent` | 财富榜，按用户送礼总金币排行 |
| `Room` | `room` | 房间榜，按房间收礼总金币排行 |
| `Charm` | `received` | 魅力榜，按用户收礼总金币排行 |

时间维度：

| H5 Tab | 后端 `period` |
| --- | --- |
| `Daily` | `today` |
| `Weekly` | `week` |
| `Monthly` | `month` |

排行榜接口：

```http
GET /api/v1/activities/user-leaderboards?board_type=sent&period=today&page=1&page_size=20
Authorization: Bearer <token>
X-App-Code: lalu
```

H5 会分页加载，`page_size=20`。如果无 token 或接口失败，页面会展示 Figma 默认占位数据，不阻塞页面打开。

## Flutter JSBridge

H5 会按以下优先级尝试发送消息：

1. `window.flutter_inappwebview.callHandler("HyAppBridge", action, payload)`
2. `window.HyAppBridgeChannel.postMessage(jsonString)`
3. `window.FlutterBridge.postMessage(jsonString)`
4. `window.webkit.messageHandlers.HyAppBridge.postMessage({ action, payload })`

Flutter 只需要实现其中一种即可。推荐统一注册 `HyAppBridge`。

### 消息格式

除 `flutter_inappwebview.callHandler` 外，postMessage 的消息是 JSON 字符串：

```json
{
  "action": "openUser",
  "payload": {
    "user_id": "10001"
  }
}
```

### H5 发出的 action

| action | payload | 触发场景 | Flutter 行为 |
| --- | --- | --- | --- |
| `ready` | `{ "page": "rank" }` | H5 初始化完成 | 可关闭加载态 |
| `back` | `{}` | 用户点击左上角返回 | 关闭 WebView 或返回上一页 |
| `openUser` | `{ "user_id": "10001" }` | 点击财富榜/魅力榜用户头像、榜单项 | 打开用户详情页 |
| `openRoom` | `{ "room_id": "room_id" }` | 点击房间榜房间头像、榜单项 | 进入或打开房间详情 |
| `openRankNote` | `{ "board_type": "sent" }` | 点击右上角问号 | 当前 H5 已内置说明页；Flutter 可只打点，不需要跳转 |

`board_type` 取值：

| 值 | 说明 |
| --- | --- |
| `sent` | 财富榜 |
| `room` | 房间榜 |
| `received` | 魅力榜 |

## Flutter 示例

### flutter_inappwebview

```dart
final url = Uri.parse(
  'http://127.0.0.1:30000/rank/index.html'
  '?env=local'
  '&token=${Uri.encodeComponent(accessToken)}'
  '&app_code=lalu',
);

InAppWebView(
  initialUrlRequest: URLRequest(url: WebUri(url.toString())),
  onWebViewCreated: (controller) {
    controller.addJavaScriptHandler(
      handlerName: 'HyAppBridge',
      callback: (args) async {
        final action = args.isNotEmpty ? args[0] as String : '';
        final payload = args.length > 1 && args[1] is Map
            ? Map<String, dynamic>.from(args[1] as Map)
            : <String, dynamic>{};

        switch (action) {
          case 'ready':
            // 关闭 loading
            break;
          case 'back':
            Navigator.of(context).maybePop();
            break;
          case 'openUser':
            final userId = payload['user_id']?.toString() ?? '';
            if (userId.isNotEmpty) {
              // TODO: 打开用户详情页
            }
            break;
          case 'openRoom':
            final roomId = payload['room_id']?.toString() ?? '';
            if (roomId.isNotEmpty) {
              // TODO: 打开房间或房间详情页
            }
            break;
          case 'openRankNote':
            // H5 内部已展示说明页，这里可做埋点
            break;
        }
        return {'ok': true};
      },
    );
  },
)
```

### webview_flutter JavaScriptChannel

如果使用 `webview_flutter`，可以注入 `HyAppBridgeChannel`：

```dart
final controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel(
    'HyAppBridgeChannel',
    onMessageReceived: (message) {
      final data = jsonDecode(message.message) as Map<String, dynamic>;
      final action = data['action']?.toString() ?? '';
      final payload = data['payload'] is Map
          ? Map<String, dynamic>.from(data['payload'] as Map)
          : <String, dynamic>{};

      switch (action) {
        case 'ready':
          break;
        case 'back':
          Navigator.of(context).maybePop();
          break;
        case 'openUser':
          final userId = payload['user_id']?.toString() ?? '';
          break;
        case 'openRoom':
          final roomId = payload['room_id']?.toString() ?? '';
          break;
      }
    },
  )
  ..loadRequest(Uri.parse(rankUrl));
```

## 后端依赖

H5 依赖以下 Gateway HTTP 接口：

| 接口 | 说明 |
| --- | --- |
| `GET /api/v1/users/me/overview` | 解析 token 后获取当前用户信息 |
| `GET /api/v1/activities/user-leaderboards` | 获取排行榜 |

业务接口返回 envelope：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {}
}
```

H5 也兼容旧的 `code: 0` 成功格式。

## 本地联调

在 `hyapp-h5` 目录运行：

```bash
make run
```

默认打开：

```text
http://127.0.0.1:30000/rank/index.html?env=local
```

Flutter 真机调本机服务时，`env=local` 对 H5 来说会请求 `http://localhost:13000/`。如果 WebView 运行在真机上，`localhost` 指向手机自身，不是开发机。真机联调建议：

1. 使用测试环境 `env=test`。
2. 或把 H5/API 部署到同一局域网可访问地址。
3. 或后续给 H5 增加可配置 `api_base` 参数。

## 验收点

1. Flutter 打开 H5 时带上 `token` 和 `app_code`。
2. H5 首次加载后发出 `ready`。
3. 点击左上角返回，Flutter 收到 `back` 并关闭 WebView。
4. 点击财富榜/魅力榜用户，Flutter 收到 `openUser`。
5. 点击房间榜房间，Flutter 收到 `openRoom`。
6. 切换 `Wealth / Room / Charm` 和 `Daily / Weekly / Monthly` 时，H5 正确请求排行榜接口。
7. 点击右上角问号，H5 展示说明页，返回后仍停留在排行榜页。