YANG JIANKUAN
db062c8ee3
- 落地手机端双形态适配框架：同名布局+资源限定符（layout/手机、 layout-sw600dp/平板）自动切换，DeviceUtil 设备形态判定，7个 手机版公共组件（PhoneSearchBar/StatusTab/DataLayout/FilterPanel/ BottomBar/StatBox/KvItem） - 完成「国际出港移库」「国际出港出库交接」两页手机端适配，新增 各自详情页（IntExpMoveDetailActivity/IntExpOutHandoverDetailActivity） - 手机端首页菜单接入"出港移库""出库交接"入口 - 修复手机端进入页面先横屏后转竖屏的闪屏问题：Manifest 全项目 192 处改为 screenOrientation="unspecified"，由 BaseActivity 按设备形态运行时锁定方向 - 修复该方案的中间版本在平板端引入的回归（先竖后横 + UI放大1.6倍） - AutoSize 补充手机竖屏 390×844 设计基准 - 修复 CHANGELOG.md 因脚本异常导致的内容重复损坏（膨胀至12万行）， 恢复正常结构并补充本次变更记录 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
327 lines
12 KiB
Markdown
327 lines
12 KiB
Markdown
# 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)
|