# PROJECT_STRUCTURE

# 新大洲 Android 项目结构文档

## 一、项目结构图

    xdz_android/
    ├── app/                          # 应用主模块（业务层）
    │   ├── src/main/
    │   │   ├── java/                # 业务代码（Activity、Fragment、ViewModel等）
    │   │   └── res/                  # 资源文件（布局、图片、字符串等）
    │   └── build.gradle
    │
    ├── base-core/                    # 基础核心模块（最底层）
    │   └── src/main/
    │       └── java/                # 核心工具类和接口定义
    │
    ├── base-common/                  # 基础通用模块
    │   └── src/main/
    │       └── java/                # 通用组件（Dialog、网络请求封装等）
    │
    ├── capability-ble/               # BLE 蓝牙能力模块
    │   └── src/main/
    │       └── java/                # BLE 相关功能实现
    │
    ├── capability-socketio/          # SocketIO 实时通信能力模块
    │   └── src/main/
    │       └── java/                # SocketIO 客户端封装
    │
    ├── capability-push/              # 推送能力模块
    │   └── src/main/
    │       └── java/                # 推送功能封装（极光推送等）
    │
    ├── capability-qrcode/           # 二维码能力模块
    │   └── src/main/
    │       └── java/                # 二维码扫描/生成功能
    │
    ├── capability-share/            # 分享能力模块
    │   └── src/main/
    │       └── java/                # 微信、QQ等分享功能
    │
    ├── capability-nfc/              # NFC 能力模块
    │   └── src/main/
    │       └── java/                # NFC 读写功能
    │
    ├── build.gradle                  # 项目根 build.gradle
    ├── settings.gradle              # 模块配置
    └── gradle/                       # Gradle 配置
        └── libs.versions.toml       # 依赖版本管理

## 二、模块说明

### 2.1 应用层

模块 | 命名空间 | 说明
--- | --- | ---
app | `com.narutohuo.xindazhou` | 应用主模块，包含所有业务代码和UI

### 2.2 基础层

模块 | 命名空间 | 说明
--- | --- | ---
base-core | `com.narutohuo.xindazhou.core` | 核心基础模块，提供最基础的接口和工具类
base-common | `com.narutohuo.xindazhou.common` | 通用基础模块，提供通用组件和网络封装

### 2.3 能力层（SDK层）

模块 | 命名空间 | 说明
--- | --- | ---
capability-ble | `com.narutohuo.xindazhou.ble` | 蓝牙BLE功能封装
capability-socketio | `com.narutohuo.xindazhou.socketio` | SocketIO实时通信封装
capability-push | `com.narutohuo.xindazhou.push` | 推送功能封装（极光推送等）
capability-qrcode | `com.narutohuo.xindazhou.qrcode` | 二维码扫描/生成功能
capability-share | `com.narutohuo.xindazhou.share` | 分享功能封装（微信、QQ等）
capability-nfc | `com.narutohuo.xindazhou.nfc` | NFC读写功能封装

## 三、依赖关系图

### 3.1 模块依赖关系

    ┌─────────────────────────────────────────────────────────┐
    │                        app                               │
    │              (应用主模块 - 业务层)                        │
    └────────────┬────────────────────────────────────────────┘
                 │
                 │ 依赖所有模块
                 │
        ┌────────┼────────┬────────┬────────┬────────┬────────┐
        │        │        │        │        │        │        │
        ▼        ▼        ▼        ▼        ▼        ▼        ▼
    ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
    │base- │ │base-  │ │cap-   │ │cap-   │ │cap-   │ │cap-   │
    │common│ │core   │ │socket │ │ble    │ │push   │ │qrcode │
    └───┬───┘ └───────┘ │io     │ └───────┘ └───────┘ └───────┘
        │               └───────┘
        │               ┌───────┐
        │               │cap-   │
        │               │share  │
        │               └───────┘
        │               ┌───────┐
        │               │cap-   │
        │               │nfc    │
        │               └───────┘
        │
        │ 依赖
        ▼
    ┌───────┐
    │base-  │
    │core   │
    └───────┘
        ▲
        │ 所有 capability-* 模块都依赖
        │
    ┌───┴───────────────────────────────────────────┐
    │  capability-ble                               │
    │  capability-socketio                          │
    │  capability-push                               │
    │  capability-qrcode                             │
    │  capability-share                              │
    │  capability-nfc                                │
    └───────────────────────────────────────────────┘

### 3.2 详细依赖关系

