From 109d7e12a2de24325049d8095459dcf1f06cde94 Mon Sep 17 00:00:00 2001 From: imac-maxwell Date: Tue, 9 Dec 2025 10:04:45 +0800 Subject: [PATCH] vault backup: 2025-12-09 10:04:45 --- app_prd/Document Converter Backend Service.md | 57 ++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/app_prd/Document Converter Backend Service.md b/app_prd/Document Converter Backend Service.md index 39c70de..e733b1a 100644 --- a/app_prd/Document Converter Backend Service.md +++ b/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 搭建。