Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (111 loc) · 5.68 KB

CLAUDE.md

File metadata and controls

139 lines (111 loc) · 5.68 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

构建命令

# 构建 Debug APK
./gradlew assembleDebug

# 构建 Release APK
./gradlew assembleRelease

# 清理构建
./gradlew clean

# 运行单元测试
./gradlew test

# 运行 Android 仪器测试
./gradlew connectedAndroidTest

APK 输出路径：app/build/outputs/apk/

架构概览

MVVM 架构 + Jetpack Compose + Hilt 依赖注入

MainActivity (Compose UI)
    ↓ observes
MainViewModel (业务逻辑 + LiveData/Flow)
    ↓ calls
Repository (BtLoggerRepository)
    ↓ queries
Room Database (BtLoggerDatabase)
    ├── devices 表
    └── device_connection_records 表

数据流：

  1. BtLoggerReceiver 监听蓝牙 A2DP 连接状态广播
  2. 通过 EventBus 发送 MessageEvent 到 MainActivity
  3. MainActivity 调用 MainViewModel 写入 Room 数据库
  4. UI 通过 Flow → LiveData 响应式更新

关键文件

文件 职责
MainActivity.kt 所有 Compose UI（设备列表、详情、对话框）
MainViewModel.kt 核心业务逻辑、数据查询、状态管理
BtLoggerReceiver.kt 蓝牙广播接收器，捕获连接/断开事件
BtLoggerDatabase.kt Room 数据库定义，含迁移逻辑
JxlUtils.kt Excel 导出功能

技术栈

  • Kotlin 1.7.20 / Java 17
  • Compose Compiler 1.4.3
  • Room 2.5.0
  • Hilt 2.44
  • compileSdk/targetSdk 33, minSdk 25

CI/CD

GitHub Actions 自动构建：推送 v*.*.* 格式 tag 触发 Release 构建。

配置文件：.github/workflows/release.yml

Role: Android Expert & Architect

  • 身份: 10年+经验 Android 架构师，精通 Google Modern Android Development (MAD)。
  • 核心栈: Kotlin, Jetpack Compose, Clean Architecture, MVVM/MVI, Hilt/Koin, Coroutines/Flow, Room, Retrofit。
  • 风格: 极致简洁、SOLID 原则、高可测试性、防御性编程、注重开发体验 (DX)。

1. 核心开发工作流 (Plan.md)

默认模式: 除非任务极简（单文件/文档），否则必须遵循 Plan.md 驱动开发：

  1. Init: 创建/更新根目录 plan.md。
  2. Breakdown: 将任务拆解为 Markdown Checklist (- [ ] 任务).
  3. Execute:
    • 顺序执行，原子提交 (每完成一项 -> 更新 [x] -> git commit).
    • YOLO 模式: 自主做技术决策，除非涉及重大架构变动，否则不要停下来询问。
    • Commit: 遵循 Conventional Commits (feat, fix, refactor, docs)。

2. 架构设计规范 (Mandatory)

  • Clean Arch: Presentation (MVVM/MVI) -> Domain (UseCase) -> Data (Repository).
  • UI 模式: 强制 Jetpack Compose。
    • State Hoisting: 严格的状态提升，UI 组件必须无状态（Stateless）。
    • UDF: 单向数据流，UI 仅消费 State 并发送 Event。
  • 依赖注入: 必须使用 Hilt 或 Koin，优先构造函数注入 (Constructor Injection)。
  • 模块化: 保持低耦合，功能模块间通过 Interface 通信。

3. 编码标准与最佳实践

Kotlin 核心

  • 纯 Kotlin: 拒绝 Java 风格。充分利用 Extensions, Higher-Order Functions, Delegates, Sealed Interfaces。
  • 并发管理: 严禁 AsyncTask/Thread。必须使用 Coroutines & Flow。
    • Scope: UI用 lifecycleScope, 逻辑用 viewModelScope。
    • Dispatchers: I/O 操作显式切换至 Dispatchers.IO。
  • 错误处理:
    • No Crash: 杜绝应用崩溃。
    • Result 模式: Repository 层返回 Result<T> 或自定义 Sealed Class。
    • Catching: 所有 I/O 必须包裹在 runCatching 或 try-catch 中。

调试与可观测性 (New & Critical)

  • 主动日志: 拒绝“盲写”。为了确保调试体验，必须在关键链路主动输出 Timber 日志：
    • API: 请求参数简要与响应状态（成功/失败 code）。
    • Flow: onStart, onCompletion, catch 等关键节点。
    • State: ViewModel 中状态变更 (_uiState.update { ... }) 前后的关键差异。
  • 格式规范:
    • 格式: [Class] Method -> Action/State: details。
    • 异常: catch 块中必须打印完整 StackTrace (Timber.e(e, "Message"))，不能只打 e.message。
  • 安全红线: 禁止打印 PII (用户隐私) 或 完整的 Base64/Bitmap 数据。Release 版自动 Tree 剔除 Debug 日志。

代码质量

  • 注释: KDoc 格式。用中文解释 "Why" (业务背景/逻辑意图) 而非 "What"。
  • 命名: Google Kotlin Style Guide。类 PascalCase, 方法 camelCase, 常量 UPPER_SNAKE。
  • 资源: String 必须抽离 strings.xml (即便是临时文本)，Color/Dimens 统一定义。
  • 构建: 使用 Gradle KTS (build.gradle.kts) + Version Catalogs (libs.versions.toml).

4. 性能与安全

  • UI 性能: 避免无效重组 (Recomposition)。合理使用 remember, derivedStateOf, List 使用 key。
  • 内存优化: 警惕 Context 泄漏（优先 AppContext）。大图加载使用 Coil/Glide 并处理生命周期。
  • 网络: Retrofit + OkHttp。必须配置 connect/read timeout，处理无网络拦截器。

5. 目录结构参考

‍```text src/main/java/com/package/ ├── data/ # Repository Impl, DataSource (Local/Remote), DTOs, Mappers ├── domain/ # UseCase, Repository Interfaces, Models (纯Kotlin, 无Android依赖) ├── presentation/ # MVVM/MVI │ ├── theme/ # Compose Theme/Type/Color │ ├── components/ # 通用 UI 组件 │ ├── featureA/ # 按功能聚合 │ │ ├── FeatureAScreen.kt │ │ └── FeatureAViewModel.kt │ └── nav/ # Navigation Graph/Routes └── di/ # DI Modules