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-core（符合架构要求）。

使用原则

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

🏗️ 整体代码结构

base-core（基础设施层）

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

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                       ✅ 工具类接口（时间处理、字符串处理、加密解密）
│                                                                       ⚠️ **使用规则**：只允许纯函数型工具（无副作用、无状态），不允许业务相关、UI相关或依赖Context的工具
│   └── wxapi/
│       └── WXEntryActivity.kt             ⚠️ 微信分享回调 Activity（微信 SDK 要求，包名必须是应用包名）
│                                                                       ⚠️ **架构说明**：虽然文件在 base-core 模块中，但包名使用应用包名（com.narutohuo.xindazhou.wxapi），通过 ARouter 依赖注入获取 IShareCallback 实现，实现解耦
└── build.gradle                           ✅ 第三方库管理（Retrofit, OkHttp, Gson, Glide, Coroutines, ARouter, Timber）

base-common（业务封装层）

内部概念分层（虽然是一个物理模块，但内部按职责分层）：

core-facade（核心封装层）：log、network、storage、util
mvvm-support（MVVM 支持层）：network/ApiServiceFactory、ApiBaseRemoteDataSource、ApiBaseRepository
ui-kit（UI 工具层）：ui、dialog、image、permission、router
app-support（应用支持层）：config、bridge、executor

xdz_android/base-common/
├── src/main/java/com/narutohuo/xindazhou/common/
│   ├── bridge/                           # app-support
│   │   └── BridgeManager.kt              ✅ H5通信、模块间通信封装（直接实现，无需接口）
│   ├── config/                           # app-support
│   │   ├── ConfigManager.kt               ✅ 配置管理封装（直接使用 SharedPreferences，无需接口）
│   │   └── ServerConfigManager.kt        ⚠️ 特定业务场景（开发测试时的服务器配置，待移到 app 模块）
│   ├── executor/                         # app-support
│   │   └── ExecutorManager.kt            ✅ 异步任务执行封装（直接使用协程，无需接口）
│   ├── log/                              # core-facade
│   │   └── LogHelper.kt                  ✅ 封装 ILog，提供日志记录的便捷方法
│   ├── storage/                          # core-facade
│   │   └── StorageManager.kt              ✅ 封装 IStorage，提供存储管理的便捷方法
│   ├── util/                             # core-facade
│   │   └── UtilManager.kt                ✅ 封装 IUtil，提供工具方法的便捷调用
│   ├── network/                          # core-facade + mvvm-support
│   │   ├── NetworkHelper.kt              ✅ 封装 NetworkManager，提供网络初始化和 Token 设置（core-facade）
│   │   ├── ApiServiceFactory.kt          ✅ API 服务工厂，统一创建 API 服务实例（mvvm-support）
│   │   ├── ApiBaseRemoteDataSource.kt     ✅ 远程数据源基类，封装通用网络请求逻辑（mvvm-support）
│   │   ├── ApiBaseRepository.kt          ✅ Repository 基类，提供通用错误处理和数据转换（mvvm-support）
│   │   └── ApiResponseParser.kt          ✅ 响应解析器，解析 Retrofit Response（mvvm-support）
│   ├── ui/                               # ui-kit
│   │   ├── BaseActivity.kt               ⚠️ Activity 基类，支持 ViewBinding、加载状态管理、网络请求封装（单 Activity 架构下不推荐使用）
│   │   ├── BaseFragment.kt               ✅ Fragment 基类，支持 ViewBinding、加载状态管理、MVVM 模式、网络请求封装、回调风格异步操作（推荐使用）
│   │   ├── ActivityExtensions.kt         ✅ Activity 扩展函数，简化 StateFlow 观察
│   │   ├── FragmentExtensions.kt         ✅ Fragment 扩展函数，简化 StateFlow 观察
│   │   ├── MessageHelper.kt               ✅ Toast/Snackbar 统一封装，提供便捷的消息提示
│   │   └── StatusBarHelper.kt            ✅ 状态栏/导航栏管理，沉浸式状态栏支持
│   ├── image/                            # ui-kit
│   │   └── ImageLoader.kt                ✅ 图片加载封装（Glide），支持圆形、圆角、占位图
│   ├── dialog/                           # ui-kit
│   │   └── DialogHelper.kt                ✅ 对话框统一封装，确认、输入、列表选择对话框
│   ├── file/                             # ui-kit
│   │   └── FilePickerHelper.kt           ✅ 文件选择器封装，支持图片、文件、多文件选择
│   ├── camera/                           # ui-kit
│   │   └── CameraHelper.kt               ✅ 相机/相册封装，支持拍照、相册选择、图片裁剪
│   ├── router/                           # ui-kit
│   │   └── RouterHelper.kt               ✅ ARouter 路由封装，统一路由跳转、参数传递
│   ├── permission/                       # ui-kit
│   │   └── PermissionHelper.kt           ✅ 权限管理封装，权限检查、请求、说明对话框
│   └── crash/                            # app-support
│       └── CrashHelper.kt                 ✅ 崩溃收集封装，自动捕获崩溃并记录日志
└── build.gradle                           ✅ 依赖 base-core

