# base-common 模块说明

## 📋 模块定位

**base-common** 是业务封装层，提供：
- 封装 base-core 的接口（BridgeManager、ConfigManager、ExecutorManager）
- MVVM 网络封装（ApiServiceFactory、ApiBaseRemoteDataSource）
- UI 基础类（BaseActivity、BaseFragment）

## 🎯 使用原则

- ✅ **业务层（app 模块）可以调用 base-common**
- ✅ **能力层（capability 模块）也可以调用 base-common**（如果需要业务封装）

---

## 📁 目录结构

### 1. bridge/ - 桥接服务封装

```
✅ BridgeManager.kt           - 封装 IBridge，提供 H5通信、模块间通信的便捷方法
```

**功能：**
- H5 通信：`callH5Method()`、`onH5Call()`
- 模块间通信：`postEvent()`、`subscribeEvent()`

### 2. config/ - 配置管理封装

```
✅ ConfigManager.kt           - 封装 IConfig，提供通用的配置管理
⚠️ ServerConfigManager.kt    - 特定业务场景（开发测试时的服务器配置，待移到 app 模块）
```

**功能：**
- 基础配置：`getString()`、`getInt()`、`getBoolean()`
- 环境切换：`getEnvironment()`、`setEnvironment()`
- 功能开关：`isFeatureEnabled()`、`setFeatureEnabled()`

### 3. executor/ - 执行器封装

```
✅ ExecutorManager.kt         - 封装 IExecutor，提供异步任务执行的便捷方法
```

**功能：**
- IO 线程执行：`executeIO()`
- 主线程执行：`executeMain()`
- 延迟执行：`executeDelayed()`
- 降级方案：如果 IExecutor 未注册，使用协程实现

### 4. network/ - MVVM 网络封装

```
✅ ApiServiceFactory.kt       - API 服务工厂，统一创建 API 服务实例
✅ ApiBaseRemoteDataSource.kt - 远程数据源基类，封装通用网络请求逻辑
✅ ApiBaseRepository.kt       - Repository 基类，提供通用错误处理和数据转换
✅ ApiResponseParser.kt       - 响应解析器，解析 Retrofit Response
```

**功能：**
- 统一创建 API 服务：`ApiServiceFactory.create<AuthApi>()`
- 统一错误处理：超时、网络异常、业务错误
- 自动线程切换：IO 线程执行请求
- 统一日志记录

### 5. ui/ - UI 基础类

```
✅ BaseActivity.kt            - Activity 基类，支持 ViewBinding、加载状态管理
✅ BaseFragment.kt            - Fragment 基类，支持 ViewBinding、加载状态管理
✅ ActivityExtensions.kt      - Activity 扩展函数，简化 StateFlow 观察
✅ FragmentExtensions.kt      - Fragment 扩展函数，简化 StateFlow 观察
```

**功能：**
- ViewBinding 支持
- 加载状态管理：`showLoading()`、`hideLoading()`
- 错误/成功消息显示：`showError()`、`showSuccess()`
- StateFlow 观察：`observeStateFlow()`

---

## 💡 核心作用

### 1. 封装 base-core 的接口

**提供便捷的调用方式：**
```kotlin
// 使用 BridgeManager（封装 IBridge）
BridgeManager.postEvent("user_login", userData)

// 使用 ConfigManager（封装 IConfig）
val apiUrl = ConfigManager.getString("api_url", "https://api.example.com")

// 使用 ExecutorManager（封装 IExecutor）
ExecutorManager.executeIO {
    // 执行耗时操作
}
```

### 2. MVVM 网络封装

**简化网络请求：**
```kotlin
// 创建 API 服务
val authApi = ApiServiceFactory.create<AuthApi>()

// 封装数据源
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiServiceFactory.create<AuthApi>()
    suspend fun login() = executeRequest { authApi.login() }
}
```

### 3. UI 基础类

**简化 UI 开发：**
```kotlin
class LoginActivity : BaseActivity<ActivityLoginBinding>() {
    override fun getViewBinding() = ActivityLoginBinding.inflate(layoutInflater)
    
    override fun initObserver() {
        observeStateFlow(viewModel.uiState) { state ->
            // 处理状态变化
        }
    }
}
```

