note/Document Converter Backend Service.md at e0f02b5d4c57c63fd2a36553547012b4b14a3276

imac-maxwell e0f02b5d4c vault backup: 2025-12-09 10:14:07

2025-12-09 10:14:07 +08:00

9.8 KiB

Raw Blame History

文档版本	V2.0 (集成文档管理)
最后更新	2025-12-09
状态	待开发
涉及端	后端 API, 异步 Worker, 对象存储, 关系型数据库

1. 项目背景与目标

1.1 背景

在构建智能题库、知识库或 RAG 应用时，文档不仅是需要被“消费”的临时素材，更是核心的数字资产。当前的痛点在于：

缺乏统一的文档仓库，原始文件容易丢失。
不同格式（PDF, Word, Excel）解析标准不一。
解析过程中的图片/公式资源难以复用。

1.2 目标

构建一个具备资产管理能力的高性能文档服务。

资产沉淀：所有上传的原始文档（PDF, DOCX, XLSX, 图片等）均永久存储，并支持去重和历史记录查询。
格式归一：将异构文档转换为标准 Markdown（供 AI 使用）或 PDF/DOCX（供人阅读）。
资源云化：自动提取文档内的图片/公式，转为 MinIO 永久链接。
样式定制：支持 Word 模板渲染。

2. 系统架构设计

系统采用 API 服务 + 关系型数据库 + 异步任务队列 的架构。

2.1 核心组件

API Gateway (FastAPI):
- 提供文档上传、查询、转换接口。
- 负责文件 Hash 计算与秒传校验。
Metadata DB (PostgreSQL):
- 存储文档元数据（文件名、大小、Hash、上传人）。
- 存储转换任务记录（Task History）。
Task Broker (Redis): 维护任务队列 (gpu-queue, cpu-queue)。
Worker Cluster (Celery):
- GPU Worker: MinerU (PDF/Image -> Markdown)。
- CPU Worker: Pandoc/Pandas/WPS-RPC (Office -> Markdown, Markdown -> Docx)。
Storage (MinIO):
- udc-raw: [永久] 存放用户上传的原始文件（按 hash/filename 存储）。
- udc-assets: [永久] 存放解析出的图片资源。
- udc-results: [永久] 存放转换结果（MD/PDF）。
- udc-templates: [永久] 样式模板。

3. 功能需求详细说明

3.1 文档管理 (DMS Core)

上传与去重：用户上传文件时，计算 SHA256。若库中已存在该 Hash，则直接返回现有的 document_id（秒传），不重复上传 MinIO。
版本/历史：同一个 document_id 可以对应多个 task_id（例如：第一次解析失败，修正 bug 后重新解析；或者分别转换为 Markdown 和 PDF）。
元数据检索：支持按文件名、上传时间、文件类型查询文档。

3.2 转换路由策略 (Conversion Strategy)

输入格式	目标格式	引擎	逻辑说明
PDF / Image	Markdown	MinerU (GPU)	强依赖 GPU，提取截图并替换链接。
DOCX	Markdown	Pandoc	提取内嵌图片，保留 LaTeX 公式。
DOC	Markdown	WPS-RPC -> PDF -> MinerU	解决老旧 MathType 公式渲染问题。
XLSX	Markdown	Pandas	纯文本拼接，忽略内嵌图。
Markdown	DOCX	Pandoc	支持 `--reference-doc` 模板定制。

3.3 资产与链接处理

图片处理：所有转换产生的图片，均重命名为 MD5 Hash，存入 udc-assets。
Markdown 清洗：输出的 Markdown 中，所有图片链接必须是 MinIO 的完整 URL（如 https://oss.example.com/udc-assets/a1b2...jpg），禁止出现相对路径。

4. 数据库设计 (PostgreSQL Schema)

使用 SQLModel 定义，支撑 DMS 能力。

4.1 Table: `documents` (文档主表)

字段	类型	说明
`id`	UUID (PK)	文档唯一标识
`file_hash`	VARCHAR(64)	SHA256，唯一索引 (Unique)
`filename`	VARCHAR	原始文件名
`file_type`	VARCHAR	扩展名 (pdf, docx)
`file_size`	BIGINT	字节数
`storage_path`	VARCHAR	MinIO 路径 (`udc-raw/hash/filename`)
`created_at`	TIMESTAMP	上传时间

4.2 Table: `conversion_tasks` (转换历史表)

