# 贡献指南 (Contributing Guide)

感谢你对 AirLogistics 项目的关注!本文档将指导你如何参与项目开发。

## 开发环境搭建

### 前置要求

- **IDE**: Android Studio Arctic Fox (2020.3.1) 或更高版本
- **JDK**: JDK 1.8
- **Gradle**: 7.3.3 (使用项目内置的 Gradle Wrapper)
- **Kotlin**: 1.6.21 (已在项目中配置)
- **Android SDK**: API 24-31

### 克隆项目

```bash
git clone ssh://git@git.njcqit.com:2222/eric/aerologic-app.git
cd aerologic-app
```

### 配置 Android SDK

1. 创建 `local.properties` 文件 (如果不存在):
   ```properties
   sdk.dir=/path/to/your/android/sdk
   ```

2. 在 Android Studio 中:
   - 打开项目
   - 等待 Gradle 同步完成
   - 如提示 SDK 路径问题,在 Settings → Android SDK 中配置

### Gradle 依赖配置

项目已配置阿里云 Maven 镜像和私有仓库,正常情况下依赖会自动下载。

如遇依赖下载问题:
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
# 清理并构建 Debug 版本
./gradlew clean assembleDebug

# 或使用快捷命令
/clean-build
```

### 常用构建命令

```bash
# 构建 Debug APK
./gradlew assembleDebug
# 或使用: /build-debug

# 构建 Release APK (已签名)
./gradlew assembleRelease
# 或使用: /build-release

# 安装到设备
./gradlew installDebug
# 或使用: /install

# 运行代码检查
./gradlew lint
# 或使用: /lint

# 查看已连接设备
adb devices -l
# 或使用: /devices

# 查看应用日志
adb logcat | grep "com.lukouguoji.aerologic"
# 或使用: /logs
```

### 组件化开发模式

项目支持模块独立运行,方便单模块调试:

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

**注意**: 切换模式后需要重新 Sync 项目。

## 分支策略

### 分支类型

- **main**: 主分支,用于发布稳定版本
- **feature/xxx**: 功能开发分支 (例: `feature/cargo-tracking`)
- **hotfix/xxx**: 紧急修复分支 (例: `hotfix/login-crash`)
- **refactor/xxx**: 重构分支 (例: `refactor/network-layer`)

### 分支命名规范

- 使用小写字母和连字符
- 功能分支: `feature/功能名称-简短描述`
- 修复分支: `hotfix/问题简述`
- 重构分支: `refactor/重构范围`

### 工作流程

1. 从 main 分支创建新分支:
   ```bash
   git checkout main
   git pull
   git checkout -b feature/your-feature-name
   ```

2. 在新分支上开发并提交

3. 推送到远程仓库:
   ```bash
   git push -u origin feature/your-feature-name
   ```

4. 创建 Pull Request,等待代码审查

## 提交规范

### Conventional Commits 格式

提交信息应遵循以下格式:

```
<类型>: <简短描述>

[可选的详细说明]

[可选的 footer]
```

### 提交类型

- **feat**: 新功能 (例: `feat: 添加国内出港货物复磅功能`)
- **fix**: Bug修复 (例: `fix: 修复登录页面崩溃问题`)
- **refactor**: 代码重构 (例: `refactor: 优化网络请求层架构`)
- **docs**: 文档更新 (例: `docs: 更新 README 安装说明`)
- **style**: 代码格式调整 (例: `style: 格式化 LoginActivity 代码`)
- **test**: 测试相关 (例: `test: 添加货物追踪单元测试`)
- **chore**: 构建/工具相关 (例: `chore: 升级 Kotlin 到 1.6.21`)

### 提交示例

```bash
# 好的提交信息
git commit -m "feat: 添加国际进港舱单管理功能"
git commit -m "fix: 修复蓝牙打印机连接失败问题"
git commit -m "refactor: 重构 BaseViewModel 生命周期管理"

# 不好的提交信息
git commit -m "update"
git commit -m "修改了一些文件"
git commit -m "功能完成"
```

## 代码审查流程

### 创建 Pull Request

1. 确保代码已推送到远程仓库
2. 在 Git 托管平台创建 Pull Request
3. 填写 PR 描述:
   - 功能说明
   - 变更内容
   - 测试情况
   - 相关 Issue (如有)

### 代码审查要点

审查者应关注:
- [ ] 代码是否符合项目架构和规范
- [ ] 是否使用了正确的基类 (BaseActivity, BaseViewModel等)
- [ ] DataBinding 和协程使用是否正确
- [ ] 命名是否清晰、符合约定
- [ ] 是否有明显的性能问题
- [ ] 是否有代码重复或可复用的逻辑

### 合并前检查清单

提交者在创建 PR 前应确保:
- [ ] 代码编译通过,无编译错误
- [ ] 遵循项目命名和文件组织规范
- [ ] 使用了项目提供的基类和工具类
- [ ] DataBinding 正确使用
- [ ] 协程和 Flow 使用规范
- [ ] 无明显的内存泄漏风险
- [ ] 已在真机或模拟器上测试
- [ ] 提交信息符合规范

## 开发注意事项

### 架构要求

1. **优先使用现有基类**
   - Activity 继承 `BaseActivity` 或 `BaseBindingActivity`
   - ViewModel 继承 `BaseViewModel` 或 `BasePageViewModel`
   - 列表适配器使用 `CommonAdapter` + `BaseViewHolder`

2. **使用统一 UI 组件**
   - 搜索输入: 使用 `PadSearchLayout`
   - 数据展示: 使用 `PadDataLayout`
   - 遵循全局样式规范 (colors, dimens, styles)

3. **网络请求规范**
   - 使用 `launchCollect` 或 `launchLoadingCollect` 扩展函数
   - API 定义在对应模块的 `api/` 目录下
   - 数据模型继承 `BaseResultBean` 或 `BaseListBean`

### 代码风格

- 遵循 Kotlin 官方编码规范
- 使用有意义的变量名和函数名
- 避免过长的函数,单个函数不超过 50 行
- 复杂逻辑添加注释说明

### 安全要求

- **禁止提交敏感信息**:
  - API密钥
  - 密码
  - Token
  - 个人信息
  - 签名文件 (key.jks 已在 .gitignore 中)

- **配置信息管理**:
  - 服务器地址配置在 `module_base/res/values/strings.xml`
  - 本地开发配置使用 `local.properties`
  - 运行时配置使用 SharedPreferences

## 模块开发规范

### 新增业务页面

1. 在对应模块的 `ui/page/` 目录下创建 Activity
2. 在 `service/viewModel/` 目录下创建 ViewModel
3. 在 `bean/` 目录下定义数据模型
4. 布局文件使用 DataBinding

### 模块间通信

- 使用 ARouter 进行页面跳转
- 路由路径定义在 `module_base/router/` 目录
- 事件通信使用 FlowBus 或 EventBus

## 获取帮助

如有问题或建议,可以通过以下方式:

1. 查看项目文档:
   - [CLAUDE.md](./CLAUDE.md) - 详细开发指南
   - [README.md](./README.md) - 项目概览

2. 联系项目维护者

3. 提交 Issue (如果支持)

---

再次感谢你的贡献!🎉