從零開始理解並使用完整 API

Machine Component 需要穩定 fingerprint，但不希望保存原始序號時。

• 先確認輸入值或檔案是你真正要綁定的穩定資料。

• 只計算雜湊、fingerprint 或本機資源資訊。
• 不會建立 License、Machine、Device Registration 或扣除 Usage。

格式為 <prefix>:<sha256> 的字串。

• ValueError：value 為空。

• namespace 應固定且與元件種類相關。
• 同一 namespace 與 value 會得到同一結果。

同步、本機計算

不會建立背景執行緒。

• 在目前呼叫執行緒計算 checksum、fingerprint 或讀取系統資訊。

• 決定何時呼叫並保存結果。
• 對檔案 I/O 錯誤提供可理解訊息。

• 建立 ClientConfig 前、準備 ValidationScope 或同步 Component 前。

計算大型檔案 checksum 可能阻塞；GUI 應在 worker thread 執行。

準備可信輸入。 → 呼叫 helper。 → 把結果交給後續驗證或 Component API。

不連線。只讀取本機值、檔案或系統資訊。

不修改 Server；可能只在記憶體產生 checksum、fingerprint 或 metrics。

輸入檔案暫時被占用時可在確認路徑正確後重試；輸入值錯誤則應先修正，不要無限重試。

確認結果格式符合方法文件，並以同一輸入重算得到相同結果。

把錯誤描述成『本機資料無法讀取』並顯示安全化路徑，不要輸出敏感原始序號。

1. 確認檔案存在且目前帳號可讀。
2. 確認 fingerprint 輸入是長期穩定值，而不是時間、暫存路徑或隨機值。

• 把會變動的路徑、時間或暫存值當成永久 fingerprint。
• 把 Platform／SDK 版本誤當成檔案 checksum。

Policy 要求 checksum scope，或應用程式需要確認受保護 Artifact 時。

• 先確認輸入值或檔案是你真正要綁定的穩定資料。

• 只計算雜湊、fingerprint 或本機資源資訊。
• 不會建立 License、Machine、Device Registration 或扣除 Usage。

十六進位雜湊字串。

• FileNotFoundError／OSError：檔案不可讀。
• ValueError：演算法不支援。

• 不要把 Platform 版本代替 checksum。

同步、本機計算

不會建立背景執行緒。

• 在目前呼叫執行緒計算 checksum、fingerprint 或讀取系統資訊。

• 決定何時呼叫並保存結果。
• 對檔案 I/O 錯誤提供可理解訊息。

• 建立 ClientConfig 前、準備 ValidationScope 或同步 Component 前。

計算大型檔案 checksum 可能阻塞；GUI 應在 worker thread 執行。

準備可信輸入。 → 呼叫 helper。 → 把結果交給後續驗證或 Component API。

不連線。只讀取本機值、檔案或系統資訊。

不修改 Server；可能只在記憶體產生 checksum、fingerprint 或 metrics。

輸入檔案暫時被占用時可在確認路徑正確後重試；輸入值錯誤則應先修正，不要無限重試。

確認結果格式符合方法文件，並以同一輸入重算得到相同結果。

把錯誤描述成『本機資料無法讀取』並顯示安全化路徑，不要輸出敏感原始序號。

1. 確認檔案存在且目前帳號可讀。
2. 確認 fingerprint 輸入是長期穩定值，而不是時間、暫存路徑或隨機值。

• 把會變動的路徑、時間或暫存值當成永久 fingerprint。
• 把 Platform／SDK 版本誤當成檔案 checksum。

要預覽或自行提供 Machine Profile 資源資訊時。

• 先確認輸入值或檔案是你真正要綁定的穩定資料。

• 只計算雜湊、fingerprint 或本機資源資訊。
• 不會建立 License、Machine、Device Registration 或扣除 Usage。

MachineMetrics。

• 通常不拋例外；不可讀欄位會回 0。

• ClientConfig.auto_collect_machine_metrics=True 時 SDK 會自動收集。

同步、本機計算

不會建立背景執行緒。

• 在目前呼叫執行緒計算 checksum、fingerprint 或讀取系統資訊。

• 決定何時呼叫並保存結果。
• 對檔案 I/O 錯誤提供可理解訊息。

• 建立 ClientConfig 前、準備 ValidationScope 或同步 Component 前。

計算大型檔案 checksum 可能阻塞；GUI 應在 worker thread 執行。

準備可信輸入。 → 呼叫 helper。 → 把結果交給後續驗證或 Component API。

不連線。只讀取本機值、檔案或系統資訊。

不修改 Server；可能只在記憶體產生 checksum、fingerprint 或 metrics。

輸入檔案暫時被占用時可在確認路徑正確後重試；輸入值錯誤則應先修正，不要無限重試。

確認結果格式符合方法文件，並以同一輸入重算得到相同結果。

把錯誤描述成『本機資料無法讀取』並顯示安全化路徑，不要輸出敏感原始序號。

1. 確認檔案存在且目前帳號可讀。
2. 確認 fingerprint 輸入是長期穩定值，而不是時間、暫存路徑或隨機值。

• 把會變動的路徑、時間或暫存值當成永久 fingerprint。
• 把 Platform／SDK 版本誤當成檔案 checksum。

每個 Product／Namespace 建立一個長生命週期 Client instance。

• 先向管理員取得 Gateway URL、Product UUID、固定 Product Namespace、Gateway Public Key 與 Key ID。
• 確認 Windows TPM 可用，並決定 registration.json 與 Connection Log 的保存位置。

• 只在記憶體建立 Client 設定與物件。
• 直到呼叫註冊、驗證、Heartbeat、Usage 或其他線上方法前，不會修改 Server。

DeviceLicenseClient。

• ValueError：URL、Public Key、Clock Skew 或 Heartbeat 設定不合法。
• TPMUnavailableError：實際存取 TPM 時。

• 同一 Product 的 product_namespace 必須長期固定。
• 不要把 Admin Token、License Token 或 Gateway Private Key 放入 ClientConfig。

同步、本機、立即回傳

不會建立背景執行緒。

• 只驗證設定並建立 Python 物件。

• 在應用程式啟動時建立一個長生命週期 Client。
• 自行保存 Client reference；不要每個按鈕事件都重新建立。

• 應用程式啟動或依賴注入初始化階段。

不做網路 I/O，通常只花極短時間；參數不合法時立即拋 ValueError。

建立 ClientConfig。 → 建立 DeviceLicenseClient。 → 後續由其他 API 使用同一 Client。

不連線。只在目前 Python 程序中建立設定與 Client 物件。

不寫入 Server；通常也不建立 registration.json。

建立失敗通常是參數問題，修正設定後直接重建 Client，不需要網路重試。

Client 物件成功建立，而且公開設定、Namespace 與 Gateway 公鑰和管理員提供值一致。

設定錯誤時顯示『授權元件設定不完整，請聯絡管理員』，不要要求一般使用者猜 UUID 或公鑰。

1. 逐字比對 Product UUID、Namespace、Gateway URL 與 Key ID。
2. 確認 URL 只包含 HTTPS 根網址，沒有手動附加 /device/v1。

• 把 /device/v1 手動接到 Gateway URL 後面。
• 把 Admin Token、License Token 或 Gateway Private Key 放進 Client。
• 每個版本更換 product_namespace，造成同一產品被視為不同本機身分。

UI 要決定是否顯示首次 License Key 輸入欄時。

• ClientConfig 的 Product ID 與 Namespace 必須和建立 registration.json 時一致。

• 主要讀取 registration.json、TPM Key 與目前 fingerprint。
• 除非方法文件明確說明，這一類方法不會向 Server 重新驗證 License。

bool。

• 無特定 SDK 例外。

• 只代表本機有 registration.json，不代表 License 現在仍有效。

同步、本機狀態讀取

不會建立背景執行緒。

• 讀取 registration.json、TPM Key metadata 或本機 fingerprint。

• 把結果當成診斷或流程分支，不要當成最新 License 驗證。

• 應用程式啟動時決定是否要求 License Key。
• 支援頁面或修復流程開始前。

大多快速完成；實際存取 TPM 的方法可能短暫阻塞。

讀取本機狀態。 → 判斷是否健康。 → 需要最新授權時再呼叫線上驗證。

主要不連線；讀取 registration.json、TPM Key 與本機 fingerprint。

唯讀方法不修改本機或 Server。

本機檔案暫時鎖定可短暫重試；內容損壞、Namespace 不一致或 TPM Key 遺失時不要自動反覆重試。

檢查回傳的 healthy、problem_code、device_id、machine_id 與 key_name 是否符合目前 Product。

顯示『本機授權身分需要修復』與 problem_code；不要直接提示使用者刪除所有 TPM Key。

1. 先確認程式使用正確的 state_directory 與 product_namespace。
2. 使用 local_identity_info() 取得 recovery_hint，再決定是否需要管理員協助。

• 看到 is_activated=True 就當成 License 目前有效。
• 手動修改 registration.json。
• 把其他產品的 TPM Key 當成目前產品的 Key。

啟動流程要安全地只在第一次詢問 Key。

• ClientConfig 的 Product ID 與 Namespace 必須和建立 registration.json 時一致。

• 主要讀取 registration.json、TPM Key 與目前 fingerprint。
• 除非方法文件明確說明，這一類方法不會向 Server 重新驗證 License。

bool。

• 無特定 SDK 例外。

• 不要把 License Key 寫死在程式中。

同步、本機狀態讀取

不會建立背景執行緒。

• 讀取 registration.json、TPM Key metadata 或本機 fingerprint。

• 把結果當成診斷或流程分支，不要當成最新 License 驗證。

• 應用程式啟動時決定是否要求 License Key。
• 支援頁面或修復流程開始前。

大多快速完成；實際存取 TPM 的方法可能短暫阻塞。

讀取本機狀態。 → 判斷是否健康。 → 需要最新授權時再呼叫線上驗證。

主要不連線；讀取 registration.json、TPM Key 與本機 fingerprint。

唯讀方法不修改本機或 Server。

本機檔案暫時鎖定可短暫重試；內容損壞、Namespace 不一致或 TPM Key 遺失時不要自動反覆重試。

檢查回傳的 healthy、problem_code、device_id、machine_id 與 key_name 是否符合目前 Product。

顯示『本機授權身分需要修復』與 problem_code；不要直接提示使用者刪除所有 TPM Key。

1. 先確認程式使用正確的 state_directory 與 product_namespace。
2. 使用 local_identity_info() 取得 recovery_hint，再決定是否需要管理員協助。

