# acp-admin-solon

**Repository Path**: zhangbinhub/acp-admin-solon

## Basic Information

- **Project Name**: acp-admin-solon
- **Description**: 使用 Kotlin 语言编写，基于 Solon Cloud 的微服务架构。该项目是前后端分离中的"后端部分"
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-09-27
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Kotlin, Solon4, SolonCloud, java21

## README

# acp-admin-solon

###### v2.4.2 [版本更新日志](doc/version_history.md)

基于 [Acp（Application Construction Platform）](https://gitee.com/zhangbinhub/acp) 应用构建平台作为脚手架开发的后台管理系统（后端部分），使用 **Kotlin + Solon** 技术栈构建。

- 同一套业务代码，支持两种运行形态：
    - **单机版**：[acp-admin-server](acp-admin-server/README.md) —— 基于 Solon Boot，单进程整合全部业务功能，仅需 MySQL
    - **微服务版**：[acp-admin-cloud](acp-admin-cloud/README.md) —— 基于 Solon Cloud，按业务域拆分为 5 个独立服务
- 该项目是前后端分离架构中的“后端部分”，前端工程请查看[这里](https://gitee.com/zhangbinhub/acp-admin-cloud-web)

## 相关项目

- [Acp](https://gitee.com/zhangbinhub/acp) —— 应用构建平台（脚手架，提供 Boot/Cloud 基础能力封装）
- [sensitive](https://github.com/houbb/sensitive) —— 日志脱敏工具
- [acp-admin-cloud-web](https://gitee.com/zhangbinhub/acp-admin-cloud-web) —— 前端工程

## 技术栈

| 分类     | 组件           | Solon技术栈                                                                                                                                                                                                             |
|----------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 构建工具 | -              | Gradle 9.0+                                                                                                                                                                                                             |
| 开发语言 | JVM            | 21+                                                                                                                                                                                                                     |
|          | Java           | 21+                                                                                                                                                                                                                     |
|          | Kotlin         | 2.3+                                                                                                                                                                                                                    |
| Core     | UUID           | [uuid-creator](https://github.com/f4b6a3/uuid-creator)                                                                                                                                                                  |
|          | 加解密库       | bouncycastle                                                                                                                                                                                                            |
|          | PDF处理        | itextpdf<br/>html2pdf                                                                                                                                                                                                   |
|          | 综合工具       | [Hutool（国产）](https://hutool.cn/)                                                                                                                                                                                    |
| Boot     | WEB服务        | [solon-boot-smarthttp（国产）](https://solon.noear.org/article/90)                                                                                                                                                      |
|          | http工具类     | [solon-net-httputils（国产）](https://solon.noear.org/article/770)                                                                                                                                                      |
|          | 日志框架       | slf4j<br/>[solon-logging-logback](https://solon.noear.org/article/437)                                                                                                                                                  |
|          | Json处理       | [Snack4（国产）](https://gitee.com/noear/snackjson)<br/>[solon.serialization.snack4](https://solon.noear.org/article/1200)                                                                                              |
|          | Xml处理        | Jackson3<br/>solon-serialization-jackson3-xml                                                                                                                                                                           |
|          | ORM框架        | [MyBatis-Flex](https://gitee.com/mybatis-flex/mybatis-flex)                                                                                                                                                             |
|          | Api文档        | [Knife4j（国产）](https://doc.xiaominfo.com/)<br/>[solon-openapi3-knife4j](https://solon.noear.org/article/1311)                                                                                                        |
|          | 安全框架       | [Sa-Token（国产）](https://sa-token.cc/index.html)                                                                                                                                                                      |
|          | 资源服务       | [sa-token-solon-plugin（国产）](https://solon.noear.org/article/110)<br/>sa-token-oauth2                                                                                                                                |
|          | 认证服务       | [sa-token-solon-plugin（国产）](https://solon.noear.org/article/110)<br/>sa-token-oauth2                                                                                                                                |
|          | 认证协议       | Oauth 2.0                                                                                                                                                                                                               |
|          | WebSocket      | [solon-boot-smarthttp（国产）](https://solon.noear.org/article/90)<br/>[java-websocket-ns](https://solon.noear.org/article/644)                                                                                         |
|          | TCP/UDP        | Netty                                                                                                                                                                                                                   |
|          | 校验           | [solon-security-validation（国产）](https://solon.noear.org/article/225)                                                                                                                                                |
|          | 缓存           | [valkey](https://valkey.io)<br/>[redisson-solon-plugin（国产）](https://solon.noear.org/article/533)                                                                                                                    |
|          | 工作流引擎     | [warm-flow（国产）](https://warm-flow.dromara.org/)                                                                                                                                                                     |
| Cloud    | 监控           | [solon-admin-server（国产）](https://solon.noear.org/article/581)                                                                                                                                                       |
|          | 注册中心       | [Nacos（国产）](https://nacos.io/)<br/>[nacos3-solon-cloud-plugin](https://solon.noear.org/article/1268)                                                                                                                |
|          | 配置中心       | [Nacos（国产）](https://nacos.io/)<br/>[nacos3-solon-cloud-plugin](https://solon.noear.org/article/1268)                                                                                                                |
|          | 熔断/限流      | [Sentinel（国产）](http://sentinelguard.io/zh-cn/)<br/>[sentinel-solon-cloud-plugin](https://solon.noear.org/article/160)                                                                                               |
|          | 服务间调用     | [nami](https://solon.noear.org/article/334)                                                                                                                                                                             |
|          | 负载均衡       | [CloudLoadBalance（国产）](https://solon.noear.org/article/793)                                                                                                                                                         |
|          | 消息总线       | [Solon Cloud Event（国产）](https://solon.noear.org/article/family-solon-cloud-event)<br/>Kafka<br/>[kafka-solon-cloud-plugin](https://solon.noear.org/article/157)                                                     |
|          | 日志收集       | [Solon Cloud Event（国产）](https://solon.noear.org/article/family-solon-cloud-event)<br/>Kafka<br/>[kafka-solon-cloud-plugin](https://solon.noear.org/article/157)                                                     |
|          | 网关           | [solon-cloud-gateway（国产）](https://solon.noear.org/article/804)                                                                                                                                                      |
|          | 分布式锁       | 默认集成Redisson，需要自定义时实现`io.gitee.zhangbinhub.acp.core.common.lock.DistributedLock`接口即可                                                                                                                   |
|          | 链路追踪       | [zipkin-solon-cloud-plugin](https://solon.noear.org/article/525)                                                                                                                                                        |
|          | 分布式任务调度 | [xxl-job（国产）](https://www.xuxueli.com/xxl-job/),[配置参考](https://gitee.com/xuxueli0323/xxl-job/blob/master/xxl-job-executor-samples/xxl-job-executor-sample-springboot/src/main/resources/application.properties) |

## 总体架构

![Architecture diagram](doc/images/Acp%20Admin%20Solon%20Cloud总体架构图.png)

#### 说明

- 各服务在 **Nacos** 上进行注册，**gateway-server** 和其他各个服务通过 **Nacos** 发现和查找目标服务进行访问
- 各服务在 **Solon Admin Server**（admin-server）上注册客户端，由其进行可视化监控
- **gateway-server** 通过 [GateWayConfigHandler](acp-admin-cloud/gateway-server/src/main/kotlin/io/gitee/zhangbinhub/admin/gateway/conf/GateWayConfigHandler.kt)
  监听 Nacos 配置中心的网关配置（`solon.cloud.gateway` 前缀），配置变更时自动增删路由及默认过滤器，实现**动态路由**，可据此扩展实现灰度发布
- **【依赖中间件 redis】 main-server** 通过 `sa-token-redisson` 将 **token** 存储至 **Redis**，实现分布式会话共享
- **【依赖中间件 kafka】** 发布和订阅 **Bus** 总线事件，通知各服务更新缓存
- **【依赖中间件 kafka】** 各服务通过 **kafka** 发送日志消息，**log-server** 从 **Kafka** 中消费消息并进行日志的统一记录
- **【依赖中间件 kafka、logstash、elasticsearch】** 日志收集：**logstash** 从 **Kafka** 中消费日志消息并存储到 **elasticsearch** 中
- **【可选 zipkin】** 链路追踪：各服务通过 `zipkin-solon-cloud-plugin` 上报链路数据至 **Zipkin**
- 需要进行防重请求的 controller 方法上增加注解 **io.gitee.zhangbinhub.acp.boot.annotation.AcpDuplicateSubmission**
  ，默认30秒过期
- 前后端交互 **HttpStatus Code** 说明

| HttpStatus | 描述              |
|------------|-------------------|
| 200        | 请求成功          |
| 201        | 资源创建成功      |
| 400        | 业务错误          |
| 401        | token（登录）失效 |
| 403        | 权限不足          |
| 404        | 找不到资源        |
| 500        | 系统异常          |

## 模块总览

```
acp-admin-solon
├── acp-admin-common                             ------- 公共模块：常量、基础依赖、数据库、资源服务等基础设施
│   ├── acp-admin-common-constant                ------- 全局静态常量
│   ├── acp-admin-common-dependencies            ------- 基础依赖（ACP平台依赖 + 脱敏工具 + DTO/VO + 服务接口）
│   ├── acp-admin-common-db                      ------- 数据库基础（MyBatis-Flex 通用 Repository/Service）
│   ├── acp-admin-common-resource-server         ------- 单机版统一认证资源服务基础
│   ├── acp-admin-common-cloud                   ------- 微服务基础（Nami客户端 + Cloud实现 + 总线事件）
│   └── acp-admin-common-cloud-resource-server   ------- 微服务统一认证资源服务基础
├── acp-admin-modules                            ------- 业务逻辑模块：不含启动入口，由启动器聚合
│   ├── acp-admin-bus                            ------- 外部对接模块
│   ├── acp-admin-log                            ------- 日志模块（登录/操作/路由日志）
│   ├── acp-admin-main                           ------- 主模块（用户/机构/角色/菜单/权限等）
│   └── acp-admin-workflow                       ------- 工作流模块（warm-flow）
├── acp-admin-cloud                              ------- 微服务版启动器（基于 Solon Cloud）
│   ├── admin-server                             ------- 监控服务（Solon Admin）
│   ├── bus-server                               ------- 外部对接服务
│   ├── gateway-server                           ------- 网关服务（动态路由）
│   ├── log-server                               ------- 日志服务
│   ├── main-server                              ------- 主服务
│   └── workflow-server                          ------- 工作流服务
├── acp-admin-server                             ------- 单机版启动器（基于 Solon Boot，聚合全部业务模块）
├── deploy                                       ------- 部署脚本（docker / k8s / 初始化SQL）
├── doc                                          ------- 文档
├── gradle                                       ------- gradle脚本
└── script                                       ------- 应用启停脚本
```

#### 模块依赖关系

```
                         ┌────────────────────── 启动器 ──────────────────────┐
                         │                                                    │
     单机版 acp-admin-server                        微服务版 acp-admin-cloud
     （common-resource-server                        admin-server   ← common-cloud
       + log + main + workflow）                     gateway-server ← common-cloud
                         │                          log-server     ← common-cloud-resource-server + acp-admin-log
                         │                          main-server    ← common-cloud-resource-server + acp-admin-main
                         │                          bus-server     ← common-cloud-resource-server + acp-admin-bus
                         │                          workflow-server← common-cloud-resource-server + acp-admin-workflow
                         ▼                                                    ▼
    ┌──────────────────────── 逻辑模块 acp-admin-modules ─────────────────────────┐
    │  acp-admin-log / acp-admin-bus / acp-admin-main / acp-admin-workflow       │
    │  （均依赖 acp-admin-common-db + acp-admin-common-resource-server）          │
    └────────────────────────────────────────────────────────────────────────────┘
                                        │
    ┌───────────────────── 公共模块 acp-admin-common ─────────────────────────────┐
    │  constant ← dependencies ← db                                              │
    │                ├──← resource-server ←─ cloud-resource-server ← cloud       │
    │                └──← cloud                                                  │
    └────────────────────────────────────────────────────────────────────────────┘
```

各模块的详细说明请查看：

| 分组           | 说明文档                                                   | 内容                                          |
|----------------|------------------------------------------------------------|-----------------------------------------------|
| 公共模块       | [acp-admin-common/README.md](acp-admin-common/README.md)   | 常量、基础依赖、数据库、资源服务等 6 个子模块 |
| 逻辑模块       | [acp-admin-modules/README.md](acp-admin-modules/README.md) | 日志、认证授权、工作流 3 个业务模块           |
| 微服务版启动器 | [acp-admin-cloud/README.md](acp-admin-cloud/README.md)     | admin/gateway/log/main/workflow 5 个服务      |
| 单机版启动器   | [acp-admin-server/README.md](acp-admin-server/README.md)   | 单进程整合全部业务功能                        |

## 一、环境要求

- JDK 21+
- Gradle 9.7+
- Kotlin 2.3+
- 微服务版另需中间件：Nacos、Redis（Valkey）、Kafka（详见[快速开始](#快速开始)）

## 快速开始

### 方式一：单机版（推荐快速体验）

单机版仅依赖数据库，单进程提供全部功能，详细说明见 [acp-admin-server/README.md](acp-admin-server/README.md)。

1. 克隆项目

```bash
git clone https://gitee.com/zhangbinhub/acp-admin-solon-cloud.git
cd acp-admin-solon
```

2. 准备 MySQL：创建数据库 `acp-admin-standalone`（字符集 utf8mb4），首次启动时必要资源数据会自动初始化

3. 编译打包

```bash
./gradlew :acp-admin-server:release
```

4. 启动应用（数据源可通过环境变量 `db_url`、`db_username`、`db_password` 覆盖）

```bash
java -jar release/acp-admin-server/acp-admin-server-2.4.0.jar
```

5. 访问服务

- API 文档：http://localhost:8771/doc.html （basic 认证，默认 admin/888888）

### 方式二：微服务版

微服务版依赖 Nacos、Redis、Kafka 等中间件，详细说明见 [acp-admin-cloud/README.md](acp-admin-cloud/README.md)。

1. 克隆项目（同上）

2. 启动中间件：依次进入中间件目录并启动

```bash
cd deploy/docker/middleware
docker compose up -d

cd ../elk
docker compose up -d
```

3. 初始化 Nacos 配置

- 访问 Nacos 控制台：http://localhost:8080/nacos （默认账号 nacos/nacos）
- 导入配置文件：将 [doc/nacos_config_export_dev.zip](doc/nacos_config_export_dev.zip) 导入 Nacos 配置中心
- 修改 Redis、Kafka 等中间件连接地址为实际地址
- 公共配置样例见 [doc/atom-server-common-dev.yaml](doc/atom-server-common-dev.yaml)

4. 编译构建

```bash
./gradlew build
```

5. 启动服务：建议按以下顺序启动各服务

| 顺序 | 服务              | 默认端口 | 说明                     |
|------|-------------------|----------|--------------------------|
| 1    | `admin-server`    | 9099     | 监控服务（Solon Admin）  |
| 2    | `gateway-server`  | 8771     | 网关服务（对外统一入口） |
| 3    | `log-server`      | 8982     | 日志服务                 |
| 4    | `main-server`     | 8983     | 统一认证服务             |
| 5    | `bus-server`      | 8984     | 外部对接服务             |
| 6    | `workflow-server` | 8985     | 工作流服务               |

6. 访问服务

- API 文档（经网关）：http://localhost:8771/doc.html
- Solon Admin 监控面板：http://localhost:9099 （basic 认证，默认 admin/888888）

## 二、gradle 脚本配置及使用

### （一）配置文件

##### 1.[gradle/application.gradle](gradle/application.gradle)

应用模块公共配置（release 输出、OCI 镜像构建等）

##### 2.[gradle/commonTask.gradle](gradle/commonTask.gradle)

公共自定义任务配置，适用于所有项目模块

##### 3.[gradle/libs.versions.toml](gradle/libs.versions.toml)

定义外部依赖版本号

##### 4.[gradle/globalTask.gradle](gradle/globalTask.gradle)

全局自定义任务（批量发布、批量打包镜像等）

##### 5.[gradle/publishJar.gradle](gradle/publishJar.gradle)

发布任务配置，适用于所有项目模块

##### 6.[settings.gradle](settings.gradle)

定义项目/模块结构

##### 7.[project.properties](project.properties)

gradle全局参数：

- gradleVersion：gradle版本号
- group：对应打包时的最外层groupid，最终的groupid还会加上模块路径，例如`groupid.acp.core`
- version：版本号
- encoding：编译字符集
- mavenCentralUrl：maven中央仓库地址
- javaVersion：jdk版本号

##### 8.[build.gradle](build.gradle)

公共构建脚本

### （二）自定义任务

- 全局自定义任务
    - publishAll 发布所有构建至maven中央仓库
    - publishToMavenLocalAll 发布所有构建至maven本地仓库
    - buildImageAll 所有模块打包镜像（Dockerfile模式）
    - bootBuildImageAll 所有模块打包镜像（Boot模式）
- 公共自定义任务
    - clearPj 清理所有输出文件
    - release 编译、打包并输出
        - 如需编译打包对应环境，命令中使用参数```active```，例如
          ```
          gradlew project:release -Pactive=test
          ```
    - buildImage 通过```Dockerfile```打包镜像
    - pushImage 通过```Dockerfile```打包镜像并上传
    - buildAndSaveImage 打包镜像并导出为 tar 文件

> 镜像构建任务基于 **podman** 命令执行，镜像仓库地址在 [project.properties](project.properties) 的 `imagePushUrl` 中配置

### （三）发布至maven仓库

##### 1、发布至本地仓库

- 执行 publishToMavenLocal 任务
    - publishToMavenLocalAll

##### 2、发布至私服

- 项目根路径下创建 gradle.properties 并添加如下参数（参数值根据实际情况修改）

```
mavenUploadUrlRelease=https://maven.com/repositories/releases/
mavenUploadUrlSnapshot=https://maven.com/repositories/snapshot/
mavenUserName=username
mavenPassword=password
```

- 执行 publish 任务
    - publishAll

##### 3、发布至中央仓库

- 项目根路径下创建 gradle.properties 并添加如下参数（参数值根据实际情况修改）

```
mavenUploadUrlRelease=https://maven.com/repositories/releases/
mavenUploadUrlSnapshot=https://maven.com/repositories/snapshot/
mavenUserName=username
mavenPassword=password
signing.keyId=shortId
signing.password=keyPassword
signing.secretKeyRingFile=keyFile
```

- 执行 publish 任务
    - publishAll

### （四）升级命令

```
gradlew wrapper --gradle-distribution-url=https://mirrors.cloud.tencent.com/gradle/gradle-9.7.1-all.zip
```

## 三、工程说明

- 工程全局默认使用 UTF-8 字符集
- 工程结构见[模块总览](#模块总览)
- deploy 部署文件
    - nacos数据库初始化脚本 [nacos-mysql-3.2.sql](deploy/init/nacos-mysql-3.2.sql)
    - [docker部署](deploy/docker/README.md)
    - [k8s部署](deploy/k8s-demo/README.md)
- swagger url : /doc.html

## 四、启停 Solon 应用

- [启停脚本模板(Linux)](script/server.model)
- [启停脚本(windows)](script/server.bat)：根据实际情况修改第9行需要执行的 jar 名称，和 Solon 应用的 .jar
  放在同一路径下
- windows：修改[server.bat](script/server.bat)内相关参数后，直接运行即可
- Linux 命令：

| 命令                | 描述             |
|---------------------|------------------|
| ./server.sh         | 查看可用参数     |
| ./server.sh status  | 查看系统运行状态 |
| ./server.sh start   | 启动应用         |
| ./server.sh stop    | 停止应用         |
| ./server.sh restart | 重启应用         |

## 五、基础中间件环境搭建（docker）

中间件包括：MySQL、Nacos、Redis（Valkey）+ RedisInsight、Kafka（3节点）+ Kafka UI、Zipkin、xxl-job-admin、ELK（Elasticsearch + Logstash + Kibana）

- 启动服务

命令模式依次进入```deploy/docker/middleware deploy/docker/elk```目录，执行启动命令

```
docker compose up -d
```

- 停止服务

```
docker compose stop
```

- 停止并删除容器实例

```
docker compose down
```

常用中间件访问地址：

| 中间件        | 地址                                | 说明                 |
|---------------|-------------------------------------|----------------------|
| Nacos 控制台  | http://localhost:8080/nacos         | 默认账号 nacos/nacos |
| Kafka UI      | http://localhost:8989               | -                    |
| Zipkin        | http://localhost:9411               | -                    |
| xxl-job-admin | http://localhost:8093/xxl-job-admin | -                    |

## 六、系统初始化

### （一）数据库

- 服务首次启动时，必要资源数据会自动进行初始化

## 七、认证授权

- 认证协议、Token 获取方式及方法级权限注解说明见 [oauth认证](doc/auth/oauth认证.md)
- 提供客户端应用管理、用户管理、机构管理、角色管理、菜单及功能权限管理、token管理、字典配置管理等全套权限体系，详见 [acp-admin-modules/README.md](acp-admin-modules/README.md)

## 八、[公共配置信息](doc/atom-server-common-dev.yaml)

微服务版各服务从 Nacos 配置中心加载公共配置 `atom-server-common-{env}.yaml` 及各服务专属配置 `{server-name}-{env}.yaml`

## 九、环境变量及启动参数

| 变量名              | 描述                       | 默认值                                              | 说明                                                                                                                                                                                                        |
|---------------------|----------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| JAVA_TOOL_OPTIONS   | JVM启动参数                |                                                     | 该环境变量在容器部署时使用                                                                                                                                                                                  |
| acp_profile_active  | 激活的配置环境             | dev                                                 | 服务器部署时建议java启动命令加入参数 -Dacp_profile_active 或 --acp_profile_active；容器部署时指定环境变量即可                                                                                               |
| acp_server_port     | 服务启动端口               |                                                     | 服务器部署时建议java启动命令加入参数 -Dacp_server_port 或 --acp_server_port；容器部署时指定环境变量即可。服务不需要外部直接访问时，建议保持默认值。注：admin-server默认值：9099，gateway-server默认值：8771 |
| acp_admin_token     | solon admin client请求令牌 | 3C41D632-A070-060C-40D2-6D84B3C07094                | 各服务（admin client）连接 solon admin server 获取应用信息时的身份令牌，在 Nacos 公共配置中下发                                                                                                             |
| acp_admin_password  | solon admin server密码     | 888888                                              | solon admin server 监控面板（admin-server）basic 认证密码，用户名 admin                                                                                                                                     |
| acp_nacos_addr      | nacos地址                  | 127.0.0.1:8848                                      | nacos服务地址，ip:port                                                                                                                                                                                      |
| acp_nacos_username  | nacos用户名                | nacos                                               | nacos用户名，默认nacos，可自行在nacos管理端添加用户                                                                                                                                                         |
| acp_nacos_password  | nacos密码                  | nacos                                               | nacos用户密码，默认nacos，可自行在nacos管理端添加用户                                                                                                                                                       |
| acp_nacos_namespace | nacos命名空间              | acp-solon-cloud-admin                               | nacos命名空间，默认nacos，可自行在nacos管理端配置                                                                                                                                                           |
| db_url              | 数据库连接（单机版）       | jdbc:mysql://127.0.0.1:3306/acp-admin-standalone... | 单机版启动器 acp-admin-server 的数据源连接串                                                                                                                                                                |
| db_username         | 数据库用户名（单机版）     | root                                                | 单机版启动器 acp-admin-server 的数据源用户名                                                                                                                                                                |
| db_password         | 数据库密码（单机版）       | test                                                | 单机版启动器 acp-admin-server 的数据源密码                                                                                                                                                                  |
| knife4j_username    | API文档用户名              | admin                                               | Knife4j basic 认证用户名（微服务版在 Nacos 公共配置中下发）                                                                                                                                                 |
| knife4j_password    | API文档密码                | 单机版：888888；微服务版：changeme                  | Knife4j basic 认证密码                                                                                                                                                                                      |

## 十、打包OCI镜像

- 单个模块
    - 打包：`buildImage`
    - 打包并导出：`buildAndSaveImage`
    - 打包并上传：`pushImage`
- 批量
    - 打包：`buildImageAll`
    - 打包并上传：`pushImageAll`

## 十一、容器部署

- [docker 部署](deploy/docker/README.md)
- [k8s 部署](deploy/k8s-demo/README.md)

## 贡献指南

### 提交代码

1. Fork 本项目到你的仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -m 'feat: add your feature'`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request

### 提交规范

- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整（不影响功能）
- `refactor`: 代码重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具链变更

### 开发约定

- 遵循 Kotlin 官方编码规范
- 新增功能需附带对应的单元测试
- 提交前确保 `./gradlew build` 通过
- PR 描述需清晰说明变更内容和影响范围