XuqmGroup-AndroidSDK/sdk-file/README.md

# sdk-file

XuqmGroup Android SDK 的平台文件扩展。它是依赖 `sdk-core` 的可选模块，统一承载：

- 使用 XuqmSDK 当前登录态和租户平台文件服务上传文件；
- 通过模块唯一声明的 `FileProvider` 安全打开本地文件。

纯下载、SHA-256、MediaStore 保存等无需初始化的能力仍由
`com.xuqm.sdk.file.FileSDK` 提供，`sdk-core` 不包含上传转发 API 或 FileProvider。

## 集成

```kotlin
dependencies {
    implementation("com.xuqm:sdk-file:VERSION")
}
```

宿主同时应用 `com.xuqm.common` 构建插件，并将租户平台签发的
`config.xuqmconfig` 放在 `app/src/main/assets/config/config.xuqmconfig`。模块的
`XuqmMergedProvider` 只有检测到构建插件生成的标记后才会自动初始化 SDK。

## 上传

```kotlin
val fromUri = PlatformFileSDK.upload(
    context = context,
    uri = uri,
    onProgress = { progress -> /* 0..100 */ },
)

val fromFile = PlatformFileSDK.upload(
    file = file,
    onProgress = { progress -> /* 0..100 */ },
)

val fromBytes = PlatformFileSDK.uploadBytes(
    fileName = "photo.jpg",
    mimeType = "image/jpeg",
    bytes = bytes,
)
```

`Uri` 和 `File` 使用流式请求体，不会把完整文件读入内存。返回
`FileUploadResult`，字段包括 `url`、`thumbnailUrl`、`hash`、`size`、
`originalName`、`mimeType` 和 `ext`。

三个上传入口都会先等待签名配置和平台服务配置初始化完成，宿主无需自行增加等待
逻辑。平台返回失败、状态不一致或成功响应缺少 data 时抛出
`PlatformFileException`；其 `code`、`status`、`message` 保留服务端结构化错误，
但不会暴露原始响应体。

## 打开文件

```kotlin
PlatformFileSDK.openFile(context, file)
```

打开本地文件不依赖平台初始化或登录。

模块通过独立的 `XuqmFileProvider` 声明 `${applicationId}.xuqm.fileprovider`。
它不会与宿主或其他 SDK 自己的 `FileProvider` 合并冲突，宿主无需添加
`tools:replace`。其他模块不得重复声明同一 Xuqm authority。