# CLAUDE.md

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

## CLAUDE.md 自动同步声明
- 忽略细微修改，对变量名、注释、小范围格式等不影响架构或逻辑的变更，无需同步更新。
- CLAUDE.md 内容关联同步
  - 新增对外暴露的接口、模块时，Claude 必须在此文件中添加相应的描述。
  - 若本文件中描述的内容（如模块职责、接口定义等）在代码中被修改、重命名或移除，Claude 必须同时在此文件中反映这些更改。
  - 修改内容如在原 CLAUDE.md 中未涉及，则无需添加新内容。
- 数量限制
  - 根目录 CLAUDE.md 控制在400行内
  - 模块内 CLAUDE.md 控制在300行内
  - 超出行数限制时，优先保留核心架构和规范内容，删除冗余或重复信息。

## 角色
你是一个资深的 Android 架构专家，尤其擅长Kotlin+Jetpack技术栈。

### 编码风格要求
- 遵循 Kotlin 官方代码规范
- 遵循单一职责原则（每个类只负责一件事）
- 避免冗余注释，保持代码简洁清晰

### 项目约定
- 异步操作使用协程，通过 frame/coroutine 模块使用
- 网络请求、文件操作、事件处理返回结果使用 RLT类(result)，RLT类封装在 frame/zero 中
- 日志必须使用 `AppBase.log` 进行输出
  - `AppBase` 导入方式 `import com.adealink.frame.base.AppBase`
  - `AppBase.log.d(tag, msg)` - 调试日志（Debug）
  - `AppBase.log.i(tag, msg)` - 信息日志（Info），会保留到线上，要求重要步骤或重要信息才使用该级别的日志
  - `AppBase.log.e(tag, msg)` - 错误日志（Error，无异常）
  - `AppBase.log.e(tag, msg, exception)` - 错误日志（Error，带异常对象）
- 编写与业务无关的公共功能，优先调用 frame/util 模块中已有的工具类，若不存在对应逻辑，请将该逻辑封装为新的工具方法或类

