# AirLogistics - 航空物流信息管理系统

一款专业的航空物流管理Android应用，为机场货运站提供全流程数字化解决方案，涵盖国内外货物进出港、仓储管理、车辆调度等核心业务。

## 📋 项目信息

- **版本**: 1.7.9 (versionCode 79)
- **包名**: com.lukouguoji.aerologic
- **最低支持**: Android 7.0 (API 24)
- **目标版本**: Android 10 (API 30)
- **开发语言**: Kotlin + Java
- **架构模式**: MVVM + 组件化

## 🏗️ 架构设计

### 核心架构

```
┌─────────────────────────────────────────────────────┐
│                   应用层 (App)                        │
├─────────────────────────────────────────────────────┤
│  国内出港  │  国内进港  │  国际出港  │  国际进港    │
│   (GNC)   │   (GNJ)   │   (GJC)   │   (GJJ)      │
├─────────────────────────────────────────────────────┤
│         基础服务层 (module_base)                      │
│  • MVVM基类  • 网络框架  • UI组件  • 工具类         │
├─────────────────────────────────────────────────────┤
│  蓝牙打印  │  图表库  │  航班管理  │  货物追踪      │
│ (Printer) │ (Chart)  │ (Hangban) │ (Cargo)       │
└─────────────────────────────────────────────────────┘
```

### MVVM模式

- **View层**: Activity/Fragment + DataBinding
- **ViewModel层**: BaseViewModel / BasePageViewModel
- **Model层**: Repository + Retrofit API
- **数据流**: 协程(Coroutines) + Flow

### 组件化架构

- **模块独立**: 通过`isBuildModule`参数控制模块独立运行或集成
- **路由通信**: ARouter实现模块间页面跳转和通信
- **事件总线**: FlowBus(基于Flow) + EventBus
- **依赖注入**: 基于ServiceLoader的服务发现机制

### 基础设施

#### 核心基类
- `BaseActivity`: 协程支持、Loading管理、扫码功能、键盘控制
- `BaseBindingActivity`: DataBinding自动绑定、ViewModel生命周期管理
- `BaseViewModel`: Loading管理、Activity结果处理
- `BasePageViewModel`: 分页列表专用，集成PageModel自动处理分页
- `CommonAdapter + BaseViewHolder`: 统一列表适配器封装

#### 网络请求层
- **ServiceCreator**: Retrofit实例创建，动态IP配置
- **拦截器**: 自动添加Token、时间戳，统一错误处理
- **扩展函数**:
  - `launchCollect`: 无Loading的后台请求
  - `launchLoadingCollect`: 带Loading的关键操作
  - `toRequestBody`: Map/Bean自动转JSON

#### 统一UI组件
- **PadSearchLayout**: 搜索输入框组合控件（支持文本/数字/下拉/日期）
- **PadDataLayout**: 数据展示/编辑组合控件（标题对齐）
- **StatusView**: 状态栏占位View
- **统一样式**: 颜色、字体、圆角、间距的全局规范

#### 双形态适配（平板 / 手机）
同时支持 **10 寸平板横屏** 与 **5.5 寸手机竖屏**，业务逻辑层完全复用，只重写布局。

- **DeviceUtil**: 设备形态判定（按 `smallestScreenWidthDp >= 600` 区分），提供调试用强制形态开关
- **布局自动切换**: 通过 Android 资源限定符实现，`res/layout-sw600dp/`（平板）与 `res/layout/`（手机）下放**同名**布局，DataBinding 生成同一个 Binding 类，Activity / ViewModel / ViewHolder 无需任何设备判断
- **屏幕方向**: Manifest 统一写 `android:screenOrientation="unspecified"`，系统按设备当前物理方向建窗口，`BaseActivity.applyDeviceOrientation()` 再按形态锁定（手机竖屏 / 平板横屏），两端均无「先横屏再转竖屏」闪屏。**不要改用资源引用**——系统解析 Manifest 不套用限定符，会导致平板取到竖屏值并触发 AutoSize 放大
- **AutoSize 基准**: 横屏 1152×720 / 手机竖屏 390×844 / 平板竖屏 720×1280
- **手机端资源**: `phone_*` 配色 + `bg_phone_*` drawable + 手机版公共标题栏

