# 产品需求文档：通用文档转换与管理服务 (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 公式）。
*   完善样式模板功能。