# Flutter 金币流水对接

本文只描述 Flutter App 读取当前登录用户金币流水的接口。金币余额和流水事实由 `wallet-service` 维护；客户端只展示 gateway 返回的分录投影，不在本地推算余额。

## 接口

`GET /api/v1/wallet/coin-transactions`

登录接口，需要 `Authorization: Bearer <access_token>`。接口固定查询当前登录用户的 `COIN` 资产流水，不接受客户端传 `user_id` 或 `asset_type`。

请求头：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | App 登录 access token。 |
| `X-App-Code` | 否 | App 编码，默认 `lalu`。 |

Query：

| 字段 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| `page` | 否 | `1` | 页码，从 1 开始。 |
| `page_size` | 否 | `30` | 每页数量。首屏不传时返回最近 30 条。 |

排序固定为 `created_at_ms DESC, entry_id DESC`，即最新流水在前。分页字段使用通用 `page` / `page_size`，不要使用业务专属分页名。

示例：

```http
GET /api/v1/wallet/coin-transactions?page=1&page_size=30
Authorization: Bearer <access_token>
X-App-Code: lalu
```

成功响应：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "items": [
      {
        "entry_id": 101,
        "transaction_id": "wtx_abc",
        "biz_type": "coin_seller_transfer",
        "asset_type": "COIN",
        "available_delta": 3000,
        "frozen_delta": 0,
        "available_after": 12800,
        "frozen_after": 0,
        "counterparty_user_id": 90001,
        "room_id": "",
        "created_at_ms": 1710000000000
      }
    ],
    "total": 48,
    "page": 1,
    "page_size": 30
  }
}
```

字段规则：

| 字段 | 说明 |
| --- | --- |
| `available_delta` | 本次可用金币变化；正数是收入，负数是支出。 |
| `available_after` | 本条流水落账后的可用金币余额，余额展示以该字段为准。 |
| `biz_type` | 业务类型，例如 `coin_seller_transfer`、`gift_debit`、`task_reward`、`game_credit`、`game_debit`、`game_refund`、`vip_purchase`。客户端可本地映射展示文案。 |
| `counterparty_user_id` | 对手用户长 ID；没有对手方时为 `0`。 |
| `room_id` | 房间相关流水的房间 ID；非房间流水为空字符串。 |
| `created_at_ms` | Unix epoch milliseconds；展示层按用户本地时区格式化。 |

## Flutter 解析示例

```dart
class CoinTransactionPage {
  CoinTransactionPage({
    required this.items,
    required this.total,
    required this.page,
    required this.pageSize,
  });

  final List<CoinTransaction> items;
  final int total;
  final int page;
  final int pageSize;

  factory CoinTransactionPage.fromJson(Map<String, dynamic> json) {
    return CoinTransactionPage(
      items: (json['items'] as List<dynamic>? ?? const [])
          .map((item) => CoinTransaction.fromJson(item as Map<String, dynamic>))
          .toList(),
      total: (json['total'] as num?)?.toInt() ?? 0,
      page: (json['page'] as num?)?.toInt() ?? 1,
      pageSize: (json['page_size'] as num?)?.toInt() ?? 30,
    );
  }
}

class CoinTransaction {
  CoinTransaction({
    required this.entryId,
    required this.transactionId,
    required this.bizType,
    required this.availableDelta,
    required this.availableAfter,
    required this.createdAtMs,
  });

  final int entryId;
  final String transactionId;
  final String bizType;
  final int availableDelta;
  final int availableAfter;
  final int createdAtMs;

  bool get isIncome => availableDelta > 0;
  int get amount => availableDelta.abs();

  factory CoinTransaction.fromJson(Map<String, dynamic> json) {
    return CoinTransaction(
      entryId: (json['entry_id'] as num).toInt(),
      transactionId: json['transaction_id'] as String? ?? '',
      bizType: json['biz_type'] as String? ?? '',
      availableDelta: (json['available_delta'] as num?)?.toInt() ?? 0,
      availableAfter: (json['available_after'] as num?)?.toInt() ?? 0,
      createdAtMs: (json['created_at_ms'] as num?)?.toInt() ?? 0,
    );
  }
}
```

接口调用时，先解析外层 envelope：只有 `code == "OK"` 时读取 `data`；其他 `code` 按登录态、参数错误或服务错误处理，并把 `request_id` 记录到客户端日志。