# 單元簡報與匯出簡報

## 新結構(單元簡報)
- **每個教材單元(type 為 text 或 lab)自己就有簡報**,直接顯示在單元頁最上面(標題與說明之後),簡報下面才是完整文字講義,中間有一行「完整講義:想看更詳細的說明請往下讀」。學員與訪客都看得到(受既有的報名/鎖定規則限制)。
- 互動實驗、動畫、機器人、終端機、影片與所有測驗(含牛刀小試/章末/期末)**不產生**簡報;沒有文字內容的單元也不顯示。
- 資料模型只有一份:`App\Services\UnitSlides`(`for()` 快取版,以單元 id + updated_at + 內容雜湊為鍵快取 24 小時;`forWeb()` 去掉備忘稿)。網頁檢視器(`resources/views/learn/slides.blade.php`、`resources/js/slides.js`)與 .pptx(`SlideExporter::renderUnit`)都吃同一份標準化陣列(kind: cover/quote/bullets/think/formula/example-q/steps/figure/closing)。內容只來自講義文字,不含任何測驗題、答案或單元小測 checks。
- 一個單元 3~16 張(實測平均約 5~15,故事約 5 張):封面 → 依【小標題】每個一張(每張 ≤5 條、每條 ≤40 字,過長自動分頁,太碎的相鄰小節會合併)→ 每個 `[圖:…]` 一張 → 公式頁、例題題目頁、解答步驟頁 → 「本節回顧」。故事單元是 3~4 張關鍵情境 + 「想一想」。超過 16 張時截斷內容(公式單元例題很多時會發生,完整內容仍在下方講義)。
- 檢視器:16:9 舞台(手機改 4:5 以放大字)、上一張/下一張、進度點與「第 n / m 張」、鍵盤 ← → / 空白鍵(舞台聚焦時)、手機左右滑、全螢幕(Esc 離開)、圖片點擊放大、「收合簡報」(偏好記在 localStorage)。配色用學院佈景的 CSS 變數,跟隨明亮/深色模式;字級用容器單位,全螢幕時跟著放大;無 JS 時所有投影片垂直排列;尊重 prefers-reduced-motion;`role="region" aria-roledescription="carousel"`。語音朗讀仍只讀下方的完整文字(簡報內沒有 `data-speak`)。
- 下載:管理員與負責講師在簡報右上角看得到「下載本單元簡報(.pptx)」(`GET /admin/courses/{course}/lessons/{lesson}/slides.pptx`)。**學員沒有 pptx 下載**,只有網頁內嵌檢視。整章 pptx 現在是「章封面 + 學習目標/章節地圖 + 各單元投影片依序串起來」(每個單元的第一張標題頁就是單元之間的分隔;互動實驗與測驗單元仍有「請到網站操作」頁與測驗頁),所以內容和網頁一致。

# 匯出簡報(後台)

管理員與課程負責講師可以把一章或整門課的講義匯出成 `.pptx` 投影簡報,給老師上課用。每次下載都依資料庫**最新內容即時產生**,不是一次性檔案。對任何課程通用(先針對「國中理化」jh-science-g8-1、g8-2、g9-1、g9-2 調校)。

## 怎麼用
後台 → 課程 → 編輯 → 「章節與單元」區塊:
- 每章標題列右側「匯出簡報」:下載單章 `課程名稱-第N章-章名.pptx`。
- 區塊標題旁「匯出整門課簡報(zip)」:每章一個 pptx 打包成 zip。
- 草稿(未上架)課程也可匯出。授權是 `Gate::authorize('manage', $course)`:管理員、該課程負責講師;其他人 403。
- 路由:`GET /admin/courses/{course}/chapters/{chapter}/slides.pptx`(限流 20 次/分)、`GET /admin/courses/{course}/slides.zip`(限流 4 次/分)。
- 每次匯出寫稽核紀錄 `course.slides_exported`(只記課程與章)。整門課匯出逐章產生、寫入暫存檔再打包,並放寬 `set_time_limit(300)` 與記憶體 512M。

