docs(mobile-app): sync native packaging guidance

2026-07-23 15:05:15 +08:00
parent 0f5c2e8667
commit 6a90fd977c
6 changed files with 13 additions and 4 deletions
@@ -8,7 +8,7 @@

 - `backend/` 是 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支检出。
 - `frontend/` 是 `CrazyLionCat/plus-ui` 的 `5.X` 分支检出，只承载管理端。
- `mobile-uni/` 是当前用户侧工程，承载员工端、候选人端、主管端，使用 uni-app Vue3 H5，后续便于转换 H5/APP/小程序；旧 `mobile/` 仅保留为 MVP 演示兜底，不再承载新增功能。
+- `mobile-uni/` 是当前用户侧工程，承载员工端、候选人端、主管端，使用 uni-app Vue3 H5 + App-Plus；原生资源、隐私/签名和真机门禁见 `docs/MOBILE_APP_PACKAGING.md`，旧 `mobile/` 仅保留为 MVP 演示兜底，不再承载新增功能。
 - 本项目自己的本地编排放在根目录：`docker-compose.dev.yml`、`scripts/`；运行说明在 `docs/DEV_SETUP.md`。
 - 除非确实要接业务模块，不要改上游框架默认配置；本地端口和开关优先放根目录脚本里覆盖。

@@ -42,6 +42,7 @@
 - 线上管理端：`https://peilian.njzhmj.top/`，Caddy 服务 `/opt/wygj/www`；该目录包含移动端 `/h5`，发布管理端时先备份整个目录，再 `rsync -az frontend/dist/ YCWY:/opt/wygj/www/`，**不得**对根目录使用 `--delete`。纯管理端静态修复不需要重启后端。
 - 线上移动端 H5：`https://peilian.njzhmj.top/h5/`，Caddy 服务 `/opt/wygj/www/h5`。
 - 只发布移动端静态资源时，用 `npm --prefix mobile-uni run build:h5` 后备份远端 `/opt/wygj/www/h5`，再 `rsync -az --delete mobile-uni/dist/build/h5/ YCWY:/opt/wygj/www/h5/`；前端静态修复不需要重启后端。
+- 原生 App 不复用 H5 静态发布流程；`npm --prefix mobile-uni run build:app` 仅生成 HBuilderX 出包资源，未提供法务 HTTPS 链接、签名或真机验收前不得称为已出包或上架。

 ## 当前业务边界

@@ -6,7 +6,7 @@

 - 后端：`backend`，来自 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支。
 - 管理端前端：`frontend`，来自 `CrazyLionCat/plus-ui` 的 `5.X` 分支。
- 用户侧前端：`mobile-uni`，uni-app Vue3 H5 工程，承接员工端、候选人端、主管端；旧 `mobile` 保留为 MVP 演示兜底。
+- 用户侧前端：`mobile-uni`，uni-app Vue3 H5 + App-Plus 工程，承接员工端、候选人端、主管端；旧 `mobile` 保留为 MVP 演示兜底。原生资源构建、签名边界和真机验收见 [原生 App 打包](docs/MOBILE_APP_PACKAGING.md)。
 - 本地依赖：MySQL + Redis + MinIO + Qdrant 由 `docker-compose.dev.yml` 启动。
 - 品牌：前端标题为“物业AI人力资源系统”，侧栏 logo 使用银城物业图标。
 - 基础链路：租户列表、验证码、`000000 / admin / admin123` 加密登录已验证。
@@ -34,7 +34,7 @@
 |---|---|
 | `backend/` | RuoYi-Vue-Plus 后端基座 |
 | `frontend/` | plus-ui 管理端前端基座 |
-| `mobile-uni/` | 当前用户侧 uni-app H5 工程 |
+| `mobile-uni/` | 当前用户侧 uni-app H5 + App-Plus 工程 |
 | `mobile/` | 旧移动端 H5，保留为 MVP 演示兜底 |
 | `scripts/` | 本地 MVP 启动与数据重置脚本 |
 | `docker-compose.dev.yml` | 本地 MySQL / Redis / MinIO / Qdrant |