---

## 📝 使用示例

### 业务层使用 base-common

#### 1. 使用 BridgeManager（H5通信、模块间通信）

```kotlin
// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.bridge.BridgeManager

class MainActivity : AppCompatActivity() {
    fun initBridge() {
        // H5通信
        BridgeManager.callH5Method("showToast", "Hello")
        BridgeManager.onH5Call("getUserInfo") { result ->
            // 处理结果
        }
        
        // 模块间通信
        BridgeManager.postEvent("user_login", userData)
        BridgeManager.subscribeEvent("user_logout") { data ->
            // 处理事件
        }
    }
}
```

#### 2. 使用 ConfigManager（配置管理）

```kotlin
// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.config.ConfigManager

class MainActivity : AppCompatActivity() {
    fun initConfig() {
        // 获取配置
        val apiUrl = ConfigManager.getString("api_url", "https://api.example.com")
        val isDebug = ConfigManager.getBoolean("is_debug", false)
        
        // 设置配置
        ConfigManager.setString("api_url", "https://api.example.com")
        ConfigManager.setEnvironment("prod")
        
        // 功能开关
        if (ConfigManager.isFeatureEnabled("new_feature")) {
            // 启用新功能
        }
    }
}
```

#### 3. 使用 ExecutorManager（异步任务执行）

```kotlin
// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.executor.ExecutorManager

class MainActivity : AppCompatActivity() {
    fun executeTask() {
        // IO线程执行
        ExecutorManager.executeIO {
            // 执行耗时操作
            val data = fetchData()
            
            // 主线程更新UI
            ExecutorManager.executeMain {
                updateUI(data)
            }
        }
        
        // 延迟执行
        ExecutorManager.executeDelayed(1000) {
            // 1秒后执行
        }
    }
}
```

#### 4. 使用 ApiServiceFactory（网络请求）

```kotlin
// Application 中初始化
class XinDaZhouApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // 设置默认 baseUrl
        ApiServiceFactory.baseUrlProvider = { 
            ServerConfigManager.getHttpServerUrl() 
        }
    }
}

// 业务层使用
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiServiceFactory.create<AuthApi>()
    
    suspend fun login(request: LoginRequest): Result<LoginResponse> {
        return executeRequest(
            request = { authApi.login(request) },
            errorMessage = "登录失败"
        )
    }
}
```

#### 5. 使用 BaseActivity/BaseFragment（UI 基础类）

```kotlin
// app/src/.../LoginActivity.kt
import com.narutohuo.xindazhou.common.ui.BaseActivity
import com.narutohuo.xindazhou.common.ui.observeStateFlow

class LoginActivity : BaseActivity<ActivityLoginBinding>() {
    
    private val viewModel: LoginViewModel by viewModels()
    
    override fun getViewBinding() = ActivityLoginBinding.inflate(layoutInflater)
    
    override fun initView() {
        binding.btnLogin.setOnClickListener {
            viewModel.login()
        }
    }
    
    override fun initObserver() {
        // 观察 UI 状态
        observeStateFlow(viewModel.uiState) { state ->
            when (state) {
                is LoginUiState.Loading -> showLoading()
                is LoginUiState.Success -> {
                    hideLoading()
                    showSuccess("登录成功")
                }
                is LoginUiState.Error -> {
                    hideLoading()
                    showError(state.message)
                }
            }
        }
    }
}
```

---

## ⚠️ 注意事项

1. **业务层统一使用 base-common**，不直接使用 base-core
2. **ApiServiceFactory 需要在 Application 中初始化** `baseUrlProvider`
3. **ConfigManager、BridgeManager、ExecutorManager 需要 app 模块实现对应的接口**（通过 ARouter 注册）
4. **ServerConfigManager 是特定业务场景**，后续考虑移到 app 模块

---

## 🔗 相关文档

- [base-core README](../base-core/README.md)
- [网络请求 MVVM 封装方案](./src/main/java/com/narutohuo/xindazhou/common/network/网络请求MVVM封装方案.md)
- [UI 层封装方案](./src/main/java/com/narutohuo/xindazhou/common/ui/UI层封装方案.md)