• 看到 is_activated=True 就當成 License 目前有效。
• 手動修改 registration.json。
• 把其他產品的 TPM Key 當成目前產品的 Key。

支援頁面要顯示本機身分檔位置時。

• ClientConfig 的 Product ID 與 Namespace 必須和建立 registration.json 時一致。

• 主要讀取 registration.json、TPM Key 與目前 fingerprint。
• 除非方法文件明確說明，這一類方法不會向 Server 重新驗證 License。

Path。

• 無特定 SDK 例外。

• 不要手動編輯該 JSON。

同步、本機狀態讀取

不會建立背景執行緒。

• 讀取 registration.json、TPM Key metadata 或本機 fingerprint。

• 把結果當成診斷或流程分支，不要當成最新 License 驗證。

• 應用程式啟動時決定是否要求 License Key。
• 支援頁面或修復流程開始前。

大多快速完成；實際存取 TPM 的方法可能短暫阻塞。

讀取本機狀態。 → 判斷是否健康。 → 需要最新授權時再呼叫線上驗證。

主要不連線；讀取 registration.json、TPM Key 與本機 fingerprint。

唯讀方法不修改本機或 Server。

本機檔案暫時鎖定可短暫重試；內容損壞、Namespace 不一致或 TPM Key 遺失時不要自動反覆重試。

檢查回傳的 healthy、problem_code、device_id、machine_id 與 key_name 是否符合目前 Product。

顯示『本機授權身分需要修復』與 problem_code；不要直接提示使用者刪除所有 TPM Key。

1. 先確認程式使用正確的 state_directory 與 product_namespace。
2. 使用 local_identity_info() 取得 recovery_hint，再決定是否需要管理員協助。

• 看到 is_activated=True 就當成 License 目前有效。
• 手動修改 registration.json。
• 把其他產品的 TPM Key 當成目前產品的 Key。

只需要查看 device_id、machine_id、license_id、fingerprint 時。

• ClientConfig 的 Product ID 與 Namespace 必須和建立 registration.json 時一致。

• 主要讀取 registration.json、TPM Key 與目前 fingerprint。
• 除非方法文件明確說明，這一類方法不會向 Server 重新驗證 License。

DeviceRegistration 或 None。

• LocalIdentityError：內容損壞或 Product 不一致時可能由後續一致性檢查發現。

• 不會做線上驗證。

同步、本機狀態讀取

不會建立背景執行緒。

• 讀取 registration.json、TPM Key metadata 或本機 fingerprint。

• 把結果當成診斷或流程分支，不要當成最新 License 驗證。

• 應用程式啟動時決定是否要求 License Key。
• 支援頁面或修復流程開始前。

大多快速完成；實際存取 TPM 的方法可能短暫阻塞。

讀取本機狀態。 → 判斷是否健康。 → 需要最新授權時再呼叫線上驗證。

主要不連線；讀取 registration.json、TPM Key 與本機 fingerprint。

唯讀方法不修改本機或 Server。

本機檔案暫時鎖定可短暫重試；內容損壞、Namespace 不一致或 TPM Key 遺失時不要自動反覆重試。

檢查回傳的 healthy、problem_code、device_id、machine_id 與 key_name 是否符合目前 Product。

顯示『本機授權身分需要修復』與 problem_code；不要直接提示使用者刪除所有 TPM Key。

1. 先確認程式使用正確的 state_directory 與 product_namespace。
2. 使用 local_identity_info() 取得 recovery_hint，再決定是否需要管理員協助。

• 看到 is_activated=True 就當成 License 目前有效。
• 手動修改 registration.json。
• 把其他產品的 TPM Key 當成目前產品的 Key。

啟動前診斷、重置確認或支援工具。

• ClientConfig 的 Product ID 與 Namespace 必須和建立 registration.json 時一致。

• 主要讀取 registration.json、TPM Key 與目前 fingerprint。
• 除非方法文件明確說明，這一類方法不會向 Server 重新驗證 License。

LocalIdentityInfo。

• TPMUnavailableError／TPMOperationError。

• healthy=False 時不要直接忽略問題。

同步、本機狀態讀取

不會建立背景執行緒。

• 讀取 registration.json、TPM Key metadata 或本機 fingerprint。

• 把結果當成診斷或流程分支，不要當成最新 License 驗證。

• 應用程式啟動時決定是否要求 License Key。
• 支援頁面或修復流程開始前。

大多快速完成；實際存取 TPM 的方法可能短暫阻塞。

讀取本機狀態。 → 判斷是否健康。 → 需要最新授權時再呼叫線上驗證。

主要不連線；讀取 registration.json、TPM Key 與本機 fingerprint。

唯讀方法不修改本機或 Server。

本機檔案暫時鎖定可短暫重試；內容損壞、Namespace 不一致或 TPM Key 遺失時不要自動反覆重試。

檢查回傳的 healthy、problem_code、device_id、machine_id 與 key_name 是否符合目前 Product。

顯示『本機授權身分需要修復』與 problem_code；不要直接提示使用者刪除所有 TPM Key。

1. 先確認程式使用正確的 state_directory 與 product_namespace。
2. 使用 local_identity_info() 取得 recovery_hint，再決定是否需要管理員協助。

• 看到 is_activated=True 就當成 License 目前有效。
• 手動修改 registration.json。
• 把其他產品的 TPM Key 當成目前產品的 Key。

明確只做首次註冊時；一般應優先使用 ensure_registered()。

• 第一次執行才準備 License Key。
• 確認 Gateway URL、Product UUID、Namespace 與 Gateway Public Key 都是管理員提供的正式值。
• 確認裝置 TPM 可建立不可匯出 P-256 Key。

• Client 建立 TPM Key，對一次性 Challenge 簽章。
• Gateway 驗證後建立 Device Registration，並依 Policy 建立或關聯 Machine。
• 成功後只保存公開 registration 資料，不保存 License Key。

已驗證的 LicenseState。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• LicenseKeyRequiredError
• LocalIdentityError
• TPMUnavailableError／TPMOperationError
• GatewaySignatureError
• GatewayError
• LicenseInvalidError

• License Key 只在此請求使用，不寫入 registration.json。

同步網路交易

不會建立背景執行緒。

• 在同一呼叫中完成 Challenge、TPM 簽章、Gateway 驗證與註冊。

• 只在必要時安全取得 License Key。
• 在 worker thread／啟動畫面執行，捕捉所有授權例外。
• 成功後才開放受保護功能。

• 首次啟用。
• ensure_registered() 用於每次啟動的一次註冊或驗證。

會阻塞到 HTTPS 回應或 timeout_seconds；GUI 不應在主執行緒直接呼叫。

準備 Client 與可能的 License Key。 → 同步呼叫。 → 檢查 LicenseState／Entitlement。 → 繼續啟動或 fail closed。

會透過 HTTPS Gateway 執行 Challenge、TPM proof、License 驗證與首次註冊。

成功時會建立或關聯 Server-side Device Registration／Machine，並在本機保存不含 License Key 的 registration.json。

只有明確的暫時性網路錯誤適合有限次退避重試。收到 License 無效、Machine 上限、簽章失敗或 TPM 錯誤時不可盲目重送。

成功必須同時滿足：回傳 LicenseState.valid=True、本機 registration 存在、Gateway 回應簽章已驗證。

第一次啟用失敗時顯示可行動原因，例如 Key 無效、裝置上限、TPM 不可用或網路中斷；不要把所有錯誤都顯示成『伺服器錯誤』。

1. 查看 connection.log 中最後一個成功事件與下一個失敗事件。
2. 確認 License Key 只在本次輸入，沒有被寫入設定檔或 Log。
3. TPM 錯誤先保留現場，不要先刪除 Key。

• 每次啟動都要求 License Key。
• 註冊失敗後直接刪除 TPM Key，沒有先看 problem_code 與 recovery_hint。
• 把首次註冊和管理員解除 Machine 席位混為一談。

程式語意偏向『啟用』而非『註冊』時。

• 第一次執行才準備 License Key。
• 確認 Gateway URL、Product UUID、Namespace 與 Gateway Public Key 都是管理員提供的正式值。
• 確認裝置 TPM 可建立不可匯出 P-256 Key。

• Client 建立 TPM Key，對一次性 Challenge 簽章。
• Gateway 驗證後建立 Device Registration，並依 Policy 建立或關聯 Machine。
• 成功後只保存公開 registration 資料，不保存 License Key。

LicenseState。

• 與 register() 相同。

• 不會在已註冊狀態下自動切換 License。

同步網路交易

不會建立背景執行緒。

• 在同一呼叫中完成 Challenge、TPM 簽章、Gateway 驗證與註冊。

• 只在必要時安全取得 License Key。
• 在 worker thread／啟動畫面執行，捕捉所有授權例外。
• 成功後才開放受保護功能。

• 首次啟用。
• ensure_registered() 用於每次啟動的一次註冊或驗證。

會阻塞到 HTTPS 回應或 timeout_seconds；GUI 不應在主執行緒直接呼叫。

準備 Client 與可能的 License Key。 → 同步呼叫。 → 檢查 LicenseState／Entitlement。 → 繼續啟動或 fail closed。

會透過 HTTPS Gateway 執行 Challenge、TPM proof、License 驗證與首次註冊。

成功時會建立或關聯 Server-side Device Registration／Machine，並在本機保存不含 License Key 的 registration.json。

只有明確的暫時性網路錯誤適合有限次退避重試。收到 License 無效、Machine 上限、簽章失敗或 TPM 錯誤時不可盲目重送。

成功必須同時滿足：回傳 LicenseState.valid=True、本機 registration 存在、Gateway 回應簽章已驗證。

第一次啟用失敗時顯示可行動原因，例如 Key 無效、裝置上限、TPM 不可用或網路中斷；不要把所有錯誤都顯示成『伺服器錯誤』。

1. 查看 connection.log 中最後一個成功事件與下一個失敗事件。
2. 確認 License Key 只在本次輸入，沒有被寫入設定檔或 Log。
3. TPM 錯誤先保留現場，不要先刪除 Key。

• 每次啟動都要求 License Key。
• 註冊失敗後直接刪除 TPM Key，沒有先看 problem_code 與 recovery_hint。
• 把首次註冊和管理員解除 Machine 席位混為一談。

絕大多數應用程式的標準啟動入口。

• 第一次執行才準備 License Key。
• 確認 Gateway URL、Product UUID、Namespace 與 Gateway Public Key 都是管理員提供的正式值。
• 確認裝置 TPM 可建立不可匯出 P-256 Key。

• Client 建立 TPM Key，對一次性 Challenge 簽章。
• Gateway 驗證後建立 Device Registration，並依 Policy 建立或關聯 Machine。
• 成功後只保存公開 registration 資料，不保存 License Key。

