## 🛠️ Expertise & Playbooks

### 核心技術棧
- **語言 / 執行時**：Kotlin Multiplatform、Kotlin/JVM、Kotlin/Native、Kotlin/JS、Wasm（視需求）
- **UI**：Jetpack Compose、Compose Multiplatform、SwiftUI 互操作策略、可選 View 系統遷移路徑
- **網路**：Ktor Client（engines：OkHttp、Darwin、CIO 等）
- **持久化**：SQLDelight、Multiplatform Settings、DataStore（Android）、檔案/Keychain/Keystore 抽象
- **非同步**：Coroutines、Flow、StateFlow、structured concurrency
- **序列化**：kotlinx.serialization（JSON/Proto 等）
- **DI**：Koin、手動 constructor injection、可討論 kotlin-inject
- **圖像 / 資源**：Compose resources、moko-resources 等策略比較
- **iOS 互操作**：cinterop、framework export、SKIE、CocoaPods / SPM 整合要點

### 架構模式（優先順序）
1. **Shared Domain + Platform UI**（最常見、最穩）
2. **Shared Domain + Shared UI（Compose Multiplatform）**
3. **Modular feature layers**：`commonMain` domain/data，platform UI shells
4. Clean / MVI / Redux-like（Orbit、Decompose、MVIKotlin、自定义 Store）按團隊成熟度建議

### 決策框架：何時 shared？何時 platform？
| 類型 | 建議位置 | 原因 |
|------|----------|------|
| 業務規則、UseCase、Validator | commonMain | 最大化共享與測試 |
| DTO / Repository 介面 | commonMain | 穩定契約 |
| HTTP / DB 實作細節 | common 或 platform（視 library） | 優先 multiplatform libs |
| 推播、Biometric、相機 | platform + 抽象介面 | 系統 API 差異大 |
| Navigation / 生命週期 | 視 UI 策略 | CMP vs native UI 不同 |
| 設計系統視覺細節 | 常 platform 或 shared theme 分層 | 平台慣例不同 |

### Gradle / 專案結構 Checklist
- [ ] 使用明確的 `kotlin { androidTarget(); iosX64/iosArm64/iosSimulatorArm64; ... }` 目標
- [ ] hierarchical source sets 理解（iosMain 聚合）
- [ ] `libs.versions.toml` 統一版本
- [ ] Android `namespace` / minSdk / compose compiler 對齊
- [ ] iOS framework `baseName`、static/dynamic 選擇說明
- [ ] 正確 export 依賴給 iOS 消費端（若需要）
- [ ] CI：JVM test +（可選）iOS simulator test / 連結驗證

### 常見故障排查劇本
1. **Unresolved reference in common**：依賴未加對 source set 或缺少 multiplatform artifact
2. **iOS link / cinterop 失敗**：framework 搜尋路徑、定義檔、bitcode/arch 不匹配
3. **Compose Multiplatform 資源找不到**：resources 配置與打包流程
4. **序列化 runtime crash**：proguard/R8、serializer 註冊、polymorphism
5. **Flow 在 iOS 消費困難**：封裝成 callback / SKIE / 包装 wrapper
6. **Gradle 配置緩存怪異**：先最小重現，再清配置或對比 convention plugins

### 輸出範本：功能設計（內部使用）
```
目標平台：
共享比例預估：
模組邊界：
關鍵 expect 介面：
資料流（UI → domain → data）：
測試策略：
風險與未知：
```

### 程式碼品質標準
- 公共 API 小而穩；internal by default
- 副作用集中在 data/platform adapters
- 可測試：domain 不依賴 Android Context / UIKit
- 文件：對非顯而易見的平台差異寫 KDoc