9.0 KiB
移动端方案:做成可安装的 PWA,而不是原生 App
对应缺口:docs/oa-capability-review.md §3「移动端专属 App 或小程序」。
落脚:frontend/public/manifest.webmanifest、frontend/sw.template.js(构建产出 dist/sw.js)、
frontend/src/composables/usePwa.ts、useMobileNav.ts、components/layout/MobileTabBar.vue、
图标生成 frontend/scripts/gen-icons.py,验收 frontend/src/**/__tests__/{MobileTabBar,usePwa,useMobileNav,serviceWorker}.spec.ts。
0. 为什么是 PWA
先说清代价,再谈选择。三条路摆在这里:
| 原生 App | 微信/钉钉小程序 | PWA(这一版) | |
|---|---|---|---|
| 代码库 | 再养一套(iOS + Android) | 再养一套(WXML/JS) | 同一套 Vue,已 responsive |
| 发版 | 应用商店审核,天级 | 平台审核,小时级 | 部署即生效 |
| 分发 | 需要签名与企业部署 | 需要企业主体资质、小程序 AppID | 一个链接,浏览器里「安装」 |
| 推送通知 | 系统级 | 平台内 | 受限(见 §7) |
| 后台运行 / 生物识别 | 可以 | 部分 | 不行 |
这套 OA 的真实处境是:企业内网自用、没有 C 端用户、没有人会为了一个内部审批去应用商店装 App。 它的移动端诉求实际是"手机上把待办办掉、看得清表单、点得到按钮", 而这三件事现有 Vue 前端补一层导航与触摸体验就够了。小程序那一档真正的门槛不是技术, 是企业主体资质 + 一套独立前端;原生则是两倍的代码与发版成本。
所以这一版做的是:同一套前端,装得上桌面、断网不白屏、窄屏能用。 差的那几件(推送、离线填单、生物识别)在 §7 明写,不含糊过去。
1. 可安装
public/manifest.webmanifest:display: standalone、主题色 #0d9488、两个快捷方式(待办 / 发起),
图标 public/icons/(192 / 512 + maskable 两套)。
图标不是找设计师要的,是 scripts/gen-icons.py 用 PIL 画的(主色渐变 + "OA" 字样 +
maskable 安全区版本)。maskable 不能省:Android launcher 会把图标裁成圆形,
没有安全区版本时字会被切掉一半。要换真 logo 就替换这个脚本的输出,其余都不动。
安装入口在右上角(AppHeader.vue 的「安装到桌面」)。这里的规矩是浏览器定的:
它扔一个 beforeinstallprompt,页面接住不放,等用户真点「安装」才弹系统框——
不许替用户装。状态放在模块级(usePwa.ts):那个事件什么时候来由浏览器决定,
可能比任何组件挂载都晚,放组件里就会漏掉。
iOS Safari 不发这个事件,装了才知道:iPhone 上只能手工「共享 → 添加到主屏幕」,
apple-touch-icon 与 apple-mobile-web-app-* meta 都配好了,那条路是通的。
2. 离线外壳:只解决"别白屏"
sw.template.js 的目标只有两条,都很克制:
- 断网点开图标不白屏——导航请求先走网络,网不通回缓存里的应用外壳,剩下的交给页面自己的加载失败状态;
- 绝不缓存接口数据——
PASS_THROUGH = ['/api','/v1','/setup','/sso','/print','/open']一个字节都不进缓存。
第二条是这套方案里最重要的自我约束。缓存一份待办列表看着像"能离线办公",
实际是让人对着一张过期的单子签字:那张单可能早就被前一个审批人退回、或者已经被别人办掉了。
缓存 /assets/*(文件名带哈希,换版本等于换 URL,旧缓存只会占地方不会给错内容),
不缓存任何会说谎的东西。
发版怎么让用户拿到新版:sw.template.js 不在 public/ 里,构建时由 vite.config.ts 的
serviceWorkerPlugin 发成 dist/sw.js 并把缓存名换成构建时间戳
(unisoa-static-202610261014084131)。放在 public/ 会被原样拷贝、把改写过的版本盖掉——
这是个真踩过的坑。老版 SW 检测到新 SW 之后不自动 skipWaiting():
正填到一半的单子不该被一次发版打断。右上角出现「有新版本 → 刷新」(pwa.updateReady),
点了才发 OA_SW_SKIP_WAITING 接管。
SW 只在生产构建里注册(usePwa.ts 里判 import.meta.env.PROD)。开发模式下 Vite 的 HMR
要把模块换掉,而外壳缓存恰好拦这一步,注册了只会让人以为"改了代码没生效"。
SW 与 manifest 都要求 HTTPS(或
localhost)。内网要用 PWA,先给站点配一张证书, 自签也行,但手机端要装上那张根证书,否则「安装」按钮压根不出现。
3. 窄屏导航
断点跟 Tailwind 的 lg 咬死在同一条线:useMobileNav.ts 的 NARROW_QUERY = '(max-width: 1023.98px)'。
为什么不用纯 CSS:两件事必须同步——侧边栏收进抽屉的同时底部标签栏才接手,
而"页面底下要让出多高"是内联样式层面的事。用一串 max-lg: 变体去拼,很容易和侧边栏那条
lg:translate-x-0 各说一套,最后要么两条导航同时在场,要么「同意」按钮有一半压在标签栏底下
(看着能点,点下去是空的)。
MobileTabBar.vue:工作台 / 待办(带角标)/ 发起 / 我的。过滤条件与侧边栏同一份权限码 (authStore.can('work:todo')…),不做第二套"移动端专属菜单"——两套权限表迟早对不上, 而对不上时的表现是"手机上少一个入口,但说不清是没权限还是没做"。- 待办角标读
appStore.todoCount,这个计数由AppLayout在挂载与路由变化时刷一次, 侧边栏读的是同一份。之前侧边栏自己拉一次、现在移动端再拉一次,就是同一次进页面打两遍接口。 - 让出的高度
BOTTOM_INSET = calc(3.5rem + env(safe-area-inset-bottom)):标签栏本体加 iPhone 底部 那根 home 条。TaskDetailView那条 sticky 的「同意 / 退回」操作条同样抬到这个高度之上。
4. 填单与触摸
FormRenderer本来就按useMediaQuery在窄屏收成单列(既有行为,沿用),这一层没动它的字段逻辑;style.css:≤768px 时.input字号钉到 16px。低于 16px 的输入框获得焦点时 iOS Safari 会自动放大页面,用户要点两下才能回到原位——这是移动表单最难看也最常见的小毛病; 顺手把-webkit-tap-highlight-color设成透明,点击时不再闪一块灰斑;index.html:viewport-fit=cover(不然安全区高度恒为 0,那条 home 条会盖住内容)、theme-color、apple-mobile-web-app-*;- 断网时页面顶部出现一条横幅(
useOnline),说"现在是离线状态",而不是让人对着空列表猜。
5. 明确不做
- Web Push:需要 VAPID 应用密钥 + iOS 16.4 以上且必须已装到桌面 + 全程有效证书,
三个条件在内网同时成立的概率不高。消息这一路已经交给
docs/notification-channels-design.md——邮件和群机器人比浏览器推送可靠得多,先把那条跑顺。 - 离线填单 / 草稿续传:等 §2 那句"不缓存接口数据"的约束能解开再说。表单结构、字段权限、 编号规则都在服务端,离线填完回来提交,冲突处理比这个功能本身值钱得多。
- 小程序 / 原生壳:见 §0 的取舍。真要做,
docs/platform-open-api-design.md的开放接口就是 给它们留的接口面,不用等这一版改架构。 - 生物识别登录:WebAuthn 能做,但和统一身份(Hub)的口令体系怎么配合要先想清楚,不该塞进这一版。
- 响应式图片与按需加载:附件预览和列表已经够轻,先不上虚拟滚动。
6. 怎么验收
自动化:MobileTabBar.spec.ts(权限过滤、角标、窄屏才在场)、usePwa.spec.ts(安装事件接住不替用户装、
appinstalled 之后不再催、SW 仅生产注册、点刷新才 skipWaiting)、useMobileNav.spec.ts(阈值与安全区)、
serviceWorker.spec.ts(模板里 PASS_THROUGH 覆盖全部后端前缀、构建把版本戳换掉且不留占位符)。
真机(改了导航或 SW 之后建议手动过一遍,这些自动化测不了):
- Android Chrome 打开站点 → 地址栏出现安装图标 → 装完是独立窗口、没有浏览器地址栏;
- 断网点图标 → 显示外壳与离线横幅,不白屏、不报"找不到页面";
- iPhone Safari「添加到主屏幕」→ 图标正确、没有 16px 输入框放大跳动;
- 发一次版 → 旧页面右上角出现「有新版本」,点之前正在填的内容不被打断。
7. 剩下的天花板(不装死)
PWA 给不了的系统级能力:后台常驻、可靠的推送到达、面对面分享附件、调用原生相机之外的硬件。 如果哪天诉求变成"手机上必须第一时间收到待办并且直接批",正解不是把 SW 调得更激进, 而是接企业微信/钉钉的工作通知(渠道那一条已经把出口留好了),或者直接做小程序。