[codex] 新增教學檔案處理工具包

Learning-Materials/Teaching-File-Toolkit/README.md

@@ -0,0 +1,62 @@
+# 教學檔案處理工具包
+
+結論：這個資料夾提供教學檔案處理常用的 Python 套件清單與驗證工具，適合處理 Word、Excel、PowerPoint、PDF、圖片、QR code、Markdown 轉換與 OCR 前處理。
+
+## 成功標準
+
+1. 可以用 `requirements.txt` 安裝核心 Python 套件。
+2. `setup_teaching_file_toolkit.py verify` 顯示全部核心 Python 套件匯入成功。
+3. `setup_teaching_file_toolkit.py check-system` 能列出 Tesseract、Poppler、ffmpeg、Office 是否已在 PATH。
+
+## 建議安裝方式
+
+在此 repo 根目錄建立虛擬環境：
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py install
+```
+
+驗證：
+
+```powershell
+.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py verify
+.\.venv\Scripts\python.exe Learning-Materials\Teaching-File-Toolkit\setup_teaching_file_toolkit.py check-system
+```
+
+## 核心套件
+
+- Word：`python-docx`、`docxcompose`、`docx2pdf`
+- Excel：`openpyxl`、`xlsxwriter`、`pandas`
+- PowerPoint：`python-pptx`
+- PDF：`pypdf`、`PyMuPDF`、`pdfplumber`、`pdf2image`、`reportlab`、`fpdf2`
+- 圖片與圖表：`pillow`、`matplotlib`
+- 其他：`qrcode`、`markitdown`、`ocrmypdf`
+- Windows Office 自動化：`pywin32`
+
+## 選用影音套件
+
+影音、字幕、旁白或 YouTube 處理才需要安裝：
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -r Learning-Materials\Teaching-File-Toolkit\optional-media-requirements.txt
+```
+
+## 系統相依
+
+這些不是 pip 套件，需另外安裝：
+
+- Tesseract OCR：`ocrmypdf` 做掃描 PDF OCR 時需要。
+- Poppler：`pdf2image` 轉圖時需要。
+- ffmpeg：`openai-whisper` 或影音處理時需要。
+- Microsoft Word / PowerPoint：`docx2pdf` 與 Office COM 轉 PDF 時需要。
+
+Windows 可用的常見安裝方式：
+
+```powershell
+winget install UB-Mannheim.TesseractOCR
+winget install Gyan.FFmpeg
+```
+
+Poppler 可用 Chocolatey 安裝，或下載 Windows 版 Poppler 後加入 PATH。

Learning-Materials/Teaching-File-Toolkit/optional-media-requirements.txt

@@ -0,0 +1,4 @@
+openai-whisper
+edge-tts
+yt-dlp
+youtube-transcript-api

Learning-Materials/Teaching-File-Toolkit/requirements.txt

@@ -0,0 +1,19 @@
+python-docx
+docxcompose
+openpyxl
+xlsxwriter
+pandas
+python-pptx
+pypdf
+PyMuPDF
+pdfplumber
+pdf2image
+reportlab
+fpdf2
+pillow
+matplotlib
+qrcode
+markitdown
+ocrmypdf
+docx2pdf
+pywin32; platform_system == "Windows"

Learning-Materials/Teaching-File-Toolkit/setup_teaching_file_toolkit.py

@@ -0,0 +1,138 @@
+"""教學檔案處理工具包安裝與驗證工具。
+
+用法：
+    python setup_teaching_file_toolkit.py verify
+    python setup_teaching_file_toolkit.py install
+    python setup_teaching_file_toolkit.py check-system
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+PACKAGE_IMPORTS = {
+    "python-docx": "docx",
+    "docxcompose": "docxcompose",
+    "openpyxl": "openpyxl",
+    "xlsxwriter": "xlsxwriter",
+    "pandas": "pandas",
+    "python-pptx": "pptx",
+    "pypdf": "pypdf",
+    "PyMuPDF": "fitz",
+    "pdfplumber": "pdfplumber",
+    "pdf2image": "pdf2image",
+    "reportlab": "reportlab",
+    "fpdf2": "fpdf",
+    "pillow": "PIL",
+    "matplotlib": "matplotlib",
+    "qrcode": "qrcode",
+    "markitdown": "markitdown",
+    "ocrmypdf": "ocrmypdf",
+    "docx2pdf": "docx2pdf",
+}
+
+WINDOWS_PACKAGE_IMPORTS = {
+    "pywin32": "win32com.client",
+}
+
+SYSTEM_DEPENDENCIES = {
+    "Tesseract OCR": ["tesseract"],
+    "Poppler": ["pdftoppm", "pdfinfo"],
+    "ffmpeg": ["ffmpeg"],
+}
+
+WINDOWS_SYSTEM_DEPENDENCIES = {
+    "Microsoft Word": ["winword"],
+    "Microsoft PowerPoint": ["powerpnt"],
+}
+
+
+def requirements_path() -> Path:
+    return Path(__file__).with_name("requirements.txt")
+
+
+def install_core_packages() -> None:
+    """安裝核心 pip 套件。"""
+    command = [sys.executable, "-m", "pip", "install", "-r", str(requirements_path())]
+    subprocess.check_call(command)
+
+
+def validate_imports() -> dict[str, str]:
+    """回傳無法 import 的套件與錯誤訊息；空 dict 代表全部成功。"""
+    targets = dict(PACKAGE_IMPORTS)
+    if platform.system() == "Windows":
+        targets.update(WINDOWS_PACKAGE_IMPORTS)
+
+    failures: dict[str, str] = {}
+    for package_name, import_name in targets.items():
+        try:
+            importlib.import_module(import_name)
+        except Exception as exc:  # noqa: BLE001 - 驗證工具需回報所有 import 失敗原因。
+            failures[package_name] = f"{type(exc).__name__}: {exc}"
+    return failures
+
+
+def check_system_dependencies() -> dict[str, list[str]]:
+    """檢查 PATH 上可找到的系統工具。"""
+    dependencies = dict(SYSTEM_DEPENDENCIES)
+    if platform.system() == "Windows":
+        dependencies.update(WINDOWS_SYSTEM_DEPENDENCIES)
+
+    found: dict[str, list[str]] = {}
+    for dependency, commands in dependencies.items():
+        found[dependency] = [command for command in commands if shutil.which(command)]
+    return found
+
+
+def print_import_report() -> int:
+    failures = validate_imports()
+    if not failures:
+        print("全部核心 Python 套件匯入成功")
+        return 0
+
+    print("以下 Python 套件匯入失敗：")
+    for package_name, reason in failures.items():
+        print(f"- {package_name}: {reason}")
+    return 1
+
+
+def print_system_report() -> int:
+    results = check_system_dependencies()
+    missing = []
+    for dependency, commands in results.items():
+        if commands:
+            print(f"{dependency}: 已找到 ({', '.join(commands)})")
+        else:
+            print(f"{dependency}: 未在 PATH 找到")
+            missing.append(dependency)
+    return 1 if missing else 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="教學檔案處理工具包安裝與驗證")
+    parser.add_argument(
+        "command",
+        choices=["install", "verify", "check-system"],
+        help="install 安裝核心套件；verify 驗證 import；check-system 檢查外部工具。",
+    )
+    args = parser.parse_args()
+
+    if args.command == "install":
+        install_core_packages()
+        return print_import_report()
+    if args.command == "verify":
+        return print_import_report()
+    if args.command == "check-system":
+        return print_system_report()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())