eric/aerologic-app

Fork 0

Files

YANGJIANKUAN 0c3c78b42e feat: power claude templates

2025-12-02 16:21:19 +08:00

6.8 KiB

Raw Permalink Blame History

贡献指南 (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

克隆项目

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

配置 Android SDK

创建 local.properties 文件 (如果不存在):
```
sdk.dir=/path/to/your/android/sdk
```
在 Android Studio 中:
- 打开项目
- 等待 Gradle 同步完成
- 如提示 SDK 路径问题,在 Settings → Android SDK 中配置

Gradle 依赖配置

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

如遇依赖下载问题:

下载 gradle-7.3.3-bin.zip
- 百度网盘: https://pan.baidu.com/s/18wsuGRlNxjMYbxLhBH9yeg
- 提取码: 1029
配置 Gradle:
- Settings → Build, Execution, Deployment → Build Tools → Gradle
- 解压并替换到 "Gradle user home" 目录

项目构建

首次构建

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

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

常用构建命令

# 构建 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

组件化开发模式

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

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

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

分支策略

分支类型

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

分支命名规范

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

工作流程

从 main 分支创建新分支:

git checkout main
git pull
git checkout -b feature/your-feature-name

在新分支上开发并提交

推送到远程仓库:

git push -u origin feature/your-feature-name

创建 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)

提交示例

# 好的提交信息
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

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

代码审查要点

审查者应关注:

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

合并前检查清单

提交者在创建 PR 前应确保:

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

开发注意事项

架构要求

优先使用现有基类
- Activity 继承 BaseActivity 或 BaseBindingActivity
- ViewModel 继承 BaseViewModel 或 BasePageViewModel
- 列表适配器使用 CommonAdapter + BaseViewHolder
使用统一 UI 组件
- 搜索输入: 使用 PadSearchLayout
- 数据展示: 使用 PadDataLayout
- 遵循全局样式规范 (colors, dimens, styles)
网络请求规范
- 使用 launchCollect 或 launchLoadingCollect 扩展函数
- API 定义在对应模块的 api/ 目录下
- 数据模型继承 BaseResultBean 或 BaseListBean

代码风格

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

安全要求

禁止提交敏感信息:
- API密钥
- 密码
- Token
- 个人信息
- 签名文件 (key.jks 已在 .gitignore 中)
配置信息管理:
- 服务器地址配置在 module_base/res/values/strings.xml
- 本地开发配置使用 local.properties
- 运行时配置使用 SharedPreferences

模块开发规范

新增业务页面

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

模块间通信

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

获取帮助

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

查看项目文档:
- CLAUDE.md - 详细开发指南
- README.md - 项目概览
联系项目维护者
提交 Issue (如果支持)

再次感谢你的贡献!🎉

6.8 KiB Raw Permalink Blame History