# 通用确认消息 Flutter 对接

本文定义 Flutter 对接 `im_confirm` 私聊确认消息所需的 IM 解析、HTTP 接口、状态刷新和按钮置灰规则。业务类型首版是 `host / agency / bd` 身份邀请，Flutter 只做通用展示，不写业务分支。

## 通用约定

### Base URL

```text
https://{api_host}
```

本地开发：

```text
http://127.0.0.1:13000
```

### Headers

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization: Bearer {access_token}` | 是 | 登录后的 App token |
| `Content-Type: application/json` | POST 必填 | 请求体 JSON |
| `X-App-Code` | 否 | 多 App 包场景可传，通常由 gateway 解析 |

### 响应 Envelope

成功：

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

失败：

```json
{
  "code": "CONFLICT",
  "message": "conflict",
  "request_id": "req_xxx"
}
```

## IM 消息格式

腾讯 IM C2C 自定义消息：

| TIM 字段 | 值 |
| --- | --- |
| `Desc` | `im_confirm` |
| `Ext` | `im_confirm` |
| `Data` | JSON 字符串 |

`Data` 示例：

```json
{
  "type": "im_confirm",
  "version": 1,
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "msg": "Alice has invited you to join ABC guild",
  "status": "pending",
  "actions": [
    {
      "action": "reject",
      "label": "Reject",
      "style": "secondary"
    },
    {
      "action": "accept",
      "label": "Accept",
      "style": "primary"
    }
  ],
  "created_at_ms": 1710000000000,
  "expire_at_ms": 1710604800000
}
```

字段说明：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | string | 固定 `im_confirm` |
| `version` | int | 当前为 `1` |
| `confirm_id` | string | 确认消息 ID，后续接口只传这个 |
| `business_type` | string | 业务类型，只用于日志和埋点 |
| `business_subtype` | string | 业务子类型，只用于展示或埋点 |
| `msg` | string | 气泡文案 |
| `status` | string | 初始状态，一般为 `pending` |
| `actions` | array | 按钮配置 |
| `created_at_ms` | int64 | 创建时间 |
| `expire_at_ms` | int64 | 过期时间，可能为 0 |

Flutter 不要把 `business_type`、`business_subtype` 当成接口参数。确认接口只需要 `confirm_id`。

## 状态含义

| 状态 | Flutter 展示 |
| --- | --- |
| `pending` | 展示可点击按钮 |
| `processing` | 按钮置灰，显示处理中或本地 loading |
| `accepted` | 按钮置灰，接受态 |
| `rejected` | 按钮置灰，拒绝态 |
| `cancelled` | 按钮置灰，已取消 |
| `expired` | 按钮置灰，已过期 |
| `failed` | 按钮置灰，可提示稍后重试或联系客服 |

按钮是否可点只看最新状态是否为 `pending`。

## 接口 1：接受

地址：

```text
POST /api/v1/message/action-confirms/{confirm_id}/accept
```

参数：

```json
{
  "command_id": "cfm_123_accept_001"
}
```

返回值 `data`：

```json
{
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "business_id": "987",
  "status": "accepted",
  "processed_action": "accept",
  "processed_at_ms": 1710000001000
}
```

相关 IM：用户点击 `actions.action=accept` 的按钮时调用。

## 接口 2：拒绝

地址：

```text
POST /api/v1/message/action-confirms/{confirm_id}/reject
```

参数：

```json
{
  "command_id": "cfm_123_reject_001",
  "reason": ""
}
```

返回值 `data`：

```json
{
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "business_id": "987",
  "status": "rejected",
  "processed_action": "reject",
  "processed_at_ms": 1710000001000
}
```

相关 IM：用户点击 `actions.action=reject` 的按钮时调用。

## 接口 3：批量刷新状态

地址：

```text
POST /api/v1/message/action-confirms/status
```

参数：

```json
{
  "confirm_ids": ["cfm_123", "cfm_456"]
}
```

返回值 `data`：

```json
{
  "items": [
    {
      "confirm_id": "cfm_123",
      "business_type": "role_invitation",
      "business_subtype": "host",
      "business_id": "987",
      "status": "accepted",
      "processed_action": "accept",
      "processed_at_ms": 1710000001000
    }
  ]
}
```

使用场景：

- 打开会话时，收集当前会话里所有 `im_confirm.confirm_id` 后批量刷新。
- App 从后台回到前台时，刷新当前可见页面的确认消息状态。
- 接口返回的状态覆盖 IM 初始 `status`。

## 接口 4：按会话刷新状态

地址：

```text
GET /api/v1/message/action-confirms?peer_user_id=10001&page_size=50
```

参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `peer_user_id` | 是 | 当前会话对方用户 ID |
| `page_size` | 否 | 默认 50，最大 100 |
| `page_token` | 否 | 下一页游标 |

返回值 `data`：

```json
{
  "items": [
    {
      "confirm_id": "cfm_123",
      "sender_user_id": "10001",
      "receiver_user_id": "10002",
      "business_type": "role_invitation",
      "business_subtype": "host",
      "business_id": "987",
      "status": "pending",
      "processed_action": "",
      "processed_at_ms": 0,
      "created_at_ms": 1710000000000
    }
  ],
  "next_page_token": ""
}
```

使用场景：

- 当前 IM SDK 本地消息无法快速遍历 `confirm_id` 时使用。
- 当前用户由 token 决定，Flutter 只传对方 `peer_user_id`。

## Flutter 数据模型

```dart
class ImConfirmMessage {
  final String confirmId;
  final String businessType;
  final String businessSubtype;
  final String msg;
  final String status;
  final List<ConfirmAction> actions;
  final int createdAtMs;
  final int expireAtMs;

