汉秋
be9c844bd3
恢复 USB 相机连接、边拍边传、三品牌驱动与 SwiftUI 历史导入页，通过适配层对接现有本地上传与 OSS 管道。 Co-authored-by: Cursor <cursoragent@cursor.com>
120 lines
6.8 KiB
Markdown
120 lines
6.8 KiB
Markdown
# TravelAlbum
|
||
|
||
## 职责
|
||
|
||
旅拍相册（新增相册 / 新建相册任务）模块，包含任务创建、相册详情、小程序码与 USB 有线传图上传。
|
||
|
||
## 入口
|
||
|
||
- 权限 URI：`travel_album` → `TravelAlbumEntryView`
|
||
- Android 对照：`ui/travelalbum` → `WiredCameraTransferScreen.kt`
|
||
|
||
## 核心页面
|
||
|
||
| 页面 | 说明 |
|
||
| --- | --- |
|
||
| `TravelAlbumEntryView` | 新增相册列表、新建任务入口；卡片主区域点击进入详情，底部保留「拍传」「相册码」 |
|
||
| `CreateTravelAlbumSheet` | 先拍再买 / 买了再拍创建弹窗 |
|
||
| `TravelAlbumDetailView` | 相册详情与素材管理（UI 对齐 Android） |
|
||
| `WiredCameraTransferView` | 有线传图页（UI 对齐 Android） |
|
||
|
||
## 相册详情 UI 结构
|
||
|
||
Android 对照：`zhiflyfollow/.../TravelAlbumDetailScreen.kt`
|
||
|
||
```
|
||
TravelAlbumDetailInfoCard # 信息卡片：手机号 + 创建时间 + 拨号
|
||
TravelAlbumDetailPhotoManageCard # 白卡片：Tab / 排序 / 批量选择 + 网格
|
||
TravelAlbumDetailMaterialGridItem# 缩略图 + 已购买角标（条件显示）+ 文件名 + 大小
|
||
BottomBar # 上传照片 + 条件删除选中
|
||
```
|
||
|
||
## 相册详情交互流程
|
||
|
||
1. **Tab**：全部照片 / 已购照片，切换后重载素材列表
|
||
2. **排序**：创建时间正序/倒序、文件名正序/倒序
|
||
3. **批量删除**：仅在「全部照片」Tab 可选，且仅未购买素材可删
|
||
4. **上传照片**：底部按钮进入 `WiredCameraTransferView`，返回后自动刷新
|
||
5. **删除相册**：右上角更多菜单
|
||
6. **图片预览**：非选择模式下点击网格项打开大图预览，可左右滑动浏览当前列表
|
||
|
||
## 有线传图 UI 结构
|
||
|
||
Android 对照：`zhiflyfollow/.../WiredCameraTransferScreen.kt`
|
||
|
||
```
|
||
WiredTransferHeaderView # 蓝色顶栏：相册名 + 手机号
|
||
WiredTransferControlCard # 浮动白卡片：设备存储 / 连接状态 / 筛选 Chip / Tab
|
||
WiredTransferSelectAllBar # 勾选模式全选栏（条件显示）
|
||
WiredTransferPhotoListPanel # 时间侧栏 + 30 分钟分组列表
|
||
WiredTransferBottomBar # 批量上传 + 指定上传 + 历史导入
|
||
SpecifyUploadBottomSheet # 指定上传选项弹层
|
||
CameraHistoryImportView # 相机 SD 卡历史导入全屏 Sheet
|
||
SonyMTPHelpView # Sony MTP 模式帮助说明
|
||
```
|
||
|
||
## 有线传图交互流程
|
||
|
||
1. **USB 连接**：进入页面后 `OTGLiveTransferCoordinator` 驱动 `Core/CameraOTG` 的 `ConnectionManager` 搜索并连接 Sony / Canon / Nikon 相机；连接成功 Toast 提示，断开时弹窗警告
|
||
2. **刷新**：catalog 就绪后点击「刷新」→ `refreshCameraFiles()` 同步相机内已有照片（拍后传输模式仅下载不上传）；未连接时刷新本地持久化记录
|
||
3. **历史导入**：底部「历史导入」在 `catalogReady && 已连接` 时可点，打开 `CameraHistoryImportView` 按日多选导入；Sony catalog 为空时展示 MTP 帮助入口
|
||
4. **批量上传三态**：
|
||
- 首次点击 → 进入勾选模式
|
||
- 有选中项 → 上传选中照片
|
||
- 无选中项 → 取消选择
|
||
5. **指定上传**：底部 Sheet 选择「上传所有未上传的照片」或「上传所有今日拍摄的照片」
|
||
- 指定上传会同时处理当前管道任务和本地持久化记录；仅存在本地记录的照片会先按本地路径恢复到传输管道，再上传 OSS 并登记素材
|
||
6. **时间侧栏**：按 30 分钟时间段分组，点击侧栏滚动到对应 section
|
||
7. **格式 Chip**：当前固定展示 JPG，与「不修图」一样不可点击；RAW 等格式后续扩展
|
||
8. **传输模式**：「边拍边传 / 拍后传输」按账号缓存，下次进入有线传图页自动恢复
|
||
- 「边拍边传」：相机新拍照片经 OTG 落盘后自动进入上传队列（最多 3 张并发）
|
||
- 「拍后传输」：下载到 App 的照片不自动上传，需通过批量上传、指定上传、勾选上传或单张重试显式上传
|
||
9. **前后台**：App 回到前台且未连接时自动重新搜索相机；离开页面仅 detach UI，保持设备缓存（与 demo 一致）
|
||
|
||
## OTG 与上传管道
|
||
|
||
```
|
||
WiredCameraTransferView → WiredCameraTransferViewModel
|
||
→ OTGLiveTransferCoordinator → ConnectionManager (Core/CameraOTG)
|
||
→ TravelAlbumOTGPhotoSink → WiredCameraTransferPipeline → OSS 上传
|
||
CameraHistoryImportView → CameraHistoryImportViewModel → CameraDriver + OTGPhotoSink
|
||
```
|
||
|
||
- OTG 引擎详见 `Core/CameraOTG/CameraOTG.md`
|
||
- 边拍边传路径：`ConnectionManager` live shot → `OTGPhotoSink` → `pipeline.ingestDownloadedAsset(autoUpload:)` → `TravelAlbumMaterialUploader`
|
||
- 历史导入路径：批量下载落盘，不自动上传，导入完成后刷新主列表
|
||
|
||
## 业务流程
|
||
|
||
1. 创建任务：`POST .../travel-album/create`
|
||
2. 进入有线传图：USB 连接相机，边拍边传或拍后传输 / 历史导入
|
||
3. OSS 上传：复用 `OSSUploadService.uploadAlbumFile`
|
||
4. 素材登记：`POST .../travel-album/upload-material`
|
||
5. 本地照片路径以账号 + 相册 scoped 目录持久化（`CameraDownloads/<accountKey>/<albumID>/originals/xxx.JPG`）
|
||
|
||
## 有线传图性能策略
|
||
|
||
- 本地下载原图只用于上传与大图预览，按 `accountCachePrefix + albumId` 写入 `CameraDownloads/<accountKey>/<albumID>/originals/`；列表缩略图在后台下采样生成到同 scope 的 `thumbnails/`，由 Kingfisher 统一加载与缓存。
|
||
- 连拍上传进度采用节流通知和任务签名去重，下载/上传关键状态立即刷新，普通进度合并后再更新 UI；边拍边传、指定上传和勾选上传最多 3 张照片并发上传，避免滚动时高频触发整页重绘或网络资源被打满。
|
||
- `WiredCameraTransferViewModel` 缓存当前 Tab、时间侧栏和 30 分钟分组；新增/删除/切换 Tab 才重建分组，单张进度变化只替换对应行数据。
|
||
- 本地记录和物理文件都以账号上下文和相册维度隔离，状态终态、路径变化立即保存，普通进度按步长或时间间隔降频保存；删除相册会清理当前账号当前相册的 scoped 文件目录，不影响同手机号下其他账号或其他相册。
|
||
|
||
## 解耦关系
|
||
|
||
- `WiredCameraTransferPipeline` 只依赖 `CameraAssetUploadSink` 协议
|
||
- `TravelAlbumMaterialUploader` 实现 OSS + 后端登记
|
||
- `OTGLiveTransferCoordinator` 桥接 `Core/CameraOTG` 与旅拍上传管道，通过 `OTGPhotoSink` 注入存储
|
||
- 与「相册管理」（`Features/Assets`）API、Store、路由完全隔离
|
||
|
||
## 依赖模块
|
||
|
||
- `Core/CameraOTG` — USB 连接、品牌 Driver、边拍边传、PTP
|
||
- `Features/TravelAlbum/Services` — 本地存储、上传编排、OTG 协调器
|
||
- `Core/Upload` — OSS STS 上传
|
||
|
||
## 二期待补齐
|
||
|
||
- RAW 预览
|
||
- 格式 Chip 扩展 RAW / JPEG+RAW，并与 `WiredCameraTransferPipeline` 联动
|
||
- 设备存储不足时的业务侧限制（当前仅 UI 提示弹窗）
|