principle-type-system-discipline | 讓型別排除不合法狀態
本頁以 pstack-claude 0.9.126 為基準。原文設定 user-invocable: false，通常由 poteto-mode 按需讀取。它適用於靜態型別語言，並非只有 TypeScript。
定位與適用情境
讓編譯器拒絕不可能狀態、語意混用的基本值，以及未處理的變體。外部資料在解析前沒有可信型別。若某份結構定義已是權威來源，應從它衍生型別，不另抄一套平行版本。
例如出貨服務收到訂單事件。UserId 與 OrderId 都是字串，但不能互換。出貨結果只有待處理、成功附追蹤號、失敗附原因三種。若使用數個可選欄位，便可能出現「成功卻沒有追蹤號」或「待處理卻帶失敗原因」的資料。
準備
- 提供事件的 OpenAPI 結構描述（schema）或其他權威協定，以及接收入口和出貨函式簽章。
- 準備有效事件、缺少訂單識別碼的事件與識別碼格式錯誤的事件。
- 確認領域需要哪些狀態、識別碼格式及錯誤處理。上游原則未替此出貨情境定義具體欄位，必須以專案需求為準。
操作步驟
- 找出真正擁有資料形狀的權威結構。沿用專案既有衍生方式取得傳輸型別，不另寫一份可能漂移的事件型別。列出傳輸資料與領域模型的對應。
- 將語意不同的識別碼分成不同型別，例如品牌型別（branded type）或新型別（newtype）。在建立時驗證一次，避免把兩個同為字串的參數交換後仍能編譯。
- 在事件接收邊界解析外部資料，成功後才交給內部出貨流程。型別註記或強制斷言不等於解析，JSON、環境變數與資料庫資料都不能只因來源熟悉就跳過邊界檢查。
- 用帶標記的聯集（discriminated union）等結構表達三種結果，讓每個狀態只帶合法欄位。加入窮盡性檢查（exhaustiveness check），並用型別負向案例及邊界輸入測試分別檢查編譯期與執行期約束。
可直接使用的提示詞
套用 principle-type-system-discipline，檢查出貨事件與結果型別。
輸入包含權威 OpenAPI 結構、事件接收入口、出貨函式簽章與有效及無效事件。
區分 UserId 與 OrderId，從權威結構衍生傳輸型別，在邊界解析後才建立領域模型。
將待處理、成功附追蹤號、失敗附原因建模成合法狀態，列出窮盡性檢查方式。
交付型別設計及編譯期、執行期的驗收案例，不用強制斷言假裝完成驗證。
這次只提出方案，不安裝產生器或修改程式。預期結果與驗收
- 將
UserId傳入要求OrderId的位置時，型別檢查應拒絕。 - 成功結果缺少追蹤號時無法建立合法值；新增狀態卻未處理時，窮盡性檢查應指出缺漏。
- 缺少或格式錯誤的外部識別碼在解析邊界被拒絕，不流入已型別化的內部流程。
- 傳輸型別可追溯到權威結構，沒有另一份手寫副本。每項編譯與執行期主張都各有對應檢查。
限制與權限
常見誤用是替任意字串加上型別斷言就當成已驗證，或在每個內部函式重做相同解析。品牌型別能防止靜態語意混用，不能自行驗證外部輸入或保證使用者有權操作該訂單。
靜態型別通過也不代表支付、授權或外部系統整合正確。具體 TypeScript 寫法可另參考上游原文指向的 typescript-best-practices；本頁不假設讀者已具備產生工具。本頁未修改型別、安裝依賴或處理真實事件，實作仍受任務權限限制。