# Fami 房间封面上传 Flutter 接口对接

## 接入结论

Fami 创建房间和修改房间封面前，必须先调用 `POST /api/v1/rooms/covers/upload`。上传成功后只把 `cover_upload_id` 提交给创建/更新接口；响应里的 `url` 只用于本地预览，不能继续作为 `room_avatar` 提交。

服务端根据文件魔数识别实际格式，校验扩展名、multipart Content-Type、尺寸、字节数、帧数和动画时长。文件原始字节直接写 COS，不裁剪、不转码。动态 GIF/WebP 由服务端调用 Wallet `CheckVipBenefit(animated_room_cover)`；Fami 当前配置为 VIP4 解锁，Flutter 不得用本地 `vipLevel >= 4` 代替服务端判定。

## 1. 上传接口

```http
POST /api/v1/rooms/covers/upload
Authorization: Bearer {access_token}
Content-Type: multipart/form-data

command_id={本次选择文件的上传幂等键}
file={原始文件字节}
```

约束：

| 项目 | 规则 |
| --- | --- |
| 格式 | JPEG、PNG、GIF、WebP；不支持 APNG |
| 一致性 | 魔数、文件扩展名、multipart Content-Type 必须一致 |
| 大小 | 最大 10 MiB，服务端读取字节数必须与 multipart 文件大小一致 |
| 尺寸 | 宽、高均不超过 4096，总像素不超过 16,777,216 |
| 动画 | 仅多帧 GIF/WebP；最多 120 帧，总时长 `(0, 15000]ms` |
| 静态 | `frame_count=1`、`animated=false`、`duration_ms=0` |

同一次上传因超时重试时复用原 `command_id` 和同一文件；用户重新选择文件时生成新的 `command_id`。不要统一发送 `application/octet-stream`。

成功响应：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {
    "cover_upload_id": "cover_12ab34cd56ef789012ab34cd56ef7890",
    "url": "https://cdn.example.com/room-media/fami/covers/10001/x.gif",
    "sha256": "64位小写十六进制",
    "frame_count": 18,
    "animated": true,
    "content_type": "image/gif",
    "format": "gif",
    "size_bytes": 1256789,
    "width": 640,
    "height": 640,
    "duration_ms": 3600,
    "server_time_ms": 1784592000000
  }
}
```

`url`、后缀和 `content_type` 都是服务端按实际格式生成的结果。Flutter 可以立即用 `url` 预览，但持久化房间封面只能使用 `cover_upload_id`。

## 2. 创建房间

```http
POST /api/v1/rooms/create
Content-Type: application/json

{
  "command_id": "create_room_550e8400-e29b-41d4-a716-446655440000",
  "seat_count": 10,
  "mode": "voice",
  "room_name": "My Room",
  "cover_upload_id": "cover_12ab34cd56ef789012ab34cd56ef7890",
  "room_description": ""
}
```

Fami 不再提交 `room_avatar`。服务端会校验上传记录属于当前 `app_code + user_id`、状态为可消费，并在创建命令事务内绑定房间和推进 `consumed`。一个 `cover_upload_id` 不能创建两个房间。

## 3. 修改房间封面

```http
POST /api/v1/rooms/profile/update
Content-Type: application/json

{
  "room_id": "fami_room_xxx",
  "command_id": "update_cover_550e8400-e29b-41d4-a716-446655440000",
  "cover_upload_id": "cover_98ab76cd54ef321098ab76cd54ef3210"
}
```

`cover_upload_id` 与历史字段 `room_avatar` 互斥。资料修改成功后凭证立即消费；HTTP 超时重试要同时复用原更新 `command_id` 和原 `cover_upload_id`。

## 4. Dio 示例

```dart
import 'package:dio/dio.dart';
import 'package:http_parser/http_parser.dart';

class RoomCoverUploadResult {
  const RoomCoverUploadResult({
    required this.coverUploadId,
    required this.url,
    required this.sha256,
    required this.frameCount,
    required this.animated,
  });

  final String coverUploadId;
  final String url;
  final String sha256;
  final int frameCount;
  final bool animated;