@@ -50,6 +50,8 @@
 | [Figma 页面实现矩阵](docs/FIGMA_IMPLEMENTATION_MATRIX.md) | 70 张正式画板与代码/线上实现状态、二期边界和剩余动作 |
 | [Figma 与线上 H5 差异矩阵](docs/FIGMA_ONLINE_DELTA.md) | 线上真实页面与 Figma 目标的差异、调整顺序和验收口径 |
 | [本地运行手册](docs/DEV_SETUP.md) | 端口、账号、启动和基础验证 |
+| [原生 App 打包](docs/MOBILE_APP_PACKAGING.md) | Android/iOS 资源构建、隐私/签名边界和出包前置条件 |
+| [原生 App 真机验收](docs/MOBILE_APP_DEVICE_ACCEPTANCE.md) | Android/iOS 自定义基座或签名包的验收清单 |
 | [MVP 演示与验收清单](docs/DEMO_ACCEPTANCE.md) | MVP 演示脚本、录屏兜底和验收口径 |
 | [后端 API 对接指南](docs/API_INTEGRATION.md) | 后端模块落点、正式试点 CSV、移动端训练/复盘、候选资料上传/审核和 SOP 上传解析接口 |
 | [问师傅多轮会话与原始资料交付设计](docs/20260718/问师傅多轮会话与原始资料交付设计.md) | 已实现的短期会话、指代改写、意图路由、原文件/视频安全交付及分层验收记录 |
@@ -4,7 +4,7 @@

 - 后端：`backend`，来自 `dromara/RuoYi-Vue-Plus` 的 `5.X` 分支
 - 管理端前端：`frontend`，来自 `CrazyLionCat/plus-ui` 的 `5.X` 分支
- 用户侧前端：`mobile-uni`，uni-app Vue3 H5 工程；旧 `mobile` 仅保留为 MVP 演示兜底
+- 用户侧前端：`mobile-uni`，uni-app Vue3 H5 + App-Plus 工程；旧 `mobile` 仅保留为 MVP 演示兜底

 ## 本地入口与依赖端口

@@ -48,6 +48,8 @@ portless

 旧 `mobile/` 只在显式 `PORTLESS=0 ./scripts/dev.sh` 时作为固定端口兜底启动；后端开发测试优先看 `wygj-api.localhost`，管理端开发测试优先看 `wygj-admin.localhost`，新用户侧开发测试优先看 `wygj-mobile-uni.localhost`。

+原生 Android/iOS 资源使用 `npm --prefix mobile-uni run build:app` 构建；它不生成签名 APK/IPA，也不适用本文件的 H5 `rsync` 发布流程。自定义基座、协议链接、签名和真机门禁见 [MOBILE_APP_PACKAGING.md](MOBILE_APP_PACKAGING.md)。
+
 Qdrant 默认本地无需配置；远端或自定义 collection 可用 `AIHR_QDRANT_URL`、`AIHR_QDRANT_COLLECTION`、`AIHR_QDRANT_API_KEY` 覆盖。服务端资料导入根目录可用 `AIHR_IMPORT_ROOT` 或 `-Daihr.import.root` 覆盖。组织人员同步可用 `AIHR_ORG_SYNC_BASE_URL` 指向外部开放平台 `/api/open/v1` 前缀，并配置 `AIHR_ORG_SYNC_ACCESS_TOKEN` 或 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`；业务请求会用 client secret 生成 HMAC-SHA256 hex 签名。移动端手机号登录的短信模板 ID、阿里云 AccessKey、Secret 和短信签名都通过环境变量注入；本地放根目录 `.env.local`，`scripts/dev-backend.sh` 会自动加载。若开放平台凭证放在 `backend/.env`，启动脚本也会加载该文件，并把 `client_id`/`client_secret` 映射为组织同步实际读取的 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`。

 组织同步写入前先运行只读预检：`node scripts/verify-demo-questions.mjs --org-dry-run`。dry-run 不检查或变更本地快照表结构，也不写数据库；输出只包含人数、手机号覆盖、脱敏数、疑似乱码数和警告，不输出员工姓名。2026-07-15 当前开放平台数据已满足写入条件：3417 名员工中 3392 人可手机号映射，疑似乱码为 0；仍有 25 人手机号不可用，确认后可用 `allowPartialReplace=true` 覆盖写入。
