Record the data storage architecture and phase-1 plan in the project documents

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/research_plan.md

@@ -1,6 +1,7 @@
 # 研究步驟規劃
 
-（2026-07-30 討論定案版；後續變更請記入 `decision_log.md`）
+（2026-07-30 討論定案、2026-07-31 增補資料架構；
+後續變更請記入 `decision_log.md`）
 
 ## 總體框架
 
@@ -24,12 +25,54 @@
   人工黃金標準終審。可重現性定義為「程序透明＋可稽核」：
   公開定義檔、記錄 model ID 與執行時間、保存全部原始輸出。
 
+## 資料儲存與模型（2026-07-31 定案）
+
+- **Commit 判準**：凡能由「committed 的輸入＋committed 的程式」
+  決定性再生者，不 commit；凡不能者——源頭資料、外部世界的
+  捕捉（Wikidata 快照、LLM 原始輸出）、人工著作（核定、編碼）
+  ——一律以文字格式 commit。格式跟著層次走，不跟著偏好走。
+- **分層**：
+  - 源頭：原始榜單 CSV（進 git）。
+  - 捕捉：Wikidata 快照 CSV、人工 overrides CSV、你的編碼
+    CSV、`runs/` JSONL（皆進 git）；歌詞 `.txt` 快取
+    （版權因素 gitignored，為已知的稽核缺口）。
+  - 工作儲存：SQLite 單檔（`tools/instance/`，generated、
+    不進 git），SQLAlchemy 2.0 typed ORM 定義 schema，
+    設定經 pydantic-settings（`.env` 供應
+    `SQLALCHEMY_DATABASE_URL` 與 `ANTHROPIC_API_KEY`）。
+    歌詞全文入 DB（不進 git 故無版權疑慮）。
+  - 報表：論文引用的最終表由 export 產出 CSV 進 `results/`
+    ——此為「可再生仍 commit」的唯一例外，理由：引用穩定性
+    （十年尺度的環境會腐化）、審稿人零門檻、撰稿期數字變動
+    可 diff。
+- **資料模型**：`songs`（歌曲實體）、`chart_entries`
+  （1 歌—N 筆榜單紀錄）、`artists`（歌手實體：Wikidata QID、
+  性別、型態、曲風、國籍）、`song_artists`（M—N 關聯：角色、
+  署名順序）、`lyrics`（1—1）。領域不變量（恰 1000 筆榜單、
+  每歌至少一 primary 歌手等）檢查內建於 `build-db`，違規即
+  建置失敗。
+- **歌手背景防火牆**：歌手背景資料只進人工解讀階段（證據表、
+  論文討論），**絕不進 LLM 輸入**——LLM 分類的 user message
+  維持歌詞-only，避免光環偏誤污染條件 A/B 實驗。women-power
+  候選歌曲的歌手另做深度背景（族裔以公開自我認同為準、音樂
+  場景），script 輔助、人工核定。
+- **Pilot 歌詞沿用**：先導研究捕捉檔（lyrics.json，684 首，
+  2018–2025）匯入歌詞快取——只取識別欄位與歌詞本文，pilot
+  的分析欄位一律不匯入；以 (year, rank) 精確匹配 song_id。
+  出處記於 `data/lyrics_provenance.csv`（進 git）：`source`
+  （原始 API）與 `method`（pilot-import / api-fetch）兩層，
+  取得日期不可考者不假造，僅記可證上界。
+- **子命令**（`pop-fem-audit-tools <cmd>` 或
+  `python -m pop_fem_audit_tools <cmd>`）：`run-llm`（已完成）、
+  `build-db`、`import-lyrics`、`fetch-lyrics`、`fetch-artists`、
+  `export-llm-input`；之後再加報表 export 與統計。
+
 ## 階段與時程（全文截稿 2026-08-15）
 
 | 階段 | 內容 | 方式 | 時程 |
 |---|---|---|---|
 | 0 | 基礎建設：git init、目錄結構、.gitignore、決策日誌、runner script（含 Batch API）、codebook v0 骨架 | script + 討論 | 7/30–7/31 |
-| 1 | 資料準備：去重唯一歌曲表（song id）、抓歌詞（Lyrics.ovh / LRCLIB，缺漏留 log）、演唱者性別表（Wikidata + 人工核對） | scripts | 7/31–8/2 |
+| 1 | 資料準備：`run_llm` 改走統一設定 → `build-db`（解析榜單成 songs/chart_entries/artists/song_artists）→ `import-lyrics`（pilot 2018–2025）→ `fetch-lyrics`（2016–17 與缺漏，Lyrics.ovh / LRCLIB）→ `fetch-artists`（Wikidata 快照 + 人工 overrides）→ `export-llm-input` | 子命令 | 7/31–8/3 |
 | 2 | 候選篩選：全部唯一歌曲高召回 women-power 候選篩選（寧可多抓，人工剔除） | API 2+1 | 8/2–8/3 |
 | 3 | 黃金標準：依 codebook 人工逐首判定 genuine/peripheral/fake，附引用歌詞證據表（LLM 只做摘錄，不給判定建議）；先以 10–15 首校準樣本試編並修訂 codebook 後凍結；同批校準樣本實測 Sonnet 4.6 vs Opus 5 一致率 | 人工 + script 輔助 | 8/4–8/8 |
 | 4 | 受控比較（盲點實驗）：條件 A（詞彙層提示）vs 條件 B（框架感知提示），各 2+1，對照黃金標準計算假陽／假陰率 | API | 8/6–8/9 |