字段	类型	说明
`id`	UUID (PK)	任务 ID
`document_id`	UUID (FK)	关联文档
`target_format`	VARCHAR	markdown, pdf, docx
`status`	VARCHAR	queued, processing, success, failed
`result_url`	VARCHAR	结果文件下载链接
`error_msg`	TEXT	失败原因
`created_at`	TIMESTAMP	任务创建时间
`completed_at`	TIMESTAMP	完成时间

5. API 接口定义 (RESTful)

Base URL: /api/v1

5.1 文档管理

POST /documents
- 功能：上传新文档（支持秒传）。
- Body: file (binary)
- Response: {"document_id": "...", "is_exist": true/false}
GET /documents
- 功能：分页查询文档列表。
- Query: page, size, keyword

5.2 转换服务

POST /conversions
- 功能：发起转换任务。
- Body:
  - document_id (必填): 指向已上传的文档 ID。
  - target_format (必填): markdown, docx 等。
  - template_id (选填): 样式模板 ID。
  - force_ocr (选填): Boolean。
- Response: {"task_id": "..."}

5.3 任务与结果

GET /conversions/{task_id}

功能：查询状态及结果。

Response:

{
  "status": "success",
  "result": {
     "content": "# Markdown内容...",
     "file_url": "https://minio.../res.md"
  }
}

5.4 辅助接口

POST /templates: 上传 Word 样式模板。
GET /files/{path}: 文件代理下载（用于预览）。

6. 存储策略 (MinIO)

udc-raw: 永久存储。目录结构建议：/{year}/{month}/{hash}.ext。
udc-assets: 永久存储。用于存放 OCR 截图，目录结构：/{hash_prefix}/{hash}.jpg。
udc-results: 永久存储。建议保留转换历史。
udc-temp: 1天过期。用于打包下载的临时 ZIP 文件。

7. 非功能需求 (NFR)

大文件支持: API 需支持 Stream 上传，避免内存溢出；Nginx 需放开 client_max_body_size。
GPU 调度: 通过 Celery 限制 GPU Worker 的并发数（建议 1:1 或 1:2），防止显存 OOM。
超时控制:
- PDF/OCR 任务：超时设定为 10 分钟。
- Office 转换任务：超时设定为 1 分钟。
可观测性: 关键节点（开始转换、MinerU调用、上传MinIO）需打 Log，并在 Redis 记录进度百分比。

8. 技术选型与开发规范 (Technology Stack)

本系统采用 "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 支持；配合 SQLModel 使用体验最佳。
ORM 框架	SQLModel	Latest	结合 SQLAlchemy 和 Pydantic，让数据库操作与数据验证统一，降低 AI 上下文切换成本。
对象存储	MinIO	Latest	S3 兼容协议；用于存储海量非结构化数据。

8.2 Vibe Coding 开发工作流

为确保 AI 辅助编码的准确性和可维护性，开发过程需严格遵循以下工作流：

Schema First (模型驱动)：
- 在编写业务逻辑前，必须先定义 Pydantic/SQLModel。
- 理由：Schema 是 AI 理解数据的“骨架”，骨架定义好，AI 填充“血肉”（逻辑）的准确率极高。
微提交策略 (Micro-Commits)：
- 原则：将 Git Commit 视为“游戏存档点”。
- 操作：每当 AI 完成一个独立功能（如“完成MinIO上传函数”），立即 Commit。
模块化上下文 (Modular Context)：
- 强制分包：routers/, services/, models/, tasks/。
- 理由：模块化让开发者可以只将相关文件喂给 AI，避免 Token 超限和幻觉。
环境隔离：
- 使用 uv venv 创建虚拟环境，依赖变更后运行 uv sync。

8.3 关键依赖库

PDF/OCR: magic-pdf (MinerU SDK) - 需 GPU 环境。
Word: pypandoc (Pandoc 包装), python-docx。
Excel: pandas, openpyxl。
WPS调用: pywpsrpc (如果部署在 Linux) 或 pywin32 (如果部署在 Windows 节点)。

9. 开发阶段规划

Phase 1: 核心资产管理 (DMS)

搭建 FastAPI + PostgreSQL + MinIO。
实现文件上传、SHA256 去重、元数据存储。
实现基础的 API：POST /documents, GET /documents。

Phase 2: CPU 转换能力

集成 Redis + Celery。
实现 Pandoc (Docx->MD) 和 Pandas (Excel->MD) Worker。
实现 Markdown 图片提取与 MinIO 上传逻辑。

Phase 3: GPU 转换能力与优化

部署 MinerU 环境，实现 PDF -> Markdown。
实现 WPS/Windows 节点集成（解决老旧 Doc 公式）。
完善样式模板功能。

9.8 KiB Raw Blame History Unescape Escape