送貨地區維護工作流

返回：文件索引 / README

本文說明自動送貨模組在新增或調整地區時應該如何維護。通常只需要更新地區資料和對應模板資源，不必修改送貨流程本身。

---

一、適用場景

以下情況建議按這份流程處理：

1. 新增一個送貨地區。
2. 調整現有地區的委託地點、目標 NPC 或 OCR 容錯規則。
3. 補充新的接單特徵標籤或模板標註。
4. 修正某個地區的傳送點搜尋區域。
5. 新增接單券數或補齊多語言地點/NPC 名稱。

---

二、先改資料

送貨地區的主配置集中在 src/data/delivery_area.py。

2.1 地區配置結構

每個地區通常需要補齊以下欄位：

欄位	作用
task_model_area	地區名。若與地區名一致，可以省略。
feature_label_area_code	接單特徵標籤字首，例如武陵使用 wuling。
delivery_locations	當前地區可識別的區域名列表。
delivery_targets_by_location	每個地點對應的目標 NPC 列表。
transfer_search_area	每個地點在地圖裡搜尋傳送點時使用的區域。
ocr_priority_locations	預留的 OCR 地點優先順序；當前只有 service 訪問器，任務流程尚未呼叫。

讀取和校驗這些欄位的入口位於 src/data/delivery_area_service.py，任務流程不應自行復制地區對映。

2.2 新增地區時的最小修改

如果只是新增一個地區，建議直接參考 src/data/delivery_area.py 裡現有的“武陵”配置，補一份完整塊：

1. 先填寫地區名。
2. 再填寫對應區域名列表和每個地點對應的目標 NPC。
3. 為每個地點補上傳送點搜尋區域。
4. 按需要補充新的接單特徵標籤。

2.3 接單特徵標籤

接單券數需要先加入 DELIVERY_TARGET_TICKET_NUM_OPTIONS。format_delivery_ticket_price_code() 會自動把正整數轉換為萬券價格碼，無需維護第二張對映表。

系統會把目標券數轉換成價格碼，再拼成形如 wuling_7_31w 的標籤。

券價格碼的含義如下：

價格碼	含義
7_31w	7.31 萬券
7_98w	7.98 萬券
11_9w	11.9 萬券
15_9w	15.9 萬券
16_3w	16.3 萬券

當前下拉值為 163000、159000、119000、79800、73100。新增數值後，必須存在 {feature_label_area_code}_{价格码} 的基礎標籤；否則 get_accept_feature_labels() 會返回空列表，即使 _2k/_4k 變體已經存在也不會啟用該券數。

如果新增地區需要接單特徵模板：

1. 先在 feature_label_area_code 中定義地區字首。
2. 再確認 src/data/FeatureList.py 裡已經存在對應標籤，例如 wuling_7_31w。
3. 如果沒有，在模板 Tab 裡框選裁圖後儲存；命名格式為 {feature_label_area_code}_{券价格码}。
4. 儲存時建議勾選“儲存列舉”，填入 src/data/FeatureList，這樣會自動生成對應 FeatureList 列舉，後續程式碼可直接引用，避免手寫標籤字串導致拼寫錯誤。
5. 建議一併補齊 _2k、_4k 等變體。

當前程式碼會在任務配置裡自動讀取地區列表，所以只要 DELIVERY_AREA_CONFIG 裡增加了新地區，UI 下拉框也會自動出現新選項。

2.4 地點、NPC 與本地化

delivery_area.py 使用簡體中文規範名作為資料鍵。新增地區、地點或目標 NPC 後，還要在 assets/lang/world_map.json 中補齊對應條目和現有 locale：

1. 地區和地點用於地圖文本、地點提取與傳送區域回填。
2. NPC 名用於 get_delivery_target_ocr_pattern() 生成當前語言 OCR 匹配器。
3. 等長字元的穩定 OCR 混淆可加入 assets/ocr_fix/ocr_text_fix.json。執行時補丁會擴充套件傳入 OCR 的字串/正則匹配條件，使其容忍錯字，但不會改寫 OCR 輸出文本；不要把錯字寫進規範主資料。

---

四、驗證順序

flowchart TD
    A[新增或调整地区数据] --> B[打开自动送货配置]
    B --> C{地区下拉是否出现}
    C -->|否| D[检查 DELIVERY_AREA_CONFIG]
    C -->|是| E[运行仅接取或仅送货]
    E --> F{地点识别正确}
    F -->|否| G[调整 OCR 容错或地点配置]
    F -->|是| H{目标 NPC 正确}
    H -->|否| I[调整目标列表或 OCR 修正]
    H -->|是| J[验证传送点和滑索序列]

建議按下面順序檢查，能最快定位問題：

1. 開啟任務配置頁，確認地區下拉框裡已經出現新地區。
2. 執行一次“僅接取”或“僅送貨”流程，驗證地點識別是否正確。
3. 檢查目標 NPC 是否能被 OCR 正確識別。
4. 如果傳送點選擇錯誤，再回頭調整 transfer_search_area；配置支援 {"preset": "top"} 或 x/y/to_x/to_y 相對座標。
5. 如果接單按鈕識別失敗，確認基礎價格標籤存在，再補模板和解析度變體。
6. 執行聚焦測試：

python -m unittest tests.TestDeliveryAreaConfig tests.TestCheckLang tests.TestPoLocaleConsistency

新增券數時應在 TestDeliveryAreaConfig.test_get_accept_feature_labels_returns_mapping_by_target_ticket 中補期望值；新增自定義區域欄位時補 service 層測試，不要只依賴手工執行。

---

五、維護原則

1. 地區資料優先放在 src/data/delivery_area.py，不要把地區邏輯散落到任務類裡。
2. 等長字元混淆的匹配容錯由 assets/ocr_fix/ocr_text_fix.json 統一維護；它擴充套件匹配條件而不改寫識別結果。長度變化、詞序變化或業務專屬規則應維護在語言 pattern 或對應解析邏輯中。
3. 使用框架的模板 Tab 功能新增模板。
4. 新地區先補資料，再補模板，最後做一次最小閉環驗證。

相關文件：自動送貨 / 滑索與送貨邏輯