wangdl/startup-plan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
startup-plan/技术设计/ios-file-upload-import-flow.md
WangDL 0eb5f53873 docs: iOS integration audit report + 5 CAPI docs + nginx fix 
- 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>
2026-05-25 16:55:22 +08:00

4.4 KiB
Raw Permalink Blame History

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