capability-xxx（能力层）

⚠️ 边界定义：capability 模块必须保持系统能力/通用能力的定位，不能包含业务流程。

允许的能力类型：

✅ 系统能力：推送（push）、分享（share）、蓝牙（ble）、NFC（nfc）
✅ 通用能力：二维码（qrcode）、文件选择、相机、SocketIO 通信
✅ 可被多个 app 复用的能力：任何可以被不同业务场景复用的能力

xdz_android/capability-push/
├── src/main/java/com/narutohuo/xindazhou/push/
│   ├── api/
│   │   └── PushService.kt                 ✅ 推送服务接口（模块内部，封装极光推送 SDK）
│   ├── factory/
│   │   └── PushServiceFactory.kt          ✅ 推送服务工厂，提供单例实例
│   ├── impl/
│   │   └── PushServiceImpl.kt             ✅ 实现 IPushService（base-core 定义）
│   ├── model/
│   │   ├── PushConfig.kt                  ✅ 推送服务配置（AppKey、AppSecret 等）
│   │   └── PushResponse.kt                 ✅ 推送响应模型
│   └── receiver/
│       └── JPushReceiver.kt                ✅ 极光推送广播接收器（处理推送消息）
└── build.gradle                           ✅ 直接依赖 base-core

xdz_android/capability-share/
├── src/main/java/com/narutohuo/xindazhou/share/
│   ├── api/
│   │   └── ShareService.kt                 ✅ 分享服务接口（模块内部，封装友盟分享 SDK）
│   ├── factory/
│   │   └── ShareServiceFactory.kt          ✅ 分享服务工厂，提供单例实例
│   ├── impl/
│   │   └── ShareServiceImpl.kt             ✅ 实现 IShareService（base-core 定义）
│   ├── callback/
│   │   └── ShareCallbackImpl.kt            ✅ 分享回调实现（处理友盟 SDK 回调）
│   ├── model/
│   │   ├── ShareConfig.kt                  ✅ 分享服务配置（各平台 AppKey、AppSecret）
│   │   └── ShareResponse.kt                 ✅ 分享响应模型（包含 ShareContent、SharePlatform 等）
│   ├── ui/
│   │   ├── ShareProxyActivity.kt           ✅ 透明代理 Activity（统一处理分享回调）
│   │   └── ShareDialogFragment.kt           ✅ 分享弹窗 Fragment（显示分享平台选择）
│   └── douyinapi/
│       └── DouYinEntryActivity.kt          ⚠️ 抖音分享回调 Activity（已注释，待 SDK 支持）
└── build.gradle                           ✅ 直接依赖 base-core

