feat(t73): 轉檔層接進主流程——docx 真的走得通（零件完成≠功能完成）

ExtractWithGemma 讀檔後改走 ConvertToText，LLM 只會收到文字永不收二進位。
刻意不吞錯：ErrNoText(掃描件/空檔) 與 ErrUnsupported(未支援格式) 都往上拋，
因為靜默略過正是 leo 撞到的病。

接線測試 5/5（驗用戶真的會走的那條路，非只測零件）：
  scan 收得到 .docx／收 .md／不收 .png
  ⭐ docx 一路走到 Gemini API 才因假 key 失敗 ＝ 決定性證據：
     轉檔確實發生在送模型之前（非宣稱）
  抽不出文字 → 明確失敗且 errors.Is(ErrNoText) 可判定，不靜默送空卡
  未支援格式 → ErrUnsupported，與 ErrNoText 可區分（給用戶的說法不同）
  .md 迴歸保護：不因接了轉檔層而壞掉

順帶修：變數名與既有 text(LLM 回應) 衝突 → 改 srcText(輸入原稿)，IDE 診斷抓到。
全 collector 測試綠。

convert_wiring_test.go

@@ -0,0 +1,137 @@
+package main
+
+import (
+	"archive/zip"
+	"bytes"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 這一組測的是**接線**，不是轉檔本身（那在 convert_test.go）。
+//
+// 為什麼要獨立測：t73 的教訓是「零件完成 ≠ 功能完成」——convert.go 寫得再對，
+// 沒接進 ExtractWithGemma 就等於不存在。這裡驗的是**用戶真的會走的那條路**：
+// 檔案落在資料夾 → scan 收不收 → 萃取前有沒有真的過轉檔層。
+
+func writeDocx(t *testing.T, path, bodyXML string) {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	w, _ := zw.Create("word/document.xml")
+	w.Write([]byte(`<?xml version="1.0" encoding="UTF-8"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+<w:body>` + bodyXML + `</w:body></w:document>`))
+	zw.Close()
+	if err := os.WriteFile(path, buf.Bytes(), 0o644); err != nil {
+		t.Fatalf("寫檔失敗: %v", err)
+	}
+}
+
+// scan 必須把 .docx 當成要處理的檔案收進來——否則轉檔層再好也輪不到它。
+func TestWiring_scan收得到docx(t *testing.T) {
+	dir := t.TempDir()
+	writeDocx(t, filepath.Join(dir, "合約.docx"), `<w:p><w:r><w:t>內容</w:t></w:r></w:p>`)
+	os.WriteFile(filepath.Join(dir, "筆記.md"), []byte("# 標題"), 0o644)
+	os.WriteFile(filepath.Join(dir, "圖.png"), []byte("\x89PNG"), 0o644)
+
+	m := &Manifest{FolderID: "test-folder-id", Entries: map[string]*ManifestEntry{}}
+	payload, err := Scan(dir, m, ScanOptions{})
+	if err != nil {
+		t.Fatalf("scan 失敗: %v", err)
+	}
+	var got []string
+	for _, ev := range payload.Events {
+		got = append(got, filepath.Base(ev.Path))
+	}
+	joined := strings.Join(got, ",")
+	if !strings.Contains(joined, "合約.docx") {
+		t.Errorf(".docx 應被 scan 收進來，實得: %v", got)
+	}
+	if !strings.Contains(joined, "筆記.md") {
+		t.Errorf(".md 應被收，實得: %v", got)
+	}
+	if strings.Contains(joined, "圖.png") {
+		t.Errorf(".png 不該被收，實得: %v", got)
+	}
+}
+
+// 接線的核心：ExtractWithGemma 讀完檔之後，送進 LLM 的必須是**轉好的文字**，
+// 不是原始位元組。這裡不打真 API——用「缺 API key 會在轉檔之後才失敗」來反證
+// 轉檔確實發生在送出之前。
+func TestWiring_docx轉檔發生在送LLM之前(t *testing.T) {
+	dir := t.TempDir()
+	rel := "合約.docx"
+	writeDocx(t, filepath.Join(dir, rel), `<w:p><w:r><w:t>維修費用 350,000 元</w:t></w:r></w:p>`)
+
+	// 空 API key → 函式最前面就擋下，證明不了轉檔。給假 key 讓它走到轉檔那一步。
+	_, err := ExtractWithGemma("fake-key-for-test", "", dir, rel)
+	if err == nil {
+		t.Fatal("用假 key 不該成功")
+	}
+	// 關鍵斷言：錯誤不可以是「轉檔失敗」——那代表轉檔層把正常的 docx 擋掉了。
+	if strings.Contains(err.Error(), "轉檔失敗") {
+		t.Errorf("正常的 docx 不該在轉檔層失敗，實得: %v", err)
+	}
+	// 也不該是「讀原稿失敗」——檔案是存在的。
+	if strings.Contains(err.Error(), "讀原稿失敗") {
+		t.Errorf("檔案存在卻讀不到: %v", err)
+	}
+	// 走到這裡代表：讀檔 ok → 轉檔 ok → 死在 API 呼叫（預期，因為 key 是假的）
+	t.Logf("如預期死在 API 階段（證明轉檔已通過）: %v", err)
+}
+
+// 掃描件 PDF 的行為契約：轉不出文字要**明確失敗**並說得出原因，
+// 不能靜默當成空內容送給 LLM（那會產生一張空卡，用戶以為成功了）。
+func TestWiring_抽不出文字要明確失敗不靜默(t *testing.T) {
+	dir := t.TempDir()
+	rel := "空的.docx"
+	writeDocx(t, filepath.Join(dir, rel), `<w:p><w:r><w:t>   </w:t></w:r></w:p>`)
+
+	_, err := ExtractWithGemma("fake-key-for-test", "", dir, rel)
+	if err == nil {
+		t.Fatal("抽不出文字應該失敗")
+	}
+	if !strings.Contains(err.Error(), "轉檔失敗") {
+		t.Errorf("應該明確說是轉檔失敗，實得: %v", err)
+	}
+	if !errors.Is(err, ErrNoText) {
+		t.Errorf("應可用 errors.Is 判定為 ErrNoText（呼叫端才能給對的訊息），實得: %v", err)
+	}
+}
+
+// 還沒支援的格式（例如 .pptx 目前沒抽取器）要回 ErrUnsupported，
+// 訊息要跟「掃描件」區分開——給用戶的說法不同。
+func TestWiring_未支援格式與無文字要能區分(t *testing.T) {
+	dir := t.TempDir()
+	rel := "簡報.pptx"
+	os.WriteFile(filepath.Join(dir, rel), []byte("PK\x03\x04fake"), 0o644)
+
+	_, err := ExtractWithGemma("fake-key-for-test", "", dir, rel)
+	if err == nil {
+		t.Fatal("未支援格式應該失敗")
+	}
+	if !errors.Is(err, ErrUnsupported) {
+		t.Errorf("應為 ErrUnsupported，實得: %v", err)
+	}
+	if errors.Is(err, ErrNoText) {
+		t.Error("未支援格式不該同時是 ErrNoText（兩者給用戶的說法不同）")
+	}
+}
+
+// .md 走純文字直通，不可因為接了轉檔層而壞掉（迴歸保護）。
+func TestWiring_md不受轉檔層影響(t *testing.T) {
+	dir := t.TempDir()
+	rel := "筆記.md"
+	os.WriteFile(filepath.Join(dir, rel), []byte("# 標題\n\n內容"), 0o644)
+
+	_, err := ExtractWithGemma("fake-key-for-test", "", dir, rel)
+	if err == nil {
+		t.Fatal("假 key 不該成功")
+	}
+	if strings.Contains(err.Error(), "轉檔失敗") {
+		t.Errorf(".md 不該進轉檔層失敗路徑，實得: %v", err)
+	}
+}

extract_gemma.go

@@ -56,11 +56,22 @@ func ExtractWithGemma(apiKey, model, absRoot, relPath string) ([]string, error)
 	if err != nil {
 		return nil, fmt.Errorf("讀原稿失敗：%w", err)
 	}
+
+	// 本地轉檔層（t73/t16，2026-07-27）：任何格式在這裡變成「模型可讀的純文字」。
+	// 純文字檔原樣通過；.docx 等走對應抽取器。**LLM 只會收到文字，永遠不會收到二進位**
+	//（那正是這一層存在的理由——見 convert.go 檔頭與 pdf-extraction-options.md 洞 B）。
+	srcText, err := ConvertToText(relPath, raw)
+	if err != nil {
+		// 這裡刻意**不吞錯**：靜默略過正是 leo 撞到的病（丟檔進去沒反應）。
+		// ErrNoText＝掃描件/空檔，ErrUnsupported＝還沒支援的格式，兩者訊息不同但都要說出來。
+		return nil, fmt.Errorf("轉檔失敗（%s）：%w", relPath, err)
+	}
+
 	pageName := pageNameOf(relPath)
 
 	reqBody, _ := json.Marshal(map[string]any{
 		"contents": []map[string]any{
-			{"parts": []map[string]any{{"text": gemmaPrompt(pageName, string(raw))}}},
+			{"parts": []map[string]any{{"text": gemmaPrompt(pageName, srcText)}}},
 		},
 		"generationConfig": map[string]any{"temperature": 0.2, "maxOutputTokens": 8192},
 	})