富媒体上传

富媒体（图片/视频/语音/文件）的发送统一封装在 Bngeuit 门面：ByUrl（公网 URL）与 ByFile（本地文件）两种方式，命名对称成对。

FileType

枚举值	数值	说明
IMAGE	1	图片（png/jpg，软限制 20MB）
VIDEO	2	视频（mp4，软限制 30MB）
VOICE	3	语音（silk，软限制 20MB）
FILE	4	文件（任意格式，软限制 200MB）

方式一：公网 URL（ByUrl）

传入一个公网可访问的 URL，内部自动完成上传 → 发送：

import cn.org.bukkit.bngeuit.Bngeuit;

// 群聊
Bngeuit.sendGroupImageByUrl(groupOpenid, msgSeq, "https://example.com/img.png");
Bngeuit.sendGroupVideoByUrl(groupOpenid, msgSeq, "https://example.com/video.mp4");

// 私聊
Bngeuit.sendC2CVoiceByUrl(openid, msgSeq, "https://example.com/voice.silk");
Bngeuit.sendC2CFileByUrl(openid, msgSeq, "https://example.com/file.rar");

方式二：本地文件（ByFile）

传入本地 File 对象，内部自动分片上传 → 发送（预上传 → 逐片 PUT → 分片确认 → 合并），无需关心分片细节：

import cn.org.bukkit.bngeuit.Bngeuit;

// 群聊
Bngeuit.sendGroupImageByFile(groupOpenid, msgSeq, new File("path/to/img.png"));
Bngeuit.sendGroupVideoByFile(groupOpenid, msgSeq, new File("path/to/video.mp4"));

// 私聊
Bngeuit.sendC2CVoiceByFile(openid, msgSeq, new File("path/to/voice.silk"));
Bngeuit.sendC2CFileByFile(openid, msgSeq, new File("path/to/file.rar"));

便捷助手

Bngeuit.getMediaFile(String fileName) 返回 media_files/<fileName>（存在且为文件），可直接喂给 ByFile 方法：

Bngeuit.sendGroupImageByFile(groupOpenid, msgSeq, Bngeuit.getMediaFile("测试图片.jpg"));

高级：只上传不发送

需要分步控制时，用 Bngeuit.api() 手动完成上传，拿到 UploadResponse.fileInfo() 后自行发送：

import cn.org.bukkit.bngeuit.Bngeuit;
import cn.org.bukkit.bngeuit.core.BotApi;
import cn.org.bukkit.bngeuit.dto.message.*;

BotApi api = Bngeuit.api();

// URL 上传（单次 HTTP）
UploadResponse r = api.uploadGroupFile(groupOpenid, FileType.IMAGE, url, false);

// 本地文件分片上传（自动分片全流程）
UploadResponse r2 = api.uploadGroupFileByFile(groupOpenid, FileType.IMAGE, new File("img.png"));

// 用 file_info 手动发送
api.sendGroupMessage(GroupMessageRequest.builder()
    .groupOpenid(groupOpenid)
    .msgType(MsgType.MEDIA)
    .media(new MediaInfo(r2.fileInfo()))
    .msgSeq(msgSeq)
    .build());

分片上传底层端点

需要完全手控分片流程时，BotApi 暴露以下底层端点（预上传 → 分片确认 → 合并，分片 PUT 需自行处理）：

• 群聊：uploadPrepareGroup(...) → uploadPartFinishGroup(...) → uploadGroupChunked(groupOpenid, fileType, uploadId, File)
• 私聊：uploadPrepareC2C(...) → uploadPartFinishC2C(...) → uploadC2CChunked(openid, fileType, uploadId, File)

日常开发建议直接使用门面 sendGroupXxxByFile 或 api().uploadGroupFileByFile。

分片上传事件

本地分片上传会触发可取消的发送事件，可在各步骤拦截：

步骤	事件
预上传前	GroupUploadPrepareEvent / C2CUploadPrepareEvent
每片确认前	GroupUploadPartFinishEvent / C2CUploadPartFinishEvent
合并前	GroupUploadChunkedEvent / C2CUploadChunkedEvent（携带 File 对象，getFile() / getFileName() / getFilePath()）

取消事件则对应 API 调用被跳过并返回 null。