# SLMS 四端应用打包工具配置指南

**Smart Library Management System - Multi-Application Package Tools Guide**

本文档提供 SLMS 四端应用（CLI、GUI、Web、Android）打包所需工具的详细安装步骤、配置方法和验证流程。

**四端应用说明**:
- **CLI 应用**: 命令行界面，打包为 JAR
- **GUI 应用**: 图形界面（JavaFX），打包为 JAR/EXE/MSI
- **Web 应用**: Spring Boot Web，打包为 WAR
- **Android 应用**: 移动端，打包为 APK

**相关文档**:
- `SLMS_MultiAPP_Package.xml`: Maven 打包配置（CLI/GUI/Web）
- `ATM流水线.md`: CI/CD 流水线配置文档
- `Jenkinsfile`: Jenkins 自动化构建脚本

---

## 一、CLI 应用打包 (JAR)

### 所需工具
- ✅ JDK 21
- ✅ Maven 3.9+

### 验证命令
```bash
java -version
mvn -version
```

### 测试打包
```bash
mvn clean package -P cli -DskipTests
```

**预期输出**: `target/slms-cli.jar`

---

## 二、GUI 应用打包 (EXE/MSI)

### 所需工具
1. **JDK 21** (包含 jpackage)
2. **WiX Toolset 3.11+** (用于生成 MSI)

### 2.1 安装 WiX Toolset

#### 下载
- 官网: https://wixtoolset.org/releases/
- 推荐版本: WiX Toolset 3.11.2
- 下载文件: `wix311.exe`

#### 安装步骤
1. 运行 `wix311.exe`
2. 选择安装路径: `C:\Program Files (x86)\WiX Toolset v3.11`
3. 完成安装

#### 配置环境变量
```bash
# 添加到系统 PATH
C:\Program Files (x86)\WiX Toolset v3.11\bin
```

**重启命令行窗口**使环境变量生效。

### 2.2 验证安装

```bash
# 验证 jpackage
jpackage --version

# 验证 WiX
candle.exe -?
light.exe -?
```

### 2.3 测试打包

#### 打包为 EXE
```bash
# 先打包 JAR
mvn clean package -P gui -DskipTests

# 使用 jpackage 打包为 EXE
jpackage --input target ^
         --name SLMS-GUI ^
         --main-jar slms-gui.jar ^
         --type exe ^
         --win-console ^
         --dest target
```

**预期输出**: `target/SLMS-GUI.exe`

#### 打包为 MSI
```bash
jpackage --input target ^
         --name SLMS-GUI ^
         --main-jar slms-gui.jar ^
         --type msi ^
         --win-console ^
         --dest target
```

**预期输出**: `target/SLMS-GUI.msi`

---

## 三、Web 应用打包 (WAR)

### 所需工具
- ✅ JDK 21
- ✅ Maven 3.9+
- ✅ Spring Boot (已在 pom.xml 中配置)

### 验证命令
```bash
mvn -version
```

### 测试打包
```bash
mvn clean package -P web -DskipTests
```

**预期输出**: `target/slms-web.war`

---

## 四、Android 应用打包 (APK)

### 所需工具
1. **JDK 21**
2. **Android SDK**
3. **Gradle 8.5+**

### 4.1 安装 Android SDK

#### 方法一：通过 Android Studio
1. 下载 Android Studio: https://developer.android.com/studio
2. 安装并打开 Android Studio
3. 通过 SDK Manager 安装:
   - Android SDK Platform 34
   - Android SDK Build-Tools 34.0.0
   - Android SDK Command-line Tools

#### 方法二：命令行工具
1. 下载 Command Line Tools: https://developer.android.com/studio#command-tools
2. 解压到: `D:\development\Android\cmdline-tools`
3. 使用 sdkmanager 安装组件:
```bash
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
```

### 4.2 配置环境变量

```bash
# 设置 ANDROID_HOME
ANDROID_HOME=D:\development\Android

# 添加到 PATH
%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\cmdline-tools\latest\bin
```

### 4.3 生成签名密钥

```bash
# 创建密钥存储目录
mkdir android\keystore

# 生成签名密钥
keytool -genkey -v ^
        -keystore android\keystore\slms-release.jks ^
        -keyalg RSA ^
        -keysize 2048 ^
        -validity 10000 ^
        -alias slms-key
```

**记录密钥信息**:
- Keystore 密码: `your-store-password`
- Key 别名: `slms-key`
- Key 密码: `your-key-password`

### 4.4 配置 Gradle 签名

编辑 `android/build.gradle`:

```gradle
android {
    signingConfigs {
        release {
            storeFile file("keystore/slms-release.jks")
            storePassword "your-store-password"
            keyAlias "slms-key"
            keyPassword "your-key-password"
        }
    }
    
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}
```

### 4.5 验证安装

