# FHL MCP Server - Bug 修復計劃
**基於測試報告**: `testing_report.md` (2025-11-05)
**修復日期**: 2025-11-05
**負責人**: Development Team
---
## 📋 問題優先級分類
### 🔴 P0 - 核心功能失效（立即修復）
#### P0-1: 書卷映射錯置
**問題描述**:
- `get_bible_chapter("Acts", 12)` → 返回 Genesis 12
- `get_bible_chapter("John", 3)` → 返回 Genesis 3
- `get_audio_chapter_with_text("詩篇", 23)` → 文字為 Genesis 23
- `get_apocrypha_verse("智慧書", 1, "1-5")` → 返回瑪加伯上
**影響範圍**:
- 所有經文查詢功能
- 有聲聖經配文字功能
- 次經查詢功能
**根因分析**:
1. 書卷名稱解析邏輯錯誤
2. 可能使用了錯誤的書卷 ID 或順序
3. 中英文書卷名稱對應表不正確
**修復計劃**:
- [ ] 檢查 `booknames.py` 中的書卷映射表
- [ ] 檢查 API 調用時的書卷名稱轉換邏輯
- [ ] 添加書卷名稱驗證測試
- [ ] 建立回歸測試用例
**預計工作量**: 4-6 小時
---
#### P0-2: Strong's 字典功能失效
**問題描述**:
- `lookup_strongs("G3056")` → 返回 00000 範例說明
- `search_strongs_occurrences("G1344")` → 返回 0 筆 + 00000 範例
**影響範圍**:
- 原文字典查詢
- Strong's 編號搜尋
- 詞彙分析功能
**根因分析**:
1. Strong's 資料未正確載入或連接
2. API endpoint 參數格式不正確
3. 可能是 demo 資料未清除
**修復計劃**:
- [ ] 檢查 Strong's 資料源連接
- [ ] 驗證 API 請求格式
- [ ] 測試 G/H 前綴處理
- [ ] 添加真實資料驗證
**預計工作量**: 3-4 小時
---
### 🟡 P1 - 功能受限（高優先級）
#### P1-1: 參數型別驗證不足
**問題描述**:
- `search_bible_advanced(range_start=40)` → `'int' object has no attribute 'isascii'`
- `search_bible(search_type='greek')` → 錯誤訊息不清楚
**影響範圍**:
- 進階搜尋功能
- 用戶體驗
**修復計劃**:
- [ ] 添加參數型別轉換
- [ ] 改善錯誤訊息
- [ ] 添加參數驗證測試
**預計工作量**: 2-3 小時
---
#### P1-2: 註釋查詢返回空
**問題描述**:
- `get_commentary("約翰福音", 3, 16)` → 0 筆
- `get_commentary("羅馬書", 3, 24, commentary_id=3)` → 0 筆
**影響範圍**:
- 註釋查詢功能
**根因分析**:
- 可能與書卷映射錯誤相關
- 或註釋資料源索引問題
**修復計劃**:
- [ ] 修復書卷映射後重測
- [ ] 檢查註釋資料源
- [ ] 測試多個 commentary_id
**預計工作量**: 2 小時（依賴 P0-1）
---
#### P1-3: get_word_analysis 錯誤
**問題描述**:
- 出現 "錯誤: 'N'" 訊息
**修復計劃**:
- [ ] 收集完整錯誤堆疊
- [ ] 找出觸發條件
- [ ] 修復並添加測試
**預計工作量**: 2-3 小時
---
## 🔧 修復執行順序
### Phase 1: 核心功能修復（第1天）
1. **P0-1: 書卷映射錯置** ⚠️ 最高優先
2. **P0-2: Strong's 字典失效**
### Phase 2: 功能改善（第2天）
3. **P1-1: 參數驗證**
4. **P1-2: 註釋查詢**（依賴 P0-1）
5. **P1-3: 詞彙分析錯誤**
### Phase 3: 測試與驗證（第3天）
6. 執行回歸測試
7. 更新文檔
8. 發布修復版本
---
## ✅ 回歸測試檢查清單
### 書卷映射驗證
- [ ] Acts 12 → 使徒行傳 12（非創世記）
- [ ] Acts 13 → 使徒行傳 13
- [ ] John 3 → 約翰福音 3
- [ ] Psalms 23 → 詩篇 23
- [ ] 智慧書 1:1-5 → 次經智慧書（非瑪加伯）
### Strong's 字典驗證
- [ ] G3056 → 正確的希臘文詞條（λόγος）
- [ ] H430 → 正確的希伯來文詞條（אֱלֹהִים）
- [ ] G1344 出現次數 > 0
### 參數驗證
- [ ] range_start=40 (int) → 自動轉換為 "40"
- [ ] search_type='greek' → 清楚的錯誤訊息
### 註釋查詢
- [ ] John 3:16 → 至少 1 筆註釋
- [ ] Romans 3:21-26 → 至少 1 筆註釋
---
## 📝 相關文件更新
- [ ] API.md - 更新參數說明
- [ ] EXAMPLES.md - 添加正確用法範例
- [ ] CHANGELOG.md - 記錄 bug 修復
- [ ] testing_report.md - 標記已修復問題
---
## 🚀 發布計劃
### 版本: v0.1.1-bugfix
**修復內容**:
- 修復書卷映射錯誤
- 修復 Strong's 字典查詢
- 改善參數驗證
- 修復註釋查詢
- 修復詞彙分析錯誤
**測試覆蓋率目標**: 90%+
**預計發布日期**: 2025-11-08
---
## 📞 聯絡資訊
如有問題請開 Issue 或聯繫：
- GitHub Issues: https://github.com/ytssamuel/FHL_MCP_SERVER/issues