xdz_android/capability-ble/
├── src/main/java/com/narutohuo/xindazhou/ble/
│   ├── api/
│   │   └── BLEService.kt                   ✅ BLE 服务接口（模块内部，封装蓝牙协议）
│   ├── factory/
│   │   └── BLEServiceFactory.kt            ✅ BLE 服务工厂，创建服务实例
│   ├── impl/
│   │   └── BLEServiceImpl.kt               ✅ BLE 服务实现（实现 BLEService 接口）
│   ├── callback/
│   │   └── BLECallback.kt                  ✅ BLE 回调接口定义
│   ├── config/
│   │   └── BLEConstants.kt                 ✅ BLE 常量定义（UUID、功能码、指令类型等）
│   ├── model/
│   │   ├── BLEDevice.kt                    ✅ BLE 设备模型
│   │   ├── BLEResponse.kt                  ✅ BLE 响应模型
│   │   ├── BLECommand.kt                   ✅ BLE 命令模型（完整命令，未分片）
│   │   ├── Command.kt                      ✅ 命令数据类（业务层命令封装）
│   │   ├── Packet.kt                       ✅ 数据包模型（分片后的单个数据包）
│   │   ├── BLEEncryptedData.kt             ✅ BLE 加密数据模型（加密数据区域）
│   │   └── FragmentBuffer.kt               ✅ 分片缓冲区（用于重组分片数据包）
│   └── util/
│       ├── BleScanner.kt                   ✅ BLE 扫描器（扫描蓝牙设备）
│       ├── BleConnector.kt                 ✅ BLE 连接器（连接蓝牙设备）
│       ├── BlePacketSender.kt             ✅ BLE 数据包发送器（发送分片数据包）
│       ├── BLEPacketSplitter.kt            ✅ BLE 数据包分割器（将命令分割成数据包）
│       ├── BLEPacketParser.kt              ✅ BLE 数据包解析器（解析接收到的数据包）
│       ├── BLEPacketBuilder.kt             ✅ BLE 数据包构建器（构建数据包）
│       ├── BLECrypto.kt                    ✅ BLE 加密工具（AES/ECB/PKCS7 加密解密）
│       └── BLEExtension.kt                 ✅ BLE 扩展函数（ByteArray、UShort 等扩展）
└── build.gradle                           ✅ 直接依赖 base-core

xdz_android/capability-socketio/
├── src/main/java/com/narutohuo/xindazhou/socketio/
│   ├── api/
│   │   └── SocketIOService.kt              ✅ SocketIO 服务接口（模块内部）
│   ├── factory/
│   │   ├── SocketIOServiceFactory.kt       ✅ SocketIO 服务工厂
│   │   └── SocketIORepositoryFactory.kt    ✅ SocketIO Repository 工厂
│   ├── impl/
│   │   └── SocketIOServiceImpl.kt          ✅ SocketIO 服务实现
│   ├── repository/
│   │   └── SocketIORepository.kt           ✅ SocketIO Repository（封装服务，提供高级 API）
│   └── model/
│       ├── SocketIOEvent.kt                ✅ SocketIO 事件模型
│       └── SocketIOResponse.kt             ✅ SocketIO 响应模型
└── build.gradle                           ✅ 直接依赖 base-core

xdz_android/capability-nfc/
├── src/main/java/com/narutohuo/xindazhou/nfc/
│   ├── api/
│   │   └── NFCService.kt                   ✅ NFC 服务接口（模块内部）
│   ├── impl/
│   │   └── NFCServiceImpl.kt               ✅ NFC 服务实现
│   └── model/
│       └── NFCResponse.kt                  ✅ NFC 响应模型
└── build.gradle                           ✅ 直接依赖 base-core

xdz_android/capability-qrcode/
├── src/main/java/com/narutohuo/xindazhou/qrcode/
│   ├── api/
│   │   └── QRCodeService.kt                 ✅ 二维码服务接口（模块内部）
│   ├── impl/
│   │   └── QRCodeServiceImpl.kt             ✅ 二维码服务实现
│   └── model/
│       └── QRCodeResponse.kt                ✅ 二维码响应模型
└── build.gradle                           ✅ 直接依赖 base-core

app（业务层）

xdz_android/app/
├── src/main/java/com/narutohuo/xindazhou/
│   ├── user/
│   │   ├── datasource/
│   │   │   └── remote/
│   │   │       └── AuthRemoteDataSource.kt  ✅ 使用 ApiBaseRemoteDataSource
│   │   └── ...
│   └── ...
└── build.gradle                             ✅ 依赖 base-common 和 capability-xxx