99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
|
# 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
|