  ImConfirmMessage({
    required this.confirmId,
    required this.businessType,
    required this.businessSubtype,
    required this.msg,
    required this.status,
    required this.actions,
    required this.createdAtMs,
    required this.expireAtMs,
  });

  bool get canOperate => status == 'pending';

  factory ImConfirmMessage.fromJson(Map<String, dynamic> json) {
    return ImConfirmMessage(
      confirmId: (json['confirm_id'] ?? '').toString(),
      businessType: (json['business_type'] ?? '').toString(),
      businessSubtype: (json['business_subtype'] ?? '').toString(),
      msg: (json['msg'] ?? '').toString(),
      status: (json['status'] ?? 'pending').toString(),
      actions: ((json['actions'] as List?) ?? [])
          .map((item) => ConfirmAction.fromJson(Map<String, dynamic>.from(item as Map)))
          .toList(),
      createdAtMs: (json['created_at_ms'] as num?)?.toInt() ?? 0,
      expireAtMs: (json['expire_at_ms'] as num?)?.toInt() ?? 0,
    );
  }
}

class ConfirmAction {
  final String action;
  final String label;
  final String style;

  ConfirmAction({
    required this.action,
    required this.label,
    required this.style,
  });

  factory ConfirmAction.fromJson(Map<String, dynamic> json) {
    return ConfirmAction(
      action: (json['action'] ?? '').toString(),
      label: (json['label'] ?? '').toString(),
      style: (json['style'] ?? '').toString(),
    );
  }
}

class ConfirmStatus {
  final String confirmId;
  final String status;
  final String processedAction;
  final int processedAtMs;

  ConfirmStatus({
    required this.confirmId,
    required this.status,
    required this.processedAction,
    required this.processedAtMs,
  });

  bool get canOperate => status == 'pending';

  factory ConfirmStatus.fromJson(Map<String, dynamic> json) {
    return ConfirmStatus(
      confirmId: (json['confirm_id'] ?? '').toString(),
      status: (json['status'] ?? '').toString(),
      processedAction: (json['processed_action'] ?? '').toString(),
      processedAtMs: (json['processed_at_ms'] as num?)?.toInt() ?? 0,
    );
  }
}
```

## IM 解析

```dart
ImConfirmMessage? parseImConfirmCustomData(String data) {
  final dynamic decoded = jsonDecode(data);
  if (decoded is! Map) return null;
  final map = Map<String, dynamic>.from(decoded);
  if (map['type'] != 'im_confirm') return null;
  final confirmId = (map['confirm_id'] ?? '').toString();
  if (confirmId.isEmpty) return null;
  return ImConfirmMessage.fromJson(map);
}
```

解析规则：

- 只处理 `type == im_confirm`。
- `confirm_id` 为空时按普通不支持消息处理。
- `msg` 直接展示，不在 Flutter 端拼接业务文案。
- `actions` 为空时只展示文案，不展示按钮。

## API 调用

```dart
String newConfirmCommandId(String confirmId, String action) {
  return '${confirmId}_${action}_${DateTime.now().millisecondsSinceEpoch}';
}

