賬號唯一ID與多賬戶覆蓋預設邏輯

返回：開發文件索引 / README

本文說明當前版本下，從第一次啟動軟體開始，賬號身份與賬號覆蓋配置的預設行為。

1. 首次啟動時會發生什麼

1. 軟體會載入賬號覆蓋儲存檔案 configs/account_scoped_overrides.json。
2. 如果該檔案不存在或無法解析，會使用內建空結構：
   • account_list_text: 空字串
   • account_registry: 空物件
   • accounts: 空物件
   • map_contents: 空物件
3. 此時系統裡還沒有任何賬號ID、賬號覆蓋或地圖同步 content。

2. 賬號身份規則（預設且固定）

當前規則已經固定為：

1. 賬號名（手機號）是預設穩定身份來源。
2. 密碼不參與身份判定，任務頁舊格式 账号,密码 中的密碼會被忽略。
3. 儲存賬號列表時，賬號名與登錄檔當前 username 精確匹配才複用原 account_id；歷史 aliases 不參與這一步。
4. 賬號名變化：直接建立新的 account_id。

也就是說，賬號名變化不會自動繼承舊賬號的覆蓋配置。

3. 在賬號配置頁點選“儲存賬號列表”時

當你在“賬號配置”頁儲存賬號列表後，會執行以下流程：

1. 解析每行賬號名（手機號）。
2. 相容舊格式 账号,密码，但密碼會被忽略。
3. 對每個賬號名查詢是否已有 account_id：
   • 找到則複用。
   • 找不到則新建。
4. 寫回 account_registry（賬號ID到賬號名對映）和 account_list_text。
5. 狀態列會顯示本次“複用ID數量”和“新建ID數量”。

flowchart TD
    A[保存账号列表] --> B[逐行解析账号名]
    B --> C{账号名是否已有 ID}
    C -->|有| D[复用 account_id]
    C -->|无| E[创建 account_id]
    D --> F[写回 account_registry]
    E --> F
    F --> G[写回 account_list_text]
    G --> H[刷新账号下拉]

4. 任務覆蓋是怎麼存的

賬號任務覆蓋按下面結構儲存：

1. accounts[account_id][task_class_name][config_key] = override_value
2. 賬號覆蓋的主鍵是 account_id，不是密碼。
3. 讀取時支援舊資料相容（歷史上用賬號名當鍵的結構仍可回退讀取）。

地圖同步 content 獨立儲存在 map_contents[account_id]，供 物品導航 讀取官方地圖 WebSocket 憑證。賬號頁寫入 content 時，如果賬號尚未註冊，會建立登錄檔 ID。

5. 任務執行時怎麼讀取覆蓋

執行任務時，配置讀取順序是：

1. 先讀任務原始配置值（base value）。
2. 檢查是否允許賬號覆蓋：
   • 如果任務配置裡有“多賬戶獨立配置”，則必須該開關為 True。
   • 如果任務配置裡沒有該開關，則預設允許覆蓋（相容邏輯）。
3. 使用 current_account_id（或相容回退賬號名）讀取當前任務覆蓋。多賬戶迴圈只做非建立式解析；賬號頁尚未註冊該賬號時，執行上下文會臨時以賬號名作為鍵，不會自動落盤生成 ID。
4. 如果該鍵存在覆蓋值，則用覆蓋值替換原值。

6. 首次啟動下的預設開關狀態

對於繼承 AccountMixin 的任務，預設配置是：

1. 多賬戶模式：False
2. 多賬戶獨立配置：False
3. 賬號列表：示例文本（賬號1、賬號2、賬號3）

因此第一次啟動後，如果你不改任務開關：

1. 多賬戶迴圈不會啟用。
2. 賬號覆蓋也不會生效（因為“多賬戶獨立配置”預設是關）。

7. 賬號頁賬號列表 與 任務賬號列表 的關係

兩者當前是獨立的：

1. 賬號配置頁儲存的是覆蓋系統自己的 account_list_text，用於賬號ID管理和覆蓋編輯。
2. 任務執行時 get_account_list() 讀取的是任務自身配置裡的“賬號列表”。
3. 所以賬號頁改了賬號列表，不會自動同步到各任務“賬號列表”欄位。
4. 當前任務執行只讀取賬號名；舊格式 账号,密码 中密碼欄位會被忽略。
5. 任務頁賬號列表中的空行和賬號名為空的行會被跳過。

8. 哪些任務會顯示在賬號配置頁

賬號配置頁只展示顯式宣告 support_multi_account = True 的任務。 當前典型任務包括：

1. DailyTask
2. DeliveryTask

ItemNavigatorTask 使用賬號頁儲存的地圖同步 content，但不宣告 support_multi_account，因此不作為多賬號任務覆蓋項展示。

9. 實操建議

為了讓“賬號覆蓋”按預期生效，建議按順序操作：

1. 在賬號配置頁儲存賬號列表（僅賬號名）。
2. 在對應任務頁開啟“多賬戶獨立配置”。
3. （如需多賬號迴圈）再開啟“多賬戶模式”並維護任務頁賬號列表。
4. 回到賬號配置頁按賬號與任務編輯覆蓋項。

相關文件：賬號配置使用者指南 / 物品導航與即時檢測 / API 參考