CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此仓库中工作提供指引。

常用命令

# 运行全部测试
flutter test

# 运行单个测试文件
flutter test test/features/recording/view_model_recording_test.dart

# 静态分析
flutter analyze

# 构建 Android release APK
flutter build apk --release

# 构建 Android release APK（按 ABI 拆分）
./build-apk-split.sh

# 清理并重装 iOS pods
./clean.sh

# 在指定设备上运行
flutter run -d <device-id>

架构

这是一个 Flutter 视频录制工具（酷跑录像工作台），支持 Android 和 iOS。应用从系统剪贴板读取赛事信息（来自小程序的 JSON），初始化 CameraX/AVFoundation 相机预览，录制视频并保存到文件系统。

状态管理：Riverpod

使用 NotifierProvider 模式。主状态 provider 为 recordingViewModelProvider，位于 lib/features/recording/view-model/view_model_recording.dart。UI 通过 ref.watch(provider.select(...)) 细粒度读取状态，通过 ref.read(provider.notifier).method() 调用操作。

状态模型（`RecordingSessionState`）

lib/features/recording/model/model_recording_session.dart 中的关键字段：

isTouchLocked — 防误触状态（默认 true，开始录制时置为 true）
zoomRatio, minZoomRatio, maxZoomRatio — 超广角（<1.0）与主摄（1.0）切换
isRecording, isPreviewReady, isStartingRecording
status — 原生端 RecordingState 流

原生桥接

lib/features/recording/platform/recording_platform.dart 封装了所有与 Android（Kotlin/CameraX）和 iOS（Swift/AVFoundation）通信的 MethodChannel/EventChannel 调用。禁止直接调用 channel，统一通过 RecordingPlatform。

原生关键文件

Android: android/app/src/main/kotlin/com/run/sportsx/recording/RecordingCameraController.kt
iOS: ios/Runner/RecordingPlugin.swift
两个平台均实现 lib/features/recording/platform/recording_channel_names.dart 中定义的 channel 名称

网络层

lib/core/network/ — 基于 Dio，包含 ApiClient、ApiResponse<T>、ApiException、请求头拦截器，以及离线队列（当前未启用）。网络 provider 定义在 lib/core/network/providers/dio_providers.dart。

相机倍距/镜头切换逻辑

lib/features/recording/widgets/widget_recording_hud.dart:199 中的 _ZoomPresetControl 组件渲染倍距预设按钮（超广角 = <1.0，主摄 = 1.0）。_wouldSwitchPhysicalCamera 方法在录制过程中禁止切换物理镜头。组件接收 isRecording 和倍距值；isTouchLocked 已存在于父级 RecordingHudWidget 但未传入 _ZoomPresetControl。

防误触

widget_recording_touch_lock_overlay.dart — 全屏遮罩，isTouchLocked 为 true 时显示"防误触已开启"。需长按 2 秒解锁。防误触默认 true，开始录制时也会置为 true（view_model_recording.dart:400）。

路由

lib/app/router/app_navigator.dart — 单例导航器，支持路由去重和自定义滑动过渡动画。

3.0 KiB Raw Blame History Unescape Escape