# base-core 与 base-common 整体架构说明

## 📋 架构概述

```
业务层（app 模块）
    ↓ 依赖
    ├── base-common（业务封装层）
    └── capability-xxx（能力层）
            ↓ 依赖
        base-core（基础设施层）
            ↑ 依赖
        base-common（业务封装层）
```

### 依赖关系

- ✅ **业务层（app 模块）依赖 base-common 和 capability-xxx**
- ✅ **能力层（capability 模块）依赖 base-core**（直接依赖，不通过 base-common）
- ✅ **base-common 依赖 base-core**

**注意：** capability 模块应该直接依赖 base-core，而不是通过 base-common。虽然当前实现中 capability 依赖 base-common（base-common 会传递 base-core），但更合理的做法是直接依赖 base-core。

### 使用原则

- ✅ **能力层（capability 模块）可以调用 base-core**
- ✅ **业务层（app 模块）可以调用 base-common 和 capability-xxx**
- ❌ **业务层不直接调用 base-core**（通过 base-common 间接使用）

---

## 🏗️ 整体代码结构

### base-core（基础设施层）

```
xdz_android/base-core/
├── src/main/java/com/narutohuo/xindazhou/core/
│   ├── log/
│   │   ├── ILog.kt                       ✅ 日志接口定义
│   │   └── impl/
│   │       ├── TimberLog.kt              ✅ Timber 日志实现（基于 Timber 库）
│   │       └── NoOpLog.kt                ✅ 空日志实现（生产环境使用）
│   ├── network/
│   │   └── NetworkManager.kt             ✅ Retrofit/OkHttp 管理器（单例模式）
│   ├── push/
│   │   └── IPushService.kt               ✅ 推送服务接口
│   ├── share/
│   │   ├── IShareService.kt              ✅ 分享服务接口
│   │   └── IShareCallback.kt             ✅ 分享回调接口
│   ├── storage/
│   │   └── IStorage.kt                   ✅ 存储服务接口（键值存储、文件存储、数据库存储）
│   └── util/
│       └── IUtil.kt                       ✅ 工具类接口（时间处理、字符串处理、加密解密）
└── build.gradle                           ✅ 第三方库管理（Retrofit, OkHttp, Gson, Glide, Coroutines, ARouter, Timber）
```

---

### base-common（业务封装层）

