FunMD_Convert/api.md

# FunMD 文档处理接口与测试说明

## 基本信息

- 基地址（内网）：`http://192.168.110.58:8000`
- 前端内网测试链接：`http://192.168.110.58:8000/ui/`
- 统一返回结构（API v2）：成功 `{"code":0,"msg":"ok","data":{...}}`，失败 `{"code":<错误码>,"msg":<错误>,"data":null}`（HTTP 状态保持 200）。
- 建议前端设置：`localStorage.setItem('app.api.base','http://192.168.110.58:8000')`
- 重要约定：当 MinIO 桶为私有时，优先使用返回的 `minio_presigned_url` 进行下载；直链 `minio_url` 可能 403。

## 接口列表

### 健康检查

- 方法：`GET /health`
- 返回：`{"status":"ok"}`
- 参考：`docling/app/server.py:99`

### 统一转换：DOCX/PDF → Markdown/HTML/JSON

- 方法：`POST /api/convert`
- 表单字段：
  - `file` 与 `source_url` 二选一
  - `export`: `markdown|html|json|doctags`，默认 `markdown`
  - `engine`（可选）：`word2markdown|docling`
  - `save`（可选）：`true|false`
  - `filename`（可选）：输出基名
- 返回：
  - 未保存：`data.content` 为文本，`data.media_type` 指示类型
  - 已保存：`data.minio_url` 与 `data.minio_presigned_url`
- 示例：
  ```bash
  # 本地 PDF 转 Markdown（不保存）
  curl -X POST http://192.168.110.58:8000/api/convert \
    -F file=@/path/to/file.pdf \
    -F export=markdown

  # 远程 URL 转 HTML（保存）
  curl -X POST http://192.168.110.58:8000/api/convert \
    -F source_url=https://example.com/page.pdf \
    -F export=html -F save=true -F filename=example
  ```
- 参考：`docling/app/server.py:2296`

### Markdown → DOCX/PDF（高级样式支持）

- 方法：`POST /md/convert`
- 输入三选一：`md_file` | `markdown_text` | `markdown_url`
- 必填：`target=docx|pdf`
- 可选（高级设置）：
  - 布局：`css_name`、`css_text`、`toc=true|false`、`header_text`、`footer_text`
  - 封面与 Logo：`cover_url|cover_file`、`logo_url|logo_file`
  - 封面文字：`product_name|document_name|product_version|document_version`
  - 版权：`copyright_text`
  - 保存：`save=true|false`
- 行为说明：
  - `save=false` 时，封面/Logo 会内嵌为 `data:`，避免私有桶 403；`save=true` 时返回 MinIO 链接。
- 例：
  ```bash
  # 文本转 PDF（封面、Logo、目录、页眉页脚）
  curl -X POST http://192.168.110.58:8000/md/convert \
    -F markdown_text='# 标题\n\n内容' \
    -F target=pdf -F toc=true \
    -F header_text='Internal' -F footer_text='Confidential' \
    -F product_name='CMS' -F document_name='周报' \
    -F product_version='v1.0' -F document_version='2025-W48' \
    -F cover_file=@/path/to/cover.png -F logo_file=@/path/to/logo.png

  # 文件转 DOCX（保存到 MinIO）
  curl -X POST http://192.168.110.58:8000/md/convert \
    -F md_file=@/path/to/doc.md \
    -F target=docx -F save=true -F filename='周报'
  ```
- 参考：`docling/app/server.py:1198`

### 本地文件夹批量处理（重写 MD 资源并上传）

- 方法：`POST /md/convert-folder`
- 表单字段：
  - `folder_path`（必填）：本地文件夹绝对路径（后端机器）
  - `prefix`（可选）：MinIO 前缀（如 `assets`）
- 返回：`{ ok, count, files: [{ source, minio_url, minio_presigned_url, asset_ok, asset_fail, mappings }] }`
- 示例：
  ```bash
  curl -X POST http://192.168.110.58:8000/md/convert-folder \
    -F folder_path='/Users/fanyang/Desktop/Others/CMS/达梦数据-各类示范文档/数+产品手册-MD源文件/DMDRS_Build_Manual_DM8' \
    -F prefix='assets'
  ```
- 参考：`docling/app/server.py:2075`

### 上传压缩包批量处理