有效的 LicenseState。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• LicenseKeyRequiredError
• LocalIdentityError
• LicenseInvalidError
• FeatureNotLicensedError（若後續 require）
• GatewayError
• GatewaySignatureError
• TPMUnavailableError／TPMOperationError

• recover_local_identity=True 只有在你接受自動重建本機身分時才使用。

同步網路交易

不會建立背景執行緒。

• 在同一呼叫中完成 Challenge、TPM 簽章、Gateway 驗證與註冊。

• 只在必要時安全取得 License Key。
• 在 worker thread／啟動畫面執行，捕捉所有授權例外。
• 成功後才開放受保護功能。

• 首次啟用。
• ensure_registered() 用於每次啟動的一次註冊或驗證。

會阻塞到 HTTPS 回應或 timeout_seconds；GUI 不應在主執行緒直接呼叫。

準備 Client 與可能的 License Key。 → 同步呼叫。 → 檢查 LicenseState／Entitlement。 → 繼續啟動或 fail closed。

本機未註冊時執行首次啟用；已有健康本機身分時執行 TPM Challenge 線上驗證。

首次成功會建立 Server Device Registration／Machine 與本機 registration.json；後續驗證只更新授權狀態。

只對明確暫時性網路錯誤有限重試。recover_local_identity=False 時，身分不一致必須先顯示診斷，不可偷偷重建。

state.valid=True、registration() 可讀、local_identity_info().healthy=True，且重新啟動時 requires_license_key=False。

第一次使用顯示 License Key 輸入；日常啟動只顯示驗證進度。遇到本機身分問題時顯示 problem_code 與管理員處置。

1. 先檢查 requires_license_key，再決定是否要求輸入 Key。
2. 確認 License Key 沒有保存到 registration.json。
3. 測試第一次、第二次啟動與本機資料損壞三條路徑。

• 每次啟動都要求 License Key。
• 註冊失敗後直接刪除 TPM Key，沒有先看 problem_code 與 recovery_hint。
• 把首次註冊和管理員解除 Machine 席位混為一談。

需要自行檢查 state.valid／state.code 而不想立刻拋 LicenseInvalidError 時。

• 本機必須已有健康的 Device Registration 與 TPM Key。
• 網路可連到 HTTPS Gateway，且 Client 固定正確 Gateway Public Key。

• Gateway 發出一次性 Challenge，Client 使用 TPM 簽章證明是原裝置。
• 回傳最新 License 狀態、Entitlement、Usage 與 Policy 相關欄位；不會自動執行你的功能。

LicenseState，可能 valid=False。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• LocalIdentityError
• GatewayError
• GatewaySignatureError
• TPMUnavailableError／TPMOperationError

• 不會因 valid=False 自動拋 LicenseInvalidError。

同步網路驗證

不會建立背景執行緒。

• 每次呼叫都建立新的 Challenge 並完成 TPM proof。

• 決定驗證頻率與重試策略。
• 將 License 拒絕與暫時網路錯誤分開處理。
• 在高價值操作前取得足夠新的狀態。

• 程式啟動。
• 高價值操作前。
• 長時間執行中的明確檢查點。

會阻塞到網路完成或 timeout_seconds；GUI 應移到 worker thread。

呼叫驗證。 → 驗證 Gateway 簽章。 → 檢查 valid／例外。 → 檢查 Entitlement。

透過 Gateway Challenge 與 TPM proof 取得最新 LicenseState。

不建立新 Machine；回傳 valid=False 也不自動拋 LicenseInvalidError。

暫時性網路錯誤可有限重試；valid=False 不應重試來規避 Server 決策。

必須由呼叫端明確檢查 state.valid、state.code 與 state.detail。

依 state.code 顯示過期、撤銷、額度、Scope 或裝置問題；不要只顯示『驗證失敗』。

1. 最常見錯誤是忘記檢查 state.valid。
2. 高價值功能更適合 validate_or_raise() 或 validate() 後立即 require_valid()。

• 忽略 GatewaySignatureError 後繼續執行。
• 只在程式啟動時驗證一次，長時間工作不重新確認。
• 使用 validate() 卻忘記檢查 state.valid。

功能入口、CLI 或不想手動判斷 valid 時。

• 本機必須已有健康的 Device Registration 與 TPM Key。
• 網路可連到 HTTPS Gateway，且 Client 固定正確 Gateway Public Key。

• Gateway 發出一次性 Challenge，Client 使用 TPM 簽章證明是原裝置。
• 回傳最新 License 狀態、Entitlement、Usage 與 Policy 相關欄位；不會自動執行你的功能。

有效的 LicenseState。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• LicenseInvalidError
• LocalIdentityError
• GatewayError
• GatewaySignatureError
• TPMUnavailableError／TPMOperationError

• 可從回傳 state.uses／max_uses 查看目前使用量。

同步網路驗證

不會建立背景執行緒。

• 每次呼叫都建立新的 Challenge 並完成 TPM proof。

• 決定驗證頻率與重試策略。
• 將 License 拒絕與暫時網路錯誤分開處理。
• 在高價值操作前取得足夠新的狀態。

• 程式啟動。
• 高價值操作前。
• 長時間執行中的明確檢查點。

會阻塞到網路完成或 timeout_seconds；GUI 應移到 worker thread。

呼叫驗證。 → 驗證 Gateway 簽章。 → 檢查 valid／例外。 → 檢查 Entitlement。

會透過 HTTPS Gateway 取得一次性 Challenge，並使用 TPM 簽章證明目前裝置身分。

一般不建立新 Machine；會讀取最新 License、Entitlement、Usage、Heartbeat 或 Scope 結果。

網路逾時可使用有限次指數退避。簽章錯誤、License 無效、Scope 不符或 TPM proof 失敗必須立即停止受保護功能。

確認回傳簽章已驗證，再依 validate() 的 state.valid 或 validate_or_raise() 是否成功判斷。

區分『暫時無法連線』與『授權已拒絕』；兩者都要阻擋高價值功能，但使用者處置不同。

1. 確認系統時間、DNS、TLS 憑證與 Gateway URL。
2. 若 state.valid=False，讀取 code 與 detail，而不是只看布林值。
3. GatewaySignatureError 一律視為信任鏈失敗。

• 忽略 GatewaySignatureError 後繼續執行。
• 只在程式啟動時驗證一次，長時間工作不重新確認。
• 使用 validate() 卻忘記檢查 state.valid。

validate() 後要以例外方式阻擋流程。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

同一個 LicenseState。

• LicenseInvalidError

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

只需要控制 UI 顯示，不立即拒絕流程時。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

bool。

• 無特定 SDK 例外。

• 真正執行功能前仍建議 require()。

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

一個功能需要多個權限條件時。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

bool。

• 無特定 SDK 例外。

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

多種方案任一可開啟同一功能時。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

bool。

• 無特定 SDK 例外。

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

每個受保護功能真正開始前。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

同一個 LicenseState。

• LicenseInvalidError
• FeatureNotLicensedError

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

高階功能需要多個功能碼時。

• 先從 ensure_registered()、validate() 或 validate_or_raise() 取得最新 LicenseState。
• Entitlement Code 必須與管理端建立的代碼完全一致。

• 只根據目前 LicenseState 做有效性與功能權限判斷。
• require 系列在不符合時拋例外，讓程式在功能入口 fail closed。

同一個 LicenseState。

• LicenseInvalidError
• FeatureNotLicensedError

同步、本機記憶體判斷

不會建立背景執行緒。

• 只檢查目前 LicenseState 物件。

• 確保 LicenseState 足夠新。
• 在每個真正受保護的核心函式入口再次 require。

• UI 顯示時可用 has*。
• 真正執行功能前使用 require*。

不做網路 I/O，立即回傳或拋授權例外。

先取得最新 state。 → 執行 has／require。 → 允許或拒絕功能。

不連線。只檢查目前記憶體中的 LicenseState。

不修改本機或 Server。

不需要重試；若狀態過舊，先重新呼叫 validate_or_raise() 或 session.check() 取得新狀態。

require 系列沒有拋例外，或 has／has_all／has_any 回傳符合預期。

對無權限功能顯示清楚的功能名稱與聯絡方式，不要顯示內部 Token、Policy JSON 或完整 Server 回應。

1. 確認 Entitlement Code 大小寫與管理端完全一致。
2. 確認真正的核心操作函式也執行 require，而不只限制按鈕。

• 只把按鈕設為 disabled，核心函式沒有再次 require。
• 把 has() 的 UI 判斷當成最終安全邊界。
• 硬編碼不存在或拼錯的 Entitlement Code。

GUI、CLI 與長時間自動化程式的推薦高階入口。

• 先決定程式是否真的需要 Machine Heartbeat、Process Seat、Check-in 或 Usage。
• 決定由 GUI Timer、工作迴圈或高價值操作入口在何時呼叫 session.check()。
• 理解 revalidate_interval_seconds 只是 session.check() 的到期門檻，不是背景排程。

• 進入 context 時同步完成 ensure_registered()、Entitlement Gate，以及選用的一次 Check-in／Seat 取得。
• machine_heartbeat=True 或 process_seat=True 才會建立背景 Heartbeat 執行緒；背景執行緒不會自動做完整 License 驗證。
• session.check() 由呼叫端主動執行：先檢查背景 Heartbeat 是否已失敗，再視 force_validate 或到期門檻同步重新驗證。
• 離開 Session 時停止背景 Heartbeat並釋放 Process Seat；不會解除 Server Machine。

LicenseSession context manager。

• 所有 Activation／Heartbeat／Process／Usage 相關例外。

• usage_increment_on_success 只在 with 區塊無例外時執行；若 increment 失敗，離開 context 時仍會拋錯。

先建立 context manager；真正工作在進入 with 時同步執行

machine_heartbeat=True 時建立一條 Machine Heartbeat daemon thread；process_seat=True 時再建立一條 Process Heartbeat daemon thread。revalidate_interval_seconds 絕不會建立背景驗證 thread。

• with 進入時：ensure_registered()、required_entitlements、可選的一次 Check-in、可選 Machine Heartbeat start、可選 Process Seat acquire/start。
• with 期間：只有已啟用的 Heartbeat 在背景自動 ping。
• with 正常離開：可選 Usage increment 一次，然後停止 threads 並釋放 Process Seat。

• 在 GUI Timer、工作迴圈 checkpoint 或高價值操作入口呼叫 session.check()。
• 需要立即取得撤銷／到期／Entitlement 變化時使用 force_validate=True。
• 處理所有例外並 fail closed。

