Merge pull request #91 from dofliu/claude/pptx-native-augment

feat(pptx): 上傳 PPTX 原檔就地補圖 — 原文字保持可編輯

Author: dofliu

core/pptx_augment.py

@@ -0,0 +1,213 @@
+"""core/pptx_augment.py — 在「原始 .pptx」上就地補圖 (原文字保持可編輯)。
+
+定位
+----
+slides_pdf 補圖是把每頁 PDF 渲成 PNG, 原頁文字因此變成圖、不可再編輯。若使用者
+手上是 .pptx 原檔, 更好的作法是直接在原檔上動手:
+
+  1. pptx → pdf → 逐頁 PNG (僅供分析, 用 LibreOffice + PyMuPDF)。
+  2. 偵測缺圖頁 + 每頁空白區 (複用 core.slide_image_gen)。
+  3. 為缺圖頁生 AI 配圖 (複用 generate_slide_image; prompt 取自該頁文字)。
+  4. 打開「原始 .pptx」, 把配圖**加進**該頁空白區 — 原本的文字方塊 / 圖形全部
+     原封不動, 仍可在 PowerPoint 內編輯。
+
+如此匯出的新簡報文字可改、圖在空白處, 解決「整頁變成一張圖」的問題。
+
+依賴
+----
+- python-pptx (匯入/匯出 .pptx)
+- LibreOffice (soffice) — pptx→pdf 渲染; 缺它則 render_pptx_to_pdf raise。
+- PyMuPDF (fitz) — pdf→png。
+mock=True 走 PIL 佔位圖 (不打 Gemini), 但仍需 LibreOffice 渲染原頁 (除非 caller
+直接給 page_pngs)。
+"""
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def render_pptx_to_pdf(src_pptx: str | Path, out_dir: str | Path, *, timeout: int = 180) -> Path:
+    """用 LibreOffice headless 把 .pptx 轉成 .pdf, 回傳 pdf 路徑。"""
+    soffice = shutil.which("soffice") or shutil.which("libreoffice")
+    if not soffice:
+        raise RuntimeError(
+            "找不到 LibreOffice (soffice), 無法把 PPTX 轉成 PDF 做分析。"
+            "請安裝 libreoffice-impress。"
+        )
+    src_pptx = Path(src_pptx)
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    # 用獨立 profile 避免併發鎖
+    profile = (out_dir / "_lo_profile").resolve().as_uri()
+    cmd = [
+        soffice, "--headless", f"-env:UserInstallation={profile}",
+        "--convert-to", "pdf", "--outdir", str(out_dir), str(src_pptx),
+    ]
+    res = subprocess.run(cmd, capture_output=True, timeout=timeout)
+    pdf = out_dir / (src_pptx.stem + ".pdf")
+    if res.returncode != 0 or not pdf.exists():
+        raise RuntimeError(
+            f"LibreOffice 轉檔失敗 (code {res.returncode}): "
+            f"{res.stderr.decode('utf-8', 'replace')[:300]}"
+        )
+    return pdf
+
+
+def _render_pdf_pages(pdf: Path, out_dir: Path, *, zoom: float = 2.0) -> list[Path]:
+    import fitz
+    out_dir.mkdir(parents=True, exist_ok=True)
+    doc = fitz.open(pdf)
+    paths = []
+    try:
+        for i, page in enumerate(doc, start=1):
+            p = out_dir / f"p{i:03d}.png"
+            page.get_pixmap(matrix=fitz.Matrix(zoom, zoom)).save(str(p))
+            paths.append(p)
+    finally:
+        doc.close()
+    return paths
+
+
+def extract_pptx_slide_texts(prs) -> list[tuple[str, str]]:
+    """每張投影片 → (title, body) 文字, 供生圖 prompt 用。"""
+    out = []
+    for slide in prs.slides:
+        lines = []
+        for sh in slide.shapes:
+            if sh.has_text_frame:
+                t = sh.text_frame.text.strip()
+                if t:
+                    lines.append(t)
+        title = lines[0].split("\n")[0][:60] if lines else ""
+        body = " ".join(lines)[:240]
+        out.append((title, body))
+    return out
+
+
+def insert_images_into_pptx(
+    src_pptx: str | Path,
+    out_pptx: str | Path,
+    items: list[tuple[int, Path, tuple | list | None]],
+) -> int:
+    """在 src_pptx 上插圖後另存 out_pptx (原文字/圖形不動)。回傳插入張數。
+
+    items: list of (slide_index_0based, image_path, placement)。placement 為正規化
+    (x,y,w,h)∈[0,1]; None → 右下角浮貼。圖等比 fit 進框 (置中, 不變形)。
+    """
+    from pptx import Presentation
+    from pptx.util import Emu
+
+    prs = Presentation(str(src_pptx))
+    SW, SH = prs.slide_width, prs.slide_height
+    slides = list(prs.slides)
+    n = 0
+    for idx, img, placement in items:
+        if idx < 0 or idx >= len(slides):
+            continue
+        if not Path(img).exists():
+            continue
+        if placement:
+            nx, ny, nw, nh = placement
+        else:
+            nx, ny, nw, nh = 0.68, 0.62, 0.30, 0.30
+        inner = 0.06
+        bx = (nx + nw * inner) * SW
+        by = (ny + nh * inner) * SH
+        bw = nw * (1 - 2 * inner) * SW
+        bh = nh * (1 - 2 * inner) * SH
+        # 用實際圖比例等比 fit (預設配圖近 1:1, 仍精確處理)
+        try:
+            from PIL import Image
+            with Image.open(img) as im:
+                iw, ih = im.size
+        except Exception:
+            iw, ih = 1, 1
+        scale = min(bw / iw, bh / ih)
+        w, h = iw * scale, ih * scale
+        left = Emu(int(bx + (bw - w) / 2))
+        top = Emu(int(by + (bh - h) / 2))
+        slides[idx].shapes.add_picture(str(img), left, top, Emu(int(w)), Emu(int(h)))
+        n += 1
+    Path(out_pptx).parent.mkdir(parents=True, exist_ok=True)
+    prs.save(str(out_pptx))
+    return n
+
+
+def augment_pptx(
+    src_pptx: str | Path,
+    out_pptx: str | Path,
+    *,
+    work_dir: str | Path,
+    only_missing: bool = True,
+    mock: bool = False,
+    api_key: str | None = None,
+    max_images: int | None = None,
+    page_pngs: list[Path] | None = None,
+) -> dict:
+    """在原始 .pptx 上為缺圖頁就地補圖, 另存 out_pptx。回傳 summary。
+
+    page_pngs 給定時跳過 LibreOffice 渲染 (測試 / caller 已有逐頁圖時用)。
+    """
+    from pptx import Presentation
+    from core import slide_image_gen as sig
+    from core.diagram_image_gen import _build_diagram_prompt  # noqa: F401 (確保模組可用)
+
+    src_pptx = Path(src_pptx)
+    work_dir = Path(work_dir)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    fig_dir = work_dir / "figures"
+    fig_dir.mkdir(exist_ok=True)
+
+    # 1) 逐頁 PNG (供分析) + PDF (供缺圖偵測)
+    if page_pngs is None:
+        pdf = render_pptx_to_pdf(src_pptx, work_dir)
+        page_pngs = _render_pdf_pages(pdf, work_dir / "pages")
+        imageless = set(sig.detect_imageless_pages(pdf))
+    else:
+        page_pngs = [Path(p) for p in page_pngs]
+        # 無 pdf 時退化: 只要 only_missing 仍想要偵測, 改用每頁 PNG 的內容判斷
+        imageless = set(range(1, len(page_pngs) + 1))
+
+    # 2) 每頁文字 (生圖 prompt)
+    prs = Presentation(str(src_pptx))
+    texts = extract_pptx_slide_texts(prs)
+    deck_title = src_pptx.stem
+
+    # 3) 逐頁: 缺圖才生圖 + 算空白框
+    items: list[tuple[int, Path, tuple | None]] = []
+    generated = 0
+    for i, png in enumerate(page_pngs, start=1):  # i = 1-based 頁碼
+        if max_images is not None and generated >= max_images:
+            break
+        if only_missing and i not in imageless:
+            continue
+        title, body = texts[i - 1] if i - 1 < len(texts) else ("", "")
+        slide = {"id": f"p{i:03d}", "title": title or f"投影片 {i}", "narration": body}
+        ai_path = fig_dir / f"ai_p{i:03d}.png"
+        ok, err = sig.generate_slide_image(
+            slide, ai_path, deck_title=deck_title, api_key=api_key, mock=mock,
+        )
+        if not ok:
+            logger.warning("PPTX 補圖跳過 p%d: %s", i, err)
+            continue
+        placement = sig.find_empty_region(png)
+        items.append((i - 1, ai_path, placement))  # 0-based slide index
+        generated += 1
+
+    # 4) 在原檔上插圖另存
+    inserted = insert_images_into_pptx(src_pptx, out_pptx, items)
+    summary = {
+        "pages": len(page_pngs),
+        "imageless": sorted(imageless) if imageless else [],
+        "generated": generated,
+        "inserted": inserted,
+        "mock": mock,
+    }
+    logger.info("PPTX 就地補圖完成: %s", summary)
+    return summary

