feat: update md

2025-11-12 10:55:32 +08:00
parent c1d4f5a74f
commit 5872ef3659
2 changed files with 2523 additions and 337 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
--- a/README.md
+++ b/README.md
@@ -2,92 +2,161 @@

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

-## 项目信息
+## 📋 项目信息

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

-## 核心功能
+## 🏗️ 架构设计

-### 国内出港 (GNC)
- 货物收运管理
- 复磅称重（地磅集成）
- 转运管理
- 出库装机
- 仓库管理
- 数据查询与统计
+### 核心架构

-### 国内进港 (GNJ)
- 舱单管理
- 卸机入库
- 出库提货
- 移库管理
- 货物交接
- 实时查询
+```
+┌─────────────────────────────────────────────────────┐
+│                   应用层 (App)                        │
+├─────────────────────────────────────────────────────┤
+│  国内出港  │  国内进港  │  国际出港  │  国际进港    │
+│   (GNC)   │   (GNJ)   │   (GJC)   │   (GJJ)      │
+├─────────────────────────────────────────────────────┤
+│         基础服务层 (module_base)                      │
+│  • MVVM基类  • 网络框架  • UI组件  • 工具类         │
+├─────────────────────────────────────────────────────┤
+│  蓝牙打印  │  图表库  │  航班管理  │  货物追踪      │
+│ (Printer) │ (Chart)  │ (Hangban) │ (Cargo)       │
+└─────────────────────────────────────────────────────┘
+```

-### 国际出港 (GJC)
- 国际货物收运
- 板箱组装
- ULD容器管理
- 复磅称重
- 仓储移库
+### MVVM模式

-### 国际进港 (GJJ)
- 国际舱单管理
- 报文解析
- 理货管理
- 出库操作
- 货物交接
+- **View层**: Activity/Fragment + DataBinding
+- **ViewModel层**: BaseViewModel / BasePageViewModel
+- **Model层**: Repository + Retrofit API
+- **数据流**: 协程(Coroutines) + Flow

-### 其他功能
- 航班查询与管理
- 货物状态追踪
- 运输日志
- 监装监卸管理
- 车辆调度与统计
- 消息与电报管理
- 事故签证处理
+### 组件化架构

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

-### 架构设计
- **组件化架构**: 模块间解耦，支持独立开发调试
- **MVVM模式**: 数据驱动，清晰的业务逻辑分层
- **协程异步**: Kotlin Coroutines + Flow 实现响应式编程
- **模块路由**: ARouter实现模块间通信
+### 基础设施

-### 核心技术
- **网络框架**: Retrofit + OkHttp
- **数据解析**: FastJSON + Gson
- **UI框架**: Material Design + DataBinding
- **图表展示**: MPAndroidChart定制版
- **蓝牙打印**: 佳博打印SDK集成
- **扫码功能**: ZXing条码扫描
- **屏幕适配**: AutoSize横屏适配方案
+#### 核心基类
+- `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
+- **统一样式**: 颜色、字体、圆角、间距的全局规范
+
+## 🚀 技术栈
+
+### 核心框架
+- **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/              # 数据模型
+│   └── router/            # ARouter路由常量
+├── module_gnc/            # 国内出港业务
+├── module_gnj/            # 国内进港业务
+├── module_gjc/            # 国际出港业务
+├── module_gjj/            # 国际进港业务
+├── module_hangban/        # 航班查询管理
+├── module_cargo/          # 货物追踪查询
+├── module_mit/            # 监装监卸管理
+├── module_p/              # PDA专用功能
+├── Printer/               # 蓝牙打印模块
+├── MPChartLib/            # 定制图表库
+├── CLAUDE.md              # 详细开发指南
+└── README.md              # 项目说明文档
+```
+
+## 🚀 快速开始

 ### 环境要求

- Android Studio Arctic Fox (2020.3.1) 或更高版本
- JDK 1.8
- Gradle 7.3.3
- Kotlin 1.6.21
+- **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. 在 Android Studio 中打开设置:
+2. 配置Gradle:
   - Settings → Build, Execution, Deployment → Build Tools → Gradle
-   - 解压下载的文件并替换 "Gradle user home" 目录中的对应文件夹
+   - 解压并替换到 "Gradle user home" 目录

 ### 构建项目

@@ -96,83 +165,137 @@
 git clone [repository-url]
 cd aerologic-app

+# 清理构建
+./gradlew clean
+
 # 构建Debug版本
 ./gradlew assembleDebug

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

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

-### 组件化开发
+### 组件化开发模式

-项目支持组件化开发模式，可独立运行各业务模块：
+支持模块独立运行调试：

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

-## 项目结构
-
-```
-aerologic-app/
-├── app/                    # 应用主模块
-├── module_base/           # 基础库模块（核心）
-├── module_gnc/            # 国内出港
-├── module_gnj/            # 国内进港
-├── module_gjc/            # 国际出港
-├── module_gjj/            # 国际进港
-├── module_hangban/        # 航班管理
-├── module_cargo/          # 货物追踪
-├── module_mit/            # 监装监卸
-├── module_p/              # PDA功能
-├── Printer/               # 蓝牙打印
-├── MPChartLib/            # 图表库
-└── CLAUDE.md              # 开发指南
-```
-
-## 开发文档
-
-详细的开发指南请参考 [CLAUDE.md](./CLAUDE.md)，包含：
-
- 完整的架构说明
- API调用规范
- 开发模板代码
- 常见业务场景实现
- 技术栈使用指南
-
-## 配置说明
+## ⚙️ 配置说明

 ### 网络配置

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

 ### 签名配置

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

-## 分支管理
+### 网络安全

- `develop`: 主开发分支
- `feature/*`: 功能开发分支
- `release/*`: 发布分支
+- **超时时间**: 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)