• 不需要寫一個只為 Session 而存在的緊密 for 迴圈。
• GUI 可用既有 QTimer／after／scheduler，每 10～30 秒觸發 worker check。
• 高價值操作前強制驗證一次。

進入與離開可能同步連線；session.check() 到期或 force 時同步連線。UI 主 thread 需移交 worker。

建立 context。 → 進入時同步註冊／驗證。 → 背景只維持 Heartbeat。 → 呼叫端主動 check。 → 正常離開處理 Usage／Seat／thread。

進入 context 時會同步連線註冊／驗證；只有啟用 Machine／Process Heartbeat 時才有背景網路執行緒。完整 License revalidation 不會自動排程，必須由呼叫端執行 session.check()。

可能建立／維持／釋放 Process Seat，更新 Heartbeat、執行一次啟動 Check-in，或在正常離開時增加一次 Usage；不會自動解除 Server Machine。

Heartbeat 執行緒會依設定短暫重試；完整 License 驗證沒有隱藏重試迴圈。呼叫端應以明確 Timer／工作檢查點呼叫 session.check()，並對暫時網路錯誤採有限退避。

Session 進入成功；應用程式安排的每個 session.check() 都通過；高價值操作前的強制驗證通過；退出後 Process Seat 已釋放。

長時間程式應在狀態失效時鎖定受保護功能，保留未完成工作，並顯示重新連線或聯絡管理員的步驟。

1. 確認應用程式確實有 Timer、工作迴圈或操作入口會呼叫 session.check()。
2. 確認 revalidate_interval_seconds 是門檻而不是排程器。
3. 確認 GUI 主執行緒沒有被同步網路呼叫長時間阻塞。
4. 檢查背景 Heartbeat 的 last_error 與 consecutive_failures。

• 以為 revalidate_interval_seconds 會自己建立 Timer，因此從不呼叫 session.check()。
• 在無 sleep 的緊密 for 迴圈中一直呼叫 session.check(force_validate=True)，造成網路與 UI 負載。
• 在 GUI 主執行緒直接做可能阻塞到 timeout_seconds 的強制驗證。
• 程式發生授權錯誤後仍繼續執行受保護工作。

程式運行中要立即取得撤銷、到期或 Entitlement 變化。

• 先決定程式是否真的需要 Machine Heartbeat、Process Seat、Check-in 或 Usage。
• 決定由 GUI Timer、工作迴圈或高價值操作入口在何時呼叫 session.check()。
• 理解 revalidate_interval_seconds 只是 session.check() 的到期門檻，不是背景排程。

• 進入 context 時同步完成 ensure_registered()、Entitlement Gate，以及選用的一次 Check-in／Seat 取得。
• machine_heartbeat=True 或 process_seat=True 才會建立背景 Heartbeat 執行緒；背景執行緒不會自動做完整 License 驗證。
• session.check() 由呼叫端主動執行：先檢查背景 Heartbeat 是否已失敗，再視 force_validate 或到期門檻同步重新驗證。
• 離開 Session 時停止背景 Heartbeat並釋放 Process Seat；不會解除 Server Machine。

LicenseState。

• LicenseSDKError

同步、立即完整線上驗證

不建立背景執行緒。

• 呼叫 validate_or_raise()。
• 重新要求 required_entitlements。
• 更新 session.state 與上次驗證時間。

• 在 worker thread 執行。
• 捕捉並處理授權與網路例外。

• 管理端狀態剛變更後。
• 高價值操作前需要最新狀態時。
• 除錯時明確驗證。

一定做網路與 TPM 操作，最多阻塞到 timeout_seconds。

同步驗證。 → Entitlement Gate。 → 更新 state。 → 返回 LicenseState。

進入 context 時會同步連線註冊／驗證；只有啟用 Machine／Process Heartbeat 時才有背景網路執行緒。完整 License revalidation 不會自動排程，必須由呼叫端執行 session.check()。

可能建立／維持／釋放 Process Seat，更新 Heartbeat、執行一次啟動 Check-in，或在正常離開時增加一次 Usage；不會自動解除 Server Machine。

Heartbeat 執行緒會依設定短暫重試；完整 License 驗證沒有隱藏重試迴圈。呼叫端應以明確 Timer／工作檢查點呼叫 session.check()，並對暫時網路錯誤採有限退避。

Session 進入成功；應用程式安排的每個 session.check() 都通過；高價值操作前的強制驗證通過；退出後 Process Seat 已釋放。

長時間程式應在狀態失效時鎖定受保護功能，保留未完成工作，並顯示重新連線或聯絡管理員的步驟。

1. 確認應用程式確實有 Timer、工作迴圈或操作入口會呼叫 session.check()。
2. 確認 revalidate_interval_seconds 是門檻而不是排程器。
3. 確認 GUI 主執行緒沒有被同步網路呼叫長時間阻塞。
4. 檢查背景 Heartbeat 的 last_error 與 consecutive_failures。

• 以為 revalidate_interval_seconds 會自己建立 Timer，因此從不呼叫 session.check()。
• 在無 sleep 的緊密 for 迴圈中一直呼叫 session.check(force_validate=True)，造成網路與 UI 負載。
• 在 GUI 主執行緒直接做可能阻塞到 timeout_seconds 的強制驗證。
• 程式發生授權錯誤後仍繼續執行受保護工作。

每次高價值操作前與主事件迴圈安全點。

• 先決定程式是否真的需要 Machine Heartbeat、Process Seat、Check-in 或 Usage。
• 決定由 GUI Timer、工作迴圈或高價值操作入口在何時呼叫 session.check()。
• 理解 revalidate_interval_seconds 只是 session.check() 的到期門檻，不是背景排程。

• 進入 context 時同步完成 ensure_registered()、Entitlement Gate，以及選用的一次 Check-in／Seat 取得。
• machine_heartbeat=True 或 process_seat=True 才會建立背景 Heartbeat 執行緒；背景執行緒不會自動做完整 License 驗證。
• session.check() 由呼叫端主動執行：先檢查背景 Heartbeat 是否已失敗，再視 force_validate 或到期門檻同步重新驗證。
• 離開 Session 時停止背景 Heartbeat並釋放 Process Seat；不會解除 Server Machine。

自身。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• HeartbeatError
• ProcessSeatUnavailableError
• LicenseInvalidError
• FeatureNotLicensedError
• GatewayError

同步、由呼叫端主動觸發的一次檢查

不建立任何新執行緒；也不啟動迴圈。它只讀取既有 Heartbeat manager 的狀態，必要時在目前執行緒做一次完整驗證。

• 先呼叫 machine_lease.check()／process_lease.check()，只檢查背景 thread 已保存的錯誤。
• force_validate=True 時立即 refresh()。
• force_validate=False 且距離上次驗證已達 revalidate_interval_seconds 時才 refresh()。
• 若 interval=0 且 force_validate=False，永遠不會因時間自動連線重驗。

• 自行安排呼叫頻率。
• 捕捉 HeartbeatError 與 LicenseSDKError。
• 需要高價值即時性時明確 force_validate=True。

• GUI：Timer／worker 每 10～30 秒 check(False)，操作前 check(True)。
• CLI：每個主要步驟前。
• 服務：現有 scheduler 或工作迴圈 checkpoint。

純健康檢查通常立即完成；到期或 force 時會阻塞到完整 HTTPS + TPM 驗證完成或 timeout。

呼叫 check。 → 讀背景健康。 → 判斷是否到期。 → 必要時同步 refresh。 → 成功返回同一 Session 或拋例外。

進入 context 時會同步連線註冊／驗證；只有啟用 Machine／Process Heartbeat 時才有背景網路執行緒。完整 License revalidation 不會自動排程，必須由呼叫端執行 session.check()。

可能建立／維持／釋放 Process Seat，更新 Heartbeat、執行一次啟動 Check-in，或在正常離開時增加一次 Usage；不會自動解除 Server Machine。

Heartbeat 執行緒會依設定短暫重試；完整 License 驗證沒有隱藏重試迴圈。呼叫端應以明確 Timer／工作檢查點呼叫 session.check()，並對暫時網路錯誤採有限退避。

Session 進入成功；應用程式安排的每個 session.check() 都通過；高價值操作前的強制驗證通過；退出後 Process Seat 已釋放。

長時間程式應在狀態失效時鎖定受保護功能，保留未完成工作，並顯示重新連線或聯絡管理員的步驟。

1. 確認應用程式確實有 Timer、工作迴圈或操作入口會呼叫 session.check()。
2. 確認 revalidate_interval_seconds 是門檻而不是排程器。
3. 確認 GUI 主執行緒沒有被同步網路呼叫長時間阻塞。
4. 檢查背景 Heartbeat 的 last_error 與 consecutive_failures。

• 以為 revalidate_interval_seconds 會自己建立 Timer，因此從不呼叫 session.check()。
• 在無 sleep 的緊密 for 迴圈中一直呼叫 session.check(force_validate=True)，造成網路與 UI 負載。
• 在 GUI 主執行緒直接做可能阻塞到 timeout_seconds 的強制驗證。
• 程式發生授權錯誤後仍繼續執行受保護工作。

Session 啟用 process_seat=True 時顯示或記錄。

• 先決定程式是否真的需要 Machine Heartbeat、Process Seat、Check-in 或 Usage。
• 決定由 GUI Timer、工作迴圈或高價值操作入口在何時呼叫 session.check()。
• 理解 revalidate_interval_seconds 只是 session.check() 的到期門檻，不是背景排程。

• 進入 context 時同步完成 ensure_registered()、Entitlement Gate，以及選用的一次 Check-in／Seat 取得。
• machine_heartbeat=True 或 process_seat=True 才會建立背景 Heartbeat 執行緒；背景執行緒不會自動做完整 License 驗證。
• session.check() 由呼叫端主動執行：先檢查背景 Heartbeat 是否已失敗，再視 force_validate 或到期門檻同步重新驗證。
• 離開 Session 時停止背景 Heartbeat並釋放 Process Seat；不會解除 Server Machine。

ProcessSeat 或 None。

• 無特定 SDK 例外。

同步、本機屬性讀取

不建立背景執行緒。

• 回傳 Process manager 最近一次保存的 ProcessSeat。

• 只用於顯示／診斷；授權健康仍要 session.check()。

• 需要顯示 process_id、next_heartbeat 或 metadata 時。

立即完成，不做網路。

讀取屬性。 → 得到 snapshot 或 None。

進入 context 時會同步連線註冊／驗證；只有啟用 Machine／Process Heartbeat 時才有背景網路執行緒。完整 License revalidation 不會自動排程，必須由呼叫端執行 session.check()。