server/main.py

@@ -41,6 +41,7 @@
 from .routes import themes as themes_routes
 from .routes import uploads as uploads_routes
 from .routes import uploads_html as uploads_html_routes
+from .routes import uploads_pptx as uploads_pptx_routes
 from .routes import voices as voices_routes
 from .routes import youtube as youtube_routes
 
@@ -149,6 +150,7 @@ def create_app() -> FastAPI:
     app.include_router(slides_routes.router)
     app.include_router(uploads_routes.router)
     app.include_router(uploads_html_routes.router)  # HTML 動畫 → MP4 → 接既有上傳
+    app.include_router(uploads_pptx_routes.router)  # PPTX 原檔就地補圖 (文字可編輯)
     app.include_router(voices_routes.router)
     app.include_router(library_routes.router)
     app.include_router(editor_routes.router)

server/routes/uploads_pptx.py

@@ -0,0 +1,122 @@
+"""POST /upload/pptx — 上傳 .pptx 原檔, 為缺圖頁就地補圖 (原文字可編輯)。
+
+跟 slides_pdf 補圖的差別: slides_pdf 把每頁渲成圖, 原文字變不可編輯。這條走
+core.pptx_augment, 直接在原始 .pptx 上把 AI 配圖加進缺圖頁的空白區, 原本的文字
+方塊全部保留可編輯。產出的 <stem>_augmented.pptx 落在 job artifacts/ 供下載。
+
+獨立背景 task (PENDING → RENDERING → DONE/FAILED), 不經 deck/ingest pipeline。
+需要 LibreOffice (pptx→pdf 分析) — 缺它則 job FAILED 並說明。
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile, status
+
+from ..jobs import JobStore, get_default_store
+from ..ratelimit import rate_limit
+from ..schemas import (
+    CreateJobRequest, CreateJobResponse, JobOptions, JobSource, JobState, SourceType,
+)
+from .uploads import MAX_UPLOAD_SIZE, _sanitize_filename, _unique_target_path
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/upload", tags=["uploads"])
+
+_PPTX_EXTS = {".pptx"}
+
+
+async def _render_pptx_job(
+    store: JobStore, job_id: str, *, src_pptx: Path, out_pptx: Path,
+    only_missing: bool, mock: bool,
+) -> None:
+    store.update(job_id, state=JobState.RENDERING)
+    try:
+        from core.pptx_augment import augment_pptx
+        summary = await asyncio.to_thread(
+            augment_pptx, src_pptx, out_pptx,
+            work_dir=store.job_dir(job_id) / "work",
+            only_missing=only_missing, mock=mock,
+        )
+        logger.info("PPTX 補圖 job %s: %s", job_id, summary)
+    except Exception as e:  # noqa: BLE001
+        logger.exception("PPTX 補圖失敗 (job=%s)", job_id)
+        store.update(job_id, state=JobState.FAILED, error=f"PPTX 補圖失敗: {e}")
+        return
+    store.refresh_artifacts(job_id)
+    store.update(job_id, state=JobState.DONE)
+
+
+@router.post(
+    "/pptx",
+    response_model=CreateJobResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(rate_limit)],
+)
+async def upload_pptx(
+    request: Request,
+    file: UploadFile = File(..., description=".pptx 原檔"),
+    only_missing: bool = Form(True, description="True 只補偵測到的缺圖頁; False 每頁都生"),
+    options_json: str = Form("{}", description="JobOptions JSON (目前只用 mock)"),
+    project_id: str = Form("", description="可選: 歸屬的 Project"),
+    store: JobStore = Depends(get_default_store),
+) -> CreateJobResponse:
+    """收 .pptx, 背景就地補圖, 產出可編輯的 <stem>_augmented.pptx 供下載。"""
+    if not file.filename or Path(file.filename).suffix.lower() not in _PPTX_EXTS:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "只接受 .pptx 檔")
+
+    content_length = request.headers.get("content-length")
+    if content_length and content_length.isdigit() and int(content_length) > MAX_UPLOAD_SIZE:
+        raise HTTPException(
+            status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            f"檔案過大, 超過上限 {MAX_UPLOAD_SIZE // (1024 * 1024)} MB",
+        )
+    contents = await file.read()
+    if not contents:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "上傳的 PPTX 是空的")
+    if len(contents) > MAX_UPLOAD_SIZE:
+        raise HTTPException(
+            status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            f"檔案過大, 超過上限 {MAX_UPLOAD_SIZE // (1024 * 1024)} MB",
+        )
+
+    try:
+        opts = json.loads(options_json) if options_json else {}
+        if not isinstance(opts, dict):
+            raise ValueError("options_json 不是 JSON 物件")
+    except Exception as e:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, f"options_json 解析失敗: {e}")
+    options = JobOptions(mock=bool(opts.get("mock", False)), require_review=False)
+
+    rec = store.create(CreateJobRequest(
+        source_type=SourceType.PPTX, source=JobSource(), options=options,
+    ))
+
+    # 原檔落地到 jobs/<id>/source/
+    src_dir = store.job_dir(rec.id) / "source"
+    src_dir.mkdir(parents=True, exist_ok=True)
+    src_pptx = _unique_target_path(src_dir, _sanitize_filename(file.filename))
+    src_pptx.write_bytes(contents)
+    rec = store.update(rec.id, source=JobSource(path=str(src_pptx.resolve())))
+
+    if project_id:
+        from core.project import ProjectNotFoundError
+        from .projects import get_default_project_store
+        try:
+            get_default_project_store().add_job(project_id, rec.id)
+        except ProjectNotFoundError as e:
+            store.delete(rec.id)
+            raise HTTPException(status.HTTP_404_NOT_FOUND, f"project 不存在: {project_id}") from e
+
+    stem = Path(_sanitize_filename(file.filename)).stem or "deck"
+    out_pptx = store.artifacts_dir(rec.id) / f"{stem}_augmented.pptx"
+    asyncio.create_task(_render_pptx_job(
+        store, rec.id, src_pptx=src_pptx, out_pptx=out_pptx,
+        only_missing=only_missing, mock=bool(options.mock),
+    ))
+
+    return CreateJobResponse(job_id=rec.id, state=rec.state, status_url=f"/jobs/{rec.id}")

server/schemas.py

@@ -44,6 +44,7 @@ class SourceType(str, Enum):
     URL = "url"                  # 靜態 HTML 文章 -> url adapter
     SONG = "song"                # 歌曲音檔 + 歌詞時間軸 -> AI 生圖 MV (M3, 第 4 track)
     HTML_ANIMATION = "html_animation"  # HTML 動畫網頁 -> 逐 frame 截圖 -> MP4 (core.html_video)
+    PPTX = "pptx"                # PPTX 原檔 -> 缺圖頁就地補圖 (原文字可編輯) (core.pptx_augment)
 
 
 class JobState(str, Enum):