- 方法：`POST /api/upload-archive`
- 表单字段：`file`（zip/tar.gz/tgz），`prefix`（可选）
- 返回：`{ code, msg, data: { count, files: [{ source, minio_url, minio_presigned_url, mappings }] } }`
- 示例：
  ```bash
  curl -X POST http://192.168.110.58:8000/api/upload-archive \
    -F file=@/path/to/archive.zip -F prefix='assets'
  ```
- 参考：`docling/app/server.py:2571`

### 归档分阶段处理

- 暂存上传：`POST /api/archive/stage`，返回 `{ id, name, size }`
- 批量处理：`POST /api/archive/process`，字段：`id`（必填）、`prefix`（可选）、`versionId`（可选）
- 说明：HTML 文件按“两阶段重写”策略处理（HTML 资源上传到 MinIO 并重写 → 转换为 Markdown → 再次重写 MD 中的资源与链接），支持 `data:image/*;base64,` 图片上传并替换为 MinIO 链接
- 参考：`docling/app/server.py:2714,2728`

### MinIO 配置与测试

- 设置配置：`POST /config/minio`
  - 字段：`endpoint`、`public`、`access`、`secret`、`bucket`、`secure=true|false`、`prefix`、`store_final=true|false`、`public_read=true|false`
  - 示例：
    ```bash
    curl -X POST http://192.168.110.58:8000/config/minio \
      -F endpoint='127.0.0.1:9000' -F public='127.0.0.1:9000' \
      -F access='minioadmin' -F secret='minioadmin123' \
      -F bucket='doctest' -F secure=false -F prefix='assets' \
      -F store_final=true -F public_read=true
    ```
  - 注意：请使用 MinIO API 端口 `9000`（而非 `9001` 控制台端口）；若填写控制台地址或 `:9001` 将被拒绝
  - 参考：`docling/app/server.py:488`

- 连通测试并应用策略：`POST /config/minio/test`
  - 同上字段，额外可携带 `create_if_missing=true`
  - 返回：`{ ok, connected, bucket_exists, created, error?, hint? }`
  - 参考：`docling/app/server.py:577`

- 获取配置快照：`GET /config`（参考：`docling/app/server.py:1047`）
- 配置档案：`GET /config/profiles`、`POST /config/save_profile`、`GET /config/load_profile?name=xxx`（参考：`docling/app/server.py:1058,1068,1084`）

### 系统时间检查（MinIO 时间偏差排查）

- 方法：`GET /system/time/check`
- 查询参数：`endpoint`、`public`、`secure`（可选，不传则使用当前运行时配置）
- 返回：`{ ok, server_time, local_time, diff_sec, hint }`
- 参考：`docling/app/server.py:720`

### 资源映射与代理下载（可选）

- Linkmap：`GET /config/linkmap`、`POST /config/linkmap`（参考：`docling/app/server.py:1583,1587`）
- 代理下载：`POST /proxy/download`（参考：`docling/app/server.py:1635`）

## 前端集成要点

- 基地址读取：`frontend/src/services/api.ts:56-64`（localStorage `app.api.base` 优先，其次 `VITE_API_BASE_URL`）
- 提供的方法：
  - `convertDoc` → `/api/convert`（`frontend/src/services/api.ts:96`）
  - `uploadArchive` → `/api/upload-archive`（`frontend/src/services/api.ts:104`）
  - `stageArchive` → `/api/archive/stage`（`frontend/src/services/api.ts:185`）
  - `processArchive` → `/api/archive/process`（`frontend/src/services/api.ts:193`）
  - `convertMd` → `/md/convert`（`frontend/src/services/api.ts:157`）
  - `convertFolder` → `/md/convert-folder`（`frontend/src/services/api.ts:164`）
  - MinIO 配置：`setMinioConfig`（`frontend/src/services/api.ts:112`）、`testMinioConfig`（`frontend/src/services/api.ts:128`）、`createBucket`（`frontend/src/services/api.ts:145`）
- 私有桶注意：直链可能 403，前端应优先使用 `minio_presigned_url`（UI 已支持）。

## 测试说明（覆盖所有能力）

### 1. 健康检查

- 请求：`GET /health`
- 断言：返回 `{"status":"ok"}`。

### 2. DOCX/PDF → Markdown/HTML/JSON

- 用例 A：本地 PDF → Markdown（不保存）
  - `POST /api/convert`，`file=@/path/to/file.pdf`，`export=markdown`
  - 断言：`code=0`，`data.content` 包含 Markdown 文本、`data.media_type` 为 `text/markdown; charset=utf-8`。