可能建立／維持／釋放 Process Seat，更新 Heartbeat、執行一次啟動 Check-in，或在正常離開時增加一次 Usage；不會自動解除 Server Machine。

Heartbeat 執行緒會依設定短暫重試；完整 License 驗證沒有隱藏重試迴圈。呼叫端應以明確 Timer／工作檢查點呼叫 session.check()，並對暫時網路錯誤採有限退避。

Session 進入成功；應用程式安排的每個 session.check() 都通過；高價值操作前的強制驗證通過；退出後 Process Seat 已釋放。

長時間程式應在狀態失效時鎖定受保護功能，保留未完成工作，並顯示重新連線或聯絡管理員的步驟。

1. 確認應用程式確實有 Timer、工作迴圈或操作入口會呼叫 session.check()。
2. 確認 revalidate_interval_seconds 是門檻而不是排程器。
3. 確認 GUI 主執行緒沒有被同步網路呼叫長時間阻塞。
4. 檢查背景 Heartbeat 的 last_error 與 consecutive_failures。

• 以為 revalidate_interval_seconds 會自己建立 Timer，因此從不呼叫 session.check()。
• 在無 sleep 的緊密 for 迴圈中一直呼叫 session.check(force_validate=True)，造成網路與 UI 負載。
• 在 GUI 主執行緒直接做可能阻塞到 timeout_seconds 的強制驗證。
• 程式發生授權錯誤後仍繼續執行受保護工作。

Session 啟用 machine_heartbeat=True 時。

• 先決定程式是否真的需要 Machine Heartbeat、Process Seat、Check-in 或 Usage。
• 決定由 GUI Timer、工作迴圈或高價值操作入口在何時呼叫 session.check()。
• 理解 revalidate_interval_seconds 只是 session.check() 的到期門檻，不是背景排程。

• 進入 context 時同步完成 ensure_registered()、Entitlement Gate，以及選用的一次 Check-in／Seat 取得。
• machine_heartbeat=True 或 process_seat=True 才會建立背景 Heartbeat 執行緒；背景執行緒不會自動做完整 License 驗證。
• session.check() 由呼叫端主動執行：先檢查背景 Heartbeat 是否已失敗，再視 force_validate 或到期門檻同步重新驗證。
• 離開 Session 時停止背景 Heartbeat並釋放 Process Seat；不會解除 Server Machine。

MachineHeartbeat 或 None。

• 無特定 SDK 例外。

同步、本機屬性讀取

不建立背景執行緒。

• 回傳 Machine manager 最近一次保存的 MachineHeartbeat。

• 只用於顯示／診斷；授權健康仍要 session.check()。

• 需要顯示 last／next heartbeat 時。

立即完成，不做網路。

讀取屬性。 → 得到 snapshot 或 None。

進入 context 時會同步連線註冊／驗證；只有啟用 Machine／Process Heartbeat 時才有背景網路執行緒。完整 License revalidation 不會自動排程，必須由呼叫端執行 session.check()。

可能建立／維持／釋放 Process Seat，更新 Heartbeat、執行一次啟動 Check-in，或在正常離開時增加一次 Usage；不會自動解除 Server Machine。

Heartbeat 執行緒會依設定短暫重試；完整 License 驗證沒有隱藏重試迴圈。呼叫端應以明確 Timer／工作檢查點呼叫 session.check()，並對暫時網路錯誤採有限退避。

Session 進入成功；應用程式安排的每個 session.check() 都通過；高價值操作前的強制驗證通過；退出後 Process Seat 已釋放。

長時間程式應在狀態失效時鎖定受保護功能，保留未完成工作，並顯示重新連線或聯絡管理員的步驟。

1. 確認應用程式確實有 Timer、工作迴圈或操作入口會呼叫 session.check()。
2. 確認 revalidate_interval_seconds 是門檻而不是排程器。
3. 確認 GUI 主執行緒沒有被同步網路呼叫長時間阻塞。
4. 檢查背景 Heartbeat 的 last_error 與 consecutive_failures。

• 以為 revalidate_interval_seconds 會自己建立 Timer，因此從不呼叫 session.check()。
• 在無 sleep 的緊密 for 迴圈中一直呼叫 session.check(force_validate=True)，造成網路與 UI 負載。
• 在 GUI 主執行緒直接做可能阻塞到 timeout_seconds 的強制驗證。
• 程式發生授權錯誤後仍繼續執行受保護工作。

Policy requireCheckIn 或程式需要主動回報時。

• 先明確定義何謂一次成功工作。
• 在增加 Usage 前先驗證 License 與必要 Entitlement。
• 確認失敗、取消與重試不會被重複計次。

• increment_usage 會永久增加 Server 上的使用量。
• check_in_license 只更新 License Check-in 時間，不等於 Machine／Process Heartbeat。

CheckInState。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• GatewayError
• LicenseInvalidError

• Check-in 不等於 Machine／Process Heartbeat。

同步、單次 License Check-in

不建立背景執行緒或定時器。

• 只更新一次 last_check_in／next_check_in。

• 若 Policy 要求持續 Check-in，讀取 next_check_in 並用應用程式既有 scheduler 自行安排下一次。

• 程式啟動。
• next_check_in 到期前。

會阻塞到網路完成或 timeout_seconds。

同步 Check-in。 → 保存 next_check_in。 → 自行排程後續呼叫。

會透過 HTTPS Gateway 修改 Usage 或 Check-in 狀態。

increment_usage 會永久增加使用量；check_in_license 會更新最後／下次 Check-in 時間。

Usage 遇到不確定結果時不可直接重送，應使用業務 operation ID 或查詢最新狀態避免重複扣量。Check-in 暫時失敗可有限次重試。

確認回傳 uses、max_uses、last_check_in 或 next_check_in 已更新，而且業務成果與計次順序符合設計。

額度已滿時顯示目前用量與聯絡管理員方式；網路不確定時顯示『結果待確認』，不要假裝計次成功。

1. 把計次放在工作成功邊界，而不是按下按鈕時。
2. 檢查重試流程是否可能對同一工作重複扣量。
3. 確認 Check-in、Machine Heartbeat 與 Process Heartbeat 沒有混用。

• 工作一開始就先扣 Usage。
• 網路逾時後盲目重送，造成同一工作重複扣量。
• 把 Usage 額度當成 Machine activation。

查看已註冊 FPGA、板卡或邏輯元件。

• 先為每個 Component 選擇穩定 name 與 fingerprint 規則。
• 確認 fingerprint 不包含不必要的明文序號。

• 建立、更新、刪除或同步目前 TPM-proven Machine 的 Component。
• remove_missing=True 可能刪除未出現在本次完整清單中的既有元件。

MachineComponent tuple。

• LicenseSDKError

同步網路讀寫

不會建立背景執行緒。

• 一次呼叫完成一次 Component list/add/update/remove/sync。

• 提供穩定 fingerprint。
• 對 sync/remove 建立二次確認與結果核對。

• 首次啟用後建立硬體快照。
• 硬體更換經確認後。
• 驗證前需要同步元件時。

會阻塞到網路完成或 timeout_seconds；大量元件同步應在 worker thread。

收集並正規化識別值。 → 建立雜湊 fingerprint。 → 同步。 → 重新 list 核對。

會透過 HTTPS Gateway讀取或修改目前 Machine 的 Component 清單。

新增、更新、移除或同步 Component 會修改 Server 狀態；remove_missing=True 可能批次刪除。

讀取可以有限重試；新增／移除／同步遇到不確定結果時先重新列出 Components，再決定下一步。

重新讀取 Component 清單，確認 name、fingerprint 與 metadata 和預期一致。

指出哪個元件無法綁定或同步；不要向使用者顯示未雜湊的硬體序號。

1. 確認 fingerprint 規則固定且可重現。
2. 使用 remove_missing=True 前，確認傳入的是完整快照。
3. 確認 Policy 的 component scope 需求。

• 使用會隨開機改變的值當 fingerprint。
• 傳入部分清單卻啟用 remove_missing=True。
• 誤以為 Component matching 可以取代 TPM Machine 身分。

首次綁定可更換硬體或邏輯模組時。

• 先為每個 Component 選擇穩定 name 與 fingerprint 規則。
• 確認 fingerprint 不包含不必要的明文序號。

• 建立、更新、刪除或同步目前 TPM-proven Machine 的 Component。
• remove_missing=True 可能刪除未出現在本次完整清單中的既有元件。

MachineComponent。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ValueError
• GatewayError
• LicenseInvalidError

• fingerprint 建議先用 build_component_fingerprint()。

同步網路讀寫

不會建立背景執行緒。

• 一次呼叫完成一次 Component list/add/update/remove/sync。

• 提供穩定 fingerprint。
• 對 sync/remove 建立二次確認與結果核對。

• 首次啟用後建立硬體快照。
• 硬體更換經確認後。
• 驗證前需要同步元件時。

會阻塞到網路完成或 timeout_seconds；大量元件同步應在 worker thread。

收集並正規化識別值。 → 建立雜湊 fingerprint。 → 同步。 → 重新 list 核對。

會透過 HTTPS Gateway讀取或修改目前 Machine 的 Component 清單。

新增、更新、移除或同步 Component 會修改 Server 狀態；remove_missing=True 可能批次刪除。

讀取可以有限重試；新增／移除／同步遇到不確定結果時先重新列出 Components，再決定下一步。

重新讀取 Component 清單，確認 name、fingerprint 與 metadata 和預期一致。

指出哪個元件無法綁定或同步；不要向使用者顯示未雜湊的硬體序號。

1. 確認 fingerprint 規則固定且可重現。
2. 使用 remove_missing=True 前，確認傳入的是完整快照。
3. 確認 Policy 的 component scope 需求。

• 使用會隨開機改變的值當 fingerprint。
• 傳入部分清單卻啟用 remove_missing=True。
• 誤以為 Component matching 可以取代 TPM Machine 身分。

顯示名稱或非識別屬性改變時。

• 先為每個 Component 選擇穩定 name 與 fingerprint 規則。
• 確認 fingerprint 不包含不必要的明文序號。

• 建立、更新、刪除或同步目前 TPM-proven Machine 的 Component。
• remove_missing=True 可能刪除未出現在本次完整清單中的既有元件。

更新後 MachineComponent。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ValueError
• GatewayError

• fingerprint 不在此方法變更。

同步網路讀寫

不會建立背景執行緒。

• 一次呼叫完成一次 Component list/add/update/remove/sync。

• 提供穩定 fingerprint。
• 對 sync/remove 建立二次確認與結果核對。