  factory RoomCoverUploadResult.fromJson(Map<String, dynamic> json) {
    return RoomCoverUploadResult(
      coverUploadId: json['cover_upload_id'] as String,
      url: json['url'] as String,
      sha256: json['sha256'] as String,
      frameCount: json['frame_count'] as int,
      animated: json['animated'] as bool,
    );
  }
}

MediaType roomCoverMediaType(String extension) {
  switch (extension.toLowerCase()) {
    case 'jpg':
    case 'jpeg':
      return MediaType('image', 'jpeg');
    case 'png':
      return MediaType('image', 'png');
    case 'gif':
      return MediaType('image', 'gif');
    case 'webp':
      return MediaType('image', 'webp');
    default:
      throw ArgumentError('unsupported room cover extension');
  }
}

Future<RoomCoverUploadResult> uploadRoomCover({
  required Dio dio,
  required String filePath,
  required String fileName,
  required String extension,
  required String uploadCommandId,
}) async {
  final response = await dio.post<Map<String, dynamic>>(
    '/api/v1/rooms/covers/upload',
    data: FormData.fromMap({
      'command_id': uploadCommandId,
      'file': await MultipartFile.fromFile(
        filePath,
        filename: fileName,
        contentType: roomCoverMediaType(extension),
      ),
    }),
  );
  final envelope = response.data!;
  if (envelope['code'] != 'OK') {
    throw StateError(envelope['code'] as String? ?? 'UPLOAD_FAILED');
  }
  return RoomCoverUploadResult.fromJson(envelope['data'] as Map<String, dynamic>);
}
```

选择图片时必须保留 GIF/WebP 原始字节。静态图若客户端裁剪后输出 JPEG，文件名应改成 `.jpg/.jpeg`，multipart MIME 应为 `image/jpeg`；不能保留原 `.png/.gif` 名称。

创建/更新参数示例：

```dart
await dio.post('/api/v1/rooms/create', data: {
  'command_id': createCommandId,
  'seat_count': seatCount,
  'mode': mode,
  'room_name': roomName,
  'cover_upload_id': uploaded.coverUploadId,
  'room_description': description,
});

await dio.post('/api/v1/rooms/profile/update', data: {
  'room_id': roomId,
  'command_id': updateCommandId,
  'cover_upload_id': uploaded.coverUploadId,
});
```

## 5. 错误处理

| HTTP / code | 含义 | Flutter 动作 |
| --- | --- | --- |
| `403 / VIP_BENEFIT_REQUIRED` | 动态封面缺少 `animated_room_cover` | 读取 `data.benefit_code`、`required_level`，展示升级入口；不要自行写死 VIP4 |
| `413 / FILE_TOO_LARGE` | 超过 10 MiB | 保留选择页并提示重新选择 |
| `415 / UNSUPPORTED_MEDIA_TYPE` | 魔数、扩展名、MIME 或文件结构不一致 | 不重试；重新选择或修正 multipart MIME |
| `400 / INVALID_MEDIA_DIMENSIONS` | 尺寸、总像素、帧数或时长越界 | 不重试；重新选择 |
| `409 / IDEMPOTENCY_CONFLICT` | 同一上传 `command_id` 换了文件 | 为新文件生成新 `command_id` |
| `404 / NOT_FOUND` | 创建/更新时凭证不存在 | 重新上传，再提交新凭证 |
| `403 / PERMISSION_DENIED` | 凭证不属于当前用户/租户，或不是房主 | 丢弃本地凭证并刷新房间权限 |

服务端错误是最终权限事实。本地 VIP 信息只能用于提前展示锁态，不能跳过上传请求或把动态 URL 直接交给创建/更新接口。

## 6. 发布与旧数据

发布顺序为后端接口和消费校验先上线，再发布 Flutter。客户端升级后，所有 Fami 房间封面都使用新接口。

历史上响应头为 `image/gif`、实际字节为单帧 PNG 的伪 GIF 已经没有动画帧，客户端无法恢复。后端修复上线后必须让用户重新上传原始 GIF/WebP，并按现有 CDN 管理流程刷新旧 URL 缓存；不要只改文件后缀或 Content-Type。