```bash
# 验证 Android SDK
echo %ANDROID_HOME%

# 验证 Gradle
cd android
gradlew --version
```

### 4.6 测试打包

```bash
cd android

# 打包 Debug 版本
gradlew assembleDebug

# 打包 Release 版本（需要签名）
gradlew assembleRelease
```

**预期输出**:
- Debug: `android/build/outputs/apk/debug/android-debug.apk`
- Release: `android/build/outputs/apk/release/android-release.apk`

---

## 五、Jenkins 环境配置

### 5.1 配置全局环境变量

1. 进入 Jenkins: `http://localhost:8084`
2. `Manage Jenkins` → `Configure System`
3. 找到 `Global properties`
4. 勾选 `Environment variables`
5. 添加以下变量:

```
JAVA_HOME = E:\2025-2026\GitAIOps\jdk
ANDROID_HOME = D:\development\Android
WIXSHARP_WIXDIR = C:\Program Files (x86)\WiX Toolset v3.11\bin
```

### 5.2 创建验证 Pipeline

在 Jenkins 中创建测试任务验证所有工具：

```groovy
pipeline {
    agent any
    
    stages {
        stage('验证打包工具') {
            steps {
                bat '''
                    echo ========== 验证 Java ==========
                    java -version
                    javac -version
                    
                    echo ========== 验证 Maven ==========
                    mvn -version
                    
                    echo ========== 验证 jpackage ==========
                    jpackage --version
                    
                    echo ========== 验证 WiX Toolset ==========
                    candle.exe -?
                    light.exe -?
                    
                    echo ========== 验证 Gradle ==========
                    cd android
                    gradlew --version
                    cd ..
                    
                    echo ========== 验证 Android SDK ==========
                    echo %ANDROID_HOME%
                    dir "%ANDROID_HOME%"
                    
                    echo ========== 所有工具验证完成 ==========
                '''
            }
        }
    }
}
```

---

## 六、完整验证清单

### 验证步骤

- [ ] **JDK 21 已安装**
  ```bash
  java -version
  # 输出: openjdk version "21.x.x"
  ```

- [ ] **Maven 已安装**
  ```bash
  mvn -version
  # 输出: Apache Maven 3.9.x
  ```

- [ ] **jpackage 可用**
  ```bash
  jpackage --version
  # 输出: 21.x.x
  ```

- [ ] **WiX Toolset 已安装**
  ```bash
  candle.exe -?
  light.exe -?
  # 输出: WiX 工具帮助信息
  ```

- [ ] **Android SDK 已配置**
  ```bash
  echo %ANDROID_HOME%
  # 输出: D:\development\Android
  ```

- [ ] **Gradle 可用**
  ```bash
  cd android
  gradlew --version
  # 输出: Gradle 8.5
  ```

- [ ] **Android 签名密钥已生成**
  ```bash
  dir android\keystore\slms-release.jks
  # 文件存在
  ```

- [ ] **Jenkins 环境变量已配置**
  - JAVA_HOME
  - ANDROID_HOME
  - WIXSHARP_WIXDIR

- [ ] **本地测试打包成功**
  - CLI JAR: ✅
  - GUI JAR: ✅
  - GUI EXE: ✅
  - Web WAR: ✅
  - Android APK: ✅

---

## 七、常见问题

### 问题 1: jpackage 命令找不到

**原因**: JDK 版本低于 14 或 PATH 未配置

**解决**:
```bash
# 确认 JDK 版本
java -version

# 确认 jpackage 路径
where jpackage

# 如果找不到，添加到 PATH
%JAVA_HOME%\bin
```

### 问题 2: WiX 工具找不到

**原因**: WiX 未安装或 PATH 未配置

**解决**:
```bash
# 检查安装路径
dir "C:\Program Files (x86)\WiX Toolset v3.11\bin"

# 添加到 PATH
C:\Program Files (x86)\WiX Toolset v3.11\bin
```

### 问题 3: Android SDK 找不到

**原因**: ANDROID_HOME 未设置

**解决**:
```bash
# 设置环境变量
setx ANDROID_HOME "D:\development\Android"

# 重启命令行窗口
```

### 问题 4: Gradle 构建失败

**原因**: Gradle 版本不兼容或依赖下载失败

**解决**:
```bash
# 清理 Gradle 缓存
cd android
gradlew clean

# 重新构建
gradlew assembleDebug --refresh-dependencies
```

---

## 八、下一步

完成所有工具安装和验证后：

1. ✅ 更新 `pom.xml` 添加 profiles 配置
2. ✅ 配置 `android/build.gradle` 签名信息
3. ✅ 提交 `Jenkinsfile` 到仓库
4. ✅ 推送到 Gitea 触发 Jenkins 构建
5. ✅ 查看 Jenkins 构建日志验证四端打包

---

**文档版本**: 1.0  
**最后更新**: 2025-11-20  
**维护者**: SLMS 开发团队