# mobile-uni 原生 App 打包

`mobile-uni/` 采用 uni-app Vue 3 的 App-Plus 目标，同时保留 H5。App 不是将线上 H5 包进 WebView；前端资源通过 `npm --prefix mobile-uni run build:app` 编译，再由 HBuilderX 的自定义基座或云端打包生成 Android/iOS 原生安装包。

## 当前约定

- Android applicationId 与 iOS Bundle ID 预设为 `com.yincheng.wygj`。在首次签名或注册 App ID 前，发布负责人必须确认企业实际拥有该标识；变更时 Android、iOS 必须同步修改。
- App 直接请求 `https://peilian.njzhmj.top/dev-api`。不依赖 H5 开发服务器的 `/dev-api` proxy；地址是公开配置，不得在 App 包中放入短信、模型、签名或任何服务端密钥。
- `manifest.json` 只保留不含秘密的发布配置。`.keystore`、`.p12`、`.mobileprovision` 与证书密码只能由发布负责人在 HBuilderX 云打包界面或受控 CI 秘密变量中提供，绝不能提交 Git。
- Android 最低试点设备为 Android 10，iOS 最低试点设备为 iOS 15；每次发版提升 `versionCode`，再更新 `versionName`。
- 当前编译链与本机 HBuilderX 5.22 对齐：GUI 产品版本为 `5.22.2026071707`，`D:\HBuilderX\cli.exe version` 返回 `5.22.2026072503-alpha`；`@dcloudio/uni-app`、`@dcloudio/uni-app-plus`、`@dcloudio/uni-h5`、`@dcloudio/vite-plugin-uni` 均固定为 `3.0.0-alpha-5020220260725001`。这是 HBuilderX/uni-app 编译器版本，不是 Android `minSdkVersion`。
- 四个 DCloud 编译包必须保持同一批次；否则 npm 版 uni-ui 的 easycom 解析可能落入不同的 `uni-cli-shared` 实例，表现为 `<uni-forms>`、`<uni-easyinput>` 等组件无法解析。

## 本地验证与出包

```bash
npm --prefix mobile-uni run generate:app-assets
npm --prefix mobile-uni run verify:app-assets
npm --prefix mobile-uni run typecheck
npm --prefix mobile-uni run build:h5
npm --prefix mobile-uni run build:app
```

1. 用 HBuilderX 打开 `mobile-uni`，先生成 Android/iOS **自定义运行基座**。标准基座不会加载当前的包名、权限、启动图或原生配置。
2. 在真实 Android 与 iPhone 上验证手机号登录、录音并转写、TTS 播放、图片/视频/文件上传、附件下载、拒绝权限、前后台切换、刘海和底部安全区。
3. Android 试点使用企业签名的正式 APK；上架渠道按渠道要求导出相应制品。iOS 使用企业 Apple Developer 账号的 Distribution 证书和 provisioning profile，先走 TestFlight。

标准基座可用于日常 JavaScript/WebView 兼容性调试，但不能替代自定义基座或签名包的权限、图标、启动图和原生配置验收。

## 发布前尚需提供的资产

- 经法务确认并已可公开访问的《服务协议》《隐私政策》；Android 必须用该实际链接配置原生 template 隐私弹窗，iOS 需提供相应的麦克风、相机、相册/文件用途说明。
- 无透明通道的 1024×1024 App Store 图标，以及 Android 自适应图标/启动图。
- 企业持有的 Android 签名证书、Apple Team、Bundle ID 注册与 iOS 发布证书。上述资产缺失时可以完成代码与真机调试，不能声称已具备商店上架条件。

## 已接入的资产与隐私模板

- 图标和启动图由 `scripts/generate-app-assets.sh` 从现有 `src/static/brand-logo.png` 生成，输出位于 `src/static/app/`，并由 `manifest.json` 显式关联。iOS App Store 图标为 1024×1024、无 alpha、未预制圆角；生成后可用 `npm --prefix mobile-uni run verify:app-assets` 校验尺寸和映射。
- 现有品牌源图仅为 64×64，因此这里生成的是**可用于自定义基座和测试包的派生资产**。正式提交商店前应替换为品牌方提供的高分辨率母版，再重新执行生成和预检。
- `androidPrivacy.json.example` 是**未启用的法务模板**，其中 `__TERMS_URL__` 与 `__PRIVACY_URL__` 必须替换为法务确认的 HTTPS 地址。复制为被 Git 忽略的 `androidPrivacy.json` 后，`npm --prefix mobile-uni run verify:app-release` 才会通过。
- iOS 已按实际功能填写麦克风和照片库用途说明；不申请相机、定位、通讯录、蓝牙或广告追踪权限。
- `build:app` 依赖 `@dcloudio/uni-app-plus`，它必须与 `@dcloudio/uni-app`、`@dcloudio/uni-h5`、`@dcloudio/vite-plugin-uni` 同版本。缺少 App 编译器时命令**不报错**，只静默产出带 `/h5/` 基路径的 H5 空壳，产物里没有 `app-service.js` 与 `app-renderjs.js`，App 平台代码等于从未编译。判定 `build:app` 是否真的成功要看产物中是否存在 `app-service.js`、`app-renderjs.js`、`manifest.json`，不能只看 `DONE Build complete.`。
- App-Plus 实时对练通过 `renderjs` 在系统 WebView 中执行媒体/WebRTC；认证 SDP 与工具请求仍由逻辑层代理。发布前必须在 Android/iOS 真机验证麦克风授权、实时转写、远端语音播放、前后台切换和断线降级。
- 真机步骤和证据口径见 `docs/MOBILE_APP_DEVICE_ACCEPTANCE.md`。资源预检通过不等于 Android/iOS 真机或应用商店验收通过。

## 调试基座版本不匹配

若真机提示“本应用使用 HBuilderX X 或对应 CLI 版本编译，而手机端 SDK 版本是 Y”，先核对编译依赖与基座，不要修改 Android `minSdkVersion`：

```bash
node -e "for (const n of ['@dcloudio/uni-app','@dcloudio/uni-app-plus','@dcloudio/uni-h5','@dcloudio/vite-plugin-uni']) console.log(n, require('./mobile-uni/node_modules/'+n+'/package.json').version)"
```

Windows PowerShell 再核对 HBuilderX CLI 与设备；项目已导入 HBuilderX 且设备在线后，才执行最后一条运行命令：

```powershell
& 'D:\HBuilderX\cli.exe' version
& 'D:\HBuilderX\cli.exe' devices list --platform android
& 'D:\HBuilderX\cli.exe' launch app-android `
  --project (Resolve-Path '.\mobile-uni').Path --deviceId <adb-serial> `
  --playground standard --native-log true
```

标准基座可先验证编译器/SDK 兼容、启动和页面交互；完整权限验收必须先生成 5.22 自定义基座，再把上面的 `standard` 改为 `custom` 重跑。不要在真机运行命令中加 `--compile true`，该参数表示“只编译代码”，不会安装或启动手机端应用。

当前项目依赖已与 HBuilderX 5.22 统一；升级后必须重新生成并安装 5.22 自定义运行基座，旧的 5.15 基座不能继续用于真机验收。命令行资源构建通过只证明编译链可用，不等同于已完成真机基座验证。

## 更新策略

涉及原生权限、插件、证书或 App 壳的改动必须重新云打包并通过应用商店/TestFlight 发布。仅 JavaScript/CSS/静态资源的热更新（WGT）不作为首个试点版本的发布方式；如后续启用，须有版本兼容、完整性校验、灰度与回滚方案。