unis-oa/docs/mobile-pwa-design.md

9.0 KiB
Raw Permalink Blame History

移动端方案:做成可安装的 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 的目标只有两条,都很克制:

  1. 断网点开图标不白屏——导航请求先走网络,网不通回缓存里的应用外壳,剩下的交给页面自己的加载失败状态;
  2. 绝不缓存接口数据——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 之后建议手动过一遍,这些自动化测不了):

  1. Android Chrome 打开站点 → 地址栏出现安装图标 → 装完是独立窗口、没有浏览器地址栏;
  2. 断网点图标 → 显示外壳与离线横幅,不白屏、不报"找不到页面";
  3. iPhone Safari「添加到主屏幕」→ 图标正确、没有 16px 输入框放大跳动;
  4. 发一次版 → 旧页面右上角出现「有新版本」,点之前正在填的内容不被打断。

7. 剩下的天花板(不装死)

PWA 给不了的系统级能力:后台常驻、可靠的推送到达、面对面分享附件、调用原生相机之外的硬件。 如果哪天诉求变成"手机上必须第一时间收到待办并且直接批",正解不是把 SW 调得更激进, 而是接企业微信/钉钉的工作通知(渠道那一条已经把出口留好了),或者直接做小程序。