#### app 模块依赖

    app:
      基础模块:
        - base-core
        - base-common
      能力模块:
        - capability-ble
        - capability-socketio
        - capability-push
        - capability-qrcode
        - capability-share
        - capability-nfc
      第三方库:
        - AndroidX Core KTX
        - AppCompat
        - Material Design
        - ConstraintLayout
        - Lifecycle (ViewModel, LiveData)
        - Kotlin Coroutines
        - Navigation
        - Retrofit & OkHttp
        - Glide
        - Room
        - Jetpack Compose
        - Timber (日志)
        - Hyperion (调试工具)
        - Chuck (网络调试)

#### base-common 模块依赖

    base-common:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX
        - Fragment KTX
        - Material Design
        - Gson
        - Retrofit & Gson Converter

#### base-core 模块依赖

    base-core:
      第三方库:
        - AndroidX Core KTX  # 仅依赖最基础的 AndroidX

#### capability-socketio 模块依赖

    capability-socketio:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX
        - Socket.IO Client (io.socket:socket.io-client:2.1.0)
        - Gson
        - Kotlin Coroutines

#### capability-ble 模块依赖

    capability-ble:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX

#### capability-push 模块依赖

    capability-push:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX
        # 极光推送SDK（待添加）

#### capability-qrcode 模块依赖

    capability-qrcode:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX
        # 华为扫码SDK（待添加）

#### capability-share 模块依赖

    capability-share:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX
        # 微信分享SDK（待添加）
        # QQ分享SDK（待添加）

#### capability-nfc 模块依赖

    capability-nfc:
      项目模块:
        - base-core  # 依赖基础核心模块
      第三方库:
        - AndroidX Core KTX

## 四、依赖关系总结

### 4.1 依赖层级

    层级 1: base-core
      └─ 最底层，不依赖任何项目模块，只依赖 AndroidX Core

    层级 2: base-common + 所有 capability-* 模块
      └─ 都依赖 base-core

    层级 3: app
      └─ 依赖所有基础模块和能力模块

### 4.2 依赖原则

1. base-core:

   - 最底层模块，不依赖任何项目内部模块
   - 只依赖 AndroidX Core KTX
   - 提供最基础的接口和工具类

2. base-common:

   - 依赖 base-core
   - 提供通用组件（Dialog、网络请求封装等）

3. capability- 模块*:

   - 所有能力模块都依赖 base-core
   - 每个模块独立封装特定功能
   - 不相互依赖，保持模块独立性

4. app 模块:

   - 依赖所有基础模块和能力模块
   - 包含业务代码和UI
   - 通过能力模块提供的接口使用功能

### 4.3 模块独立性

- ✅ capability- 模块之间不相互依赖*，保持独立
- ✅ 所有 capability- 模块都依赖 base-core*，统一基础
- ✅ app 模块依赖所有模块，整合所有功能

## 五、主要第三方依赖

### 5.1 网络请求

- Retrofit: `2.9.0` - HTTP 客户端
- OkHttp: `4.12.0` - HTTP 网络库
- Gson: `2.10.1` - JSON 解析

### 5.2 UI 框架

- Jetpack Compose: 现代 UI 框架
- Material Design: `1.11.0` - Material 组件
- Navigation: `2.7.6` - 导航组件

### 5.3 异步处理

- Kotlin Coroutines: `1.7.3` - 协程支持

### 5.4 数据存储

- Room: `2.6.1` - 本地数据库

### 5.5 图片加载

- Glide: `4.16.0` - 图片加载库

### 5.6 实时通信

- Socket.IO Client: `2.1.0` - SocketIO 客户端

### 5.7 调试工具

- Hyperion: `0.9.34` - 应用内调试工具
- Chuck: `4.0.0` - 网络请求拦截器（调试用）
- Timber: `5.0.1` - 日志库

## 六、项目配置

### 6.1 编译配置

- compileSdk: 36
- minSdk: 26
- targetSdk: 36
- Java Version: 17
- Kotlin JVM Target: 17

### 6.2 构建特性

- ViewBinding: 启用
- DataBinding: 部分启用
- Jetpack Compose: 启用
- BuildConfig: 启用

## 七、模块职责划分

模块 | 职责 | 可被谁依赖
--- | --- | ---
base-core | 提供最基础的接口和工具类 | 所有模块
base-common | 提供通用组件和网络封装 | app
capability-ble | BLE 功能封装 | app
capability-socketio | SocketIO 功能封装 | app
capability-push | 推送功能封装 | app
capability-qrcode | 二维码功能封装 | app
capability-share | 分享功能封装 | app
capability-nfc | NFC 功能封装 | app
app | 业务代码和UI | 无（应用入口）

文档版本: v1.0
最后更新: 2024年