WangDL
0eb5f53873
- iOS integration readiness audit (blocker list, module map, deployment check) - CAPI contract for iOS (15 modules, 80+ endpoints) - CAPI error codes and status enums - iOS auth flow, file upload import flow, learning review flow - Web product page nginx fix (reenable longde.cloud) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
|