hyb-oa/docs/adr/adr-mobile-strategy.md

ADR: 移动端路线决策（PWA vs RN vs 小程序）

• 状态: Accepted (PoC 完成)
• 日期: 2026-02-10
• 关联 Issue: S2

背景

当前系统为响应式 Web。业务关注移动场景下的“离线 PDF 发票上传、弱网上传、回填状态可追踪”。

决策目标

1. 选择下一阶段移动路线。
2. 验证离线 PDF 发票上传可靠性。
3. 输出成本、风险、回滚方案。

备选方案

方案 A：PWA（推荐）

• 优点：
  • 基于现有 React/Vite 体系，团队学习成本低。
  • 可快速实现离线草稿、上传重试队列、安装到桌面。
  • 与现有鉴权与 API 契约兼容。
• 缺点：
  • iOS 对后台同步和离线能力有限制。

方案 B：React Native

• 优点：
  • 原生能力强，上传/相机/本地缓存控制更细。
• 缺点：
  • 双端构建链路与发布流程显著增加。
  • 需要新增移动端测试与运维能力。

方案 C：微信/钉钉小程序

• 优点：
  • 企业内推广成本低，触达快。
• 缺点：
  • 生态绑定强，跨平台复用差。
  • 审核与平台能力限制较多。

PoC 结果

• PWA 原型验证：
  • 离线缓存 PDF 发票元数据可行；
  • 网络恢复后自动上传成功率高；
  • 异常重试与失败提示可在现有前端框架中快速实现。
• RN 原型验证：
  • 能力更强，但初期投入约为 PWA 的 2~3 倍。

决策

• 主路线：PWA 优先。
• 触发升级条件：当离线强需求占比持续提升，且 PWA 在 iOS 场景无法满足 SLA 时，再升级 RN。

分阶段实施建议

1. P7：补离线草稿与上传队列（仅票据上传）。
2. P8：补断点续传、失败重放、可观测埋点。
3. P9：基于指标评估是否进入 RN 立项。

回滚策略

1. 保留 Web 主站能力，PWA 特性可通过开关关闭。
2. 关闭 Service Worker 后回退到纯在线模式。
3. 离线缓存可按版本清理，不影响服务端数据。