日常送禮維護工作流

返回：文件索引 / README

簡短說明：新增聯絡（送禮）物件時，需要同步角色主資料、本地化識別名和 *_contact 模板。角色主資料的 zh 欄位決定「優先送禮物件」下拉中的規範中文值；模板與角色的 en 欄位匹配後，該物件才會進入按當前語言本地化的實際可聯絡集合。

角色主資料（canonical）已剝離為 JSON：assets/data/characters.json，由 src/data/characters.py（薄載入器）讀取，保持原匯入路徑相容。

步驟：

flowchart TD
    A[新增送礼对象] --> B[更新 assets/data/characters.json]
    B --> C[更新 assets/lang/characters.json]
    C --> D[在 Debug 模板 Tab 添加 contact 模板]
    D --> E{是否生成枚举}
    E -->|是| F[自动更新 FeatureList]
    E -->|否| G[确认 FeatureList 已有标签]
    F --> H[运行本地化与语法测试]
    G --> H
    H --> I[重启并验证下拉与联络识别]

在 assets/data/characters.json 中新增角色條目（示例）：

"han_mei": {
    "zh": "寒梅",
    "en": "hanmei",
    "stars": 5
}

提示：新幹員的官方多語言譯名可自動同步（scripts/sync_character_langs.py，資料來源 endfield.wiki.gg）；該指令碼會自動補 assets/lang/characters.json 節點，但 canonical 的 en（內部 ID）需人工確認。

在程式的 Debug → 模板 Tab 中框選聯絡模板並儲存（命名示例：hanmei_contact）。儲存後模板會寫入 assets 並可選生成列舉。
在 assets/lang/characters.json 中為角色字典鍵（示例中的 han_mei）補齊現有 locale。執行時通過這個鍵生成當前語言的聯絡識別對映；缺項時會回退到 canonical 的 zh。這不會改變下拉框儲存和顯示的規範中文值。

說明/驗證：

模板儲存後，若勾選“儲存列舉”，工具會把 hanmei_contact（或相應名字）寫入 src/data/FeatureList.py。如果未勾選，也可手動在 FeatureList 中新增 hanmei_contact。
「優先送禮物件」下拉直接來自 characters.all_list，其值始終是 canonical 中的規範中文名，不隨介面語言本地化；所以只新增角色資料也會出現選項。
實際可聯絡集合由 get_contact_list_with_feature_list(self.lang) 計算：對映鍵是 characters.json 提供的當前語言識別名，對映值是模板標籤。FeatureList 標籤必須與角色的 en + '_contact' 完全一致。缺少模板或列舉時，選項雖然可見，但自動聯絡無法使用該物件。

驗證命令：

python -m compileall src/data/characters.py src/data/characters_utils.py
python -m unittest tests.TestCheckLang tests.TestPoLocaleConsistency

隨後執行 python main_debug.py，確認下拉顯示規範中文名，並在目標遊戲語言下實際驗證本地化名稱對映及該角色的聯絡模板可以命中。

最小原則：不修改任務流程程式碼；只維護角色資料、本地化 JSON 和一個聯絡模板/列舉，並完成聚焦驗證。

相關文件：日常任務 / 影像模板匹配示例