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 的作用

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

base-common 的作用

封装 base-core 的接口：提供便捷的调用方式（StorageManager、UtilManager）
业务工具封装：
- BridgeManager：H5通信、模块间通信（直接实现）
- ConfigManager：配置管理（直接使用 SharedPreferences）
- ExecutorManager：异步任务执行（直接使用协程）
- ServerConfigManager：服务器配置管理（开发测试时使用）
MVVM 网络封装：简化网络请求（ApiServiceFactory、ApiBaseRemoteDataSource、ApiBaseRepository）
UI 基础类：简化 UI 开发（BaseActivity、BaseFragment、ActivityManager、扩展函数）
UI 工具封装：
- ImageLoader：图片加载统一封装
- MessageHelper：Toast/Snackbar 统一封装
- DialogHelper：iOS 风格对话框统一封装
- CascadePickerDialog：级联选择器对话框
- StatusBarHelper：状态栏/导航栏管理
功能封装：
- FilePickerHelper：文件选择器封装
- CameraHelper：相机/相册封装
- RouterHelper：ARouter 路由封装
- PermissionHelper：权限管理封装
- CrashHelper：崩溃收集封装
业务功能完整封装：
- 认证模块（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. 初始化顺序

ARouter 初始化
注册接口实现
NetworkManager 初始化
ApiServiceFactory 初始化（设置 baseUrlProvider）
AuthManager 初始化（传入 AuthLocalDataSource 实现）
VersionUpdateManager 初始化

4. 使用原则

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

5. 业务功能使用示例

认证功能使用

// 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)

版本管理使用

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

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

启动管理使用

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

架构说明.md 15 KB

Historia Raaka

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

📋 架构概述

依赖关系

使用原则

🏗️ 整体代码结构

base-core（基础设施层）

base-common（业务封装层）

capability-xxx（能力层）

app（业务层）

💡 核心作用

base-core 的作用

base-common 的作用

⚠️ 注意事项

1. 依赖关系

2. 接口实现

3. 初始化顺序

4. 使用原则

5. 业务功能使用示例

认证功能使用

版本管理使用

启动管理使用

📚 相关文档

架构说明.md 15 KB Historia Raaka

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

📋 架构概述

依赖关系

使用原则

🏗️ 整体代码结构

base-core（基础设施层）

base-common（业务封装层）

capability-xxx（能力层）

app（业务层）

💡 核心作用

base-core 的作用

base-common 的作用

⚠️ 注意事项

1. 依赖关系

2. 接口实现

3. 初始化顺序

4. 使用原则

5. 业务功能使用示例

认证功能使用

版本管理使用

启动管理使用

📚 相关文档

架构说明.md 15 KB

Historia Raaka