• 首次啟用後建立硬體快照。
• 硬體更換經確認後。
• 驗證前需要同步元件時。

會阻塞到網路完成或 timeout_seconds；大量元件同步應在 worker thread。

收集並正規化識別值。 → 建立雜湊 fingerprint。 → 同步。 → 重新 list 核對。

會透過 HTTPS Gateway讀取或修改目前 Machine 的 Component 清單。

新增、更新、移除或同步 Component 會修改 Server 狀態；remove_missing=True 可能批次刪除。

讀取可以有限重試；新增／移除／同步遇到不確定結果時先重新列出 Components，再決定下一步。

重新讀取 Component 清單，確認 name、fingerprint 與 metadata 和預期一致。

指出哪個元件無法綁定或同步；不要向使用者顯示未雜湊的硬體序號。

1. 確認 fingerprint 規則固定且可重現。
2. 使用 remove_missing=True 前，確認傳入的是完整快照。
3. 確認 Policy 的 component scope 需求。

• 使用會隨開機改變的值當 fingerprint。
• 傳入部分清單卻啟用 remove_missing=True。
• 誤以為 Component matching 可以取代 TPM Machine 身分。

顯示裝置資訊或確認 Server 記錄。

• 本機必須先完成 TPM Device Registration。
• 只操作 SDK 目前 registration 對應的 Machine，不接受任意 Machine ID。

• 讀取或更新目前 Machine 的管理資料與資源資訊。
• Heartbeat 只更新目前 Machine 活性，不會解除或刪除 Machine。

MachineProfile。

• LicenseSDKError

同步網路操作；Heartbeat manager 工廠除外

一般方法不建立執行緒；machine_heartbeat() 只建立 manager，必須 start()／with 才啟動背景執行緒。

• 單次讀取、更新或 ping 只做一次請求。

• 自行決定何時更新 Profile 或做單次 ping。
• 需要持續 Heartbeat 時使用 manager 並定期 check()。

• Profile：啟用後或資訊變更時。
• 單次 ping：診斷。
• 持續 Heartbeat：長時間 Floating Machine 生命週期。

單次網路方法會阻塞；manager.start() 的第一次 ping 也同步阻塞。

確認已註冊。 → 呼叫單次方法或建立 manager。 → 需要背景維持時 start。 → 主流程定期 check。 → 結束時 stop。

會透過 HTTPS Gateway讀取或更新目前 TPM-proven Machine。

Profile 更新與 Heartbeat 會修改 Server 上目前 Machine 的管理資料或活性時間；不會解除 Machine。

讀取可對暫時網路錯誤有限重試；更新操作要先確認是否已成功，避免重複覆寫或產生誤判。

確認回傳 machine_id 等於本機 registration 的 Machine，且更新欄位或 Heartbeat 時間符合預期。

Machine 操作失敗時說明是資料更新、Heartbeat 還是授權拒絕；不要引導使用者刪除 registration 來釋放席位。

1. 比對 local registration 的 machine_id。
2. 確認 Hostname、IP 只是管理資料，不是安全身分。
3. Floating Policy 下確認 Heartbeat 間隔與 cull 規則。

• 把 Hostname 或 IP 當成安全身分。
• 正常退出程式時自動解除 Server Machine。
• 使用 Client SDK 管理其他電腦的 Machine。

裝置名稱、Metadata 或硬體資源資訊更新時。

• 本機必須先完成 TPM Device Registration。
• 只操作 SDK 目前 registration 對應的 Machine，不接受任意 Machine ID。

• 讀取或更新目前 Machine 的管理資料與資源資訊。
• Heartbeat 只更新目前 Machine 活性，不會解除或刪除 Machine。

MachineProfile。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ValueError
• GatewayError

• refresh_local_system_info=True 可自動收集本機資訊。

同步網路操作；Heartbeat manager 工廠除外

一般方法不建立執行緒；machine_heartbeat() 只建立 manager，必須 start()／with 才啟動背景執行緒。

• 單次讀取、更新或 ping 只做一次請求。

• 自行決定何時更新 Profile 或做單次 ping。
• 需要持續 Heartbeat 時使用 manager 並定期 check()。

• Profile：啟用後或資訊變更時。
• 單次 ping：診斷。
• 持續 Heartbeat：長時間 Floating Machine 生命週期。

單次網路方法會阻塞；manager.start() 的第一次 ping 也同步阻塞。

確認已註冊。 → 呼叫單次方法或建立 manager。 → 需要背景維持時 start。 → 主流程定期 check。 → 結束時 stop。

會透過 HTTPS Gateway讀取或更新目前 TPM-proven Machine。

Profile 更新與 Heartbeat 會修改 Server 上目前 Machine 的管理資料或活性時間；不會解除 Machine。

讀取可對暫時網路錯誤有限重試；更新操作要先確認是否已成功，避免重複覆寫或產生誤判。

確認回傳 machine_id 等於本機 registration 的 Machine，且更新欄位或 Heartbeat 時間符合預期。

Machine 操作失敗時說明是資料更新、Heartbeat 還是授權拒絕；不要引導使用者刪除 registration 來釋放席位。

1. 比對 local registration 的 machine_id。
2. 確認 Hostname、IP 只是管理資料，不是安全身分。
3. Floating Policy 下確認 Heartbeat 間隔與 cull 規則。

• 把 Hostname 或 IP 當成安全身分。
• 正常退出程式時自動解除 Server Machine。
• 使用 Client SDK 管理其他電腦的 Machine。

測試 Heartbeat 或自行排程時。

• 本機必須先完成 TPM Device Registration。
• 只操作 SDK 目前 registration 對應的 Machine，不接受任意 Machine ID。

• 讀取或更新目前 Machine 的管理資料與資源資訊。
• Heartbeat 只更新目前 Machine 活性，不會解除或刪除 Machine。

MachineHeartbeat。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• GatewayError
• LicenseInvalidError

同步網路操作；Heartbeat manager 工廠除外

一般方法不建立執行緒；machine_heartbeat() 只建立 manager，必須 start()／with 才啟動背景執行緒。

• 單次讀取、更新或 ping 只做一次請求。

• 自行決定何時更新 Profile 或做單次 ping。
• 需要持續 Heartbeat 時使用 manager 並定期 check()。

• Profile：啟用後或資訊變更時。
• 單次 ping：診斷。
• 持續 Heartbeat：長時間 Floating Machine 生命週期。

單次網路方法會阻塞；manager.start() 的第一次 ping 也同步阻塞。

確認已註冊。 → 呼叫單次方法或建立 manager。 → 需要背景維持時 start。 → 主流程定期 check。 → 結束時 stop。

會透過 HTTPS Gateway讀取或更新目前 TPM-proven Machine。

Profile 更新與 Heartbeat 會修改 Server 上目前 Machine 的管理資料或活性時間；不會解除 Machine。

讀取可對暫時網路錯誤有限重試；更新操作要先確認是否已成功，避免重複覆寫或產生誤判。

確認回傳 machine_id 等於本機 registration 的 Machine，且更新欄位或 Heartbeat 時間符合預期。

Machine 操作失敗時說明是資料更新、Heartbeat 還是授權拒絕；不要引導使用者刪除 registration 來釋放席位。

1. 比對 local registration 的 machine_id。
2. 確認 Hostname、IP 只是管理資料，不是安全身分。
3. Floating Policy 下確認 Heartbeat 間隔與 cull 規則。

• 把 Hostname 或 IP 當成安全身分。
• 正常退出程式時自動解除 Server Machine。
• 使用 Client SDK 管理其他電腦的 Machine。

Floating Machine 或 Policy requireHeartbeat 的長時間程式。

• 本機必須先完成 TPM Device Registration。
• 只操作 SDK 目前 registration 對應的 Machine，不接受任意 Machine ID。

• 讀取或更新目前 Machine 的管理資料與資源資訊。
• Heartbeat 只更新目前 Machine 活性，不會解除或刪除 Machine。

ManagedHeartbeat。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• HeartbeatError
• GatewayError

• 停止 Heartbeat 不等於解除 Server Machine。

只建立 ManagedHeartbeat 物件；start()／with 時才連線

呼叫 machine_heartbeat() 本身不建立 thread；manager.start() 或進入 with 後建立一條 daemon thread。

• 建立含有 start/ping/interval 規則的 manager。

• 使用 with 或明確 start。
• 定期 manager.check()。
• 結束時 stop。

• 長時間 Floating Machine 應用的外層生命週期。

工廠呼叫立即回傳；start() 的首次 ping 會同步阻塞。

建立 manager。 → start／with。 → 背景 ping。 → 主流程 check。 → stop；不解除 Machine。

會透過 HTTPS Gateway讀取或更新目前 TPM-proven Machine。

Profile 更新與 Heartbeat 會修改 Server 上目前 Machine 的管理資料或活性時間；不會解除 Machine。

讀取可對暫時網路錯誤有限重試；更新操作要先確認是否已成功，避免重複覆寫或產生誤判。

確認回傳 machine_id 等於本機 registration 的 Machine，且更新欄位或 Heartbeat 時間符合預期。

Machine 操作失敗時說明是資料更新、Heartbeat 還是授權拒絕；不要引導使用者刪除 registration 來釋放席位。

1. 比對 local registration 的 machine_id。
2. 確認 Hostname、IP 只是管理資料，不是安全身分。
3. Floating Policy 下確認 Heartbeat 間隔與 cull 規則。

• 把 Hostname 或 IP 當成安全身分。
• 正常退出程式時自動解除 Server Machine。
• 使用 Client SDK 管理其他電腦的 Machine。

Policy 使用 maxProcesses，且你自行管理生命週期時。

• Policy 必須設定 maxProcesses 或要求 Process 管理。
• 每個真正執行中的程式實例使用自己的 PID／Seat。

• 建立 Process Seat 後，Client 必須依 interval 維持 Heartbeat。
• 正常結束時可以釋放 Process Seat；這不會解除 Machine。

ProcessSeat。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ProcessSeatUnavailableError
• GatewayError
• LicenseInvalidError

• 一般建議使用 process_seat() context manager。

同步網路操作；Process manager 工廠除外

一般方法不建立執行緒；process_seat() 只建立 manager，必須 start()／with 才取得 Seat 並啟動背景 Heartbeat。

• acquire/ping/release 各只執行一次。

• 每個真實程序管理自己的 Seat。
• 使用 manager 時定期 check() 並在結束時 stop／離開 with。

• 應用程式／工作程序開始時取得。
• 長時間執行期間維持。
• 正常結束時釋放。

單次網路方法與 manager.start() 會阻塞到網路完成或 timeout_seconds。