> ⚠️ 禁止用「不同文件名 + 代码判断」切换布局，会生成两个 Binding 类导致运行时 `ClassCastException`。
> 详见 [`documents/5.5寸手持端适配技术方案.md`](documents/5.5寸手持端适配技术方案.md) 与 `CLAUDE.md` 对应章节。

## 🚀 技术栈

### 核心框架
- **Kotlin**: 1.6.21 + Coroutines 1.6.0
- **Jetpack**: ViewModel、LiveData、DataBinding
- **网络**: Retrofit 2.6.1 + OkHttp 3.12.12
- **JSON**: FastJSON 1.2.73 + Gson 2.10.1

### UI相关
- **Material Design**: Material Components
- **屏幕适配**: AutoSize 1.2.+ (横屏1152dp × 720dp)
- **下拉刷新**: SmartRefreshLayout 2.0.3
- **图表**: MPAndroidChart (定制版)
- **弹窗**: XPopup 2.9.19
- **图片**: Glide 4.15.1 + PictureSelector v3.11.2

### 功能组件
- **路由**: ARouter 1.5.2
- **扫码**: ZXing 2.2.9
- **权限**: AndPermission 2.0.2
- **打印**: 佳博SDK 2.0.4
- **日志**: Timber 5.0.1

## 💼 核心业务模块

### 国内出港 (module_gnc)
货物收运、复磅称重、转运管理、出库装机、仓库管理、数据统计

### 国内进港 (module_gnj)
舱单管理、卸机入库、出库提货、移库管理、货物交接、实时查询

### 国际出港 (module_gjc)
国际货物收运、板箱组装、ULD容器管理、复磅称重、仓储移库

### 国际进港 (module_gjj)
国际舱单管理、报文解析、理货管理、出库操作、货物交接

### 支持模块
- **航班管理** (module_hangban): 航班查询、航班统计
- **货物追踪** (module_cargo): 货物状态追踪、运输日志
- **监装监卸** (module_mit): 监装监卸管理
- **PDA功能** (module_p): PDA专用功能
- **蓝牙打印** (Printer): 佳博打印机SDK集成

## 📦 项目结构

```
aerologic-app/
├── app/                    # 应用壳层，整合所有业务模块
├── module_base/           # 核心基础库，提供所有通用能力
│   ├── base/              # MVVM基类
│   ├── http/              # 网络请求框架
│   ├── ui/weight/         # 统一UI组件
│   ├── ktx/               # Kotlin扩展函数
│   ├── bean/              # 数据模型
│   ├── util/              # 工具类（含 DeviceUtil 设备形态判定）
│   └── router/            # ARouter路由常量
├── module_gnc/            # 国内出港业务
├── module_gnj/            # 国内进港业务
├── module_gjc/            # 国际出港业务
├── module_gjj/            # 国际进港业务
├── module_hangban/        # 航班查询管理
├── module_cargo/          # 货物追踪查询
├── module_mit/            # 监装监卸管理
├── module_p/              # PDA专用功能
├── Printer/               # 蓝牙打印模块
├── MPChartLib/            # 定制图表库
├── documents/             # 设计稿、报价单、技术方案文档
├── CLAUDE.md              # 详细开发指南
└── README.md              # 项目说明文档
```

各业务模块内的布局按设备形态分目录存放：

```
module_gjc/src/main/res/
├── layout/                # 手机布局（5.5 寸竖屏，兜底）
└── layout-sw600dp/        # 平板布局（10 寸横屏）
```

> 两目录下**同名**的布局是同一布局的资源变体，系统按屏幕最小宽度自动选择。
> 尚未适配手机的页面，布局保留在 `layout/` 即可（两端共用），支持渐进式适配。

## 🚀 快速开始

### 环境要求

- **IDE**: Android Studio Arctic Fox (2020.3.1) 或更高版本
- **JDK**: 1.8
- **Gradle**: 7.3.3
- **Kotlin**: 1.6.21

### 依赖配置

如遇依赖下载问题：

1. 下载 gradle-7.3.3-bin.zip
   - 百度网盘: https://pan.baidu.com/s/18wsuGRlNxjMYbxLhBH9yeg
   - 提取码: 1029

2. 配置Gradle:
   - Settings → Build, Execution, Deployment → Build Tools → Gradle
   - 解压并替换到 "Gradle user home" 目录

### 构建项目

```bash
# 克隆项目
git clone [repository-url]
cd aerologic-app

# 清理构建
./gradlew clean

# 构建Debug版本
./gradlew assembleDebug

# 构建Release版本（已签名）
./gradlew assembleRelease

# 安装到设备
./gradlew installDebug
```

