# 百利工程助手 · APP 打包指南

> 本文档面向首次部署同学。工程已基于 uni-app Vue3 + Vite 完成，H5 产物已构建，
> 后续如需打包成 Android APK，按下列步骤操作即可。

---

## 一、工程位置与产物

| 项 | 路径 |
| --- | --- |
| 工程源码 | `D:\百利电子的云文档\APP开发\百利工程助手\app\` |
| H5 产物（已构建） | `D:\百利电子的云文档\APP开发\百利工程助手\app\dist\build\h5\` |
| 后端 API 地址 | `http://api.bailitech.com`（在 `app/src/utils/request.js` 的 `API_BASE` 常量中，可改） |

---

## 二、H5 本地预览 / 部署

H5 产物是纯静态文件，可放到任意 Web 服务器根目录。

### 2.1 本地快速预览

在 `app\dist\build\h5\` 目录下起一个临时静态服务：

```powershell
cd "D:\百利电子的云文档\APP开发\百利工程助手\app\dist\build\h5"
python -m http.server 8080
```

浏览器打开 `http://localhost:8080` 即可。

> 产物内资源路径已经配置为相对路径（`./assets/...`），
> 因此放在任意子目录（如 `http://xxx.com/app/`）都能正常加载。

### 2.2 部署到正式环境

把 `dist\build\h5\` 目录整个上传到 Web 服务器（Nginx / Apache / 宝塔面板均可）的网站根目录，
确保 `index.html` 可直接访问即可。

> ⚠️ 跨域提示：APP 内 H5 直接请求 `http://api.bailitech.com`，需后端已配置 CORS，
> 或 H5 与 API 同域（推荐通过 Nginx 反向代理，把 `/api/` 转发到后端）。

---

## 三、开发调试（HBuilderX 方式）

### 3.1 安装 HBuilderX

1. 下载地址：<https://www.dcloud.io/hbuilderx.html>
2. 选 **App 开发版**（标准版不含云打包所需插件）。
3. 安装后用 DCloud 账号登录（首次云打包必须登录）。

### 3.2 打开工程

1. 启动 HBuilderX → `文件` → `打开目录` → 选择
   `D:\百利电子的云文档\APP开发\百利工程助手\app\`
2. 等待 HBuilderX 识别为 uni-app 工程（项目图标会变成 uni-app 标识）。

### 3.3 配置 AppID

打开 `src/manifest.json` → 「基础配置」 → 「DCloud AppID」：

- 首次使用点 **「重新获取」**，HBuilderX 会自动注册一个 AppID 并填回。
- 命令行工程打包时，`appid` 字段必须非空，云打包才会受理。

### 3.4 运行到浏览器（调试 H5）

菜单栏：`运行` → `运行到浏览器` → `Chrome`。
等同于命令行 `npm run dev:h5`，热更新，便于前端调试。

---

## 四、云打包 Android APK（HBuilderX 一键云打包）

> 云打包由 DCloud 服务器完成，本机无需安装 Android Studio / SDK。
> 需要联网，且 HBuilderX 已登录 DCloud 账号。

### 4.1 菜单入口

1. HBuilderX 顶部菜单：`发行` → `原生App-云打包`。
2. 在弹出窗口中选 `Android`。
3. 证书选项：
   - **首次打包**：选「使用 DCloud 公共证书」（测试用，正式上架需自建证书，见第五节）。
   - 正式发布：选「使用自有证书」，上传 `.keystore` 文件并填写别名、密码。
4. 点「打包」，等待 3~10 分钟。

### 4.2 下载产物

打包完成后，HBuilderX 控制台会给出 APK 下载链接；同时 DCloud 账号后台
（<https://dev.dcloud.net.cn>）也能在「应用管理 → 打包记录」里下载。

### 4.3 安装到手机

1. 把 APK 传到手机（微信/QQ/USB）。
2. 手机允许「安装未知来源应用」后点击安装。
3. 首次打开会请求相机、相册权限（拍照上传施工日志需要）。

---

## 五、Android 签名证书（正式发布必看）

### 5.1 为什么需要证书

- 同一个 App 后续升级必须使用**同一把签名证书**，否则系统拒绝覆盖安装。
- 应用市场上架（华为/小米/OPPO 等）也要求提供正式签名。
- DCloud 公共证书仅用于测试，**不可用于上架**。

### 5.2 生成自己的 keystore

本机已装 JDK（HBuilderX 自带），在 PowerShell 中执行：

```powershell
keytool -genkey -alias baili_project -keyalg RSA -keysize 2048 -validity 36500 -keystore baili.keystore
```

按提示输入：
- keystore 密码（请妥善保管，遗忘无法找回）
- 姓名、组织、城市等信息（可随意填，但建议真实）
- 别名密码（可与 keystore 密码一致）

生成的 `baili.keystore` 文件请**离线备份**，永久保留。

### 5.3 在云打包中使用

`发行` → `原生App-云打包` → Android → `使用自有证书`：
- 证书文件：选 `baili.keystore`
- 证书别名：`baili_project`
- 证书密码 / 别名密码：上面设置的两个密码

---

## 六、常见问题

| 现象 | 处理 |
| --- | --- |
| 云打包报「AppID 未配置」 | 按 3.3 节在 manifest.json 中重新获取 AppID |
| APP 打开后登录提示网络错误 | 检查 `utils/request.js` 中 `API_BASE` 是否可达；Android 9+ 默认禁止明文 HTTP，需在 manifest.json → app-plus → distribute → android 中开 `usesCleartextTraffic`，或把 API 升级为 HTTPS |
| 拍照上传失败 | 确认 manifest.json 已申请相机、存储权限（本工程默认已包含 CAMERA / WRITE_SETTINGS 等） |
| H5 在手机浏览器打开白屏 | 确认服务器已把 `dist/build/h5` 整个目录部署，且 `index.html` 与 `assets/` 同级 |
| 想改成 https API | 改 `src/utils/request.js` 顶部 `API_BASE` 常量，重新 `npm run build:h5` 或重新云打包 |

---

## 七、后续命令行打包（可选）

如果不想用 HBuilderX，也可在命令行直接云打包（需先装 `cli` 并登录）：

```powershell
cd "D:\百利电子的云文档\APP开发\百利工程助手\app"
npm run build:app-plus       # 生成 App 资源
# 然后用 HBuilderX 打开 unpackage/dist/build/app-plus 目录，发行 → 云打包
```

> 当前官方推荐仍以 HBuilderX 云打包为主，命令行云打包需配合 `cli` 登录 token，步骤略繁琐，
> 首次发布建议直接用第四节的 HBuilderX 图形界面流程。