取得 Seat。 → 背景維持或自行 ping。 → 主流程檢查錯誤。 → 正常結束釋放。

會透過 HTTPS Gateway 建立、維持、列出或釋放 Process Seat。

建立與釋放 Seat 會修改 Server 的並行程序狀態；Heartbeat 更新 Seat 活性。

建立 Seat 收到不確定結果時先列出目前 Process；釋放失敗可在安全關閉流程中有限重試，但不可阻止程式退出。

確認回傳 Seat 的 PID、process_id、heartbeat 與目前程序一致；結束時確認 release 結果。

席位不足時顯示並行上限與稍後重試建議；不要把它描述成 Machine 啟用失敗。

1. 每個真實程序使用自己的 PID。
2. 確認崩潰後的 Seat 回收依 Server cull 規則。
3. 不要讓多個程序共用同一個 ProcessSeat 物件。

• 多個程序共用同一個 Seat。
• 程式崩潰後假設 Seat 一定立即消失。
• 把 Process Seat 當成 Windows 使用者數。

自行管理 Seat 心跳時。

• Policy 必須設定 maxProcesses 或要求 Process 管理。
• 每個真正執行中的程式實例使用自己的 PID／Seat。

• 建立 Process Seat 後，Client 必須依 interval 維持 Heartbeat。
• 正常結束時可以釋放 Process Seat；這不會解除 Machine。

更新後 ProcessSeat。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• GatewayError
• LicenseInvalidError

同步網路操作；Process manager 工廠除外

一般方法不建立執行緒；process_seat() 只建立 manager，必須 start()／with 才取得 Seat 並啟動背景 Heartbeat。

• acquire/ping/release 各只執行一次。

• 每個真實程序管理自己的 Seat。
• 使用 manager 時定期 check() 並在結束時 stop／離開 with。

• 應用程式／工作程序開始時取得。
• 長時間執行期間維持。
• 正常結束時釋放。

單次網路方法與 manager.start() 會阻塞到網路完成或 timeout_seconds。

取得 Seat。 → 背景維持或自行 ping。 → 主流程檢查錯誤。 → 正常結束釋放。

會透過 HTTPS Gateway 建立、維持、列出或釋放 Process Seat。

建立與釋放 Seat 會修改 Server 的並行程序狀態；Heartbeat 更新 Seat 活性。

建立 Seat 收到不確定結果時先列出目前 Process；釋放失敗可在安全關閉流程中有限重試，但不可阻止程式退出。

確認回傳 Seat 的 PID、process_id、heartbeat 與目前程序一致；結束時確認 release 結果。

席位不足時顯示並行上限與稍後重試建議；不要把它描述成 Machine 啟用失敗。

1. 每個真實程序使用自己的 PID。
2. 確認崩潰後的 Seat 回收依 Server cull 規則。
3. 不要讓多個程序共用同一個 ProcessSeat 物件。

• 多個程序共用同一個 Seat。
• 程式崩潰後假設 Seat 一定立即消失。
• 把 Process Seat 當成 Windows 使用者數。

程式退出或受保護工作結束時。

• Policy 必須設定 maxProcesses 或要求 Process 管理。
• 每個真正執行中的程式實例使用自己的 PID／Seat。

• 建立 Process Seat 後，Client 必須依 interval 維持 Heartbeat。
• 正常結束時可以釋放 Process Seat；這不會解除 Machine。

True。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• GatewayError

• Process release 允許；這與 Machine deactivation 不同。

同步網路操作；Process manager 工廠除外

一般方法不建立執行緒；process_seat() 只建立 manager，必須 start()／with 才取得 Seat 並啟動背景 Heartbeat。

• acquire/ping/release 各只執行一次。

• 每個真實程序管理自己的 Seat。
• 使用 manager 時定期 check() 並在結束時 stop／離開 with。

• 應用程式／工作程序開始時取得。
• 長時間執行期間維持。
• 正常結束時釋放。

單次網路方法與 manager.start() 會阻塞到網路完成或 timeout_seconds。

取得 Seat。 → 背景維持或自行 ping。 → 主流程檢查錯誤。 → 正常結束釋放。

會透過 HTTPS Gateway 建立、維持、列出或釋放 Process Seat。

建立與釋放 Seat 會修改 Server 的並行程序狀態；Heartbeat 更新 Seat 活性。

建立 Seat 收到不確定結果時先列出目前 Process；釋放失敗可在安全關閉流程中有限重試，但不可阻止程式退出。

確認回傳 Seat 的 PID、process_id、heartbeat 與目前程序一致；結束時確認 release 結果。

席位不足時顯示並行上限與稍後重試建議；不要把它描述成 Machine 啟用失敗。

1. 每個真實程序使用自己的 PID。
2. 確認崩潰後的 Seat 回收依 Server cull 規則。
3. 不要讓多個程序共用同一個 ProcessSeat 物件。

• 多個程序共用同一個 Seat。
• 程式崩潰後假設 Seat 一定立即消失。
• 把 Process Seat 當成 Windows 使用者數。

大多數 Concurrent Process 場景。

• Policy 必須設定 maxProcesses 或要求 Process 管理。
• 每個真正執行中的程式實例使用自己的 PID／Seat。

• 建立 Process Seat 後，Client 必須依 interval 維持 Heartbeat。
• 正常結束時可以釋放 Process Seat；這不會解除 Machine。

ManagedHeartbeat[ProcessSeat]。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ProcessSeatUnavailableError
• HeartbeatError
• GatewayError

只建立 ManagedHeartbeat 物件；start()／with 時才取得 Seat 並連線

呼叫 process_seat() 本身不建立 thread；manager.start() 或進入 with 後建立一條 daemon thread。

• 建立含 acquire/ping/release 規則的 manager。

• 使用 with 或明確 start。
• 定期 manager.check()。
• 正常結束 stop／release。

• 需要 maxProcesses 控制的程序生命週期外層。

工廠呼叫立即回傳；start() 取得 Seat 時同步阻塞。

建立 manager。 → start 時 acquire。 → 背景 ping。 → 主流程 check。 → stop 時 release。

會透過 HTTPS Gateway 建立、維持、列出或釋放 Process Seat。

建立與釋放 Seat 會修改 Server 的並行程序狀態；Heartbeat 更新 Seat 活性。

建立 Seat 收到不確定結果時先列出目前 Process；釋放失敗可在安全關閉流程中有限重試，但不可阻止程式退出。

確認回傳 Seat 的 PID、process_id、heartbeat 與目前程序一致；結束時確認 release 結果。

席位不足時顯示並行上限與稍後重試建議；不要把它描述成 Machine 啟用失敗。

1. 每個真實程序使用自己的 PID。
2. 確認崩潰後的 Seat 回收依 Server cull 規則。
3. 不要讓多個程序共用同一個 ProcessSeat 物件。

• 多個程序共用同一個 Seat。
• 程式崩潰後假設 Seat 一定立即消失。
• 把 Process Seat 當成 Windows 使用者數。

沒有使用 with 語法而要手動管理時。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

自身。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• ProcessSeatUnavailableError／GatewayError

同步啟動 + 一條 daemon Heartbeat thread

會建立一條名為 keygen-<name>-heartbeat 的 daemon thread；同一 manager 重複 start 不會再建立第二條。

• 先同步呼叫 start callback 取得初始 MachineHeartbeat 或 ProcessSeat。
• 再啟動背景 loop，依 interval 自動 ping。

• 捕捉初始取得失敗。
• 在主流程安排 check()。
• 生命週期結束時 stop()。

• 進入長時間工作前呼叫一次，或直接使用 with manager。

初始網路取得會同步阻塞；背景 thread 啟動後 start() 返回 manager。

同步取得初始 state。 → 啟動 thread。 → 返回 manager。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

長時間程式的安全點或高價值操作前。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

最新 MachineHeartbeat 或 ProcessSeat。

• HeartbeatError

同步、本機讀取背景結果

不建立執行緒，也不主動送 Heartbeat。

• 若連續失敗未達門檻，回傳最近 state。
• 達門檻時把保存的 last_error 包成 HeartbeatError 拋給呼叫端。

• 在應用程式自己的 Timer／checkpoint 呼叫。
• HeartbeatError 後停止受保護操作。

• 每 5～30 秒或每個主要工作階段；不需要無延遲 for 迴圈。

通常立即完成，因為不做網路 I/O。

讀取 failure counters。 → 必要時拋錯。 → 否則回傳最近 state。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

手動生命週期結束。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

None。

• ClientCompatibilityError：HTTP 426，Client API Revision 缺少或與 Server 不相符。
• GatewayError：Process release 失敗時。

同步停止背景 thread；Process manager 可能再做一次網路 release

不建立新 thread；設定 stop event 並等待現有 thread 最多 5 秒。

• 停止後續 ping。
• 依 release_on_exit／release 參數決定是否呼叫 release callback。

• 在 finally、關閉事件或離開 with 時保證呼叫。
• 不要把 Machine stop 誤認為 deactivation。

• 應用程式正常關閉。
• 工作取消。
• 授權失效後清理。

join 最多等待 5 秒；Process release 可能再阻塞到網路 timeout。

設定 stop。 → join thread。 → 可選 release。 → 返回。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

顯示目前 Seat／Heartbeat 狀態。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

泛型 state。

• RuntimeError：尚未 start。

背景 Heartbeat 生命週期管理

start()／with 會建立一條 daemon thread；每一個 manager 各有一條。check() 不建立新執行緒。

• 背景 thread 依 Server／SDK 間隔送 Heartbeat。
• 短暫失敗會按 retry_interval_seconds 重試，達門檻後停止 thread 並保存 last_error。

• 必須呼叫 start() 或使用 with。
• 必須在 Timer／工作檢查點呼叫 check()，否則背景失敗不會自動拋到主流程。
• 結束時 stop()。

• GUI：每 5～30 秒由 Timer 觸發一次本機 check；不要每次都 force network。
• CLI／worker：每個主要階段或迴圈 checkpoint。

start() 會同步做第一次網路操作；check() 通常立即完成；stop() 最多等待背景 thread 結束並可能同步 release Process Seat。

建立 manager。 → start／進入 with。 → 背景 thread 自動 ping。 → 呼叫端定期 check。 → stop／離開 with。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

UI 要顯示警告但尚未達連續失敗門檻。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

例外或 None。

• 無特定 SDK 例外。

背景 Heartbeat 生命週期管理

start()／with 會建立一條 daemon thread；每一個 manager 各有一條。check() 不建立新執行緒。

• 背景 thread 依 Server／SDK 間隔送 Heartbeat。
• 短暫失敗會按 retry_interval_seconds 重試，達門檻後停止 thread 並保存 last_error。

