From 74e4e98a39f40eaac6368d51fe53d24f102c7df6 Mon Sep 17 00:00:00 2001
From: haotool <haotool.org@gmail.com>
Date: Sun, 28 Jun 2026 16:54:50 +0800
Subject: [PATCH] =?UTF-8?q?fix(ratewise):=20offline.html=20=E5=85=A7?=
 =?UTF-8?q?=E5=B5=8C=20SW=20=E8=87=AA=E6=88=91=E4=BF=AE=E5=BE=A9=E6=89=93?=
 =?UTF-8?q?=E7=A0=B4=E6=AD=BB=E4=BA=A1=E8=BF=B4=E5=9C=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在線卻載入 offline.html 時探針 CHECK_SHELL_PRECACHE 並 SKIP_WAITING
- 重試按鈕改為導向 app shell，移除 reload 造成的 SW 循環
- 補 pwa-offline 防回歸測試與 patch changeset

測試：vitest pwa-offline/swHealth/sw.test、typecheck、build:ratewise

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../ratewise-offline-shell-self-heal.md       |   5 +
 apps/ratewise/public/offline.html             | 163 ++++++++++++++++--
 .../scripts/templates/offline.template.html   | 163 ++++++++++++++++--
 apps/ratewise/src/pwa-offline.test.ts         |  16 +-
 .../dev/002_development_reward_penalty_log.md |   7 +-
 5 files changed, 325 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/ratewise-offline-shell-self-heal.md

diff --git a/.changeset/ratewise-offline-shell-self-heal.md b/.changeset/ratewise-offline-shell-self-heal.md
new file mode 100644
index 000000000..ad4bd5e30
--- /dev/null
+++ b/.changeset/ratewise-offline-shell-self-heal.md
@@ -0,0 +1,5 @@
+---
+'@app/ratewise': patch
+---
+
+在線卻卡在離線頁時，offline.html 會自動嘗試修復 Service Worker 並導回主應用，避免無法進入主功能的死亡迴圈。
diff --git a/apps/ratewise/public/offline.html b/apps/ratewise/public/offline.html
index 1594b5972..6c6ff95c8 100644
--- a/apps/ratewise/public/offline.html
+++ b/apps/ratewise/public/offline.html
@@ -193,7 +193,7 @@
       <h1>您目前處於離線狀態</h1>
       <p>請檢查您的網路連線，或稍後再試。HaoRate 會在連線恢復時自動更新。</p>
 
-      <button class="retry-btn" onclick="window.location.reload()">
+      <button class="retry-btn" id="retry-btn" type="button">
         <svg
           xmlns="http://www.w3.org/2000/svg"
           width="20"
@@ -227,20 +227,157 @@ <h2>小提示</h2>
     </div>
 
     <script>
