世界地圖維護工作流

返回：文件索引 / README

資料已剝離為 JSON：assets/data/world_map.json（純資料），由 src/data/world_map.py（薄載入器）讀取，保持原匯入路徑相容；涉及 FeatureList 列舉的 higher_order_feature_dict 仍在載入器中。permanent_dict（影拓豐碑敵人列表）在 JSON 中維護。

主要維護點

1. 地區列表：驅動任務遍歷

影響的功能：

• daily_trade_mixin.py 中的買賣貨任務會按 areas_list 逐區執行
• daily_outpost_mixin.py 中的據點兌換任務會按 areas_list 遍歷所有地區
• daily_buy_mixin.py 中的買物資流程也依賴地區列表
• daily_logistics_mixin.py 的物流相關流程也讀取地區列表

維護要點：

• 新增地區時，必須先把地區名加入 areas_list
• 地區名會直接影響日常任務的遍歷範圍和配置項名稱
• 地區順序會影響任務執行順序

---

2. 據點字典：決定地區內可處理的據點

影響的功能：

• world_map_utils.py 通過 get_area_by_outpost_name() 反查據點所屬地區，並由 get_goods_by_outpost_name() 返回該地區的 goods_dict
• daily_outpost_mixin.py 的據點兌換任務會從 outpost_dict 逐個取出據點執行兌換
• 當前直接業務呼叫方只有據點兌換流程；自動送貨使用獨立的 delivery_area.py 地點/NPC 資料，不讀取 outpost_dict

維護要點：

• 新增或調整據點時，要同步更新 outpost_dict（注意：應統一使用"據點"術語，避免與其他模組混淆）
• 修改據點名稱後，要檢查所有按名稱反查地區的流程是否還能匹配

---

3. 商品字典：驅動據點兌換識別與優先項

影響的功能：

• world_map_utils.py 的 get_goods_by_outpost_name() 會按據點所屬地區返回可交易貨物
• daily_outpost_mixin.py 的據點兌換任務按據點所屬地區讀取 goods_dict
• daily_routine_mixin.py 會彙總 goods_dict，生成「交易貨品優先序列」的可選項
• 買賣貨任務只按 areas_list 遍歷並從介面 OCR 採集交易資訊，不讀取 goods_dict

維護要點：

• 新增據點兌換可識別/可排序的貨物時，更新 goods_dict；送貨貨物和買賣貨掃描不由該字典驅動
• 商品必須按地區分組，否則據點兌換無法拿到正確的可交易物品列表
• 商品變動會影響據點兌換的 OCR 候選、規範化和「交易貨品優先序列」配置選項，不會改變遊戲內兌換 UI 自身的商品列表

---

4. 兌換商品字典：當前主要是預留配置

影響的功能：

• 目前程式碼裡沒有直接消費 exchange_goods_dict 的業務邏輯
• 文件和配置層面保留了這個結構，便於後續擴充套件兌換 UI 或交易邏輯

維護要點：

• 現在不要把它當作主流程資料來源
• 如果後續要接入真正的兌換功能，再補充呼叫方

---

5. 關卡字典和消耗表：驅動戰鬥任務

影響的功能：

• daily_battle_mixin.py 會用 stages_dict 生成關卡選擇項
• world_map_utils.py 的 get_stage_category() 會反查關卡所屬分類
• stages_cost 會影響體力/消耗計算
• higher_order_feature_dict 只服務高階關卡的模板識別和特殊處理

維護要點：

• 新關卡先放進 stages_dict
• 關卡消耗統一維護在 stages_cost
• 只有高階關卡才需要維護 higher_order_feature_dict
• stages_list 是派生資料，不要手改

---

6. 倉庫對映：驅動物品轉移

影響的功能：

• 倉庫物品轉移.md 對應的物品選擇依賴 item_to_warehouse_dict
• 倉庫轉移任務會按這個字典把物品歸類到礦物、產物等倉庫類別

維護要點：

• 新增物品類別時補充對映
• 對映變更會直接影響倉庫轉移任務的可選項和分類結果

---

通用維護流程

flowchart TD
    A[确认数据变更需求] --> B[定位调用方]
    B --> C[修改 assets/data/world_map.json 或加载器]
    C --> D{是否涉及模板特征}
    D -->|是| E[更新 ok_templates 和 FeatureList]
    D -->|否| F[运行 main_debug.py 验证加载]
    E --> F
    F --> G[运行相关单元测试]
    G --> H[同步 assets/lang/world_map.json]
    H --> I[同步功能文档和维护文档]

1. 先確認呼叫方使用了哪些資料
2. 修改對應配置（均在 assets/data/world_map.json）：
   • 地區：areas_list
   • 據點：outpost_dict
   • 商品：goods_dict
   • 關卡：stages_dict
   • 消耗：stages_cost
   • 倉庫對映：item_to_warehouse_dict
   • 影拓豐碑敵人：permanent_dict
3. 如有高階關卡，再補 higher_order_feature_dict（在 src/data/world_map.py 載入器內，因含 FeatureList 列舉）
4. scripts/sync_world_map_langs.py 會自動為主資料新增的名稱補齊 assets/lang/world_map.json 節點（官方有譯名則填，無則至少 zh_CN）；官方新增名稱會列印 MANUAL 提示人工決定是否加入主資料
5. 執行相關任務驗證資料是否生效

---

關鍵注意事項

• 先看呼叫方，再改資料：world_map.py 裡的欄位不是孤立配置，改之前先確認哪些任務模組在用
• 商品字典影響範圍有限：goods_dict 影響據點兌換識別、篩選和優先序列配置，不驅動買賣貨掃描、自動送貨或遊戲內商品列表
• 關卡分兩層維護：普通關卡只維護分類和消耗，高階關卡才維護模板特徵
• 兌換商品目前偏預留：exchange_goods_dict 暫時不是主流程資料來源
• 派生資料不要手改：stages_list 由 stages_dict 自動生成

---

依賴關係

• daily_trade_mixin.py 只讀取地區列表，不讀取 goods_dict
• daily_outpost_mixin.py 讀取地區列表、據點列表和商品配置
• daily_routine_mixin.py 彙總商品配置以生成交易貨品優先序列
• daily_logistics_mixin.py 讀取地區列表
• daily_battle_mixin.py 讀取關卡分類、消耗和高階特徵
• world_map_utils.py 負責據點到地區、據點到商品、關卡到分類的反查
• 倉庫物品轉移.md 對應倉庫對映字典的使用說明

---

通用驗證步驟

1. 執行 python -m compileall src/data src/tasks/daily 檢查語法和匯入前的基礎結構。
2. 執行 python -m unittest tests.TestCheckLang tests.TestPoLocaleConsistency tests.TestOutpostExchange；涉及送貨地區時追加 tests.TestDeliveryAreaConfig，涉及倉庫對映時追加 tests.TestWarehouseSwitchOCR。
3. 執行 python main_debug.py 驗證配置控制元件和資料載入。
4. 檢查日誌並遍歷受影響的日常任務，確認當前語言 OCR、據點順序和商品選項均正確。

相關文件：日常任務 / 刷體力 / 倉庫物品轉移