# 新大洲 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 模块依赖

```yaml
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 模块依赖

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

#### base-core 模块依赖

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

#### capability-socketio 模块依赖

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

#### capability-ble 模块依赖

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

#### capability-push 模块依赖

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

#### capability-qrcode 模块依赖

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

#### capability-share 模块依赖

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

#### capability-nfc 模块依赖

```yaml
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年