hyb-oa/.trellis/tasks/08-10-pwa-cross-version-cache-upgrade-validation/implement.md

PWA 跨版本缓存升级验证：执行计划

Phase A：Harness 与旧版本前置

• 在 scripts/qa/ 增加 loopback-only wrapper：生成两个临时 production outDir，注入不同 synthetic SHA，失败/退出时清理。
• 在专用 Playwright spec 中实现进程内静态/API server；同一 origin 支持 A→B 原子切换，禁止 path traversal，缓存头贴近生产。
• 显式使用 serviceWorkers: "allow"，同一 BrowserContext 建立 synthetic session。
• A 阶段断言 SHA、SW ready、controller、precache 与 A-only asset；未满足即 PAUSED，不进入 B。

Phase B：同 profile 跨版本重访

• 关闭 A page但保留 context，原位切 B，再创建 page 重访同一路由。
• B 阶段不调用测试侧 reload、clear cookie/cache、unregister 或新 context。
• 等待应用自身 SW 更新，断言最终 SHA=B、route/session 保持、refresh/me 成功。
• 以 controllerchange/CDP worker version、B sw.js 指纹、B document SHA 与 B-only chunk 联合证明接管；恒定 /sw.js URL 只作 scope 证明。
• 记录 hyb-oa:pwa-update-ready 触发次数与阶段；检查最终 cache、asset 请求、404、console/page error 与导航次数，旧-only chunk 不得残留。
• 加一个明确标注的 fresh-B sanity（如确有诊断价值），但不得把它计入 A→B AC。

Phase C：结果分叉

• PASS：固化最小 test-only runner/spec，写入脱敏 ledger，并复跑至少两次确认不是 worker 时序偶发。
• PRODUCT_FINDING：停止，不修改 pwa.ts/vite.config.ts；记录最短失败阶段和独立修复任务建议。
• 第一次 B 失败：立即冻结现场并停止，不追加 reload、重访或第二次升级尝试。
• PAUSED：记录环境/前置缺口和恢复条件，不声称真实用户升级正常或异常。

Phase D：验证与收口

• focused runner 单 worker、zero retry PASS；重复执行保持同结论。
• 若新增 TS test：cd client && npm run typecheck。
• task/process/governance/sensitive/git diff --check。
• 评估是否需要扩展 frontend PWA spec；仅在真实 witness 得到稳定结论后沉淀。
• 中文 commit 引用 08-10-pwa-cross-version-cache-upgrade-validation；不推送、不部署。

Risky Files / Stop Points

• client/src/pwa.ts、client/vite.config.ts：本任务验证阶段只读；如需改动，按 PRODUCT_FINDING 停止并回来批准。
• 新 QA wrapper：不得覆盖 client/dist，不得接受非 loopback origin，不得泄露完整临时路径。
• 新 Playwright spec：不得使用 page.route/context.route，不得 block Service Worker，不得在 B 阶段强制刷新或清缓存。
• build A 前置不成立、A/B asset 无差集、server origin 变化或 cleanup 失败：立即 PAUSED。

Expected Evidence

• A/B build SHA、asset 差集与 SW 存在性（仅 synthetic 标签/相对路径）。
• A 阶段 controller + precache 证明。
• B 阶段同 context 重访、应用驱动更新、最终 document/controller/cache/session 证明。
• /login 次数、refresh/me status、静态 404、page/chunk error、导航次数的安全 ledger。
• 单一最终状态与失败分叉，不用 fresh install 替代 upgrade。