# 🦞 2026-11-14 v14 雙龍收工交接

> 撰寫者：龍蝦總工程師（執行長兼參謀總長）
> 日期：2026-11-14
> 範圍：ahpal-wiki（詩詞、英美、節氣、演歌、英文歌）
> 最終 commit：`31d14ade`

---

## 一、這幾輪做了什麼（v9 → v14）

| 批次 | 內容 | commit |
|------|------|--------|
| v9 雙龍 | 詩詞 +5、英美 +5 | `6d7b55c3` |
| v9 單龍 | 24 節氣補環狀內鏈（24 座孤島串成環） | `f0006ba9` |
| v10 雙龍 | 詩詞 +5、英美 +5 | `19599b2b` |
| v11 單龍 | enka 5 篇短篇補齊（287~439 → 720~853 字） | `17336e51` |
| v12 單龍 | enka +5（リンゴ追分等） | `1af3adde` |
| v13 單龍 | songs-en +5（We Are the Champions 等） | `8cc9a26d` |
| 首頁改版 | songs-en 密集並排 + 分類 + 搜尋 | `a042cebd` |
| 四站擴散 | enka/poetry/lit/culture 統一改版 | `e266c9ee` |
| v14 雙龍 | enka +5、songs-en +5 | `31d14ade` |

### 五站現況（三數字全相等）

| 站 | 目錄 | 首頁 | sitemap |
|----|------|------|---------|
| 中國詩詞 | 75 | 75 | 75 |
| 英美文學 | 79 | 79 | 79 |
| 二十四節氣 | 24 | 24 | 24 |
| 日本演歌 | 21 | 21 | 21 |
| 英文歌曲 | 30 | 30 | 30 |

---

## 二、這幾輪踩的坑（學弟必看）

### 坑 1：測試餌母體名猜錯（v10）

我故意放「已存在 + -2」的假 slug 當測試餌，但**母體名猜錯**，例如 `eagles-hotel-california-2` 的母體是 `hotel-california`（不是 `eagles-hotel-california`）。結果測試餌全空，測不到。

**解法**：測試餌的母體要用**真實存在的 slug**，不是自己拼的。先撈目錄清單，再挑母體。

### 坑 2：`bohemian-rhapsody-2` 假 OK（v14）

真候選裡放了 `bohemian-rhapsody-2`，腳本只驗 `-2` 本身，標 `[OK]`，但**母體 `bohemian-rhapsody` 明明已存在**。若寫了就是第二次造假。

**解法**：真候選檢查加「母體檢查」——`re.sub(r'-\d+$', '', slug)` 去掉 `-數字` 後綴，驗母體。

### 坑 3：首頁撈卡片從舊首頁撈，class 不符（v14）

`enka` 首頁重建時，從舊首頁撈卡片，但舊 class 是 `card`，我正則寫 `class="card"`，結果只撈到新寫的 5 張，舊的 16 張沒撈到。首頁變 5 張，三數字 `21/5/21` ❌。

**解法**：**首頁撈卡片要從目錄撈，不從舊首頁撈。** `ENKA.iterdir()` 撈目錄 → 從每篇抓 `<h1>` 歌名 → 從對照表抓歌手。

### 坑 4：驗證把 `data` 資料夾當節氣（v14 前）

`culture-daily` 目錄有 25 個子目錄（24 節氣 + `data`），驗證時 `dirs = 25`，但首頁 24、sitemap 24。三數字 `25/24/24` ❌。

**解法**：目錄計數排除 `data`，`skip=("data",)`。

### 坑 5：硬灌字數就是造假（v11）

第一次補 enka 5 篇，腳本設「1,000 字硬門檻」，5 篇 591~695 字 → `[FAIL]` → 沒 push。

**董事長點破**：「有的加分，沒有的不要硬掰。」

**解法**：拿掉字數硬門檻，改成「補真實內容」（時代背景、歌手生涯、演歌史定位）。補到 720~853 字，是真的。

---

## 三、這幾輪學到的做法（SOP 等級）

### 做法 1：先診斷，再動手

每次新增/改版前，先撈三來源（目錄/首頁/sitemap），印出全部 slug、落差、字數。**不憑印象。**

### 做法 2：二次預檢 + 母體檢查

