🌐 English version · 繁體中文（正本 / canonical）

iOS 開發判準手冊

核心原則

1. 模擬器綠燈不算數：簽章、provisioning、release optimization、assert 失效、背景模式、記憶體壓力都只在實機/release 才真實——上架路徑的改動要用實機 + release 級驗證。
2. 狀態只有一個擁有者，資料只往下流、事件只往上傳：View 是狀態的函式，body 必須便宜且無副作用。
3. UI 狀態一律在 MainActor：不是靠自覺 DispatchQueue.main，而是用 @MainActor 讓型別系統替你保證。
4. continuation 必須 resume 恰好一次：橋接舊 API 時，零次＝永久卡死，兩次＝crash——這是紅線不是風格。
5. 取消是協作式的：Task 不會自動停，長工作要主動 Task.checkCancellation()；.task modifier 才自動綁生命週期。

開工分流

紅線（絕對禁止）

• 禁止只用模擬器驗證後宣告上架相關改動完成——簽章、entitlement、background mode、release optimization 在模擬器全不真實。
• 禁止讓 continuation resume 兩次或零次——兩次直接 crash，零次永久掛起；每條路徑都要恰好一次。
• 禁止在 App Store purpose string（NSCameraUsageDescription 等）寫敷衍或空字串——Apple 直接以 Guideline 5.1.1 拒；缺對應權限說明會 crash 或被拒。
• 禁止把 UI 狀態更新丟到非 MainActor——資料競爭 + 畫面更新在背景執行緒是未定義行為；用 @MainActor 標註而非手動切 queue。
• 禁止在 body 內做網路/IO/寫狀態——body 每幀可能重算多次，副作用會爆量重跑；用 .task/.onChange 或下放 model。
• 禁止把 reference type 放進 @State、或每次重建 @ObservedObject——前者 SwiftUI 不追蹤變更，後者每次刷新丟失狀態。
• 禁止改測試斷言讓 CI 變綠——連紅兩次是方向錯誤訊號，退回上一決策點。

失敗訊號（該回頭，不是重試）

references 索引

• references/architecture-state.md — SwiftUI 狀態擁有權決策表、MV vs MVVM、單向資料流、body 成本、NavigationStack 建模。動架構或新功能前讀。
• references/concurrency.md — Task 生命週期、@MainActor 標註層級、actor、Sendable/Swift 6、取消、continuation 橋接。碰非同步就讀。
• references/release-checklist.md — 簽章/provisioning 決策樹、App Store 審核被拒高頻原因、dSYM、release-only 差異、TestFlight、versioning。出版前必讀。
• references/test-scenarios.md — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。