@pilllesss/yorn 1.0.182 → 1.0.183

package/dist/skills/code-review/reference/kotlin.md

@@ -0,0 +1,1018 @@
+# Kotlin / Android Code Review Guide
+
+> Kotlin/Android 代码审查指南，覆盖协程作用域与取消、Flow 陷阱、Compose 重组、空安全、内存泄漏、架构分层与密封类状态建模等核心主题。
+
+## 目录
+
+- [协程：作用域与取消](#协程作用域与取消)
+- [Flow 陷阱](#flow-陷阱)
+- [Jetpack Compose 重组](#jetpack-compose-重组)
+- [空安全模式](#空安全模式)
+- [内存泄漏](#内存泄漏)
+- [架构：ViewModel 与 Repository](#架构viewmodel-与-repository)
+- [密封类与状态管理](#密封类与状态管理)
+- [Review Checklist](#review-checklist)
+
+---
+
+## 协程：作用域与取消
+
+> 📖 通用并发模式和跨语言示例详见 [异步与并发跨语言指南](cross-cutting/async-concurrency-patterns.md)
+
+### 避免 GlobalScope
+
+```kotlin
+// ❌ GlobalScope 生命周期不受控，Activity/Fragment 销毁后协程仍在运行
+GlobalScope.launch {
+    val data = api.fetchData()
+    binding.textView.text = data.title // Crash: view destroyed
+}
+
+// ✅ 使用 viewModelScope，ViewModel 清除时自动取消
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    fun loadData() {
+        viewModelScope.launch {
+            val data = repo.fetchData()
+            _uiState.value = UiState.Success(data)
+        }
+    }
+}
+
+// ✅ 在 Activity/Fragment 中使用 lifecycleScope
+class MyActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        lifecycleScope.launch {
+            val data = repo.fetchData()
+            binding.textView.text = data.title
+        }
+    }
+}
+```
+
+### CancellationException 不能吞掉
+
+```kotlin
+// ❌ 捕获所有异常导致取消信号丢失
+viewModelScope.launch {
+    try {
+        repo.fetchData()
+    } catch (e: Exception) {
+        // CancellationException 被吞掉，协程无法取消
+        showError(e)
+    }
+}
+
+// ✅ 重新抛出 CancellationException
+viewModelScope.launch {
+    try {
+        repo.fetchData()
+    } catch (e: CancellationException) {
+        throw e // Must rethrow
+    } catch (e: Exception) {
+        showError(e)
+    }
+}
+
+// ✅ 或使用 catch 配合 ensureActive
+viewModelScope.launch {
+    try {
+        repo.fetchData()
+    } catch (e: Exception) {
+        ensureActive() // Rethrows if cancelled
+        showError(e)
+    }
+}
+```
+
+### CPU-bound 任务需要检查取消
+
+```kotlin
+// ❌ CPU 密集计算不响应取消，即使协程已取消也会跑完
+viewModelScope.launch(Dispatchers.Default) {
+    for (item in largeList) {
+        heavyComputation(item)
+    }
+}
+
+// ✅ 定期检查 isActive 或调用 ensureActive
+viewModelScope.launch(Dispatchers.Default) {
+    for (item in largeList) {
+        ensureActive() // Throws CancellationException if cancelled
+        heavyComputation(item)
+    }
+}
+
+// ✅ 或使用 yield 让出执行权
+viewModelScope.launch(Dispatchers.Default) {
+    for (item in largeList) {
+        yield() // Checks cancellation + yields to other coroutines
+        heavyComputation(item)
+    }
+}
+```
+
+### 阻塞操作使用 runInterruptible
+
+```kotlin
+// ❌ 在协程中直接调用阻塞 I/O，阻塞线程池线程
+viewModelScope.launch(Dispatchers.IO) {
+    val result = blockingLibraryCall() // Blocks IO thread
+}
+
+// ✅ 使用 runInterruptible 包装阻塞调用，支持取消中断
+viewModelScope.launch(Dispatchers.IO) {
+    val result = runInterruptible {
+        blockingLibraryCall() // Interrupted on cancellation
+    }
+}
+```
+
+### 正确选择调度器
+
+```kotlin
+// ❌ CPU 密集任务用了 IO 调度器（线程池过大，浪费资源）
+viewModelScope.launch(Dispatchers.IO) {
+    val bitmap = decodeImage(byteArray) // CPU-bound on IO pool
+}
+
+// ✅ CPU 密集用 Default，I/O 操作用 IO
+viewModelScope.launch(Dispatchers.Default) {
+    val bitmap = decodeImage(byteArray) // CPU-bound on Default pool
+}
+
+// ❌ IO 操作用了 Default 调度器（线程池太小，容易饥饿）
+viewModelScope.launch(Dispatchers.Default) {
+    val response = okHttpClient.newCall(request).execute() // I/O on Default pool
+}
+
+// ✅ I/O 操作用 IO 调度器
+viewModelScope.launch(Dispatchers.IO) {
+    val response = okHttpClient.newCall(request).execute()
+}
+```
+
+### launch vs async
+
+```kotlin
+// ❌ async 只用于"发个火"，不需要返回值
+viewModelScope.launch {
+    async { analytics.trackEvent("click") } // Overkill
+}
+
+// ✅ 不需要返回值用 launch
+viewModelScope.launch {
+    launch { analytics.trackEvent("click") }
+}
+
+// ✅ 需要返回值且可能并行时用 async
+viewModelScope.launch {
+    val deferredA = async { api.fetchA() }
+    val deferredB = async { api.fetchB() }
+    val result = combine(deferredA.await(), deferredB.await())
+}
+```
+
+### 不要用 Job() 破坏父子关系
+
+```kotlin
+// ❌ Job() 切断了父协程的取消传播
+viewModelScope.launch {
+    launch(Job()) { // Detached from parent scope!
+        importantWork() // Will NOT be cancelled when viewModelScope cancels
+    }
+}
+
+// ✅ 保持默认的父子关系
+viewModelScope.launch {
+    launch { // Child of viewModelScope
+        importantWork() // Cancelled when viewModelScope cancels
+    }
+}
+
+// ✅ 如果确实需要独立生命周期，显式管理并说明原因
+class MyManager(private val scope: CoroutineScope) {
+    // Independent lifecycle managed by MyManager.shutdown()
+    private val managerJob = Job(scope.coroutineContext[Job])
+    private val managerScope = scope + managerJob + Dispatchers.IO
+
+    fun shutdown() {
+        managerJob.cancel()
+    }
+}
+```
+
+### NonCancellable 的正确使用
+
+```kotlin
+// ❌ 整个协程都包在 withContext(NonCancellable) 中，无法取消
+viewModelScope.launch {
+    withContext(NonCancellable) { // Entire block is uncancellable!
+        val data = repo.fetchData() // Cannot be cancelled
+        db.saveData(data) // Cannot be cancelled
+        analytics.track("saved")
+    }
+}
+
+// ✅ NonCancellable 只用于清理操作
+viewModelScope.launch {
+    try {
+        val data = repo.fetchData()
+        db.saveData(data)
+    } catch (e: CancellationException) {
+        throw e
+    } finally {
+        withContext(NonCancellable) {
+            db.cleanup() // Only cleanup is uncancellable
+        }
+    }
+}
+```
+
+---
+
+## Flow 陷阱
+
+### 冷流与热流混淆
+
+```kotlin
+// ❌ 每次 collect 都重新执行 flow {} 块（冷流特性被误解）
+val userFlow = flow {
+    emit(api.fetchUser()) // Called once per collector!
+}
+
+// Two collectors = two network requests
+lifecycleScope.launch { userFlow.collect { } }
+lifecycleScope.launch { userFlow.collect { } }
+
+// ✅ 共享数据用 StateFlow/SharedFlow（热流）
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            _uiState.value = UiState.Success(repo.fetchUser())
+        }
+    }
+}
+// Multiple collectors share the same StateFlow
+```
+
+### 不要在 flow {} 中切换上下文
+
+```kotlin
+// ❌ 在 flow builder 中使用 withContext，违反约束
+val dataFlow = flow {
+    withContext(Dispatchers.IO) { // IllegalStateException!
+        emit(api.fetchData())
+    }
+}
+
+// ✅ 使用 flowOn 操作符切换上游上下文
+val dataFlow = flow {
+    emit(api.fetchData()) // Runs on IO via flowOn
+}.flowOn(Dispatchers.IO)
+
+// ✅ 或使用 channelFlow / callbackFlow 需要切换时
+val dataFlow = channelFlow {
+    withContext(Dispatchers.IO) {
+        send(api.fetchData()) // send() is safe in channelFlow
+    }
+}
+```
+
+### collect 需要生命周期感知
+
+```kotlin
+// ❌ 在 Activity/Fragment 中 collect 不感知生命周期
+lifecycleScope.launch {
+    viewModel.uiState.collect { state ->
+        binding.textView.text = state.title // Crash if view destroyed
+    }
+}
+
+// ✅ 在 Fragment 中使用 viewLifecycleOwner.lifecycleScope + repeatOnLifecycle
+viewLifecycleOwner.lifecycleScope.launch {
+    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.uiState.collect { state ->
+            binding.textView.text = state.title
+        }
+    }
+}
+
+// ✅ 在 Compose 中使用 collectAsStateWithLifecycle
+@Composable
+fun MyScreen(viewModel: MyViewModel) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    // ...
+}
+```
+
+### 异常透明性：使用 catch 操作符
+
+```kotlin
+// ❌ 在 collect 中 try-catch 处理上游异常
+viewModelScope.launch {
+    try {
+        dataFlow.collect { data ->
+            processData(data)
+        }
+    } catch (e: Exception) {
+        // This also catches exceptions from processData, not just upstream
+        showError(e)
+    }
+}
+
+// ✅ 使用 catch 操作符保持异常透明性
+viewModelScope.launch {
+    dataFlow
+        .catch { e -> showError(e) } // Only catches upstream exceptions
+        .collect { data ->
+            processData(data) // Exceptions here propagate normally
+        }
+}
+```
+
+### StateFlow vs SharedFlow 选择
+
+```kotlin
+// ❌ 用 SharedFlow 模拟 StateFlow，丢失最新值语义
+private val _state = MutableSharedFlow<UiState>()
+val state: SharedFlow<UiState> = _state
+
+// ✅ UI 状态用 StateFlow：总是有值、新订阅者立即获得最新值
+class MyViewModel : ViewModel() {
+    private val _uiState = MutableStateFlow(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+}
+
+// ✅ 事件（一次性通知）用 SharedFlow + replay(0)
+class MyViewModel : ViewModel() {
+    private val _navigationEvent = MutableSharedFlow<NavTarget>(extraBufferCapacity = 1)
+    val navigationEvent: SharedFlow<NavTarget> = _navigationEvent.asSharedFlow()
+
+    fun navigate(target: NavTarget) {
+        _navigationEvent.tryEmit(target)
+    }
+}
+
+// ✅ Channel 用于一次性事件（替代方案）
+private val _navigationEvent = Channel<NavTarget>(Channel.BUFFERED)
+val navigationEvent = _navigationEvent.receiveAsFlow()
+```
+
+---
+
+## Jetpack Compose 重组
+
+### 不稳定参数导致多余重组
+
+```kotlin
+// ❌ 使用不稳定的类作为参数，Compose 无法判断是否变化
+data class UserProfile(
+    val name: String,
+    val friends: List<String>, // Unstable! List is not @Stable
+)
+
+@Composable
+fun ProfileCard(profile: UserProfile) { // Recomposes even if profile didn't change
+    Text(profile.name)
+}
+
+// ✅ 使用 @Immutable 标注或使用稳定的集合类型
+@Immutable
+data class UserProfile(
+    val name: String,
+    val friends: ImmutableList<String>, // kotlinx.collections.immutable
+)
+
+// ✅ 或将不稳定属性提取为单独的参数
+@Composable
+fun ProfileCard(
+    name: String, // Stable: String is primitive
+    friendCount: Int, // Stable: Int is primitive
+) {
+    Text(name)
+    Text("$friendCount friends")
+}
+```
+
+### Lambda 不稳定与记忆化
+
+```kotlin
+// ❌ 每次重组都创建新的 Lambda，导致子组件不必要的重组
+@Composable
+fun MyScreen(viewModel: MyViewModel) {
+    LazyColumn {
+        items(items, key = { it.id }) { item ->
+            ItemRow(
+                item = item,
+                onClick = { viewModel.handleClick(item.id) } // New lambda each recomposition!
+            )
+        }
+    }
+}
+
+// ✅ 使用 remember 包装 Lambda，或让 ViewModel 暴露稳定回调
+@Composable
+fun MyScreen(viewModel: MyViewModel) {
+    LazyColumn {
+        items(items, key = { it.id }) { item ->
+            ItemRow(
+                item = item,
+                onClick = remember(item.id) { { viewModel.handleClick(item.id) } }
+            )
+        }
+    }
+}
+```
+
+### 使用 derivedStateOf 避免高频率重组
+
+```kotlin
+// ❌ 每次滚动都重组整个组件
+@Composable
+fun ScrollToTopButton(lazyListState: LazyListState) {
+    val showButton = lazyListState.firstVisibleItemIndex > 0 // Recomposes on every scroll
+    if (showButton) {
+        Button(onClick = { /* scroll to top */ }) {
+            Text("Top")
+        }
+    }
+}
+
+// ✅ 使用 derivedStateOf 只在结果变化时触发重组
+@Composable
+fun ScrollToTopButton(lazyListState: LazyListState) {
+    val showButton by remember {
+        derivedStateOf { lazyListState.firstVisibleItemIndex > 0 }
+    }
+    if (showButton) {
+        Button(onClick = { /* scroll to top */ }) {
+            Text("Top")
+        }
+    }
+}
+```
+
+### 不要在 Composable 函数体中执行副作用
+
+```kotlin
+// ❌ 在 Composable 函数体中直接触发副作用，每次重组都会执行
+@Composable
+fun MyScreen(userId: String, viewModel: MyViewModel) {
+    viewModel.loadUser(userId) // Called on every recomposition!
+    val user by viewModel.user.collectAsStateWithLifecycle()
+    Text(user?.name ?: "Loading...")
+}
+
+// ✅ 使用 LaunchedEffect 在 key 变化时执行副作用
+@Composable
+fun MyScreen(userId: String, viewModel: MyViewModel) {
+    LaunchedEffect(userId) {
+        viewModel.loadUser(userId) // Only when userId changes
+    }
+    val user by viewModel.user.collectAsStateWithLifecycle()
+    Text(user?.name ?: "Loading...")
+}
+
+// ✅ 一次性初始化用 remember { ... }
+@Composable
+fun MyScreen(viewModel: MyViewModel) {
+    val initialData = remember { viewModel.getInitialData() }
+}
+```
+
+### 状态提升
+
+```kotlin
+// ❌ 状态和逻辑耦合在 Composable 内部，无法复用和测试
+@Composable
+fun ToggleButton() {
+    var isChecked by remember { mutableStateOf(false) }
+    Switch(
+        checked = isChecked,
+        onCheckedChange = { isChecked = it }
+    )
+}
+
+// ✅ 状态提升：调用者控制状态
+@Composable
+fun ToggleButton(
+    isChecked: Boolean,
+    onCheckedChange: (Boolean) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Switch(
+        checked = isChecked,
+        onCheckedChange = onCheckedChange,
+        modifier = modifier,
+    )
+}
+
+// ✅ 调用者持有状态
+@Composable
+fun ParentScreen() {
+    var enabled by rememberSaveable { mutableStateOf(false) }
+    ToggleButton(
+        isChecked = enabled,
+        onCheckedChange = { enabled = it },
+    )
+}
+```
+
+---
+
+## 空安全模式
+
+### 避免非空断言 !!
+
+```kotlin
+// ❌ 非空断言：如果为 null 直接 NPE
+val user = getUser()!!
+val name = user.name!!
+
+// ✅ 安全调用 + 空合并
+val name = getUser()?.name ?: "Unknown"
+
+// ✅ requireNotNull 提供有意义的错误信息
+val user = requireNotNull(getUser()) { "User must not be null at this point" }
+
+// ✅ 提前返回
+fun process(user: User?) {
+    val nonNullUser = user ?: return
+    nonNullUser.doSomething()
+}
+```
+
+### lateinit vs nullable vs lazy
+
+```kotlin
+// ❌ lateinit 用于可能为 null 的值（语义不对）
+lateinit var optionalConfig: Config // Might never be set
+
+// ✅ lateinit 用于一定会在使用前初始化的值
+class MyActivity : AppCompatActivity() {
+    lateinit var binding: ActivityMainBinding // Set in onCreate
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        binding = ActivityMainBinding.inflate(layoutInflater)
+        setContentView(binding.root)
+    }
+}
+
+// ✅ nullable + lateinit 取决于初始化时机
+// lateinit: 生命周期保证在使用前初始化
+// nullable: 不确定是否初始化，需要 null 检查
+// lazy: 确定在首次访问时初始化
+
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    // lazy: 首次访问时初始化，线程安全
+    val expensiveObject by lazy { ExpensiveObject(repo) }
+
+    // nullable: 可能不会初始化
+    var cachedData: Data? = null
+        private set
+}
+```
+
+### Java 互操作：平台类型泄漏
+
+```kotlin
+// ❌ Java 返回平台类型（可能 null），Kotlin 当作非空使用
+// Java:
+// public User getUser() { return null; }
+val name: String = javaService.getUser().name // NPE!
+
+// ✅ 使用可空类型接收 Java 返回值
+val user: User? = javaService.getUser()
+val name = user?.name ?: "Unknown"
+
+// ✅ 在 Kotlin 侧包装 Java API，提供安全的类型
+class SafeUserService(private val delegate: JavaUserService) {
+    fun getUser(): User? = delegate.getUser() // Explicitly nullable
+}
+```
+
+---
+
+## 内存泄漏
+
+### 避免在长生命周期协程中捕获 Context/View
+
+```kotlin
+// ❌ 协程捕获了 Activity Context，Activity 销毁后无法回收
+class MyActivity : AppCompatActivity() {
+    fun loadData() {
+        // Leaking Activity via coroutine
+        GlobalScope.launch {
+            val data = repo.fetchData()
+            // 'this' (Activity) is captured
+            binding.textView.text = data // Activity leaked!
+        }
+    }
+}
+
+// ✅ 使用 viewModelScope + 生命周期感知
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+
+    fun loadData() {
+        viewModelScope.launch {
+            val data = repo.fetchData()
+            _uiState.value = UiState.Success(data) // No Activity reference
+        }
+    }
+}
+```
+
+### 注销监听器
+
+```kotlin
+// ❌ 注册监听器但从不注销
+class MyFragment : Fragment() {
+    private val sensorListener = object : SensorEventListener {
+        override fun onSensorChanged(event: SensorEvent) { }
+        override fun onAccuracyChanged(sensor: Sensor, accuracy: Int) { }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        sensorManager.registerListener(sensorListener, sensor, SensorManager.SENSOR_DELAY_UI)
+        // Never unregistered!
+    }
+}
+
+// ✅ 在 onPause/onDestroyView 中注销
+override fun onResume() {
+    super.onResume()
+    sensorManager.registerListener(sensorListener, sensor, SensorManager.SENSOR_DELAY_UI)
+}
+
+override fun onPause() {
+    super.onPause()
+    sensorManager.unregisterListener(sensorListener)
+}
+```
+
+### 取消自定义 CoroutineScope
+
+```kotlin
+// ❌ 创建 CoroutineScope 但从不取消
+class MyManager(private val scope: CoroutineScope) {
+    private val job = SupervisorJob()
+    private val managerScope = scope + job + Dispatchers.IO
+
+    fun start() {
+        managerScope.launch {
+            while (isActive) {
+                pollServer()
+                delay(5000)
+            }
+        }
+    }
+    // Never cancelled! job lives forever.
+}
+
+// ✅ 提供关闭方法并取消 Job
+class MyManager(private val scope: CoroutineScope) {
+    private val job = SupervisorJob()
+    private val managerScope = scope + job + Dispatchers.IO
+
+    fun start() {
+        managerScope.launch {
+            while (isActive) {
+                pollServer()
+                delay(5000)
+            }
+        }
+    }
+
+    fun shutdown() {
+        job.cancel()
+    }
+}
+
+// ✅ ViewModel 里直接用内置的 viewModelScope，不用自己管生命周期
+class MyViewModel : ViewModel() {
+    private val scope = viewModelScope + Dispatchers.IO
+    // Automatically cancelled when ViewModel is cleared
+}
+```
+
+---
+
+## 架构：ViewModel 与 Repository
+
+### ViewModel 不暴露可变状态
+
+```kotlin
+// ❌ 直接暴露 MutableStateFlow，外部可以随意修改
+class MyViewModel : ViewModel() {
+    val uiState = MutableStateFlow<UiState>(UiState.Loading) // Mutable!
+
+    fun load() {
+        viewModelScope.launch {
+            uiState.value = UiState.Success(repo.fetchData())
+        }
+    }
+}
+
+// ✅ 暴露不可变接口，内部持有可变版本
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+
+    fun load() {
+        viewModelScope.launch {
+            _uiState.value = UiState.Success(repo.fetchData())
+        }
+    }
+}
+```
+
+### 业务逻辑下沉到 Repository
+
+```kotlin
+// ❌ ViewModel 中包含数据处理和业务规则逻辑
+class UserViewModel(private val api: Api) : ViewModel() {
+    private val _users = MutableStateFlow<List<User>>(emptyList())
+    val users: StateFlow<List<User>> = _users.asStateFlow()
+
+    fun loadUsers() {
+        viewModelScope.launch {
+            val raw = api.getUsers()
+            val filtered = raw.filter { it.isActive }
+            val sorted = filtered.sortedBy { it.name.lowercase() }
+            val enriched = sorted.map { user ->
+                user.copy(displayName = "${user.firstName} ${user.lastName}")
+            }
+            _users.value = enriched
+        }
+    }
+}
+
+// ✅ ViewModel 只做状态管理，逻辑下沉到 Repository
+class UserRepository(private val api: Api) {
+    suspend fun getActiveUsersSorted(): List<User> {
+        return api.getUsers()
+            .filter { it.isActive }
+            .sortedBy { it.name.lowercase() }
+            .map { it.copy(displayName = "${it.firstName} ${it.lastName}") }
+    }
+}
+
+class UserViewModel(private val repo: UserRepository) : ViewModel() {
+    private val _users = MutableStateFlow<List<User>>(emptyList())
+    val users: StateFlow<List<User>> = _users.asStateFlow()
+
+    fun loadUsers() {
+        viewModelScope.launch {
+            _users.value = repo.getActiveUsersSorted()
+        }
+    }
+}
+```
+
+### 单一数据源（Offline-First）
+
+```kotlin
+// ❌ ViewModel 直接从网络获取，无缓存，离线不可用
+class MyViewModel(private val api: Api) : ViewModel() {
+    fun load() {
+        viewModelScope.launch {
+            _uiState.value = UiState.Success(api.fetchData())
+        }
+    }
+}
+
+// ✅ Repository 作为单一数据源，先展示本地缓存再更新网络数据
+class MyRepository(
+    private val api: Api,
+    private val dao: DataDao,
+) {
+    val data: Flow<List<Data>> = dao.getAll()
+        .map { entities -> entities.map { it.toDomain() } }
+
+    suspend fun refresh() {
+        val remote = api.fetchData()
+        dao.replaceAll(remote.map { it.toEntity() })
+    }
+}
+
+class MyViewModel(private val repo: MyRepository) : ViewModel() {
+    val uiState = repo.data.map { UiState.Success(it) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), UiState.Loading)
+
+    fun refresh() {
+        viewModelScope.launch { repo.refresh() }
+    }
+}
+```
+
+### Use Case 用于复杂业务逻辑
+
+```kotlin
+// ❌ Repository 方法名变成动词短语，职责膨胀
+class OrderRepository {
+    suspend fun validateAndSubmitOrder(order: Order) { }
+    suspend fun calculateOrderTotalWithDiscounts(order: Order): Money { }
+    suspend fun checkInventoryAndReserve(items: List<Item>) { }
+}
+
+// ✅ 使用 Use Case 封装复杂业务逻辑，Repository 只做数据访问
+class SubmitOrderUseCase(
+    private val orderRepo: OrderRepository,
+    private val inventoryRepo: InventoryRepository,
+    private val paymentRepo: PaymentRepository,
+) {
+    suspend operator fun invoke(order: Order): Result<OrderConfirmation> {
+        val validated = order.validate()
+        inventoryRepo.reserve(validated.items)
+        val total = CalculateOrderTotalUseCase().invoke(validated)
+        return paymentRepo.charge(total).map { confirmation ->
+            orderRepo.save(validated.copy(status = OrderStatus.CONFIRMED))
+            confirmation
+        }
+    }
+}
+
+class OrderRepository {
+    suspend fun save(order: Order) { }
+    suspend fun getById(id: String): Order? { }
+    fun observeOrders(): Flow<List<Order>> { }
+}
+```
+
+---
+
+## 密封类与状态管理
+
+### UI 状态建模：让不可能的状态无法表达
+
+```kotlin
+// ❌ 用 nullable 组合表示状态，可能产生无效组合
+data class UiState(
+    val isLoading: Boolean = false,
+    val data: List<Item>? = null,
+    val error: String? = null,
+)
+// Invalid: isLoading=true AND error != null
+// Invalid: data != null AND error != null
+
+// ✅ 使用密封类建模，每种状态互斥
+sealed interface UiState {
+    data object Loading : UiState
+    data class Success(val data: List<Item>) : UiState
+    data class Error(val message: String, val cause: Throwable? = null) : UiState
+}
+
+class MyViewModel(private val repo: Repository) : ViewModel() {
+    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
+    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+}
+
+// ✅ Compose 中 exhaustive when
+@Composable
+fun MyScreen(viewModel: MyViewModel) {
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    when (state) {
+        is UiState.Loading -> CircularProgressIndicator()
+        is UiState.Success -> DataList((state as UiState.Success).data)
+        is UiState.Error -> ErrorMessage((state as UiState.Error).message)
+    }
+}
+```
+
+### 导航事件建模
+
+```kotlin
+// ❌ 用枚举或字符串表示导航事件，无法携带参数
+sealed class NavEvent {
+    object ToDetail : NavEvent()
+    object ToSettings : NavEvent()
+}
+// How to pass orderId to ToDetail?
+
+// ✅ 密封类携带类型安全参数
+sealed interface NavEvent {
+    data class ToDetail(val orderId: String) : NavEvent
+    data class ToSettings(val tab: SettingsTab) : NavEvent
+    data class ToProfile(val userId: String, val mode: ProfileMode) : NavEvent
+}
+
+// ✅ 处理导航事件
+navController.handleNavEvent { event ->
+    when (event) {
+        is NavEvent.ToDetail -> navController.navigate(DetailRoute(event.orderId))
+        is NavEvent.ToSettings -> navController.navigate(SettingsRoute(event.tab))
+        is NavEvent.ToProfile -> navController.navigate(ProfileRoute(event.userId, event.mode))
+    }
+}
+```
+
+### 网络结果包装
+
+```kotlin
+// ❌ 用 Result? 或 nullable 表示网络结果，丢失错误信息
+suspend fun fetchUser(id: String): User? {
+    return try {
+        api.getUser(id)
+    } catch (e: Exception) {
+        null // What went wrong?
+    }
+}
+
+// ✅ 使用密封类包装网络结果
+sealed interface NetworkResult<out T> {
+    data class Success<T>(val data: T) : NetworkResult<T>
+    data class Error(val code: Int, val message: String) : NetworkResult<Nothing>
+    data class Exception(val cause: Throwable) : NetworkResult<Nothing>
+}
+
+suspend fun fetchUser(id: String): NetworkResult<User> {
+    return try {
+        val response = api.getUser(id)
+        if (response.isSuccessful) {
+            NetworkResult.Success(response.body()!!)
+        } else {
+            NetworkResult.Error(response.code(), response.message())
+        }
+    } catch (e: Exception) {
+        NetworkResult.Exception(e)
+    }
+}
+
+// ✅ 在 ViewModel 中映射为 UI 状态
+fun loadUser(id: String) {
+    viewModelScope.launch {
+        when (val result = repo.fetchUser(id)) {
+            is NetworkResult.Success -> _uiState.value = UiState.Success(result.data)
+            is NetworkResult.Error -> _uiState.value = UiState.Error("Server error: ${result.code}")
+            is NetworkResult.Exception -> _uiState.value = UiState.Error(result.cause.message ?: "Unknown")
+        }
+    }
+}
+```
+
+---
+
+## Review Checklist
+
+### 协程
+
+- [ ] 不使用 `GlobalScope`，使用 `viewModelScope` / `lifecycleScope`
+- [ ] `CancellationException` 被正确重新抛出，未被吞掉
+- [ ] CPU 密集任务使用 `Dispatchers.Default`，I/O 操作使用 `Dispatchers.IO`
+- [ ] 长时间运行的 CPU 任务定期调用 `ensureActive()` 或 `yield()`
+- [ ] 阻塞调用使用 `runInterruptible` 包装
+- [ ] 不使用 `Job()` 破坏父子协程关系
+- [ ] `NonCancellable` 仅用于 `finally` 块中的清理操作
+- [ ] 不需要返回值用 `launch`，需要并行结果用 `async`
+
+### Flow
+
+- [ ] 理解冷流（`flow {}`）与热流（`StateFlow`/`SharedFlow`）的区别
+- [ ] 不在 `flow {}` builder 中使用 `withContext`，使用 `flowOn` 操作符
+- [ ] `collect` 配合 `repeatOnLifecycle` 或 `collectAsStateWithLifecycle` 使用
+- [ ] 异常处理使用 `.catch` 操作符而非 `try-catch` 包裹 `collect`
+- [ ] UI 状态用 `StateFlow`，一次性事件用 `SharedFlow` 或 `Channel`
+
+### Compose
+
+- [ ] Composable 参数使用稳定类型，避免不必要重组
+- [ ] Lambda 参数使用 `remember` 包装，避免每次重组创建新实例
+- [ ] 派生状态使用 `derivedStateOf` 避免高频率重组
+- [ ] 副作用使用 `LaunchedEffect` / `SideEffect`，不在函数体中直接调用
+- [ ] 状态正确提升（state hoisting），Composable 无状态且可复用
+
+### 空安全
+
+- [ ] 不滥用非空断言 `!!`，使用安全调用 `?.` 或空合并 `?:`
+- [ ] `lateinit` 仅用于生命周期保证初始化的属性
+- [ ] Java 互操作返回值使用可空类型接收
+- [ ] `lazy` 用于首次访问时初始化的昂贵对象
+
+### 内存泄漏
+
+- [ ] 协程不捕获 `Context` / `View` 等短生命周期对象
+- [ ] 监听器在 `onPause` / `onDestroyView` 中正确注销
+- [ ] 自定义 `CoroutineScope` 提供取消机制
+- [ ] 单例不持有 `Activity` / `Fragment` 引用
+
+### 架构
+
+- [ ] ViewModel 不暴露 `MutableStateFlow` / `MutableLiveData`，使用不可变接口
+- [ ] 业务逻辑下沉到 Repository / Use Case，ViewModel 只做状态管理
+- [ ] 实现 offline-first：Repository 作为单一数据源
+- [ ] 复杂业务逻辑封装为独立的 Use Case 类
+
+### 密封类与状态
+
+- [ ] UI 状态使用密封类建模，让不可能的状态无法表达
+- [ ] 导航事件使用密封类携带类型安全参数
+- [ ] 网络请求结果使用密封类包装，不丢失错误信息
+- [ ] `when` 表达式覆盖所有分支（exhaustive check）