```
xdz_android/base-common/
├── src/main/java/com/narutohuo/xindazhou/common/
│   ├── bridge/
│   │   └── BridgeManager.kt              ✅ H5通信、模块间通信封装（直接实现，无需接口）
│   ├── config/
│   │   ├── ConfigManager.kt               ✅ 配置管理封装（直接使用 SharedPreferences，无需接口）
│   │   └── ServerConfigManager.kt         ✅ 服务器配置管理（开发测试时配置服务器地址）
│   ├── executor/
│   │   └── ExecutorManager.kt             ✅ 异步任务执行封装（直接使用协程，无需接口）
│   ├── storage/
│   │   └── StorageManager.kt              ✅ 封装 IStorage，提供存储管理的便捷方法
│   ├── util/
│   │   └── UtilManager.kt                 ✅ 封装 IUtil，提供工具方法的便捷调用
│   ├── network/
│   │   ├── ApiServiceFactory.kt           ✅ API 服务工厂，统一创建 API 服务实例
│   │   ├── ApiBaseRemoteDataSource.kt     ✅ 远程数据源基类，封装通用网络请求逻辑
│   │   ├── ApiBaseRepository.kt           ✅ Repository 基类，提供通用错误处理和数据转换
│   │   └── ApiResponseParser.kt           ✅ 响应解析器，解析 Retrofit Response
│   ├── ui/
│   │   ├── BaseActivity.kt                ✅ Activity 基类，支持 ViewBinding、加载状态管理、权限请求、屏幕方向
│   │   ├── BaseFragment.kt                ✅ Fragment 基类，支持 ViewBinding、加载状态管理
│   │   ├── ActivityManager.kt              ✅ Activity 栈管理，统一管理所有 Activity 生命周期
│   │   ├── ActivityExtensions.kt          ✅ Activity 扩展函数，简化 StateFlow 观察
│   │   ├── FragmentExtensions.kt           ✅ Fragment 扩展函数，简化 StateFlow 观察
│   │   ├── MessageHelper.kt               ✅ Toast/Snackbar 统一封装，提供便捷的消息提示
│   │   └── StatusBarHelper.kt             ✅ 状态栏/导航栏管理，沉浸式状态栏支持
│   ├── image/
│   │   └── ImageLoader.kt                 ✅ 图片加载封装（Glide），支持圆形、圆角、占位图
│   ├── dialog/
│   │   ├── DialogHelper.kt                ✅ 对话框统一封装，iOS 风格确认/提示对话框
│   │   └── CascadePickerDialog.kt         ✅ 级联选择器对话框
│   ├── file/
│   │   └── FilePickerHelper.kt            ✅ 文件选择器封装，支持图片、文件、多文件选择
│   ├── camera/
│   │   └── CameraHelper.kt                ✅ 相机/相册封装，支持拍照、相册选择、图片裁剪
│   ├── router/
│   │   └── RouterHelper.kt                ✅ ARouter 路由封装，统一路由跳转、参数传递
│   ├── permission/
│   │   └── PermissionHelper.kt             ✅ 权限管理封装，权限检查、请求、说明对话框
│   ├── crash/
│   │   └── CrashHelper.kt                  ✅ 崩溃收集封装，自动捕获崩溃并记录日志
│   ├── auth/
│   │   ├── AuthManager.kt                 ✅ 认证管理器，封装登录、注册、Token 刷新逻辑
│   │   ├── LoginActivity.kt                ✅ 登录页 Activity（完整封装，可直接使用）
│   │   ├── RegisterActivity.kt             ✅ 注册页 Activity（完整封装，可直接使用）
│   │   ├── ui/
│   │   │   ├── LoginFragment.kt            ✅ 登录 Fragment（完整 UI 和逻辑）
│   │   │   └── RegisterFragment.kt         ✅ 注册 Fragment（完整 UI 和逻辑）
│   │   ├── model/
│   │   │   ├── LoginRequest.kt             ✅ 登录请求参数
│   │   │   ├── LoginResponse.kt            ✅ 登录响应数据
│   │   │   └── RegisterRequest.kt          ✅ 注册请求参数
│   │   ├── datasource/
│   │   │   ├── remote/
│   │   │   │   ├── AuthApi.kt              ✅ 认证 API 接口
│   │   │   │   └── AuthRemoteDataSource.kt ✅ 认证远程数据源
│   │   │   └── local/
│   │   │       └── AuthLocalDataSource.kt ✅ 认证本地数据源接口（需业务模块实现）
│   │   └── repository/
│   │       └── AuthRepository.kt          ✅ 认证数据仓库
│   ├── version/
│   │   ├── VersionUpdateManager.kt        ✅ 版本更新管理器，封装版本检查、更新对话框、强制更新
│   │   ├── VersionCheckActivity.kt        ✅ 版本检查 Activity（通用）
│   │   ├── ui/
│   │   │   └── UpdateDialogFragment.kt    ✅ 版本更新对话框 Fragment
│   │   ├── model/
│   │   │   └── VersionInfo.kt             ✅ 版本信息数据模型
│   │   ├── datasource/
│   │   │   └── remote/
│   │   │       └── VersionApi.kt           ✅ 版本 API 接口
│   │   └── repository/
│   │       └── VersionRepository.kt       ✅ 版本数据仓库
│   └── launch/
│       ├── LaunchActivity.kt               ✅ 启动页 Activity（通用，处理登录状态判断和跳转）
│       └── AppLaunchManager.kt             ✅ 应用启动管理器，统一处理启动逻辑
└── build.gradle                            ✅ 依赖 base-core
```

