这是一个为后端开发团队准备的、基于 RESTful 标准的**通用文档转换服务（Universal Document Converter, UDC）**的产品需求文档（PRD）。

---

# 产品需求文档：通用文档转换服务 (UDC)
**Universal Document Converter - Backend Service**

| 文档版本 | V1.0 |
| :--- | :--- |
| **最后更新** | 2025-12-09 |
| **状态** | 待开发 |
| **涉及端** | 后端 API, 异步 Worker, 对象存储 |

---

## 1. 项目背景与目标
### 1.1 背景
在构建智能题库、知识库或 RAG（检索增强生成）应用时，需要处理大量非结构化文档（PDF, Word, Excel, 图片等）。当前的痛点在于不同格式的解析方式不统一，且由 OCR 产生的图片资源难以直接被大模型引用。

### 1.2 目标
构建一个独立、无状态、高性能的**文档转换微服务**。
*   **输入**：支持 PDF, DOCX, DOC, XLSX, PPTX, JPG/PNG, Markdown。
*   **核心能力**：
    1.  **格式统一**：将异构文档转换为标准 Markdown（便于 LLM 处理）。
    2.  **逆向生成**：将 Markdown 转换为排版精美的 DOCX/PDF（便于人类阅读）。
    3.  **资产云化**：自动提取文档中的图片/公式截图，上传至 MinIO，并替换 Markdown 中的链接为永久 URL。
    4.  **样式定制**：支持通过 Word 模板定义输出文档的排版样式。
*   **输出**：标准 RESTful API，提供转换结果的 JSON 数据（含 MinIO 链接）或文件流。

---

## 2. 系统架构设计

系统采用 **异步任务队列** 架构，以应对 MinerU (OCR) 等高算力消耗场景。

### 2.1 核心组件
1.  **API Gateway (FastAPI)**: 接收 HTTP 请求，鉴权，文件校验，上传源文件至 MinIO `raw/` 桶，发布任务至 Redis。
2.  **Task Broker (Redis)**: 维护任务队列（区分 `gpu-queue` 和 `cpu-queue`）。
3.  **Worker Cluster (Celery)**:
    *   **GPU Worker**: 部署 MinerU (Magic-PDF)，处理 PDF/Image -> Markdown。
    *   **CPU Worker**: 部署 Pandoc, Python-Pandas, WPS-Python-RPC。处理 Docx/Excel -> Markdown 以及 Markdown -> Docx。
4.  **Storage (MinIO)**:
    *   `udc-raw`: 存放用户上传的原始文件。
    *   `udc-assets`: 存放解析出的图片资源（永久保存）。
    *   `udc-results`: 存放生成的 Markdown/Docx 结果文件（永久保存）。
    *   `udc-templates`: 存放用户上传的 Word 样式模板。

---

## 3. 功能需求详细说明

### 3.1 核心转换逻辑 (Router Strategy)

根据输入文件类型 (`input_format`) 和目标格式 (`target_format`) 自动路由。

| 输入格式 | 目标格式 | 处理引擎/逻辑 | 资源处理 | 备注 |
| :--- | :--- | :--- | :--- | :--- |
| **PDF / Image** | Markdown | **MinerU (GPU)** | 提取截图 -> 上传 MinIO -> 替换链接 | 核心场景 |
| **DOCX** | Markdown | **Pandoc** | Extract Media -> 上传 MinIO -> 替换链接 | 保留公式 Latex |
| **DOC** | Markdown | **LibreOffice/WPS** 转 PDF -> **MinerU** | 同 PDF 流程 | 解决旧版公式问题 |
| **XLSX / XLS** | Markdown | **Pandas** | 纯文本/Markdown Table 拼接 | 忽略 Excel 内嵌图 |
| **Markdown** | DOCX | **Pandoc** (+Reference Doc) | 下载网络图 -> 嵌入 Word | 支持样式模板 |
| **Markdown** | PDF | **Pandoc** -> DOCX -> **LibreOffice** | 同上 | 间接生成 |

### 3.2 资产管理 (Asset Pipeline)
任何转换过程中产生的本地图片（如 OCR 截图、Word 中的插图），必须经过以下流水线：
1.  **提取**: 解析器将图片存放在临时目录 `/tmp/task_id/images/`。
2.  **哈希重命名**: 计算文件 MD5，重命名为 `md5.jpg` (防止重复存储)。
3.  **上传**: 上传至 MinIO `udc-assets/{date}/{md5}.jpg`。
4.  **替换**: 在生成的 Markdown 文本中，将 `![](images/a.jpg)` 替换为 `![](https://minio.host/udc-assets/.../md5.jpg)`。

### 3.3 样式模板管理
*   允许用户上传 `.docx` 文件作为“参考文档” (Reference Doc)。
*   在 Markdown -> DOCX 转换时，通过 `--reference-doc` 参数应用字体、字号、页边距等样式。

---

## 4. API 接口定义 (RESTful)

**Base URL**: `/api/v1`