• 必須呼叫 start() 或使用 with。
• 必須在 Timer／工作檢查點呼叫 check()，否則背景失敗不會自動拋到主流程。
• 結束時 stop()。

• GUI：每 5～30 秒由 Timer 觸發一次本機 check；不要每次都 force network。
• CLI／worker：每個主要階段或迴圈 checkpoint。

start() 會同步做第一次網路操作；check() 通常立即完成；stop() 最多等待背景 thread 結束並可能同步 release Process Seat。

建立 manager。 → start／進入 with。 → 背景 thread 自動 ping。 → 呼叫端定期 check。 → stop／離開 with。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

監控與診斷。

• 先取得有效 Machine 或 Process 資源。
• 設定可接受的連續失敗次數與重試間隔。

• 背景執行緒週期呼叫 Heartbeat。
• 當連續失敗超過門檻時，check() 會把錯誤帶回主流程。

int。

• 無特定 SDK 例外。

背景 Heartbeat 生命週期管理

start()／with 會建立一條 daemon thread；每一個 manager 各有一條。check() 不建立新執行緒。

• 背景 thread 依 Server／SDK 間隔送 Heartbeat。
• 短暫失敗會按 retry_interval_seconds 重試，達門檻後停止 thread 並保存 last_error。

• 必須呼叫 start() 或使用 with。
• 必須在 Timer／工作檢查點呼叫 check()，否則背景失敗不會自動拋到主流程。
• 結束時 stop()。

• GUI：每 5～30 秒由 Timer 觸發一次本機 check；不要每次都 force network。
• CLI／worker：每個主要階段或迴圈 checkpoint。

start() 會同步做第一次網路操作；check() 通常立即完成；stop() 最多等待背景 thread 結束並可能同步 release Process Seat。

建立 manager。 → start／進入 with。 → 背景 thread 自動 ping。 → 呼叫端定期 check。 → stop／離開 with。

start() 先同步取得／更新一次 Server resource，之後背景執行緒依間隔呼叫 Machine 或 Process Heartbeat；check() 本身通常只讀取本機記錄的背景狀態。

持續更新 Server 活性時間；停止 manager 只停止後續 Heartbeat。Process manager 可在停止時釋放 Seat，Machine manager 不會解除 Machine。

背景執行緒依設定處理暫時失敗；主流程必須呼叫 check() 才會收到超過門檻的 HeartbeatError。不要用無 sleep 的緊密迴圈輪詢。

start() 成功、last_error 為 None、consecutive_failures 為 0，且應用程式安排的 check() 沒有拋例外。

連續失敗時將程式切換為受限模式，顯示網路或授權狀態，不要讓背景錯誤只留在 Log。

1. 確認 interval 與 failure threshold。
2. 確認程式結束時 stop() 或離開 with。
3. 確認 UI Timer／工作迴圈會定期呼叫 check()。
4. 確認 Machine 與 Process manager 的 release 語意不同。

• 只啟動背景管理器，主程式從不呼叫 check()。
• 停止 Machine Heartbeat 時誤以為會刪除 Machine。

要顯示支援資訊或讓使用者找到診斷檔時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

Path。

• 無特定 SDK 例外。

• Log 已做敏感資料遮罩，但仍應視為內部支援資料。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

需要把診斷輸出到自訂位置或提高／降低記錄等級時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

實際 Log Path。

• OSError：目錄不可寫。

• 正式環境通常使用 INFO。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

測試或極度受限環境不希望留下診斷檔時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

None。

• 無特定 SDK 例外。

• 停用後排錯能力會降低。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

GUI 要呈現最近連線事件時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

ConnectionLogEntry list。

• ValueError：limit 不合理時可能由內部約束拒絕。

• 適合 UI，不需自行解析 JSONL。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

CLI 或支援對話框需要複製文字時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

多行字串。

• 無特定 SDK 例外。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

完成支援或依資料保留政策清除本機紀錄時。

• 確認 Log 目錄可寫，並遵守公司資料保留政策。

• 讀取、格式化、啟用、停用或清除已遮罩的 Connection Log。
• 不會重新驗證 License，也不會修改 Server 資源。

是否實際刪除。

• OSError：檔案被鎖定或權限不足。

• 不影響 registration.json 或 TPM Key。

同步、本機 Log I/O

不會建立背景執行緒。

• 只讀寫已遮罩的本機 Connection Log。

• 決定保留時間與顯示方式。
• 交付支援前再次檢查自訂 metadata。

• 發生問題後、支援畫面、受控清除時。

讀寫大型 Log 可能短暫阻塞；limit 應保持合理。

啟用。 → 重現。 → 讀取／格式化。 → 提供支援。 → 依政策清理。

不連線。只讀寫本機已遮罩的 Connection Log。

可能建立、追加、停止或清除本機 Log；不修改 License 或 Server。

讀檔／寫檔權限錯誤可在修正路徑後重試；不要無限制增加 Log 詳細度或保留時間。

確認 Log Path 可寫、每行可解析，且內容沒有 License Key、Token、Private Key 或完整 credential。

提供『複製診斷資訊』功能並提醒使用者先檢查敏感資料；不要要求上傳整個應用程式資料目錄。

1. 先找最後一個成功事件，再看下一個失敗事件。
2. 保留 request_id、endpoint、status 與 error code。
3. 完成支援後依資料政策清理 Log。

• 完全停用 Log 後才開始排錯。
• 把 Log 視為可公開資料。
• 只貼錯誤畫面，不保留 request_id、code 與重現步驟。

測試或診斷 Scope 內容；一般呼叫由 SDK 自動完成。

• 先確認輸入 dict 或模型來自可信 SDK 回傳或已驗證資料。

• 只將資料模型轉換為 dict、文字或其他本機格式。
• 不會因為呼叫 to_payload() 就完成 Server 驗證。

dict。

• 無特定 SDK 例外。

• 不要把輸出視為已驗證資料。

同步、本機資料轉換

不會建立背景執行緒。

• 只轉換目前記憶體中的資料。

• 驗證輸入來源與型別。
• 不要將轉換結果誤認為 Server 已接受。

• 測試、診斷、序列化或自訂 UI。

立即完成，不做網路 I/O。

準備可信模型／dict。 → 轉換。 → 由後續 API 或 UI 使用。

不連線。只在本機轉換資料模型。

不修改本機持久狀態或 Server。

不需要網路重試；輸入資料不合法時應修正來源。

轉換後欄位、型別與原模型一致，並通過應用程式自己的 schema 驗證。

資料格式錯誤時顯示可理解欄位名稱，不要輸出整份可能含內部資訊的 payload。

1. 確認模型來自可信 SDK 回傳。
2. 不要把 to_payload() 當成已完成 Server 驗證。

• 把模型資料當成即時狀態。
• 直接信任外部 JSON 後建立模型。

建立 Component 前做本機檢查或測試。

• 先確認輸入 dict 或模型來自可信 SDK 回傳或已驗證資料。

• 只將資料模型轉換為 dict、文字或其他本機格式。
• 不會因為呼叫 to_payload() 就完成 Server 驗證。

dict。

• ValueError：name 或 fingerprint 為空。

同步、本機資料轉換

不會建立背景執行緒。

• 只轉換目前記憶體中的資料。

• 驗證輸入來源與型別。
• 不要將轉換結果誤認為 Server 已接受。

• 測試、診斷、序列化或自訂 UI。

立即完成，不做網路 I/O。

準備可信模型／dict。 → 轉換。 → 由後續 API 或 UI 使用。

不連線。只在本機轉換資料模型。

不修改本機持久狀態或 Server。

不需要網路重試；輸入資料不合法時應修正來源。

轉換後欄位、型別與原模型一致，並通過應用程式自己的 schema 驗證。

資料格式錯誤時顯示可理解欄位名稱，不要輸出整份可能含內部資訊的 payload。

1. 確認模型來自可信 SDK 回傳。
2. 不要把 to_payload() 當成已完成 Server 驗證。

• 把模型資料當成即時狀態。
• 直接信任外部 JSON 後建立模型。

CLI、GUI Log Viewer 或複製給支援人員。

• 先確認輸入 dict 或模型來自可信 SDK 回傳或已驗證資料。

• 只將資料模型轉換為 dict、文字或其他本機格式。
• 不會因為呼叫 to_payload() 就完成 Server 驗證。

str。

• 無特定 SDK 例外。

同步、本機資料轉換

不會建立背景執行緒。

• 只轉換目前記憶體中的資料。

• 驗證輸入來源與型別。
• 不要將轉換結果誤認為 Server 已接受。

• 測試、診斷、序列化或自訂 UI。

立即完成，不做網路 I/O。

準備可信模型／dict。 → 轉換。 → 由後續 API 或 UI 使用。

不連線。只在本機轉換資料模型。

不修改本機持久狀態或 Server。

不需要網路重試；輸入資料不合法時應修正來源。

轉換後欄位、型別與原模型一致，並通過應用程式自己的 schema 驗證。

資料格式錯誤時顯示可理解欄位名稱，不要輸出整份可能含內部資訊的 payload。

1. 確認模型來自可信 SDK 回傳。
2. 不要把 to_payload() 當成已完成 Server 驗證。

• 把模型資料當成即時狀態。
• 直接信任外部 JSON 後建立模型。

測試、匯入診斷紀錄或自訂 Log Viewer。

• 先確認輸入 dict 或模型來自可信 SDK 回傳或已驗證資料。

• 只將資料模型轉換為 dict、文字或其他本機格式。
• 不會因為呼叫 to_payload() 就完成 Server 驗證。

ConnectionLogEntry。

• ValueError／TypeError：欄位無法轉型。

同步、本機資料轉換

不會建立背景執行緒。

• 只轉換目前記憶體中的資料。

• 驗證輸入來源與型別。
• 不要將轉換結果誤認為 Server 已接受。

• 測試、診斷、序列化或自訂 UI。

立即完成，不做網路 I/O。

準備可信模型／dict。 → 轉換。 → 由後續 API 或 UI 使用。

不連線。只在本機轉換資料模型。

不修改本機持久狀態或 Server。

不需要網路重試；輸入資料不合法時應修正來源。

轉換後欄位、型別與原模型一致，並通過應用程式自己的 schema 驗證。

資料格式錯誤時顯示可理解欄位名稱，不要輸出整份可能含內部資訊的 payload。

1. 確認模型來自可信 SDK 回傳。
2. 不要把 to_payload() 當成已完成 Server 驗證。

• 把模型資料當成即時狀態。
• 直接信任外部 JSON 後建立模型。