feat: power claude templates
This commit is contained in:
273
CONTRIBUTING.md
Normal file
273
CONTRIBUTING.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# 贡献指南 (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 (如果支持)
|
||||
|
||||
---
|
||||
|
||||
再次感谢你的贡献!🎉
|
||||
Reference in New Issue
Block a user