### 4.1 提交转换任务
*   **Endpoint**: `POST /conversions`
*   **Content-Type**: `multipart/form-data`
*   **Description**: 提交一个文件进行转换。

**Request Parameters:**

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `file` | File | 是 | 二进制文件流 |
| `target_format` | String | 是 | `markdown`, `docx`, `pdf` |
| `output_mode` | String | 否 | `url` (默认,存MinIO返回链接), `archive` (返回ZIP流) |
| `template_id` | String | 否 | 仅当 `target_format=docx` 时有效，指定使用的样式模板ID |
| `is_ocr` | Boolean | 否 | 默认 `false`。若为 `true`，即使是电子版 PDF 也强制走 OCR |
| `callback_url` | String | 否 | 任务完成后的 Webhook 回调地址 |

**Response (202 Accepted):**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "eta_seconds": 30
}
```

### 4.2 查询任务状态/结果
*   **Endpoint**: `GET /conversions/{task_id}`
*   **Description**: 轮询任务状态。

**Response (Processing):**
```json
{
  "task_id": "...",
  "status": "processing",
  "progress": 45  // 0-100
}
```

**Response (Success - URL Mode):**
```json
{
  "task_id": "...",
  "status": "success",
  "completed_at": "2025-12-09T10:00:00Z",
  "result": {
    // 如果目标是 Markdown，直接把内容返回来方便前端预览/LLM读取
    "content": "# 标题\n\n正文内容...![](https://minio.../img.jpg)", 
    // 结果文件的下载地址
    "file_url": "https://minio.host/udc-results/task_id/result.md",
    // 提取出的图片列表 (方便调试)
    "images": [
      "https://minio.host/udc-assets/2025/abc.jpg",
      "https://minio.host/udc-assets/2025/def.png"
    ]
  }
}
```

### 4.3 上传样式模板
*   **Endpoint**: `POST /templates`
*   **Content-Type**: `multipart/form-data`
*   **Description**: 上传一个 `.docx` 文件作为排版模板。

**Request:** `file` (binary), `name` (string)

**Response (201 Created):**
```json
{
  "template_id": "tpl_01HE...",
  "name": "学校试卷标准模板",
  "url": "https://minio.host/udc-templates/tpl_01HE.docx"
}
```

### 4.4 预览/下载文件 (Proxy)
*   **Endpoint**: `GET /files/{bucket}/{path}`
*   **Description**: (可选) 如果 MinIO 不对外直接暴露，通过此接口代理下载或预览文件。

---

## 5. 数据存储方案

### 5.1 Redis Key 设计
*   `task:queue:gpu`: List, 待处理的 OCR 任务。
*   `task:queue:cpu`: List, 待处理的 Office/Pandoc 任务。
*   `task:status:{task_id}`: Hash, 存储任务状态、进度、结果 JSON。过期时间 24 小时。

### 5.2 MinIO Bucket 策略
*   **udc-raw**: Lifecycle Rule = expire after 1 day.
*   **udc-assets**: Policy = ReadOnly (Public or Signed URL).
*   **udc-templates**: Policy = ReadOnly.

---


## 6. 非功能需求 (NFR)

1.  **幂等性**: 对同一文件的重复上传（MD5相同），如果参数一致，应直接返回之前的 `task_id` 或缓存结果（可选优化）。
2.  **并发控制**: MinerU 极其消耗显存。需要通过 Celery 的 `worker_concurrency` 严格限制 GPU Worker 的并发数（例如 1个 GPU 对应 1-2 个并发），防止 OOM。
3.  **超时处理**:
    *   Docx 转换超时：60秒。
    *   PDF OCR 超时：300秒（视页数而定）。
4.  **异常处理**:
    *   如果 OCR 失败，应在 Response 中返回 `error_code` 和 `error_msg`。
    *   支持“部分成功”：如果文档有 100 页，解析到 99 页挂了，应尽量返回已解析的内容。

---

## 7. 错误码定义

| Code | Message | Description |
| :--- | :--- | :--- |
| `4001` | `unsupported_format` | 不支持的文件扩展名 |
| `4002` | `template_not_found` | 指定的 Template ID 不存在 |
| `5001` | `ocr_engine_error` | MinerU 内部错误 (显存不足或模型加载失败) |
| `5002` | `conversion_timeout` | 转换超时 |
| `5003` | `storage_error` | MinIO 上传失败 |

---
## 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 搭建。
*   实现 Pandoc 转换逻辑 (Docx <-> Markdown)。
*   实现 MinIO 上传与链接替换逻辑。

### Phase 2: GPU 核心 (GPU Worker)
*   集成 MinerU SDK。
*   处理 PDF 转 Markdown 流程。
*   优化大文件上传和处理超时设置。

### Phase 3: 模板与优化
*   实现 `/templates` 接口。
*   实现 Pandoc `reference-doc` 逻辑。
*   Docker 镜像封装 (分离 CPU/GPU 镜像)。