# Upload 模块业务逻辑

## 模块职责

Upload 模块负责 App 内通用文件上传能力，当前主要服务个人头像和实名认证证件图片，后续云盘、相册、任务、打卡点等模块迁移时复用同一套 OSS 上传入口。

该模块不负责业务表单提交，只负责：
- 获取阿里云 OSS STS 临时配置。
- 校验待上传文件大小和扩展名。
- 生成按业务模块隔离的 OSS objectKey。
- 调用阿里云 OSS Swift SDK 上传文件。
- 返回最终可访问的文件 URL。

## 核心对象

- `UploadAPI`：封装 `/api/app/config/get-sts-token`，只负责获取 STS 临时上传配置。
- `OSSUploadService`：统一上传服务，封装 SDK 调用和进度回调。
- `OSSUploadPolicy`：上传策略，管理大小限制、扩展名白名单、路径规则、MIME 类型和 URL 拼接。
- `AvatarImageProcessor`：头像图片处理器，上传前把图片压缩为 JPEG。
- `RealNameImageProcessor`：实名认证证件图片处理器，上传前把证件图压缩为 JPEG。
- `RemoteImage`：Kingfisher 网络图片组件，统一远程图片加载、缓存和失败占位。

## 上传流程

1. 页面或 ViewModel 将用户选择的本地图片处理成上传数据。
2. ViewModel 调用 `OSSUploadService` 的业务上传方法。
3. `OSSUploadService` 调用 `UploadAPI.aliyunOSSBucket(bucket:)` 获取 STS 配置。
4. `OSSUploadPolicy` 校验文件并生成 objectKey。
5. `OSSUploadService` 使用 `AlibabaCloudOSS` SDK 上传数据。
6. 上传成功后返回 `base_url + objectKey`。
7. 业务 ViewModel 再把 URL 提交给对应业务接口。

## 路径规则

当前模块路径：
- `user_avatar`：`avatar/yyyyMMdd/scenicId/uuid_fileName`
- `real_name`：`real_name/yyyyMMdd/scenicId/uuid_fileName`
- `task_upload`：`task_upload/yyyyMMdd/scenicId/uuid_fileName`
- `cloud_driver`：`cloud_driver/yyyyMMdd/scenicId/uuid_fileName`
- `album_upload`：`album/yyyyMMdd/scenicId/uuid_fileName`
- `alive_album`：`live_albums/yyyyMMdd/scenicId/uuid_fileName`
- `punch_point`：`punch_point/yyyyMMdd/scenicId/uuid_fileName`
- `scenic_apply`：`scenic_apply/yyyyMMdd/scenicId/uuid_fileName`

文件名会清理控制字符、`/` 和 `\`，避免生成非法 objectKey。

## 缓存边界

- OSS STS token 不落盘，只在一次上传流程中临时使用。
- 原始图片 Data、压缩后图片 Data、上传进度不落盘。
- 图片展示缓存交给 Kingfisher，业务代码不自行保存网络图片文件。
- 正式登录 token 仍由 `SessionTokenStore` 使用 Keychain 保存，上传模块不直接读取或保存登录态。