kplam/QMDSearch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b5342b32a45ad95f166ac985d81f349040316cd7
QMDSearch/.trae/specs/add-file-upload-support/tasks.md
T
kplam dce9e31bde feat: 新增多格式文件上传入库与认证体系 
- 新增 JWT 认证模块，支持登录/注册/用户管理
- 新增文件上传接口，支持 .txt/.md/.html/.pdf/.docx 等格式解析入库
- 新增检索结果 AI 总结功能
- 新增文本去重缓存机制
- 新增全局认证夹具简化测试
- 新增配置项与环境变量支持
- 完善文档与测试覆盖
2026-07-30 10:30:15 +08:00

3.0 KiB
Raw Blame History

Tasks

已完成（前期工作）

  • Task 1: 新增 app/core/file_parser.py 多格式文本提取
    • SubTask 1.1: 实现 _parse_text/_parse_html/_parse_pdf/_parse_docx 解析器与 _PARSERS 注册表
    • SubTask 1.2: 实现 parse_file(filename, content) 入口与异常包装（不支持/解析失败）
    • SubTask 1.3: 实现 supported_extensions() 辅助函数
  • Task 2: 单元测试 tests/test_file_parser.py（13 例覆盖各格式 + 异常路径）
  • Task 3: 新增 POST /api/v1/documents/upload 端点 + 测试
    • SubTask 3.1: 在 app/api/v1/document.py 增加 upload 端点（扩展名/大小/解析/落盘/metadata/默认 title-source/提交 IngestTaskManager）
    • SubTask 3.2: 增加 _allowed_extensions() 辅助函数
    • SubTask 3.3: 在 app/config.py 增加 upload_dir / upload_max_size_mb / upload_allowed_extensions
    • SubTask 3.4: tests/test_document_upload_api.py 10 例测试（合法上传/不支持扩展名/超大/空文本/损坏 PDF/落盘失败降级/metadata JSON/默认 title/source）
    • SubTask 3.5: pyproject.toml dependencies 增加 python-multipart>=0.0.20 / pypdf>=5.1.0 / python-docx>=1.1.2

剩余任务

  • Task 4: 应用启动初始化 + 环境变量模板
    • SubTask 4.1: 在 app/main.py lifespan 的 ensure_default_admin 之后增加 Path(settings.upload_dir).mkdir(parents=True, exist_ok=True)，异常仅 warning 不阻塞启动
    • SubTask 4.2: 在 .env.example 末尾增加 --- 文件上传 --- 段落，包含 UPLOAD_DIR / UPLOAD_MAX_SIZE_MB / UPLOAD_ALLOWED_EXTENSIONS 三项
  • Task 5: 管理后台 admin.html 文件上传 UI
    • SubTask 5.1: 在 #section-ingest 现有 #ingest-form 之后新增「文件上传」子表单，含 file input（accept=".txt,.md,.html,.htm,.pdf,.docx"）+ 可选 title + 可选 source + 提交按钮 #btn-upload-submit
    • SubTask 5.2: 新增 #upload-form submit 监听：构造 FormData（file/title/source）→ 调用 /api/v1/documents/upload → 复用 renderIngestHeader + startIngestPolling 展示任务进度
    • SubTask 5.3: 提交期间禁用 #btn-upload-submit 显示「上传中…」，请求完成（成功/失败）后恢复按钮文案
  • Task 6: 文档同步 CLAUDE.md
    • SubTask 6.1: API 清单表格在 POST /api/v1/documents 行之后增加 POST /api/v1/documents/upload 行（说明：multipart 文件上传入库，202 异步）
    • SubTask 6.2: 「文档入库与三级总结」节增加简述：文件上传通道（multipart 入口→parse_file 提取→复用现有 IngestTaskManager→同一任务查询端点）
  • Task 7: 全量 pytest 验证回归
    • SubTask 7.1: 执行 uv run pytest 全绿（289 passed，含新增 23 测试 + 既有 266 测试套件）

Task Dependencies

  • Task 4 独立于 Task 5/6，可并行
  • Task 5（admin.html UI）依赖 Task 3 已完成（端点已存在）✓
  • Task 6 独立
  • Task 7 依赖 Task 4/5/6 全部完成
Reference in New Issue View Git Blame Copy Permalink