Plan: Basic PWA (service worker, installable, new-version notice)¶
Status: Done (2026-10-24)
Date: 2026-10-24
Run: autopilot 2026-10-24-pwa-basic (started lite, promoted to full mode when the non-test diff reached ~130 LOC)
PRD / ADR / Spec: none (small feature; no new dependency, hand-written service worker)
Request: "PWA cơ bản: service worker, cài được, có thông báo phiên bản mới".
Facts (read by the orchestrator):
webapp/public/manifest.jsonexists (name/short_name "funny-app", start_url "/", display standalone, theme #FF0000, icons 192/512any maskable) and is linked fromwebapp/index.html:7. There is no service worker anywhere (grep serviceWorker webapp/src→ none), so Chrome does not offer install and nothing caches.webapp/index.htmlhas notheme-color,apple-touch-iconorapple-mobile-web-app-*meta.- Build id:
webapp/vite.config.js:8defines__APP_BUILD__= first 7 chars ofGITHUB_SHA(ordev). - Deploy:
.github/workflows/deploy-web.yml:28-55runsnpm run build, scp'swebapp/dist/to the VM and reloads nginx; Cloudflare sits in front (scripts/monitoring/nginx-alert/cloudflare-realip.conf). A plain/sw.jscould be held by an edge or HTTP cache, so the SW URL carries the build id. - Entry:
webapp/src/main.jsxrenders<App/>; the shell iswebapp/src/components/layout/AppShell.jsx:49(main content at:370). i18n namespaces live inwebapp/src/i18n/locales/{en,vi}/*.json(common.json,shell.json, …). - Tech strategy: no new dependency is added (hand-written classic service worker;
vite-plugin-pwa/Workbox deliberately not used, so no ADR).
| ID | Task | Files | Acceptance criteria | Est. LOC |
|---|---|---|---|---|
| PW-1 | Service worker (installable, safe caching) + build-id file | new webapp/public/sw.js; new webapp/src/pwa/registerSW.js; webapp/src/main.jsx (call it); webapp/vite.config.js (inline plugin, no dependency) |
(1) vite.config.js: an inline plugin emits version.json = {"build":"<__APP_BUILD__ value>"} in generateBundle (no new npm package). (2) sw.js (classic, no imports, no automatic reload logic): cache name fm-shell-v1; install → self.skipWaiting(); activate → delete every cache except the current one, then clients.claim(). fetch handler only for same-origin GET without a Range header: (a) navigation → fetch(req, {cache:'no-cache'}) (network-first, never a stale HTTP/edge copy); store only ok && !redirected responses, always under the fixed key '/' (never the request URL, so ?token=/?v= deep links are never cached); on network failure → caches.match('/'); (b) /assets/* → cache-first; store only ok responses whose content-type is not text/html (never the SPA fallback page); after storing, if the cache holds more than 60 entries the oldest ones (by cache.keys() order, never '/') are deleted, so assets of old builds do not pile up (plan-review r2 [A]); (c) everything else (/api/, /video-stream/, SSE, version.json, other origins such as the API host canh-labs.com, fonts, images, non-GET, any Range request) → not intercepted (no respondWith). (3) registerSW(): only when 'serviceWorker' in navigator and import.meta.env.PROD; registers /sw.js with { scope: '/', updateViaCache: 'none' }; never reloads the page itself. (4) Tests (Vitest): load public/sw.js text into a fake self (vm / new Function) and assert: /api/x, cross-origin https://canh-labs.com/api/..., /video-stream/..., POST, a Range request and version.json are not intercepted; /assets/a.js cache-first and an HTML response for /assets/missing.js is not stored; navigation to /?token=abc fetches with cache:'no-cache', stores under '/' only, and falls back to caches.match('/') offline; redirected/non-ok navigation responses are not stored; activate deletes other caches. Registration: not called without SW support or when PROD is false (vi.stubEnv), registers /sw.js with the options above |
~60 + ~100 |
| PW-2 | New-version notice + installable metadata | new webapp/src/pwa/useNewVersion.js; new webapp/src/components/layout/UpdateBanner.jsx; AppShell.jsx (render it); webapp/public/manifest.json; webapp/index.html; webapp/src/i18n/locales/{en,vi}/shell.json; styles in webapp/src/styles/index.css |
(1) useNewVersion() (PROD only; any build-id mismatch shows the banner, a rollback deploy included — documented in the hook comment): fetches /version.json?t=<Date.now()> with {cache:'no-store'} when the tab becomes visible (visibilitychange) and every 15 min; when build differs from __APP_BUILD__ it returns updateAvailable=true; network/JSON errors are ignored; listeners and the interval are removed on unmount. (2) UpdateBanner: hidden until updateAvailable; small fixed banner "Có phiên bản mới" / "A new version is available", button "Tải lại" / "Reload" → window.location.reload(), and a dismiss "×" (stays dismissed for that build); role="status", labelled buttons. (3) Manifest: name/short_name "Funny Movies", id "/", scope "/"; icons split into separate purpose: "any" and purpose: "maskable" entries (same 192/512 files). (4) index.html: theme-color #FF0000, apple-touch-icon → /icons/icon-app-192.png, apple-mobile-web-app-capable yes, apple-mobile-web-app-title "Funny Movies". (5) en/vi keys. (6) Tests: mismatch → banner shows; same build → hidden; fetch error → hidden; visibilitychange triggers a check; Reload calls location.reload; dismiss hides; no polling outside PROD (vi.stubEnv, __APP_BUILD__ stub/define); i18n keys in both languages |
~45 + ~60 |
Design note (plan-review round 1 [B]): version detection is independent of the service worker (a build-scoped SW URL is never re-fetched by an open old tab, and controllerchange would reload on first install). The SW activates immediately and never reloads pages; assets are hashed and the deploy (.github/workflows/deploy-web.yml:36-45, scp without cleanup) keeps old files, so an old tab keeps working until the user reloads.
Out of scope: install button / beforeinstallprompt UI, Web Push, offline video, caching API responses, nginx/Cloudflare header changes.
Risks: a bad SW could pin users on an old shell — mitigated by navigation network-first with cache:'no-cache', updateViaCache:'none', a stable /sw.js re-checked by the browser on navigation, and no caching of anything but hashed assets and the / shell; a SW is easy to remove later (ship one that unregisters itself). Cloudflare could hold /sw.js at the edge for its TTL — this only delays SW changes, not app updates (version.json is fetched with a unique query). iOS: install via Share → Add to Home Screen (no prompt); a 180 px apple-touch-icon is not produced (192 px is used; iOS scales it).
Manual checks for the owner (after deploy): Chrome desktop/Android shows the install icon/menu; installed app opens standalone; deploy again → within 15 min (or on returning to the tab) the banner appears in an open tab → Reload loads the new build; DevTools → Application → Service Workers shows /sw.js activated; /version.json returns the new short SHA; Network shows /api/ and /video-stream/ requests not served by the SW.
Progress Log¶
| Date | Task | Commit | Note |
|---|---|---|---|
| 2026-10-24 | — | — | Plan review r1 revise (open-tab update, first-install reload) → redesigned: version.json polling, SW never reloads; r2 approve |
| 2026-10-24 | PW-1, PW-2 | a6dfd4b3, 32839c3c, ae83a137 | Built by autopilot; code review approve (advisory fix: shell requires text/html); QA ×2 28/28; vitest 638/638, lint 0 errors, build emits sw.js + version.json |