---

### capability-xxx（能力层）

```
xdz_android/capability-push/
├── src/main/java/com/narutohuo/xindazhou/push/
│   ├── api/
│   │   └── PushService.kt                 ✅ 推送服务接口（模块内部）
│   ├── factory/
│   │   └── PushServiceFactory.kt          ✅ 推送服务工厂
│   ├── impl/
│   │   └── PushServiceImpl.kt             ✅ 实现 IPushService（base-core 定义）
│   └── ...
└── build.gradle                            ✅ 直接依赖 base-core

xdz_android/capability-share/
├── src/main/java/com/narutohuo/xindazhou/share/
│   ├── impl/
│   │   └── ShareServiceImpl.kt            ✅ 实现 IShareService（base-core 定义）
│   └── ...
└── build.gradle                            ✅ 直接依赖 base-core

xdz_android/capability-ble/
└── build.gradle                            ✅ 直接依赖 base-core

xdz_android/capability-nfc/
└── build.gradle                            ✅ 直接依赖 base-core

xdz_android/capability-qrcode/
└── build.gradle                            ✅ 直接依赖 base-core

xdz_android/capability-socketio/
└── build.gradle                            ✅ 直接依赖 base-core
```

---

### app（业务层）

```
xdz_android/app/
├── src/main/java/com/narutohuo/xindazhou/
│   ├── XinDaZhouApplication.kt             ✅ Application 类，初始化 AuthManager、VersionUpdateManager
│   ├── MainActivity.kt                     ✅ 主界面 Activity
│   ├── user/
│   │   ├── datasource/
│   │   │   └── local/
│   │   │       └── AuthLocalDataSourceImpl.kt ✅ 实现 AuthLocalDataSource（使用 TokenManager）
│   │   └── ...
│   └── ...
└── build.gradle                             ✅ 依赖 base-common 和 capability-xxx
```

**注意：** 
- ✅ 认证功能已完全封装在 base-common 中，app 模块只需实现 `AuthLocalDataSource`（因为 TokenManager 在 app 模块）
- ✅ 版本管理功能已完全封装在 base-common 中，app 模块只需在 Application 中调用 `VersionUpdateManager.init()`
- ✅ 登录/注册界面已完全封装在 base-common 中，app 模块可直接使用 `LoginActivity` 和 `RegisterActivity`

---

## 💡 核心作用

### base-core 的作用

1. **定义接口**：让 capability 模块实现（如 IPushService、IShareService）
2. **提供基础能力**：ILog、NetworkManager 等，让所有模块统一使用
3. **管理第三方库**：统一版本，避免冲突

### base-common 的作用

1. **封装 base-core 的接口**：提供便捷的调用方式（StorageManager、UtilManager）
2. **业务工具封装**：
   - BridgeManager：H5通信、模块间通信（直接实现）
   - ConfigManager：配置管理（直接使用 SharedPreferences）
   - ExecutorManager：异步任务执行（直接使用协程）
   - ServerConfigManager：服务器配置管理（开发测试时使用）
3. **MVVM 网络封装**：简化网络请求（ApiServiceFactory、ApiBaseRemoteDataSource、ApiBaseRepository）
4. **UI 基础类**：简化 UI 开发（BaseActivity、BaseFragment、ActivityManager、扩展函数）
5. **UI 工具封装**：
   - ImageLoader：图片加载统一封装
   - MessageHelper：Toast/Snackbar 统一封装
   - DialogHelper：iOS 风格对话框统一封装
   - CascadePickerDialog：级联选择器对话框
   - StatusBarHelper：状态栏/导航栏管理
6. **功能封装**：
   - FilePickerHelper：文件选择器封装
   - CameraHelper：相机/相册封装
   - RouterHelper：ARouter 路由封装
   - PermissionHelper：权限管理封装
   - CrashHelper：崩溃收集封装
