228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
|
||
# 产品需求文档：通用文档转换与管理服务 (UDC-M)
|
||
**Universal Document Converter & Manager - Backend Service**
|
||
|
||
| 文档版本 | V2.0 |
|
||
| :------- | :------------------------------ |
|
||
| **最后更新** | 2025-12-09 |
|
||
| **状态** | 待开发 |
|
||
| **涉及端** | 后端 API, 异步 Worker, 对象存储, 关系型数据库 |
|
||
| | |
|
||
|
||
---
|
||
|
||
## 1. 项目背景与目标
|
||
### 1.1 背景
|
||
在构建智能题库、知识库或 RAG 应用时，文档不仅是需要被“消费”的临时素材，更是核心的**数字资产**。当前的痛点在于：
|
||
1. 缺乏统一的文档仓库，原始文件容易丢失。
|
||
2. 不同格式（PDF, Word, Excel）解析标准不一。
|
||
3. 解析过程中的图片/公式资源难以复用。
|
||
|
||
### 1.2 目标
|
||
构建一个**具备资产管理能力**的高性能文档服务。
|
||
* **资产沉淀**：所有上传的原始文档（PDF, DOCX, XLSX, 图片等）均永久存储，并支持去重和历史记录查询。
|
||
* **格式归一**：将异构文档转换为标准 Markdown（供 AI 使用）或 PDF/DOCX（供人阅读）。
|
||
* **资源云化**：自动提取文档内的图片/公式，转为 MinIO 永久链接。
|
||
* **样式定制**：支持 Word 模板渲染。
|
||
|
||
---
|
||
|
||
## 2. 系统架构设计
|
||
|
||
系统采用 **API 服务 + 关系型数据库 + 异步任务队列** 的架构。
|
||
|
||
### 2.1 核心组件
|
||
1. **API Gateway (FastAPI)**:
|
||
* 提供文档上传、查询、转换接口。
|
||
* 负责文件 Hash 计算与秒传校验。
|
||
2. **Metadata DB (PostgreSQL)**:
|
||
* 存储文档元数据（文件名、大小、Hash、上传人）。
|
||
* 存储转换任务记录（Task History）。
|
||
3. **Task Broker (Redis)**: 维护任务队列 (`gpu-queue`, `cpu-queue`)。
|
||
4. **Worker Cluster (Celery)**:
|
||
* **GPU Worker**: MinerU (PDF/Image -> Markdown)。
|
||
* **CPU Worker**: Pandoc/Pandas/WPS-RPC (Office -> Markdown, Markdown -> Docx)。
|
||
5. **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**:
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
1. **大文件支持**: API 需支持 Stream 上传，避免内存溢出；Nginx 需放开 `client_max_body_size`。
|
||
2. **GPU 调度**: 通过 Celery 限制 GPU Worker 的并发数（建议 1:1 或 1:2），防止显存 OOM。
|
||
3. **超时控制**:
|
||
* PDF/OCR 任务：超时设定为 10 分钟。
|
||
* Office 转换任务：超时设定为 1 分钟。
|
||
4. **可观测性**: 关键节点（开始转换、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 辅助编码的准确性和可维护性，开发过程需严格遵循以下工作流：
|
||
|
||
1. **Schema First (模型驱动)**：
|
||
* 在编写业务逻辑前，**必须先定义 Pydantic/SQLModel**。
|
||
* *理由*：Schema 是 AI 理解数据的“骨架”，骨架定义好，AI 填充“血肉”（逻辑）的准确率极高。
|
||
|
||
2. **微提交策略 (Micro-Commits)**：
|
||
* **原则**：将 Git Commit 视为“游戏存档点”。
|
||
* **操作**：每当 AI 完成一个独立功能（如“完成MinIO上传函数”），**立即 Commit**。
|
||
|
||
3. **模块化上下文 (Modular Context)**：
|
||
* **强制分包**：`routers/`, `services/`, `models/`, `tasks/`。
|
||
* *理由*：模块化让开发者可以只将相关文件喂给 AI，避免 Token 超限和幻觉。
|
||
|
||
4. **环境隔离**：
|
||
* 使用 `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 公式）。
|
||
* 完善样式模板功能。 |