# iOS 文件上传与导入流程

> 版本：0.1.0 | 更新：2026-05-24

## 完整流程

```
iOS App                        API Server                    COS (腾讯云)            Worker
=======                        ==========                    ============            ======

1. 获取上传凭证
   POST /api/files/upload-url
   { filename, mimeType, sizeBytes }
   ──────────────────────────►  校验文件类型（9 种）
                                校验大小（≤20MB）
                                生成预签名 PUT URL
   ◄──────────────────────────  { uploadUrl, objectKey,
                                  bucket, region, expiresIn }

2. 直传文件到 COS
   PUT <uploadUrl>
   Content-Type: <mimeType>
   [binary file data]
   ───────────────────────────────────────────────────────►  文件存入 COS

3. 确认上传完成
   POST /api/files/complete
   { objectKey, checksum? }
   ──────────────────────────►  COS headObject 验证
                                创建 UploadedFile 记录
   ◄──────────────────────────  { id, filename, sizeBytes,
                                  mimeType }

4. 创建知识源（自动触发导入）
   POST /api/knowledge-bases/:kbId/sources
   { fileId, title, type, originalFilename, mimeType }
   ──────────────────────────►  创建 KnowledgeSource
                                自动创建 DocumentImport
                                (status=QUEUED)
   ◄──────────────────────────  { id, title, parseStatus }

5. 轮询导入状态
   GET /api/imports/:importId/status
   ──────────────────────────►  查 Redis 实时状态
                                → 回退 DB
   ◄──────────────────────────  { id, status, progress,
                                  message }

                                                                                  6. Worker 处理
                                                                                     下载文件
                                                                                     AI 解析提取
                                                                                     创建知识点
                                                                                     更新状态→COMPLETED

7. 轮询导入状态
   GET /api/imports/:importId/status
   ◄──────────────────────────  { status: "COMPLETED",
                                  progress: 100,
                                  message: "成功提取 N 个知识点" }
```

## 允许的文件类型

| 格式 | MIME |
|------|------|
| PDF | `application/pdf` |
| TXT | `text/plain` |
| Markdown | `text/markdown`, `text/x-markdown` |
| CSV | `text/csv` |
| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Excel | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| PNG | `image/png` |
| JPEG | `image/jpeg` |
| WebP | `image/webp` |

**大小上限：** 20MB

## 导入状态枚举

| 状态 | 含义 | 可操作 |
|------|------|--------|
| `QUEUED` | 排队中 | 轮询等待 |
| `CLAIMED` | 已被 Worker 认领 | 轮询等待 |
| `DOWNLOADING` | 下载中 | 轮询等待 |
| `PARSING` | 解析中 | 轮询等待 |
| `CHUNKING` | 分块中 | 轮询等待 |
| `EMBEDDING` | 向量化中 | 轮询等待 |
| `COMPLETED` | 完成 | 可查看结果 |
| `FAILED` | 失败（会重试 3 次） | 等待自动重试 |
| `FAILED_FINAL` | 最终失败 | 需重新导入 |

## iOS 实现要点

1. **直接 PUT 到 COS**：使用 URLSession 的 `uploadTask(with:fromFile:)` 或 Alamofire 的 `upload(data:to:)`
2. **预签名 URL 有过期时间**：`expiresIn` 秒内有效，拿到后立即使用
3. **支持进度回调**：大文件上传时建议显示进度条
4. **Checksum 可选但推荐**：上传完成后传 `checksum`（SHA-256）确保完整性
5. **导入轮询间隔建议**：初始 2s，逐步退避到 5s