设计跟踪：外部云盘导入 / 同步连接件

[AptS-1547]

背景

#127 和 #128 已经调整为“管理员托管 storage backend”方向：管理员授权 OneDrive / Google Drive 账号作为统一存储池，普通用户上传的 AsterDrive blob 可以落到这些存储策略命中的后端。

但“从外部云盘导入 / 同步文件到 AsterDrive”是另一条产品线，复杂度明显更高，暂时不适合直接开成可实现 issue。这里先用 discussion 跟踪设计边界和阶段拆分，避免把它和 storage driver 混在一起。

相关 issue：

• feat(storage): 支持 OneDrive 作为管理员托管存储后端 #127：OneDrive 作为管理员托管存储后端
• feat(storage): 支持 Google Drive 作为管理员托管存储后端 #128：Google Drive 作为管理员托管存储后端

核心边界

外部云盘导入 / 同步不是 storage driver。

storage backend 回答的是：

AsterDrive 内部 blob 存到哪里？

外部导入 / 同步回答的是：

外部云盘里的文件如何授权、浏览、导入或同步到 AsterDrive？

导入后的文件仍应进入 AsterDrive 现有文件链路：

external provider file
  -> download/export stream
  -> temp staging 或未来 streaming import
  -> hash / quota / policy resolve
  -> file_blob / files
  -> 当前命中的 storage_policy 后端

也就是说，从用户 Google Drive 导入的文件可以最终落到 Local、S3、COS、Google Drive storage backend、OneDrive storage backend，取决于 AsterDrive 当前存储策略。source connector 和 target storage backend 不能混成一个模型。

为什么暂时不直接做 issue

导入和同步涉及的面太多：

• 用户级或管理员级外部连接授权
• OAuth token 存储、刷新、重新授权
• 远端目录浏览
• 单文件导入
• 文件夹批量导入
• Google Docs / Sheets / Slides、Office 文档等原生文档 export
• OneDrive / Graph driveItem、Google Drive file metadata 差异
• provider API 限流和错误映射
• 同步 binding、cursor / delta token、remote-to-local 映射
• 冲突策略
• 删除策略
• 后台任务进度、重试、取消、部分失败恢复

直接把这些塞进一个 issue，很容易变成范围失控。

和现有后台下载任务的关系

远程导入可以接近现有 offline download 后台任务，但不应该作为 offline download engine。

可以复用：

• background task dispatcher
• lease / fencing token
• task steps / progress
• retry / cancel / stale reclaim
• temp dir 清理
• TaskExecutionContext 取消检查
• workspace_storage_service::store_from_temp_internal()
• 下载完成后的 hash / size / import result 展示思路

不应该复用为：

OfflineDownloadEngine::GoogleDrive
OfflineDownloadEngine::OneDrive

offline download 的 source 是 HTTP/HTTPS URL。外部云盘导入的 source 是 provider object，需要处理 connection、token refresh、remote metadata、export format、provider-specific error mapping。它应该是兄弟任务，而不是 offline download 的下载引擎。

建议未来任务类型：

BackgroundTaskKind::RemoteImport
BackgroundTaskKind::RemoteSyncRun

建议阶段

1. External connection 基础

建立通用 external connection 模型，而不是 Google Drive / OneDrive 各自复制一套表。

可能需要：

external_connections
external_oauth_flows

连接表应能表达：

• provider kind：google_drive / onedrive / future providers
• owner scope：personal / team / admin-created 等
• account subject / email / display name
• encrypted credential
• scopes
• status
• last error
• provider metadata

2. 远端浏览

提供只读浏览能力：

• list children
• get remote item metadata
• folder / file / native document 区分
• provider error mapping
• 连接失效时反馈 reauth

这一阶段不写入 AsterDrive 文件，只验证连接和远端对象模型。

3. 单文件导入

新增 RemoteImport 后台任务。

建议 payload 形状：

{
  "provider": "google_drive",
  "connection_id": 42,
  "remote_file_id": "abc",
  "remote_revision": null,
  "export_mime": null,
  "target_folder_id": 100,
  "filename": null,
  "conflict_mode": "resolve_unique"
}

建议流程：

Waiting
Validate remote source
Resolve remote metadata
Download/export remote file
Verify source
Import file

首版建议走：

remote stream -> temp file -> store_from_temp_internal()

不要第一版就重写 streaming import pipeline。那会同时碰到 hash、quota、dedup、失败回滚和 driver 写入链路，复杂度不值。

4. 文件夹批量导入

文件夹导入不建议把整个远端树塞进 task payload。

可选方案：

• 单独 import manifest / import items 表
• 一个 manifest task 扫描远端树，再逐个导入 item
• 或先限制首版只做单文件导入，文件夹导入另开 issue

需要处理：

• 部分失败
• 重试
• 远端树很大时的分页
• 目标文件夹结构创建
• 文件名冲突

5. 单向同步

同步不是一个单纯后台任务，而是长期 binding + 多次 task run。

建议模型：

external_sync_bindings
external_sync_items / remote_file_mappings
BackgroundTaskKind::RemoteSyncRun

binding 记录：

• provider
• connection id
• remote root id
• target folder id
• direction：首版只建议 remote_to_aster
• status：active / paused / error
• cursor / delta token
• conflict policy
• delete policy
• last synced at

mapping 记录：

• remote id
• remote parent id
• remote revision / etag
• remote path snapshot
• aster file id / folder id
• last imported hash
• status

没有 mapping 表，同步会很难判断远端删除、rename/move、重复导入和本地冲突。

首版建议

如果未来要落地，我建议最小可行范围是：

1. 通用 external connection
2. Google Drive 或 OneDrive 单 provider 先行
3. 远端浏览
4. 单文件导入后台任务
5. 暂不做同步
6. 暂不做文件夹批量导入，或单独拆 issue

同步应该等单文件导入和远端浏览稳定后再做。

非目标建议

首个实现 issue 不建议包含：

• 双向同步
• 文件夹深度同步
• 多 provider 同时首发
• 复杂冲突合并
• 直接远端 stream 到最终 storage backend
• 用户前端直传 provider
• 把 external connection 塞进 storage policy

待决问题

• external connection 是用户级、团队级、管理员级都支持，还是首版只支持用户级？
• 导入任务是否允许管理员代用户创建？
• Google Docs / Sheets / Slides 首版是否要求 export？如果要求，支持哪些 export MIME？
• OneDrive / Graph 首版支持 personal 还是 work/school / SharePoint？
• 文件夹导入是第一阶段目标，还是等单文件导入完成后再拆？
• 同步删除策略默认应该是忽略、标记缺失、移动到垃圾箱，还是直接删除？
• 同步冲突检测用 last imported hash、remote revision，还是更完整的版本记录？