- 用例 B：远程 PDF → HTML（保存）
  - `POST /api/convert`，`source_url=http(s)://...pdf`，`export=html`，`save=true`，`filename=example`
  - 断言：返回 `minio_url` 与 `minio_presigned_url` 可访问；中文路径正确编码。

### 3. Markdown → DOCX/PDF

- 用例 C：文本 → PDF（高级参数，`save=false`）
  - 字段：`markdown_text`、`target=pdf`、`toc=true`、`header_text`、`footer_text`、封面/Logo 文件与封面文字
  - 断言：返回 PDF 二进制可打开；封面与 Logo 可见。日志中的 `word-break: break-word` 警告不影响生成。

- 用例 D：文件 → DOCX（`save=true`）
  - 字段：`md_file`、`target=docx`、`save=true`
  - 断言：`minio_presigned_url` 可下载；中文文件名编码正确。

- 用例 E：URL → PDF
  - 字段：`markdown_url=http(s)://...md`、`target=pdf`
  - 断言：生成成功；封面与 Logo 正常加载（若私有桶则走签名链接）。

### 4. 批量处理

- 用例 F：本地文件夹批量重写并上传
  - `POST /md/convert-folder`，`folder_path='/Users/fanyang/Desktop/Others/CMS/达梦数据-各类示范文档/数+产品手册-MD源文件/DMDRS_Build_Manual_DM8'`、`prefix='assets'`
  - 断言：`count>0`；各文件 `asset_ok/asset_fail` 合理；`minio_presigned_url` 可下载。

- 用例 G：上传压缩包批量处理
  - `POST /api/upload-archive`，`file=@/path/to/archive.zip`、`prefix='assets'`
  - 断言：`data.count` 正确；各文件链接可用。

### 5. MinIO 配置与策略

- 用例 H：设置配置
  - `POST /config/minio`（真实参数）
  - 断言：返回 `ok:true`。

- 用例 I：连通测试并应用策略
  - `POST /config/minio/test`，`public_read=true|false`，`create_if_missing=true`
  - 断言：返回连通状态；私有桶下使用 `minio_presigned_url` 可访问。

### 6. 资源映射与代理（可选）

- 用例 J：`GET/POST /config/linkmap` 设置静态映射；`POST /proxy/download` 验证代理下载功能。

## 兼容性与注意事项

- 路径编码：所有返回的对象路径已进行编码，适配中文、空格、括号等字符。
- 私有桶：直链可能 403；前端测试请使用 `minio_presigned_url`。
- 样式警告：WeasyPrint 不支持 `word-break: break-word`，建议 `overflow-wrap: break-word` 或 `word-break: break-all`。
 - 安全解压：ZIP/TAR 采用路径穿越防护，解压目标限定在工作目录内；同时自动修复常见文件名乱码编码
 - HTML 资产重写：批量处理对 HTML 的资源链接进行两阶段重写并上传至 MinIO；内嵌 Base64 图片自动上传并替换为可访问链接
 - 控制台端口限制：`/config/minio` 与 `/config/minio/test` 会拒绝 `:9001` 或带 `/browser`、`/minio` 的控制台地址；请使用 `9000` API 端口

## 本地运行（后端与前端）

- 后端（FastAPI，端口 `8000`）：
  - `cd /Users/fanyang/Desktop/FunMD_Convert/docling`
  - `PYTHONPATH=. python -m uvicorn app.server:app --host 127.0.0.1 --port 8000`
- 前端（Vite）：
  - `cd /Users/fanyang/Desktop/FunMD_Convert/frontend`
  - `npm install`
  - `VITE_API_BASE_URL=http://127.0.0.1:8000 npm run dev`
- 访问：
  - 后端 UI 首页：`http://127.0.0.1:8000/ui/`
  - 前端开发页面：Vite 控制台输出的本地地址（通常为 `http://127.0.0.1:5173/`）

### 前端配置 API Base（避免代理空响应）

- 打开前端页面右上角“数据库配置”弹窗，在“接口地址”一栏填写：`http://127.0.0.1:8000`，点击“保存配置”。
- 保存后，前端会直连后端 `8000` 端口，不再通过 Vite 代理，避免长耗时请求在 `5173` 上出现 `ERR_EMPTY_RESPONSE`。