7. **业务功能完整封装**：
   - **认证模块（auth）**：完整的登录/注册功能，包括 UI、业务逻辑、数据层
     - LoginActivity/RegisterActivity：可直接使用的 Activity
     - LoginFragment/RegisterFragment：完整的 UI 和逻辑
     - AuthManager：认证管理器，统一管理登录、注册、Token 刷新
     - AuthRepository：认证数据仓库，MVVM 架构
   - **版本管理模块（version）**：完整的版本检查更新功能
     - VersionUpdateManager：版本更新管理器，封装版本检查、更新对话框、强制更新
     - VersionCheckActivity：版本检查 Activity（通用）
     - UpdateDialogFragment：版本更新对话框
   - **启动管理（launch）**：应用启动逻辑封装
     - LaunchActivity：启动页 Activity（通用）
     - AppLaunchManager：应用启动管理器，统一处理登录状态判断和跳转

---

## ⚠️ 注意事项

### 1. 依赖关系

- ✅ **业务层（app 模块）依赖 base-common 和 capability-xxx**
- ✅ **能力层（capability 模块）依赖 base-core**（直接依赖，不通过 base-common）
- ✅ **base-common 依赖 base-core**

**说明：** 
- ✅ capability 模块只需要 base-core 的接口和基础能力（ILog、NetworkManager），不需要 base-common 的业务封装
- ✅ 已优化：所有 capability 模块现在都直接依赖 base-core，不再通过 base-common

### 2. 接口实现

- ✅ base-core 定义接口（IPushService、IShareService 等能力接口）
- ✅ app 模块实现接口（通过 ARouter 注册）
- ✅ capability 模块实现接口（IPushService、IShareService 等）

### 3. 初始化顺序

1. ARouter 初始化
2. 注册接口实现
3. NetworkManager 初始化
4. ApiServiceFactory 初始化（设置 baseUrlProvider）
5. AuthManager 初始化（传入 AuthLocalDataSource 实现）
6. VersionUpdateManager 初始化

### 4. 使用原则

- ✅ 能力层使用 base-core 的接口和基础能力
- ✅ 业务层使用 base-common 的封装
- ❌ 业务层不直接使用 base-core

### 5. 业务功能使用示例

#### 认证功能使用

```kotlin
// 1. 在 Application 中初始化
val localDataSource = object : AuthLocalDataSource {
    override suspend fun saveToken(loginResponse: LoginResponse) {
        TokenManager.saveToken(...)
    }
    // ...
}
AuthManager.init(localDataSource)

// 2. 启动登录页
val intent = Intent(context, LoginActivity::class.java).apply {
    putExtra(LoginActivity.EXTRA_MAIN_ACTIVITY_CLASS, MainActivity::class.java.name)
}
startActivity(intent)
```

#### 版本管理使用

```kotlin
// 1. 在 Application 中初始化
VersionUpdateManager.init(context)

// 2. 在 Activity 中检查更新
VersionUpdateManager.checkUpdate(activity)
```

#### 启动管理使用

```kotlin
// 在 LaunchActivity 中使用
AppLaunchManager.handleLaunch(
    activity = this,
    isLoggedIn = { TokenManager.getAccessToken() != null },
    mainActivityClass = MainActivity::class.java,
    loginActivityClass = LoginActivity::class.java
)
```

---

## 📚 相关文档

- [base-core README](./base-core/README.md)
- [base-common README](./base-common/README.md)
- [网络请求 MVVM 封装方案](./base-common/src/main/java/com/narutohuo/xindazhou/common/network/网络请求MVVM封装方案.md)
- [UI 层封装方案](./base-common/src/main/java/com/narutohuo/xindazhou/common/ui/UI层封装方案.md)
- [封装功能使用说明](./base-common/src/main/java/com/narutohuo/xindazhou/common/封装功能使用说明.md)
- [待封装功能分析](./base-common/src/main/java/com/narutohuo/xindazhou/common/base-common待封装功能分析.md)