Future<ConfirmStatus> acceptConfirm(String confirmId) async {
  final response = await http.post(
    Uri.parse('$baseUrl/api/v1/message/action-confirms/$confirmId/accept'),
    headers: authJsonHeaders(),
    body: jsonEncode({
      'command_id': newConfirmCommandId(confirmId, 'accept'),
    }),
  );
  return parseConfirmStatusEnvelope(response);
}

Future<ConfirmStatus> rejectConfirm(String confirmId, {String reason = ''}) async {
  final response = await http.post(
    Uri.parse('$baseUrl/api/v1/message/action-confirms/$confirmId/reject'),
    headers: authJsonHeaders(),
    body: jsonEncode({
      'command_id': newConfirmCommandId(confirmId, 'reject'),
      'reason': reason,
    }),
  );
  return parseConfirmStatusEnvelope(response);
}
```

`command_id` 每次点击生成一个新值。网络重试同一次请求时可以复用同一个 `command_id`。

## 状态刷新

```dart
Future<Map<String, ConfirmStatus>> batchRefreshConfirmStatus(List<String> confirmIds) async {
  final ids = confirmIds.where((id) => id.isNotEmpty).toSet().toList();
  if (ids.isEmpty) return {};

  final response = await http.post(
    Uri.parse('$baseUrl/api/v1/message/action-confirms/status'),
    headers: authJsonHeaders(),
    body: jsonEncode({'confirm_ids': ids}),
  );
  final data = parseEnvelopeData(response);
  final items = (data['items'] as List? ?? []);
  return {
    for (final item in items)
      ConfirmStatus.fromJson(Map<String, dynamic>.from(item as Map)).confirmId:
          ConfirmStatus.fromJson(Map<String, dynamic>.from(item as Map)),
  };
}
```

刷新时机：

- 进入 IM 会话页。
- App resume。
- 收到新的 `im_confirm`。
- 接受或拒绝接口返回 `CONFLICT`。

## UI 规则

- 气泡文案展示 `msg`。
- `status == pending` 时展示 `actions` 里的按钮。
- `status != pending` 时按钮置灰，不能再次点击。
- 本地发起请求后，当前按钮进入 loading，同一条消息两个按钮都置灰。
- 接口成功后，用返回状态覆盖本地状态。
- 接口失败但不是鉴权错误时，调用状态接口刷新一次。

按钮样式建议：

| style | 展示 |
| --- | --- |
| `primary` | 主按钮，例如绿色 Accept |
| `secondary` | 次按钮，例如描边 Reject |

Flutter 不要根据 `business_subtype` 写死按钮文案，按钮文案以 `actions.label` 为准。

## 错误处理

| code | Flutter 处理 |
| --- | --- |
| `UNAUTHORIZED` | 重新登录 |
| `PERMISSION_DENIED` | 置灰并提示无权限 |
| `NOT_FOUND` | 置灰，消息已失效 |
| `CONFLICT` | 调状态接口刷新，按最新状态置灰 |
| `UPSTREAM_ERROR` | 解除 loading，允许稍后重试 |
| `INTERNAL_ERROR` | 解除 loading，提示稍后重试 |

重复点击、跨设备已处理、旧消息重新打开，都以状态接口返回为准。

## 对接检查

- 收到 `im_confirm` 后能渲染文案和两个按钮。
- 点击 Accept 后调用接受接口，成功后按钮置灰。
- 点击 Reject 后调用拒绝接口，成功后按钮置灰。
- 同一条消息重复点击不会重复请求；如果请求已经发出，两个按钮都置灰。
- App 重新进入会话后，通过状态接口刷新旧消息状态。
- 另一个设备处理后，本设备 resume 能刷新为终态。
- `CONFLICT` 时不弹业务成功，只刷新状态后展示最终状态。