文件与媒体附件

图片、语音、视频和文件包含消息记录与存储对象两部分。先上传获得存储标识，再发送与该对象绑定的消息；接收方使用经过授权的短效地址访问附件。

上传入口

final uploaded = await sdk.attachments.upload(
  selectedFilePath,
  fileName: 'project-note.pdf',
  mimeType: 'application/pdf',
);

sdk 为已连接的实例，selectedFilePath 由宿主文件选择器提供。宿主负责相册、摄像头或文件访问权限，用户完成选择后再提交上传。

上传结果包含存储标识、名称、大小、MIME 等信息。发送时沿用服务端返回的元数据，通过 UIKit 媒体入口或配套的类型化消息接口构造消息。

三步处理

阶段	客户端行为	服务端职责
上传	提交当前用户选择的文件	校验、扫描、保存可信元数据
发送	引用上传结果，发送媒体或文件消息	校验归属与消息权限，建立绑定
访问	使用授权地址读取，需要时刷新	校验当前用户可见性后签发短效地址

部署时配置对象存储、文件扫描和网络入口，并设置允许的文件格式与大小。参见私有化部署。

链接失效与刷新

附件链接有有效期。刷新时提供当前 IM Session，以及源消息的会话 ID、客户端消息 ID 与存储 ID，由服务端校验消息访问权限。

默认 Flutter UIKit 在授权地址失效后执行单次刷新重试。自定义页面区分地址过期与权限变化；刷新后仍返回 401/403 时结束重试并展示访问提示。

缓存与账号隔离

媒体缓存使用账号范围、对象标识和变体作为稳定键，带签名的短链作为下载地址。切号时切换缓存作用域，按当前账号权限展示附件。

消息数据库、系统相册、宿主下载目录和媒体缓存分别管理。宿主按产品策略处理保存、下载、清理和退出；本地数据库加密仅覆盖数据库，附件存储保护需单独配置，详见安全配置。

接入检查

在项目对象存储环境中检查短效链接刷新、上传中断、权限变化、账号切换和两端媒体播放，保证附件访问与消息状态一致。