-      // 檢查是否有快取的匯率數據
-      try {
-        const cached = localStorage.getItem('exchangeRates');
-        if (cached) {
-          document.getElementById('cached-info').style.display = 'block';
+      (function () {
+        var HEAL_SESSION_KEY = 'rw-offline-shell-heal';
+        var LEGACY_PRECACHE_THRESHOLD = 150;
+        var SHELL_PROBE_TIMEOUT_MS = 2000;
+        var WAITING_SW_TIMEOUT_MS = 8000;
+
+        // 檢查是否有快取的匯率數據
+        try {
+          var cached = localStorage.getItem('exchangeRates');
+          if (cached) {
+            document.getElementById('cached-info').style.display = 'block';
+          }
+        } catch (e) {
+          // localStorage 不可用時略過
         }
-      } catch (e) {
-        // Ignore localStorage errors
-      }
 
-      // 監聽網路狀態變化，自動重載
-      window.addEventListener('online', () => {
-        window.location.reload();
-      });
+        function hasHealBeenAttemptedThisSession() {
+          try {
+            return sessionStorage.getItem(HEAL_SESSION_KEY) === '1';
+          } catch (e) {
+            return false;
+          }
+        }
+
+        function markHealAttemptedThisSession() {
+          try {
+            sessionStorage.setItem(HEAL_SESSION_KEY, '1');
+          } catch (e) {
+            // sessionStorage 不可用時仍允許單次修復
+          }
+        }
+
+        function navigateToAppShell() {
+          var healQuery = 'shell-heal=' + Date.now();
+          window.location.replace('./?' + healQuery);
+        }
+
+        function probeActiveSwShellBroken() {
+          if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {
+            return Promise.resolve(true);
+          }
+
+          return new Promise(function (resolve) {
+            var channel = new MessageChannel();
+            var timeoutId = setTimeout(function () {
+              resolve(true);
+            }, SHELL_PROBE_TIMEOUT_MS);
+
+            channel.port1.onmessage = function (event) {
+              clearTimeout(timeoutId);
+              var data = event.data || {};
+              var precacheEntryCount = Number(data.precacheEntryCount || 0);
+              var hasIndexShell = Boolean(data.hasIndexShell || data.healthy);
+              resolve(!hasIndexShell || precacheEntryCount > LEGACY_PRECACHE_THRESHOLD);
+            };
+
+            navigator.serviceWorker.controller.postMessage({ type: 'CHECK_SHELL_PRECACHE' }, [
+              channel.port2,
+            ]);
+          });
+        }
+
+        function waitForWaitingServiceWorker(registration) {
+          if (registration.waiting) {
+            return Promise.resolve(registration.waiting);
+          }
+
+          return new Promise(function (resolve) {
+            var timeoutId = setTimeout(function () {
+              registration.removeEventListener('updatefound', onUpdateFound);
+              resolve(registration.waiting);
+            }, WAITING_SW_TIMEOUT_MS);
+
+            function onUpdateFound() {
+              var installing = registration.installing;
+              if (!installing) {
+                return;
+              }
+
+              installing.addEventListener('statechange', function () {
+                if (installing.state === 'installed' && registration.waiting) {
+                  clearTimeout(timeoutId);
+                  registration.removeEventListener('updatefound', onUpdateFound);
+                  resolve(registration.waiting);
+                }
+              });
+            }
+
+            registration.addEventListener('updatefound', onUpdateFound);
+          });
+        }
+
+        function skipWaitingAndNavigateToShell(waitingWorker) {
+          return new Promise(function () {
+            navigator.serviceWorker.addEventListener(
+              'controllerchange',
+              function () {
+                navigateToAppShell();
+              },
+              { once: true },
+            );
+            waitingWorker.postMessage({ type: 'SKIP_WAITING' });
+            setTimeout(navigateToAppShell, 1500);
+          });
+        }
+
+        // 在線卻載入 offline.html 時自我修復；swHealth 僅在 React 掛載後執行，無法打破死亡迴圈。
+        async function attemptOfflineShellSelfHeal(forceRetry) {
+          if (!navigator.onLine) {
+            return;
+          }
+          if (!forceRetry && hasHealBeenAttemptedThisSession()) {
+            return;
+          }
+          markHealAttemptedThisSession();
+
+          try {
+            if ('serviceWorker' in navigator) {
+              var registration = await navigator.serviceWorker.getRegistration();
+              if (registration) {
+                await registration.update();
+                var broken = await probeActiveSwShellBroken();
+                if (broken) {
+                  var waiting = await waitForWaitingServiceWorker(registration);
+                  if (waiting) {
+                    await skipWaitingAndNavigateToShell(waiting);
+                    return;
+                  }
+                }
+              }
+            }
+          } catch (e) {
+            // 修復失敗時仍嘗試導向 app shell
+          }
+
+          navigateToAppShell();
+        }
+
+        var retryBtn = document.getElementById('retry-btn');
+        if (retryBtn) {
+          retryBtn.addEventListener('click', function () {
+            void attemptOfflineShellSelfHeal(true);
+          });
+        }
+
+        window.addEventListener('online', function () {
+          void attemptOfflineShellSelfHeal(true);
+        });
+
+        void attemptOfflineShellSelfHeal(false);
+      })();
     </script>
   </body>
 </html>
diff --git a/apps/ratewise/scripts/templates/offline.template.html b/apps/ratewise/scripts/templates/offline.template.html
index 1ebbdabba..b361cfe2d 100644
--- a/apps/ratewise/scripts/templates/offline.template.html
+++ b/apps/ratewise/scripts/templates/offline.template.html
@@ -193,7 +193,7 @@
       <h1>您目前處於離線狀態</h1>
       <p>請檢查您的網路連線，或稍後再試。__BRAND_SHORT__ 會在連線恢復時自動更新。</p>
 
-      <button class="retry-btn" onclick="window.location.reload()">
+      <button class="retry-btn" id="retry-btn" type="button">
         <svg
           xmlns="http://www.w3.org/2000/svg"
           width="20"
@@ -227,20 +227,157 @@ <h2>小提示</h2>
     </div>
 
     <script>
-      // 檢查是否有快取的匯率數據
-      try {
-        const cached = localStorage.getItem('exchangeRates');
-        if (cached) {
-          document.getElementById('cached-info').style.display = 'block';
+      (function () {
+        var HEAL_SESSION_KEY = 'rw-offline-shell-heal';
+        var LEGACY_PRECACHE_THRESHOLD = 150;
+        var SHELL_PROBE_TIMEOUT_MS = 2000;
+        var WAITING_SW_TIMEOUT_MS = 8000;
+
+        // 檢查是否有快取的匯率數據
+        try {
+          var cached = localStorage.getItem('exchangeRates');
+          if (cached) {
+            document.getElementById('cached-info').style.display = 'block';
+          }
+        } catch (e) {
+          // localStorage 不可用時略過
         }
-      } catch (e) {
-        // Ignore localStorage errors
-      }
 
-      // 監聽網路狀態變化，自動重載
-      window.addEventListener('online', () => {
-        window.location.reload();
-      });
+        function hasHealBeenAttemptedThisSession() {
+          try {
+            return sessionStorage.getItem(HEAL_SESSION_KEY) === '1';
+          } catch (e) {
+            return false;
+          }
+        }
+
+        function markHealAttemptedThisSession() {
+          try {
+            sessionStorage.setItem(HEAL_SESSION_KEY, '1');
+          } catch (e) {
+            // sessionStorage 不可用時仍允許單次修復
+          }
+        }
+
+        function navigateToAppShell() {
+          var healQuery = 'shell-heal=' + Date.now();
+          window.location.replace('./?' + healQuery);
+        }
+
+        function probeActiveSwShellBroken() {
+          if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {
+            return Promise.resolve(true);
+          }
+
+          return new Promise(function (resolve) {
+            var channel = new MessageChannel();
+            var timeoutId = setTimeout(function () {
+              resolve(true);
+            }, SHELL_PROBE_TIMEOUT_MS);
+
+            channel.port1.onmessage = function (event) {
+              clearTimeout(timeoutId);
+              var data = event.data || {};
+              var precacheEntryCount = Number(data.precacheEntryCount || 0);
+              var hasIndexShell = Boolean(data.hasIndexShell || data.healthy);
+              resolve(!hasIndexShell || precacheEntryCount > LEGACY_PRECACHE_THRESHOLD);
+            };
+
+            navigator.serviceWorker.controller.postMessage({ type: 'CHECK_SHELL_PRECACHE' }, [
+              channel.port2,
+            ]);
+          });
+        }
+
+        function waitForWaitingServiceWorker(registration) {
+          if (registration.waiting) {
+            return Promise.resolve(registration.waiting);
+          }
+
+          return new Promise(function (resolve) {
+            var timeoutId = setTimeout(function () {
+              registration.removeEventListener('updatefound', onUpdateFound);
+              resolve(registration.waiting);
+            }, WAITING_SW_TIMEOUT_MS);
+
+            function onUpdateFound() {
+              var installing = registration.installing;
+              if (!installing) {
+                return;
+              }
+
+              installing.addEventListener('statechange', function () {
+                if (installing.state === 'installed' && registration.waiting) {
+                  clearTimeout(timeoutId);
+                  registration.removeEventListener('updatefound', onUpdateFound);
+                  resolve(registration.waiting);
+                }
+              });
+            }
+
+            registration.addEventListener('updatefound', onUpdateFound);
+          });
+        }
+
+        function skipWaitingAndNavigateToShell(waitingWorker) {
+          return new Promise(function () {
+            navigator.serviceWorker.addEventListener(
+              'controllerchange',
+              function () {
+                navigateToAppShell();
+              },
+              { once: true },
+            );
+            waitingWorker.postMessage({ type: 'SKIP_WAITING' });
+            setTimeout(navigateToAppShell, 1500);
+          });
+        }
+
+        // 在線卻載入 offline.html 時自我修復；swHealth 僅在 React 掛載後執行，無法打破死亡迴圈。
+        async function attemptOfflineShellSelfHeal(forceRetry) {
+          if (!navigator.onLine) {
+            return;
+          }
+          if (!forceRetry && hasHealBeenAttemptedThisSession()) {
+            return;
+          }
+          markHealAttemptedThisSession();
+
+          try {
+            if ('serviceWorker' in navigator) {
+              var registration = await navigator.serviceWorker.getRegistration();
+              if (registration) {
+                await registration.update();
+                var broken = await probeActiveSwShellBroken();
+                if (broken) {
+                  var waiting = await waitForWaitingServiceWorker(registration);
+                  if (waiting) {
+                    await skipWaitingAndNavigateToShell(waiting);
+                    return;
+                  }
+                }
+              }
+            }
+          } catch (e) {
+            // 修復失敗時仍嘗試導向 app shell
+          }
+
+          navigateToAppShell();
+        }
+
+        var retryBtn = document.getElementById('retry-btn');
+        if (retryBtn) {
+          retryBtn.addEventListener('click', function () {
+            void attemptOfflineShellSelfHeal(true);
+          });
+        }
+
+        window.addEventListener('online', function () {
+          void attemptOfflineShellSelfHeal(true);
+        });
+
+        void attemptOfflineShellSelfHeal(false);
+      })();
     </script>
   </body>
 </html>
diff --git a/apps/ratewise/src/pwa-offline.test.ts b/apps/ratewise/src/pwa-offline.test.ts
index 1949c6cd2..4ce74c56d 100644
--- a/apps/ratewise/src/pwa-offline.test.ts
+++ b/apps/ratewise/src/pwa-offline.test.ts
@@ -30,11 +30,23 @@ describe('PWA 離線功能測試', () => {
       const offlinePath = resolve(ROOT_PATH, 'public/offline.html');
       const content = readFileSync(offlinePath, 'utf-8');
 
-      // 應該有重試功能
-      expect(content).toContain('window.location.reload()');
+      // 重試按鈕應觸發 shell 自我修復，而非單純 reload（避免在線死亡迴圈）
+      expect(content).toContain('retry-btn');
+      expect(content).toContain('attemptOfflineShellSelfHeal');
       expect(content).toContain("window.addEventListener('online'");
     });
 
+    it('should self-heal when online user lands on offline shell', () => {
+      const offlinePath = resolve(ROOT_PATH, 'public/offline.html');
+      const content = readFileSync(offlinePath, 'utf-8');
+
+      expect(content).toContain('rw-offline-shell-heal');
+      expect(content).toContain('CHECK_SHELL_PRECACHE');
+      expect(content).toContain("type: 'SKIP_WAITING'");
+      expect(content).toContain('navigateToAppShell');
+      expect(content).not.toContain('window.location.reload()');
+    });
+
     it('should show cached data indicator', () => {
       const offlinePath = resolve(ROOT_PATH, 'public/offline.html');
       const content = readFileSync(offlinePath, 'utf-8');
diff --git a/docs/dev/002_development_reward_penalty_log.md b/docs/dev/002_development_reward_penalty_log.md
index 617c07407..bf11c25b3 100644
--- a/docs/dev/002_development_reward_penalty_log.md
+++ b/docs/dev/002_development_reward_penalty_log.md
@@ -2,7 +2,7 @@
 
 > 版本：outline-v2-ultra
 > 原則：每筆只保留日期、ID、原因、解法。
-> 本次分數變化：+1（reward 1、penalty 0、neutral 0）｜累計總分：+84
+> 本次分數變化：+1（reward 1、penalty 0、neutral 0）｜累計總分：+85
 
 ## 新增模板（4 行）
 
@@ -13,6 +13,11 @@
 
 ## 條目（新→舊）
 
+- 日期：2026-06-28
+- ID：reward-offline-shell-self-heal-death-loop
+- 原因：在線用戶被壞 SW 誤服 offline.html 時 React/swHealth 未掛載，reload 仍回 offline.html 形成死亡迴圈
+- 解法：offline.html 內嵌 CHECK_SHELL_PRECACHE 探針 + SKIP_WAITING + 導向 app shell，打破無 React 的修復盲區
+
 - 日期：2026-06-28
 - ID：reward-sw-aggressive-propagation-broken-shell
 - 原因：舊版 SW precache 不完整（缺 index.html 或 400+ legacy 項）仍控制 client，離線冷啟動誤觸 offline.html，且 prompt 模式離線無法拉取修復版