寫檔前，再驗一次候選 slug + 母體（去掉 `-數字` 後綴）。任一存在就 `[FAIL]` 中止。

```python
parent = re.sub(r'-\d+$', '', slug)
if slug in disk or slug in home or slug in sm: FAIL
if parent != slug and (parent in disk or parent in home or parent in sm): FAIL
```

### 做法 3：首頁撈卡片從目錄撈

改版首頁時，**從目錄撈**，不從舊首頁撈：

```python
dirs = sorted([d.name for d in FOLDER.iterdir() if d.is_dir()])
for slug in dirs:
    c = (FOLDER/slug/"index.html").read_text()
    title = re.search(r'<h1[^>]*>(.*?)</h1>', c, re.S)
```

### 做法 4：三數字對帳，全等才 push

```python
dirs = len([d for d in FOLDER.iterdir() if d.is_dir() and d.name not in skip])
home = len(set(re.findall(rf'/{section}/([^/"#?]+)/"', idx)))
sm = len(re.findall(rf'<loc>https://wiki\.ahpal\.com/{section}/[^/]+/</loc>', sitemap)))
if not (dirs == home == sm): sys.exit(1)
```

### 做法 5：首頁改版（密集並排 + 分類 + 搜尋）

抄 `songs-en` 的實作：

- grid：`repeat(auto-fill, minmax(160px, 1fr))`（5 欄）
- 卡片：icon + 名稱 + 作者，去掉描述
- 搜尋：`<input type="search">` + `addEventListener('input')` + `textContent.includes(q)`
- 分類：`<button class="cat-btn" data-cat="...">` + JS `classList.toggle('hidden')`

### 做法 6：翻唱層（有才加，沒有不硬掰）

日本演歌/英文歌，若有華語/台語翻唱，加一層「🎤 華語翻唱」，寫翻唱曲名、歌手、背景。**沒翻唱的不加**。

---

## 四、還沒做什麼

- GSC 提交：v9~v14 新增的 URL 還沒提交 Google Search Console
- 詩詞/英美繼續 +5（雙龍）
- enka 再 +5（目前已 21）
- songs-en 再 +5（目前已 30）
- 五站首頁的搜尋/分類，可再優化（例如加「年代」分類）

---

## 五、關鍵檔案

| 項目 | 路徑 |
|------|------|
| 詩詞 | `ahpal-wiki/poetry/`（75 篇） |
| 英美文學 | `ahpal-wiki/literature-en/`（79 篇） |
| 二十四節氣 | `ahpal-wiki/culture-daily/`（24 篇） |
| 日本演歌 | `ahpal-wiki/enka/`（21 篇） |
| 英文歌曲 | `ahpal-wiki/songs-en/`（30 篇） |
| sitemap | `ahpal-wiki/sitemap.xml` |
| 本輪腳本 | `ahpal-wiki/staging/audit-20261113/` |

---

## 六、死命令（累計）

1. 不跳備份
2. 不寫簡體
3. 不盲目 push（三數字全等才 push）
4. 不用 here-string 夾長字串（用 `lines.append()` + `join()`）
5. 不憑記憶猜結構（先 `c.find()` 撈真實碼）
6. 驗證看數字（目錄/首頁/sitemap 三數字必須相等）
7. 挑題目前必對清單（逐字比對，不憑印象）
8. 預檢 `[FAIL]` 就換題目，不硬跑
9. 母體檢查：`-2` 後綴的 slug，要驗母體是否存在
10. 首頁撈卡片從目錄撈，不從舊首頁撈
11. 不硬灌字數（有的加分，沒有的不硬掰）
12. 目錄計數要排除非內容資料夾（如 `data`）

---

## 七、給下一個 AI 的話

- 「先診斷，再動手。」
- 「驗證看數字，不看紅字。」
- 「挑題目逐字對清單，不憑印象。」
- 「`git commit` 沒有 `create mode` = 假新增。」
- 「三數字對帳（目錄/首頁/sitemap）全相等才 push。」
- 「母體檢查：`-2` 後綴要驗母體。」
- 「首頁撈卡片從目錄撈，不從舊首頁撈。」
- 「不硬灌字數，有的加分，沒有的不硬掰。」
- 「關卡是防造假，不是逼灌水。」

🦞 龍蝦總工程師（執行長兼參謀總長）· 2026-11-14