## 簡報結構(章簡報的整體順序;單元內容的切分見上方「新結構」)
16:9、淺色底、依學院配色(資訊科技金黃、AI 靛藍、證照考試藍、商務銀);字型 Microsoft JhengHei(Mac 沒有時 PowerPoint/Keynote 會替換成 PingFang TC,Linux 為 Noto Sans CJK TC);標題 40pt、正文 ≥28pt;每頁底部有課程名稱與頁碼。
1. 封面(課程、學期、章名)→「學習目標」(若講義有「學習目標/這一章要做的事」小標題)→「本章地圖」(各單元標題)。
2. 「故事」:3~4 張關鍵句(完整段落在備忘稿),最後一張「想一想」。
3. 「原理」「觀念教學」「生活應用」:依【小標題】分頁,每頁只放該段條列(「一、」「1.」「・」等清單;沒有清單就取每段第一句),每頁最多 5 條、每條 ≤40 字(超過截斷,完整文字在備忘稿);有公式/程式區塊就用等寬字型放在頁面底部或獨立一頁。
4. 每個 `[圖:/images/…|圖說]` 獨立一頁:圖置中放大、圖說在下方。
5. 「公式與計算」:公式區塊;每個「例題」一頁題目、一頁解答步驟。
6. 互動實驗、動畫、機器人、終端機:一頁「請到網站操作」,列出單元標題、任務清單(`config.tasks` 的 title)與網址;**不放解答**。
7. 「動手做/實作」:器材與步驟分頁(依小標題;器材以「、」拆成條列)。
8. 測驗:最多 5 題(難度 1~3 各至少 1 題,其餘依 position 穩定補滿),每題一頁只有題目與選項;**答案、解析、出處只在講者備忘稿**。
9. 「課後重點整理」依小標題分頁(自我檢核的答案放備忘稿)。
每頁的講者備忘稿放該頁對應的完整原文。所有文字一律跳脫,不含可執行內容;圖片只接受 `/images/` 底下的檔案(拒絕 `..`、`//`、其他路徑與逃出 public/images 的符號連結)。

## 圖檔快取(SVG → PNG)
PPTX 不能可靠嵌入 SVG,所以先轉成 PNG(寬 1600px、白底)快取到 `storage/app/figure-png/`(結構同 `public/images`)。該目錄已被 `storage/app/.gitignore` 排除,不進版本控制。
```
php artisan slides:render-figures          # 只轉修改時間較新的檔案,失敗的會列出
php artisan slides:render-figures --force  # 全部重轉
```
新增或修改 SVG 後再執行一次即可;沒執行也沒關係,匯出時遇到沒有快取的圖會即時轉換並寫入快取(第一次稍慢)。轉換器依序嘗試 `rsvg-convert`、`inkscape`、PHP Imagick,**伺服器至少要有其中一個**;都沒有時,該頁只放圖說與「(圖檔請見網站)」,不會報錯。PNG/JPEG/GIF 原圖直接嵌入;WebP 無法嵌入,同樣以圖說代替。

## 實作
不依賴外部函式庫:`app/Services/Pptx/Deck.php`、`Slide.php` 用 ZipArchive 直接組 OOXML(含 notesMaster,PowerPoint 開啟不需修復)。講義解析在 `Pptx/LessonText.php`,簡報編排在 `app/Services/SlideExporter.php`。測試:`php artisan test --filter=SlideExport`。

## 限制
- 互動實驗、動畫、機器人模擬、終端機無法嵌入,以網站連結代替。
- 品質取決於講義格式(【小標題】、清單、`[圖:…]`);沒有小標題的長文只會取每段第一句,建議老師匯出後自行微調。
- 一章通常 60~100 頁(每個小標題與每張圖各一頁),可在 PowerPoint 隱藏不需要的頁。
- 投影片只放摘要,逐字講解請看備忘稿。