### 组件化开发模式

支持模块独立运行调试：

1. 编辑 `gradle.properties`
2. 设置 `isBuildModule=true` (独立模块) 或 `false` (集成模式)
3. Sync项目并运行对应模块

## ⚙️ 配置说明

### 网络配置

服务器地址配置位置：
- **文件**: `module_base/src/main/res/values/strings.xml`
- **主服务器**: `system_url_inner`
- **地磅服务器**: `weight_url`
- **运行时**: 可通过SharedPreferences动态修改IP地址

### 签名配置

Release版本签名信息：
- **KeyStore**: `key.jks` (项目根目录)
- **密码**: storePassword/keyPassword均为 `123321`
- **别名**: `key`

### 网络安全

- **超时时间**: 30秒（连接/读取/写入）
- **认证方式**: Bearer Token（自动添加）
- **HTTP支持**: 配置在 `res/xml/network_security_config.xml`

## 📚 开发文档

详细的开发指南请参考 **[CLAUDE.md](./CLAUDE.md)**，包含：

- ✅ 完整的架构详解（基类、网络、UI组件）
- ✅ 标准开发模板（Activity、ViewModel、ViewHolder）
- ✅ 实际业务示例（列表页、详情页、编辑页）
- ✅ 开发检查清单（7步列表页、4步详情页、5步编辑页）
- ✅ DataBinding适配器（10+种）
- ✅ Kotlin扩展函数（20+种）
- ✅ 常见业务场景实现

## 🔄 Git工作流

### 分支策略

- **develop**: 主开发分支
- **feature/xxx**: 功能开发分支
- **release/x.x.x**: 发布分支
- **hotfix/xxx**: 紧急修复分支

### 当前分支

- **开发分支**: feature/hefei
- **主分支**: develop（用于PR）

### 提交规范

提交前确保：
- ✅ 代码编译通过
- ✅ 无明显错误和警告
- ✅ 遵循项目代码规范

## 📋 开发原则

1. ✅ **优先使用现有基类和封装**，避免重复造轮子
2. ✅ **充分利用PadDataLayout和PadSearchLayout组件**，保证UI一致性
3. ✅ **遵循统一的命名和目录组织规范**
4. ✅ **使用DataBinding简化代码**，减少findViewById
5. ✅ **利用扩展函数处理通用逻辑**（Toast、Dialog、权限等）
6. ✅ **保持架构一致性**，新增业务参考现有模块

## 🔐 特性亮点

### 1. 高度组件化
- 业务模块完全解耦，支持独立开发、测试、发布
- 通过ARouter实现模块间通信，无需直接依赖

### 2. 统一UI规范
- 自定义PadSearchLayout、PadDataLayout组合控件
- 全局统一的颜色、字体、圆角、间距规范
- 丰富的DataBinding适配器，简化UI开发

### 3. 高效网络框架
- 协程+Flow的现代化异步方案
- 统一的请求封装（launchCollect/launchLoadingCollect）
- 自动的Loading管理和错误处理

### 4. 完善的基础设施
- BaseActivity提供扫码、Loading、键盘控制等通用能力
- BasePageViewModel自动处理分页逻辑
- CommonAdapter统一列表适配器管理

### 5. 丰富的工具扩展
- 20+ Kotlin扩展函数（Toast、Dialog、JSON、日期等）
- 10+ DataBinding适配器（图片加载、可见性、Shape等）
- 完整的业务开发模板和检查清单

## 🛠️ 技术特点

- **响应式编程**: Kotlin Coroutines + Flow
- **声明式UI**: DataBinding双向绑定
- **函数式编程**: Kotlin扩展函数和高阶函数
- **依赖注入**: 基于ServiceLoader的轻量级方案
- **模块化路由**: ARouter组件化通信
- **横屏适配**: AutoSize自动适配1152dp × 720dp
- **蓝牙打印**: 佳博打印机SDK深度集成
- **二维码扫描**: ZXing高性能扫码

## 📄 许可证

本项目为企业内部系统，版权归所属公司所有。

## ⚠️ 注意事项

**重要**: 本项目包含敏感业务信息和配置，仅供授权人员使用，严禁外传。

---

**文档维护**: 本README提供项目概览和架构信息，详细开发指南请参考 [CLAUDE.md](./CLAUDE.md)