## 项目架构
这是一个模块化的Android框架库，采用多模块架构设计。项目分为两大类别：
- **frame/**: 核心框架模块
- **external/**: 第三方库集成模块

### frame 代码目录结构
**基础架构模块（Framework Core）:**
- `frame/base`: 基于 RLT 状态管理的项目基础，所有其他模块的依赖基础
- `frame/mvvm`: MVVM 架构扩展，提供 ViewModel 和 LiveData 支持
- `frame/coroutine`: Kotlin 协程工具封装
- `frame/data`: 自定义数据结构和类型转换
- `frame/util`: 通用工具类集合
- `frame/spi`: 服务发现和依赖注入框架（Service Provider Interface）
- `frame/startup`: 应用启动初始化框架（统一管理模块初始化顺序）
- `frame/bom`: 统一依赖版本管理（Bill of Materials）

**网络与存储（Network & Storage）:**
- `frame/network`: 基于 Retrofit 的网络请求框架
- `frame/storage`: 统一的存储管理（文件存储、SharedPreferences）
- `frame/oss`: 对象存储服务封装（支持阿里云 OSS、腾讯 COS）
- `frame/cachebean`: 缓存数据模型定义及持久化管理
- `frame/download`: 下载管理器封装（多线程断点续传、任务调度）

**UI组件（UI & Visual Components）:**
- `frame/effect`: 动画效果播放框架（支持 SVGA、VAP 等格式）
- `frame/effectpreview`: 动画效果预览与编辑工具
- `frame/image`: 图片加载框架（基于 Fresco）
- `frame/commonui`: 公共 UI 组件库
- `frame/dot`: 红点提醒系统
- `frame/guide`: 新手引导与引导浮层组件
- `frame/media`: 音视频媒体播放、录制与处理封装

**实时通信（RTC & 音视频）:**
- `frame/agorartc`: 声网 RTC SDK 封装
- `frame/trtc`: 腾讯云 RTC SDK 封装
- `frame/volcrtc`: 火山引擎 RTC SDK 封装
- `frame/zegortc`: 即构 RTC SDK 封装
- `frame/room`: 统一的房间信令管理
- `frame/audio`: 音频播放与录制管理
- `frame/sound`: 音效与提示音管理模块

**系统与服务（System & Platform）:**
- `frame/router`: 基于注解的页面路由框架
- `frame/security`: 应用安全检测和防护功能
- `frame/deviceid`: 设备唯一标识管理
- `frame/locale`: 多语言本地化支持和位置定位
- `frame/log`: 统一日志采集与打印框架
- `frame/crash`: 崩溃捕获与上报
- `frame/statistics`: 埋点与数据统计上报框架
- `frame/apm`: 性能监控系统（内存、卡顿、CPU、FPS 等）
- `frame/tceffect`: 腾讯特效 SDK 封装

**平台集成与外部服务（Integration & Cloud Service）:**
- `frame/googleservice`: Google 服务集成（Firebase、FCM 等）
- `frame/push`: 多厂商推送统一封装（华为、小米、OPPO、FCM）
- `frame/share`: 第三方分享与社交平台封装
- `frame/game`: 游戏 SDK 封装或小游戏容器集成
- `frame/zero`: 零配置接入工具包（用于快速初始化）
- `frame/bundletool`: Android App Bundle 构建与动态模块拆分工具
- `frame/aab`: AAB（Android App Bundle）打包支持工具
- `frame/asr`: 语音识别（ASR）模块

**开发与测试支持（Dev & Debug）:**
- `frame/debug`: 调试工具（悬浮窗、日志面板、环境切换）
- `frame/trace`: 性能追踪和调试分析（函数耗时、启动性能）

### external 代码目录结构
- `external/androidautosize`: AndroidAutoSize 屏幕适配库集成
- `external/animplayer`: 腾讯 VAP（Video Animation Player），用于播放酷炫动画的实现方案
- `external/SVGAPlayer`: SVGA 动画播放器集成
- `external/retrofit`: Retrofit 网络请求库集成
- `external/drawee`: Fresco DraweeView 图片渲染库集成
- `external/libcocos2dx`: Cocos2d-x 游戏引擎集成
- `external/tcturing`: 腾讯图灵盾风险识别

### 开发规范
1. **模块独立性**: 每个frame模块都应该可以独立编译和使用
2. **依赖方向**: 框架模块之间避免循环依赖
3. **base模块**: 是所有其他模块的基础依赖，包含核心的状态管理和通用功能

### 常用代码路径
- 主要业务逻辑：`frame/*/src/main/java/com/adealink/`
- 资源文件：`frame/*/src/main/res/`
- 第三方集成：`external/*/src/main/java/`

## 代码核心架构规范

### 1. 接口-工厂-初始化
**适用场景:**
- 模块需要全局访问

```kotlin
// 1. 定义模块能力的核心接口
interface IModuleName {
    fun primaryAction()
    fun secondaryAction()
}

// 2. 用于依赖注入的配置接口
interface IModuleConfig {
    val requiredDependency: Type
    val optionalSetting: String
}

// 3. 创建实例的工厂函数，管理类可以 *Manager 规则命名
@Synchronized
fun createModule(config: IModuleConfig): IModuleName {
    return ModuleImpl(config)
}

// 4. 模块全局初始化函数
fun initModule(initiator: (() -> IModuleName)) {
    ModuleImpl.initiator = initiator
}

// 5. 内部实现类（带惰性单例）
internal class ModuleImpl(val config: IModuleConfig) : IModuleName {
    companion object {
        var initiator: (() -> IModuleName)? = null
        var instance: IModuleName? = null
            get() = field ?: initiator?.invoke()?.also { field = it }
                ?: throw IllegalArgumentException("Module not initialized")
    }
}
```