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 与 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" 目录

构建项目

# 克隆项目
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，包含：

• ✅ 完整的架构详解（基类、网络、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