# 移动端编译

移动端分两层：**H5 客户端**（终端镜像 + 遥控界面）与承载它的**安卓 WebView 壳**（APK）。同一份 H5 也被桌面网关与中继直接托管，因此用手机浏览器不装 App 也能用。

## H5：源文件与生成物

- `mobile-src.html`：**源文件**，引用 CDN 上的 xterm。可编辑。
- `mobile-test.html`：把 CDN 引用替换为 `vendor/` 下本地副本后生成的**自包含单文件**（离线可用）。它被三处复用：
  - 桌面后端 `include_str!` 内嵌；
  - 安卓工程作为 `assets/mobile.html` 内置；
  - 中继作为 `mobile.html` 托管。
  它是生成物，**不要直接编辑**。

### 生成 mobile-test.html
```
# PowerShell（项目根）
./build-mobile-html.ps1
```
脚本把 mobile-src.html 里的 5 个 CDN 引用（xterm 及 fit/webgl/unicode11 插件）内联为 `vendor/` 本地内容，输出 `mobile-test.html`，并打印剩余外部引用数（应为 0）。

## 安卓 APK

WebView 壳工程在 `android/`：单 Activity + WebView，加载内置的 `assets/mobile.html`（通过 WebViewAssetLoader 以 https 源加载，兼容连中继 wss:// 与直连局域网 ws://）。

### 依赖安装
- **JDK 17**（设 `JAVA_HOME` 指向其安装目录）
- **Android SDK**，compileSdk 34（用 Android Studio 或 cmdline-tools 安装）
- **Gradle 8.x**（8.7 实测通过）：设 `GRADLE_HOME`（其 `bin/gradle.bat` 存在），或让 PATH 中已有 `gradle`
- **Windows PowerShell**（运行一键脚本）

### 配置本机 SDK 路径（不入库）
`android/local.properties`：复制 `local.properties.example` 为 `local.properties`，把 `sdk.dir` 改成本机 Android SDK 路径（如 `sdk.dir=D\:\\Android\\Sdk`）。

### 签名
签名配置由 `android/keystore.properties` 提供（该文件与 `.jks` 密钥库均**不入库**，模板见 `keystore.properties.example`）：

要用你自己的密钥：先生成密钥库
```
keytool -genkeypair -v -keystore android/ccgui.jks -storetype JKS ^
  -keyalg RSA -keysize 2048 -validity 36500 -alias ccgui
```
再复制 `android/keystore.properties.example` 为 `android/keystore.properties`，按实际填写 `storeFile`（路径相对 `android/app`）与口令、别名。之后 `assembleRelease` 即出 release 签名包。

不配 `keystore.properties` 也能构建：`release` 自动回退 debug 签名（开箱可跑，仅供自测，不要对外分发）。

> 安全提醒：`.jks` 与 `keystore.properties` 已在 `.gitignore` 忽略，请勿 `git add -f` 强制提交。

### 一键出包
```
# PowerShell（项目根）：重建 H5 → 拷入 assets → Gradle 打包 → 拷到 out/
./build-android.ps1
```
产物：`out/CCGUI-mobile-<版本>.apk`（out/ 不入库）。版本号自动跟随 `package.json`（`versionName` 取版本串，`versionCode = major×10000 + minor×100 + patch`）。

也可手动构建：
```
gradle -p android assembleRelease -PappVersionName=1.0.0 -PappVersionCode=10000
```
产物在 `android/app/build/outputs/apk/release/`。

## 编译好之后怎么用

手机端的配对、连接与操作见 [docs/05-移动端-使用.md](05-移动端-使用.md)。
