# 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（基础设施层）

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

    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

## 📚 相关文档

- base-core README
- base-common README
- 网络请求 MVVM 封装方案
- UI 层封装方案
- 封装功能使用说明
- 待封装功能分析