vault backup: 2025-12-09 10:04:45

app_prd/Document Converter Backend Service.md

@@ -173,6 +173,7 @@
 
 ---
 
+
 ## 6. 非功能需求 (NFR)
 
 1.  **幂等性**: 对同一文件的重复上传（MD5相同），如果参数一致，应直接返回之前的 `task_id` 或缓存结果（可选优化）。
@@ -197,8 +198,62 @@
 | `5003` | `storage_error` | MinIO 上传失败 |
 
 ---
+## 8. 技术选型
 
-## 8. 开发阶段规划
+本系统采用 **"AI-Native"** 的开发策略，技术选型优先考虑与大模型（LLM）的兼容性、社区文档丰富度以及类型系统的完备性，以实现极致的 **Vibe Coding** 开发体验。
+
+### 8.1 核心技术栈 (Core Stack)
+
+| 组件         | 选型             | 版本要求      | 选型理由                                                         |
+| :--------- | :------------- | :-------- | :----------------------------------------------------------- |
+| **开发语言**   | **Python**     | **3.10+** | 必须启用强类型提示 (Type Hints)；MinerU/Pandas 等核心库的原生语言；LLM 生成代码质量最高。 |
+| **Web 框架** | **FastAPI**    | Latest    | 自动生成 OpenAPI 文档；基于 Pydantic 的类型验证是 AI 理解业务逻辑的最佳桥梁。           |
+| **数据验证**   | **Pydantic**   | **V2**    | 通过定义 Class Schema 驱动开发，AI 可根据 Schema 自动补全业务代码。               |
+| **异步队列**   | **Celery**     | Latest    | 处理 PDF OCR 等长耗时任务的工业级标准；配合 Redis 使用。                         |
+| **包管理**    | **uv**         | Latest    | 极速 Python 包管理器（比 pip 快 10-100 倍），保障开发心流不被打断。                 |
+| **数据库**    | **PostgreSQL** | 14+       | 优异的 JSONB 支持（存储试题结构）；pgvector 扩展方便未来做向量检索。                   |
+| **对象存储**   | **MinIO**      | Latest    | S3 兼容协议；用于存储文档、图片及中间产物。                                      |
+| **ORM 框架** | **SQLModel**   | Latest    | 结合了 SQLAlchemy 和 Pydantic，让数据库操作与数据验证统一，降低 AI 上下文切换成本。       |
+
+### 8.2 Vibe Coding 开发工作流
+
+为确保 AI 辅助编码的准确性和可维护性，开发过程需严格遵循以下工作流：
+
+1.  **Schema First (模型驱动)**：
+    *   在编写业务逻辑前，**必须先定义 Pydantic Model**（输入/输出数据结构）。
+    *   *理由*：一旦 Schema 定义清晰，AI 能以接近 100% 的准确率自动生成 API 接口代码和数据库迁移脚本。
+
+2.  **微提交策略 (Micro-Commits)**：
+    *   **原则**：将 Git Commit 视为“游戏存档点”。
+    *   **操作**：每当 AI 完成一个独立功能函数（Function）或修复一个 Bug 并验证通过后，**立即 Commit**。
+    *   *理由*：AI 有时会产生“幻觉”改坏现有逻辑。高频提交允许开发者随时回滚到上一个“稳态”，避免代码崩坏。
+
+3.  **模块化上下文 (Modular Context)**：
+    *   **禁止**将所有代码写在 `main.py` 或单文件中。
+    *   **强制**按功能分包：`routers/`, `services/`, `models/`, `tasks/`, `core/`。
+    *   *理由*：AI 的上下文窗口有限。模块化让开发者可以只将相关文件（如 `minio_service.py`）喂给 AI，从而获得更精准的代码生成。
+
+4.  **环境隔离与极速构建**：
+    *   使用 `uv venv` 创建虚拟环境。
+    *   依赖变更后立即运行 `uv sync`。
+    *   *理由*：保持环境纯净，避免依赖冲突导致的 AI 调试死循环。
+
+### 8.3 关键依赖库
+
+*   **PDF/OCR**: `magic-pdf` (MinerU SDK) - **需 GPU 环境**。
+*   **Word**: `pypandoc` (Pandoc 包装), `python-docx` (后处理)。
+*   **Excel**: `pandas`, `openpyxl`。
+*   **LLM 交互**: `openai` (官方 SDK, 兼容 DeepSeek)。
+*   **文档生成**: `jinja2` (配合 Pandoc 做模板渲染)。
+
+### 8.4 Git 提交规范
+推荐使用 `Conventional Commits` 规范，以便 AI 自动生成 Changelog：
+*   `feat: add pdf parser service`
+*   `fix: resolve minio upload timeout`
+*   `chore: update dependencies via uv`
+*   `refactor: optimize celery task structure`
+
+## 9. 开发阶段规划
 
 ### Phase 1: 基础框架 (CPU Worker)
 *   完成 FastAPI + Redis + Celery 搭建。