# CLAUDE.md

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

## 模块概述

这是一个新手引导与引导浮层组件模块，用于为Android应用提供用户引导功能。该模块支持高亮特定View、显示引导内容、管理引导页面的生命周期等功能。

## 核心架构

### 主要组件

1. **BaseGuide** - 引导的抽象基类
   - 管理Activity/Fragment/Dialog的引导注册
   - 提供引导显示/隐藏的生命周期管理
   - 子类需要实现 `buildGuide()`, `interceptGuide()`, `guideType()` 方法

2. **GuideCenter** - 引导管理中心
   - 全局引导注册管理器
   - 支持引导类型标识和缓存机制
   - 提供激活/取消激活引导的统一接口

3. **GuideController** - 引导控制器
   - 管理引导页面的显示逻辑
   - 支持多页引导的顺序播放
   - 处理引导页面的生命周期回调

4. **GuidePage** - 引导页面模型
   - 定义单个引导页的配置
   - 支持高亮区域、背景色、交互行为等设置
   - 包含自动消失、标签管理等功能

5. **NewbieGuide** - 引导构建器
   - 提供链式调用API构建引导
   - 支持Activity/Fragment/Dialog三种容器
   - Builder模式创建GuideController实例

### 高亮系统

- **HighLight** - 高亮区域抽象类
- **HighLightView** - 基于View标签的高亮实现  
- **HighLightOptions** - 高亮区域配置选项
- **RelativeGuide** - 相对于高亮区域的引导内容布局

### 持久化机制

- **GuideLabel** - 引导状态管理
  - 使用SharedPreferences持久化引导完成状态
  - 支持标签化管理，避免重复显示引导

## 常用开发命令

```bash
# 编译模块
./gradlew :frame:guide:assemble

# 运行单元测试
./gradlew :frame:guide:test

# 运行Android测试
./gradlew :frame:guide:connectedAndroidTest

# 检查代码风格
./gradlew :frame:guide:ktlintCheck
```

## 架构设计模式

遵循项目标准的**接口-工厂-初始化**模式：

```kotlin
// 1. 继承BaseGuide实现具体引导类
class MyGuide : BaseGuide() {
    override fun buildGuide(): GuideController? {
        return NewbieGuide.with(activity)
            .addGuidePage(/* 引导页配置 */)
            .build()
    }
    
    override fun interceptGuide(): Boolean = false
    override fun guideType(): String = "my_guide"
}

// 2. 注册引导
val guide = MyGuide()
guide.register(activity)

// 3. 激活引导显示
GuideCenter.activeGuide("my_guide")
```

## 关键实现细节

### 高亮区域查找机制
- 通过View标签(@StringRes viewTag)定位目标View
- 支持圆形和圆角矩形两种高亮形状
- 可设置内边距和圆角半径

### 引导页面显示逻辑
- GuideLayout使用PorterDuff.Mode.CLEAR绘制透明高亮区域
- 支持点击高亮区域或任意位置消失
- 可配置延迟自动消失

### 状态管理
- 每个引导页可设置唯一label标识
- 显示后自动标记为完成状态，下次不再显示
- 支持组标签(groupLabel)控制整组引导的显示

### 生命周期管理
- Activity/Fragment/Dialog销毁时自动清理引导资源
- 支持引导页面的刷新(refresh)机制
- 提供显示和消失的回调监听

## 依赖关系

- 依赖 `frame:base` 基础框架
- 依赖 `frame:util` 工具类
- 依赖 `frame:log` 日志框架
- 可选依赖 `frame:zero` 零配置工具