@@ -14,6 +14,7 @@
 - [ ] 首次启动先显示原生隐私弹窗；两个协议链接可打开，拒绝后退出，同意后才进入登录。
 - [ ] 手机号登录、短信验证码错误、登录失效重登均符合预期。
 - [ ] 首次录音允许麦克风后，可完成转写；拒绝麦克风后不循环申请，能选择本地音频继续。
+- [ ] 对练入口在原生端明确降级为录音后转写，不出现不可用的浏览器 WebRTC 实时通话承诺。
 - [ ] 图片、视频、文档和音频可选择并上传；受控附件下载后可打开，不泄露 OSS 地址。
 - [ ] 前后台切换、网络断开/恢复、窄屏和底部手势区无白屏、遮挡或重复提交。
 - [ ] 再次安装同版本后，桌面图标、启动图和 Android 导航栏不闪白。
@@ -35,6 +35,7 @@ npm --prefix mobile-uni run build:app
 - 现有品牌源图仅为 64×64，因此这里生成的是**可用于自定义基座和测试包的派生资产**。正式提交商店前应替换为品牌方提供的高分辨率母版，再重新执行生成和预检。
 - `androidPrivacy.json.example` 是**未启用的法务模板**，其中 `__TERMS_URL__` 与 `__PRIVACY_URL__` 必须替换为法务确认的 HTTPS 地址。复制为被 Git 忽略的 `androidPrivacy.json` 后，`npm --prefix mobile-uni run verify:app-release` 才会通过。
 - iOS 已按实际功能填写麦克风和照片库用途说明；不申请相机、定位、通讯录、蓝牙或广告追踪权限。
+- App-Plus 当前不启用浏览器 WebRTC 实时对练；界面必须降级为录音后转写，不能将该路径宣传为实时语音通话。
 - 真机步骤和证据口径见 `docs/MOBILE_APP_DEVICE_ACCEPTANCE.md`。资源预检通过不等于 Android/iOS 真机或应用商店验收通过。

 ## 更新策略
@@ -18,6 +18,8 @@
 | 文档 | 用途 |
 |---|---|
 | [DEV_SETUP.md](DEV_SETUP.md) | 本地端口、账号、启动步骤、基础链路验证、管理端与移动端 H5 静态发布 |
+| [MOBILE_APP_PACKAGING.md](MOBILE_APP_PACKAGING.md) | `mobile-uni` Android/iOS 资源构建、隐私/签名边界和出包前置条件 |
+| [MOBILE_APP_DEVICE_ACCEPTANCE.md](MOBILE_APP_DEVICE_ACCEPTANCE.md) | Android/iOS 自定义基座或签名包的真机验收清单 |
 | [FIGMA_DESIGN_INVENTORY.md](FIGMA_DESIGN_INVENTORY.md) | Figma 页面节点索引、设计批次范围、取消项和全文件一致性审计结果 |
 | [FIGMA_DESIGN_SYSTEM_GUIDE.md](FIGMA_DESIGN_SYSTEM_GUIDE.md) | 员工端通用视觉元素、业务元素、状态映射和 LLM 组页规则 |
 | [FIGMA_IMPLEMENTATION_MATRIX.md](FIGMA_IMPLEMENTATION_MATRIX.md) | 70 张正式画板与代码/线上实现状态、二期边界和剩余动作 |