feat(api): support self-hosted MinerU 4.x via the V1 API - #209

Relates to #208（维护者回复欢迎先提交自部署 MinerU 的 PR）

背景 / Why

SAG 目前只能接 302 和 mineru.net 云端 MinerU：_assert_public_host 会拒绝 loopback/内网地址，无法对接本机或局域网部署的 MinerU。MinerU 4.0 把 HTTP 服务重写为 V1 API（/v1/uploads、/v1/parse/jobs、/v1/files，移除了 /file_parse、/tasks），结果 zip 中的 Markdown 也改名为 markdown.md。

SAG can only use cloud MinerU today; self-hosted MinerU 4.x (V1 API) is blocked by the private-address check and the new protocol/zip layout.

修改 / What

• 新增 mineru_provider="self_hosted"（parsing/mineru_v1.py），按 MinerU 4.0 官方 docs/usage/http_api.md 与 scripts/http_api_example.sh 实现 V1 流程：
  POST /v1/uploads（带 sha256，命中去重时跳过上传）→ PUT upload_url → POST /v1/uploads/{id}/complete → POST /v1/parse/jobs（output_formats=["zip"]、ocr_mode、可选 tier）→ 轮询 GET /v1/parse/jobs/{id} 至 completed/partial/failed/canceled → GET /v1/files/{zip_file_id}/content 下载 zip。
• 复用现有解析状态：file_id/job_id 写入断点状态，暂停（should_pause）与续跑沿用原逻辑；V1 任务状态只在服务进程内，服务重启后 job 404 时自动重新上传提交一次。失败、超时、鉴权错误都映射为现有错误类型，因此继续走 MarkItDown 降级。
• 安全边界 / Security：
  • 新增 mineru_allow_private_base_url（默认 false）。只有显式开启后，用户配置的 Base URL 才允许解析到本机/内网；未开启时给出明确的配置提示。
  • 结果下载（含重定向）必须与 Base URL 同源（scheme + host + 端口），否则拒绝。
  • 上传地址同源时才带 API Key；跨源上传地址（如对象存储签名 URL）不带 Key，并继续走原有公网地址校验。其余 SSRF 检查不变。
• _markdown_from_zip 同时识别 markdown.md。
• mineru_tier（可选，留空用服务端默认档位）；自部署服务可匿名，mineru_configured 对 self_hosted 不再要求 API Key。
• settings_service._normalize_overrides：只在持久化配置里有 MinerU 地址时才推断服务商。此前即使从未保存过 MinerU 配置，启动时也会把 SAG_MINERU_PROVIDER 重置为 302（official 同样受影响）。
• compose.yaml、.env.example 透传并说明 SAG_MINERU_PROVIDER / SAG_MINERU_TIER / SAG_MINERU_ALLOW_PRIVATE_BASE_URL。
• 仅后端，不新增依赖（纯 httpx）；设置页会在后续 PR 中补充。Backend only, no new dependencies; the settings page will follow in a separate PR.

验证 / How verified

真实 MinerU 4.0.10 端到端（本机 mineru-kit api-server --tier flash --api-key ...，CPU，SAG 客户端直连 http://127.0.0.1:18000）：

1) 未开启 allow_private：ConfigurationError：MinerU 自部署 Base URL 指向本机或内网地址；确认可信后请设置 SAG_MINERU_ALLOW_PRIVATE_BASE_URL=true
2) 开启后：markdown = 'Self hosted MinerU marker\n'；状态依次记录 file_id → job_id → running → done
3) prepare_document：provider=mineru，缓存 e2e2.pdf.parsed.mineru-v1-flash-auto.md
4) 错误 API Key：服务端 401 → 降级 markitdown，fallback_error = "MinerU 创建上传鉴权失败，请检查 MinerU API Key"
5) 断点中的 job_id 已失效（模拟服务重启）：GET job 404 → 重新上传并提交 → 成功
6) 同一文件再次解析：POST /v1/uploads 直接返回 completed（sha256 去重），跳过 PUT → 成功

服务端日志中的请求序列：POST /v1/uploads 200 → PUT /v1/uploads/{id}/content 200 → POST .../complete 200 → POST /v1/parse/jobs 202 → GET /v1/parse/jobs/{id} 200 ×N → GET /v1/files/{id}/content 200；真实 zip 内容为 markdown.md、middle_json.json、structured_content.json、model_output.json。

单元测试：新增 tests/test_mineru_self_hosted.py（httpx MockTransport，响应结构按 4.0.10 实际返回编写），覆盖：完整流程与请求体、sha256 去重、匿名访问、内网地址开关（关闭拒绝 / 开启放行 / 公网无需开关）、下载重定向同源校验、跨源上传不带 Key 且内网跨源被拒、failed/canceled/partial/缺 zip/未知状态、轮询超时保留 job、请求超时与 401、断点续跑和服务重启后重提、暂停中断、prepare_document 降级 MarkItDown、env provider 不被重置、markdown.md 优先。

cd apps/api
ruff check（CI 同款后端检查）           -> All checks passed!
python -m pytest -q                     -> 734 passed, 1 skipped
CI 中的 node 脚本测试（仓库根目录）     -> pass 28, fail 0