npm - botrun-horse - Versions diffs - 2.29.2 → 2.30.0 - Mend

botrun-horse 2.29.2 → 2.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (574) hide show

package/botrun-c/html-architecture/architecture/user-flow.html ADDED Viewed

@@ -0,0 +1,370 @@
+<!DOCTYPE html>
+<html lang="zh-TW">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>使用者流程圖 - 日本醫療表單系統</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <!-- 導覽列 -->
+  <nav class="nav">
+    <div class="nav-container">
+      <a href="index.html" class="nav-logo">
+        🏥 日本醫療表單系統
+      </a>
+      <ul class="nav-links">
+        <li><a href="index.html" class="nav-link">總覽</a></li>
+        <li><a href="user-flow.html" class="nav-link active">使用者流程</a></li>
+        <li><a href="system-components.html" class="nav-link">系統元件</a></li>
+        <li><a href="deployment.html" class="nav-link">部署架構</a></li>
+      </ul>
+    </div>
+  </nav>
+  <!-- 主內容 -->
+  <div class="container">
+    <!-- 頁面標題 -->
+    <div class="section fade-in">
+      <h1>👤 使用者流程圖</h1>
+      <p class="text-center" style="font-size: 1.15rem; color: var(--text-secondary);">
+        這個頁面用簡單易懂的圖表，說明使用者從登入到下載表單的完整流程
+      </p>
+    </div>
+    <!-- 完整流程圖 SVG -->
+    <div class="diagram-container fade-in">
+      <div class="diagram-title">📊 完整使用者流程 (6 個步驟)</div>
+      <svg viewBox="0 0 800 1400" xmlns="http://www.w3.org/2000/svg">
+        <!-- 定義箭頭 -->
+        <defs>
+          <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+            <polygon points="0 0, 10 3, 0 6" fill="#2196F3" />
+          </marker>
+          <marker id="arrowhead-error" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+            <polygon points="0 0, 10 3, 0 6" fill="#F44336" />
+          </marker>
+        </defs>
+        <!-- 步驟 1: 使用者造訪網站 -->
+        <g id="step1">
+          <rect x="250" y="20" width="300" height="80" rx="10" fill="#2196F3" stroke="#1976D2" stroke-width="2"/>
+          <text x="400" y="50" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 1</text>
+          <text x="400" y="75" text-anchor="middle" fill="white" font-size="14">使用者造訪 j.cameo.tw</text>
+          <text x="400" y="93" text-anchor="middle" fill="white" font-size="12">(統一入口網站)</text>
+        </g>
+        <!-- 箭頭 1 -->
+        <line x1="400" y1="100" x2="400" y2="140" stroke="#2196F3" stroke-width="2" marker-end="url(#arrowhead)"/>
+        <!-- 步驟 2: 點擊 Google 登入 -->
+        <g id="step2">
+          <rect x="250" y="140" width="300" height="80" rx="10" fill="#4CAF50" stroke="#388E3C" stroke-width="2"/>
+          <text x="400" y="170" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 2</text>
+          <text x="400" y="195" text-anchor="middle" fill="white" font-size="14">點擊「使用 Google 登入」</text>
+          <text x="400" y="213" text-anchor="middle" fill="white" font-size="12">(Firebase Authentication)</text>
+        </g>
+        <!-- 箭頭 2 -->
+        <line x1="400" y1="220" x2="400" y2="260" stroke="#2196F3" stroke-width="2" marker-end="url(#arrowhead)"/>
+        <!-- 步驟 3: 權限檢查 (分支) -->
+        <g id="step3">
+          <rect x="250" y="260" width="300" height="100" rx="10" fill="#FF9800" stroke="#F57C00" stroke-width="2"/>
+          <text x="400" y="290" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 3</text>
+          <text x="400" y="315" text-anchor="middle" fill="white" font-size="14">系統檢查使用權限</text>
+          <text x="400" y="335" text-anchor="middle" fill="white" font-size="12">檢查 Firestore 白名單</text>
+          <text x="400" y="353" text-anchor="middle" fill="white" font-size="12">檢查 Custom Claims</text>
+        </g>
+        <!-- 分支：權限檢查失敗 -->
+        <g id="step3-fail">
+          <line x1="250" y1="310" x2="120" y2="310" stroke="#F44336" stroke-width="2" marker-end="url(#arrowhead-error)"/>
+          <rect x="20" y="280" width="100" height="60" rx="8" fill="#FFEBEE" stroke="#F44336" stroke-width="2"/>
+          <text x="70" y="305" text-anchor="middle" fill="#F44336" font-size="12" font-weight="bold">❌ 拒絕</text>
+          <text x="70" y="323" text-anchor="middle" fill="#C62828" font-size="10">顯示錯誤</text>
+          <text x="70" y="336" text-anchor="middle" fill="#C62828" font-size="10">訊息</text>
+        </g>
+        <!-- 分支：權限檢查成功 -->
+        <line x1="400" y1="360" x2="400" y2="400" stroke="#4CAF50" stroke-width="3" marker-end="url(#arrowhead)"/>
+        <text x="430" y="380" fill="#4CAF50" font-size="12" font-weight="bold">✓ 通過</text>
+        <!-- 步驟 4: 重定向到個人後端 -->
+        <g id="step4">
+          <rect x="200" y="400" width="400" height="100" rx="10" fill="#2196F3" stroke="#1976D2" stroke-width="2"/>
+          <text x="400" y="430" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 4</text>
+          <text x="400" y="455" text-anchor="middle" fill="white" font-size="14">重定向到個人專屬後端</text>
+          <text x="400" y="475" text-anchor="middle" fill="white" font-size="12">j.cameo.tw/u/53288a47/</text>
+          <text x="400" y="493" text-anchor="middle" fill="white" font-size="11">(Load Balancer 自動路由)</text>
+        </g>
+        <!-- 箭頭 4 -->
+        <line x1="400" y1="500" x2="400" y2="540" stroke="#2196F3" stroke-width="2" marker-end="url(#arrowhead)"/>
+        <!-- 步驟 5: 填寫表單資料 -->
+        <g id="step5">
+          <rect x="200" y="540" width="400" height="120" rx="10" fill="#4CAF50" stroke="#388E3C" stroke-width="2"/>
+          <text x="400" y="570" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 5</text>
+          <text x="400" y="595" text-anchor="middle" fill="white" font-size="14">選擇表單並填寫患者資料</text>
+          <text x="400" y="615" text-anchor="middle" fill="white" font-size="12">• 選擇表單類型 (Form 1/2-1/2-2)</text>
+          <text x="400" y="633" text-anchor="middle" fill="white" font-size="12">• 輸入患者基本資料</text>
+          <text x="400" y="651" text-anchor="middle" fill="white" font-size="12">• 輸入診斷與病歷資訊</text>
+        </g>
+        <!-- 箭頭 5 -->
+        <line x1="400" y1="660" x2="400" y2="700" stroke="#2196F3" stroke-width="2" marker-end="url(#arrowhead)"/>
+        <!-- 步驟 6: 生成並下載表單 -->
+        <g id="step6">
+          <rect x="200" y="700" width="400" height="120" rx="10" fill="#FF9800" stroke="#F57C00" stroke-width="2"/>
+          <text x="400" y="730" text-anchor="middle" fill="white" font-size="16" font-weight="bold">步驟 6</text>
+          <text x="400" y="755" text-anchor="middle" fill="white" font-size="14">系統生成表單並提供下載</text>
+          <text x="400" y="775" text-anchor="middle" fill="white" font-size="12">• 使用 JSDOM 填入資料 (3-5 秒)</text>
+          <text x="400" y="793" text-anchor="middle" fill="white" font-size="12">• 上傳至 GCS 暫存 (3 小時)</text>
+          <text x="400" y="811" text-anchor="middle" fill="white" font-size="12">• 提供一次性下載連結</text>
+        </g>
+        <!-- 箭頭 6 -->
+        <line x1="400" y1="820" x2="400" y2="860" stroke="#2196F3" stroke-width="2" marker-end="url(#arrowhead)"/>
+        <!-- 結束：下載成功 -->
+        <g id="end">
+          <rect x="250" y="860" width="300" height="80" rx="40" fill="#4CAF50" stroke="#388E3C" stroke-width="3"/>
+          <text x="400" y="890" text-anchor="middle" fill="white" font-size="16" font-weight="bold">✅ 完成</text>
+          <text x="400" y="915" text-anchor="middle" fill="white" font-size="14">取得填好的日本醫療表單</text>
+          <text x="400" y="933" text-anchor="middle" fill="white" font-size="12">(HTML 格式，可列印或轉 PDF)</text>
+        </g>
+        <!-- 時間軸標記 -->
+        <g id="timeline">
+          <text x="680" y="60" fill="#607D8B" font-size="11">⏱️ 登入階段</text>
+          <text x="680" y="180" fill="#607D8B" font-size="11">⏱️ 約 3-5 秒</text>
+          <text x="680" y="310" fill="#607D8B" font-size="11">⏱️ 約 1 秒</text>
+          <text x="680" y="450" fill="#607D8B" font-size="11">⏱️ 約 1 秒</text>
+          <text x="680" y="600" fill="#607D8B" font-size="11">⏱️ 約 2-3 分鐘</text>
+          <text x="680" y="760" fill="#607D8B" font-size="11">⏱️ 約 3-5 秒</text>
+          <text x="650" y="900" fill="#388E3C" font-size="12" font-weight="bold">✓ 總計: 3-5 分鐘</text>
+        </g>
+        <!-- 背景裝飾 -->
+        <rect x="10" y="10" width="780" height="940" rx="15" fill="none" stroke="#E0E0E0" stroke-width="2" stroke-dasharray="10,5"/>
+      </svg>
+    </div>
+    <!-- 流程說明 -->
+    <div class="section fade-in">
+      <h2>📝 流程詳細說明</h2>
+      <div class="steps">
+        <div class="step">
+          <div class="step-number">1</div>
+          <div class="step-content">
+            <div class="step-title">造訪統一入口網站</div>
+            <div class="step-description">
+              所有使用者都從同一個網址 <strong class="text-primary">j.cameo.tw</strong> 開始。
+              這是一個「統一前端」，負責處理登入和權限檢查，但不處理個人資料。
+              <br><br>
+              <span class="badge badge-outline">技術細節</span>
+              使用 Google Cloud Load Balancer 路由，統一域名設定在 Cloud DNS。
+            </div>
+          </div>
+        </div>
+        <div class="step">
+          <div class="step-number">2</div>
+          <div class="step-content">
+            <div class="step-title">使用 Google 登入</div>
+            <div class="step-description">
+              點擊「使用 Google 登入」按鈕後，系統會透過 <strong>Firebase Authentication</strong>
+              開啟 Google 登入視窗。你可以選擇任何一個 Gmail 帳號登入。
+              <br><br>
+              <span class="badge badge-primary">安全性</span>
+              系統不會儲存你的 Google 密碼，只會取得你的 email 和名稱資訊。
+            </div>
+          </div>
+        </div>
+        <div class="step">
+          <div class="step-number">3</div>
+          <div class="step-content">
+            <div class="step-title">系統檢查使用權限</div>
+            <div class="step-description">
+              登入成功後，系統會進行兩道權限檢查：
+              <ul style="margin-top: 0.5rem; padding-left: 1.5rem;">
+                <li><strong>Firestore 白名單檢查：</strong>確認你的 email 是否在 <code>system/allowedUsers</code> 集合中</li>
+                <li><strong>Custom Claims 檢查：</strong>確認你的帳號是否有 <code>allowedService</code> 權限</li>
+              </ul>
+              <br>
+              ❌ <strong>如果檢查失敗：</strong>系統會顯示錯誤訊息，請聯絡管理員申請開通。
+              <br>
+              ✅ <strong>如果檢查通過：</strong>系統會自動進入下一步。
+            </div>
+          </div>
+        </div>
+        <div class="step">
+          <div class="step-number">4</div>
+          <div class="step-content">
+            <div class="step-title">重定向到個人專屬後端</div>
+            <div class="step-description">
+              權限檢查通過後，系統會自動重定向到你的個人專屬後端網址，例如：
+              <br>
+              <code style="display: block; background: var(--bg-main); padding: 0.5rem; border-radius: 4px; margin: 0.5rem 0;">
+                j.cameo.tw/u/53288a47/
+              </code>
+              <br>
+              其中 <code>53288a47</code> 是你的 email 經過 SHA256 雜湊後的前 8 碼，確保每位使用者都有獨立的後端服務。
+              <br><br>
+              <span class="badge badge-secondary">資料隔離</span>
+              每位使用者的資料完全獨立，不會互相影響。
+            </div>
+          </div>
+        </div>
+        <div class="step">
+          <div class="step-number">5</div>
+          <div class="step-content">
+            <div class="step-title">填寫表單資料</div>
+            <div class="step-description">
+              進入個人後端後，你可以：
+              <ul style="margin-top: 0.5rem; padding-left: 1.5rem;">
+                <li>選擇需要的表單類型（Form 1 / Form 2-1 / Form 2-2）</li>
+                <li>填寫患者基本資料（姓名、生日、地址等）</li>
+                <li>填寫診斷資料（疾病名稱、ICD-10 代碼等）</li>
+                <li>填寫病歷資訊（發病時間、治療歷程等）</li>
+                <li>勾選相關症狀（如有）</li>
+              </ul>
+              <br>
+              💡 <strong>提示：</strong>系統提供範例資料，如果不確定如何填寫，可以參考範例。
+            </div>
+          </div>
+        </div>
+        <div class="step">
+          <div class="step-number">6</div>
+          <div class="step-content">
+            <div class="step-title">生成並下載表單</div>
+            <div class="step-description">
+              點擊「生成表單」後，系統會：
+              <ul style="margin-top: 0.5rem; padding-left: 1.5rem;">
+                <li>使用 <strong>JSDOM</strong> 技術自動填入資料（3-5 秒）</li>
+                <li>將填好的 HTML 表單上傳至 <strong>Google Cloud Storage</strong></li>
+                <li>產生一個安全的下載連結（有效期 3 小時）</li>
+                <li>提供下載按鈕讓你下載表單</li>
+              </ul>
+              <br>
+              下載後的表單是 HTML 格式，你可以：
+              <ul style="margin-top: 0.5rem; padding-left: 1.5rem;">
+                <li>用瀏覽器開啟檢查內容</li>
+                <li>直接列印</li>
+                <li>轉存為 PDF（使用瀏覽器的「列印 → 儲存為 PDF」）</li>
+              </ul>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <!-- 常見情境 -->
+    <div class="section fade-in">
+      <h2>🔍 常見情境說明</h2>
+      <div class="card mb-md">
+        <h3 class="card-title">❓ 如果登入失敗怎麼辦？</h3>
+        <p class="card-text">
+          <strong>可能原因：</strong>
+        </p>
+        <ul style="padding-left: 1.5rem; color: var(--text-secondary);">
+          <li>你的 email 尚未加入白名單 → 請聯絡管理員 (bohachu@gmail.com) 申請開通</li>
+          <li>瀏覽器阻擋 popup 視窗 → 請允許彈出視窗，或系統會自動改用重定向登入</li>
+          <li>網路連線問題 → 請檢查網路並重新整理頁面</li>
+        </ul>
+      </div>
+      <div class="card mb-md">
+        <h3 class="card-title">❓ 表單生成失敗怎麼辦？</h3>
+        <p class="card-text">
+          <strong>可能原因：</strong>
+        </p>
+        <ul style="padding-left: 1.5rem; color: var(--text-secondary);">
+          <li>必填欄位未填寫 → 系統會標示哪些欄位缺少資料</li>
+          <li>日期格式錯誤 → 請使用系統提供的日期選擇器</li>
+          <li>網路連線中斷 → 請檢查網路並重試</li>
+          <li>系統暫時故障 → 請稍後再試，或聯絡管理員</li>
+        </ul>
+      </div>
+      <div class="card">
+        <h3 class="card-title">❓ 下載連結過期怎麼辦？</h3>
+        <p class="card-text">
+          下載連結有效期為 3 小時，過期後會自動刪除。
+          <br><br>
+          <strong>解決方法：</strong>重新生成表單即可（原本填寫的資料可能需要重新輸入，建議生成後立即下載）。
+        </p>
+      </div>
+    </div>
+    <!-- 安全性說明 -->
+    <div class="highlight-box fade-in">
+      <h2>🔒 安全性與隱私保護</h2>
+      <div class="grid-2">
+        <div>
+          <h3 style="color: white; margin-bottom: 1rem;">資料隔離</h3>
+          <p style="color: rgba(255, 255, 255, 0.95);">
+            每位使用者都有獨立的後端服務和資料庫，
+            其他使用者無法存取你的資料。
+          </p>
+        </div>
+        <div>
+          <h3 style="color: white; margin-bottom: 1rem;">自動刪除</h3>
+          <p style="color: rgba(255, 255, 255, 0.95);">
+            生成的表單會在 3 小時後自動刪除，
+            減少資料外洩風險。
+          </p>
+        </div>
+        <div>
+          <h3 style="color: white; margin-bottom: 1rem;">加密傳輸</h3>
+          <p style="color: rgba(255, 255, 255, 0.95);">
+            所有網路傳輸都使用 HTTPS 加密，
+            確保資料在傳輸過程中的安全。
+          </p>
+        </div>
+        <div>
+          <h3 style="color: white; margin-bottom: 1rem;">最小權限</h3>
+          <p style="color: rgba(255, 255, 255, 0.95);">
+            系統僅取得必要的 Google 帳號資訊（email、名稱），
+            不會存取其他 Google 服務資料。
+          </p>
+        </div>
+      </div>
+    </div>
+    <!-- 頁尾導覽 -->
+    <div class="section text-center fade-in">
+      <p style="font-size: 1.1rem; margin-bottom: var(--space-md);">
+        📚 想了解更多技術細節嗎？
+      </p>
+      <div style="display: flex; gap: var(--space-sm); justify-content: center; flex-wrap: wrap;">
+        <a href="system-components.html" class="btn btn-primary">查看系統元件圖 →</a>
+        <a href="deployment.html" class="btn btn-secondary">查看部署架構圖 →</a>
+        <a href="index.html" class="btn btn-outline">返回總覽</a>
+      </div>
+    </div>
+  </div>
+  <script>
+    // 頁面淡入效果
+    document.addEventListener('DOMContentLoaded', () => {
+      const fadeElements = document.querySelectorAll('.fade-in');
+      fadeElements.forEach((el, index) => {
+        el.style.opacity = '0';
+        setTimeout(() => {
+          el.style.transition = 'opacity 0.6s ease-out';
+          el.style.opacity = '1';
+        }, index * 100);
+      });
+    });
+  </script>
+</body>
+</html>

package/botrun-c/mobile-android/FIREBASE-AUTH-SETUP.md ADDED Viewed

@@ -0,0 +1,302 @@
+# 🔥 Firebase Authentication Native 設定指南
+## 📋 問題診斷
+### 錯誤訊息
+```
+Authentication service unavailable.
+```
+### 根本原因
+1. ❌ **缺少 `google-services.json`**：Android Firebase 必需檔案
+2. ❌ **LoginPage 未支援 Native**：使用 `signInWithPopup()` 只適用於 Web
+3. ⚠️ **需要整合 Capacitor Firebase plugin**：Native 環境需要特殊處理
+---
+## 🚀 解決步驟
+### **步驟 1：下載 google-services.json**
+#### 1.1 前往 Firebase Console
+https://console.firebase.google.com/
+#### 1.2 選擇專案並新增 Android App
+1. 點擊 **Project Settings** (齒輪圖示)
+2. 選擇 **General** 標籤
+3. 向下捲動到 **Your apps**
+4. 點擊 **Add app** → 選擇 **Android**
+#### 1.3 填寫 Android 套件名稱
+```
+Package name: com.botrun.c
+App nickname: Botrun Android (選填)
+```
+**重要**：Package name 必須與 `capacitor.config.ts` 中的 `appId` 一致！
+#### 1.4 下載 google-services.json
+1. 點擊 **Download google-services.json**
+2. 儲存到電腦（例如：`~/Downloads/google-services.json`）
+#### 1.5 複製到 Android 專案
+```bash
+# 從 Windows 下載資料夾複製到 WSL
+cp /mnt/c/Users/你的使用者名稱/Downloads/google-services.json \
+   /home/bigcookie/github/botrun-c/mobile-android/android/app/
+# 驗證檔案存在
+ls -la /home/bigcookie/github/botrun-c/mobile-android/android/app/google-services.json
+```
+---
+### **步驟 2：設定 SHA-1 憑證（Google 登入必需）**
+#### 2.1 產生 Debug SHA-1
+```bash
+cd /home/bigcookie/github/botrun-c/mobile-android/android
+# 產生 debug keystore 的 SHA-1
+keytool -list -v -keystore ~/.android/debug.keystore \
+  -alias androiddebugkey -storepass android -keypass android | grep SHA1
+# 複製輸出的 SHA1，例如：
+# SHA1: AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD
+```
+#### 2.2 在 Firebase Console 新增 SHA-1
+1. 回到 Firebase Console → **Project Settings**
+2. 找到剛才新增的 Android App
+3. 向下捲動到 **SHA certificate fingerprints**
+4. 點擊 **Add fingerprint**
+5. 貼上 SHA-1 並儲存
+#### 2.3 重新下載 google-services.json
+⚠️ **重要**：新增 SHA-1 後，需要重新下載最新的 `google-services.json`！
+```bash
+# 再次下載並覆蓋
+cp /mnt/c/Users/你的使用者名稱/Downloads/google-services.json \
+   /home/bigcookie/github/botrun-c/mobile-android/android/app/google-services.json
+```
+---
+### **步驟 3：修改 LoginPage 支援 Native**
+**目前程式碼問題**：
+```typescript
+// ❌ 只適用於 Web
+const result = await signInWithPopup(auth, googleProvider);
+```
+**需要改成**：
+```typescript
+// ✅ 支援 Web + Native
+if (window.Capacitor) {
+  // Native: 使用 Capacitor Firebase plugin
+  const result = await FirebaseAuthentication.signInWithGoogle();
+} else {
+  // Web: 使用 signInWithPopup
+  const result = await signInWithPopup(auth, googleProvider);
+}
+```
+#### 3.1 修改 LoginPage.tsx
+建立新版本：`web/components/LoginPage-Native.tsx`
+```typescript
+"use client";
+import { Button } from '@/components/ui/button';
+import { Bot, Mail } from 'lucide-react';
+import { useState } from 'react';
+import { signInWithPopup, signInWithCredential, GoogleAuthProvider } from 'firebase/auth';
+import { getClientAuth, googleProvider } from '@/lib/firebase';
+import { FirebaseAuthentication } from '@capacitor-firebase/authentication';
+export function LoginPage() {
+  const [isSigningIn, setIsSigningIn] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const handleGoogleSignIn = async () => {
+    console.log('[LoginPage] Google sign-in button clicked');
+    const auth = getClientAuth();
+    if (!auth) {
+      console.error('[LoginPage] Firebase Auth not initialized');
+      setError('Authentication service unavailable. Please refresh the page.');
+      return;
+    }
+    try {
+      setIsSigningIn(true);
+      setError(null);
+      // 檢測是否在 Capacitor (Native) 環境
+      const isNative = !!(window as any).Capacitor;
+      if (isNative) {
+        console.log('[LoginPage] Using Capacitor Firebase Authentication (Native)');
+        // Native: 使用 Capacitor Firebase plugin
+        const result = await FirebaseAuthentication.signInWithGoogle();
+        // 將 Capacitor 的憑證轉換為 Firebase 憑證
+        const credential = GoogleAuthProvider.credential(result.credential?.idToken);
+        // 登入到 Firebase
+        const userCredential = await signInWithCredential(auth, credential);
+        console.log('[LoginPage] ✅ Native sign-in successful:', userCredential.user.email);
+      } else {
+        console.log('[LoginPage] Using signInWithPopup (Web)');
+        // Web: 使用 signInWithPopup
+        const result = await signInWithPopup(auth, googleProvider);
+        console.log('[LoginPage] ✅ Web sign-in successful:', result.user.email);
+      }
+      // onAuthStateChanged will automatically trigger and update the UI
+    } catch (error: any) {
+      console.error('[LoginPage] ❌ Sign-in failed:', error);
+      setError(error.message || 'Sign-in failed. Please try again.');
+    } finally {
+      setIsSigningIn(false);
+    }
+  };
+  return (
+    <div className="flex h-screen w-full items-center justify-center bg-background">
+      <div className="w-full max-w-md space-y-8 px-4">
+        <div className="text-center">
+          <div className="mx-auto mb-6 flex h-20 w-20 items-center justify-center rounded-full bg-primary/10">
+            <Bot className="h-10 w-10 text-primary" />
+          </div>
+          <h1 className="mb-2 text-2xl sm:text-3xl font-bold tracking-tight">
+            Welcome to Botrun-C
+          </h1>
+          <p className="text-muted-foreground">
+            Sign in to start chatting with your AI assistant
+          </p>
+        </div>
+        <div className="space-y-4">
+          <Button
+            onClick={handleGoogleSignIn}
+            className="w-full"
+            size="lg"
+            variant="outline"
+            disabled={isSigningIn}
+          >
+            <Mail className="mr-2 h-5 w-5" />
+            {isSigningIn ? 'Signing in...' : 'Sign in with Google'}
+          </Button>
+          {error && (
+            <div className="rounded-md bg-destructive/10 p-4 text-sm text-destructive">
+              <p className="font-semibold mb-1">Sign-in Error</p>
+              <p>{error}</p>
+            </div>
+          )}
+        </div>
+        <p className="text-center text-xs text-muted-foreground">
+          By signing in, you agree to our Terms of Service and Privacy Policy
+        </p>
+        <div className="text-center">
+          <p className="text-xs text-muted-foreground/60 font-mono">
+            v.{process.env.NEXT_PUBLIC_APP_VERSION || 'unknown'}
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+---
+### **步驟 4：安裝 Capacitor Firebase Authentication**
+#### 4.1 在 web/ 安裝依賴
+```bash
+cd /home/bigcookie/github/botrun-c/web
+npm install @capacitor-firebase/authentication
+```
+#### 4.2 重新建置並同步
+```bash
+# 建置 web
+npm run build
+# 同步到 Android
+cd ../mobile-android
+npx cap sync android
+```
+---
+### **步驟 5：測試**
+#### 5.1 重新開啟 Android Studio
+```bash
+cd /home/bigcookie/github/botrun-c/mobile-android
+npx cap open android
+```
+#### 5.2 重新執行 App（點擊綠色 ▶️）
+#### 5.3 測試 Google 登入
+1. 點擊 "Sign in with Google"
+2. 應該會彈出 Google 帳號選擇畫面
+3. 選擇帳號
+4. 授權
+5. 成功登入 ✅
+---
+## 🐛 常見問題
+### ❌ 錯誤 1：`10: Developer Error`
+**原因**：SHA-1 未設定或 google-services.json 未更新
+**解決**：
+1. 確認 SHA-1 已新增到 Firebase Console
+2. 重新下載 google-services.json
+3. 重新 build
+### ❌ 錯誤 2：`MISSING_GOOGLE_SERVICES_FILE`
+**原因**：google-services.json 不存在
+**解決**：
+```bash
+# 確認檔案存在
+ls /home/bigcookie/github/botrun-c/mobile-android/android/app/google-services.json
+# 如果不存在，重新複製
+```
+### ❌ 錯誤 3：`API not enabled`
+**原因**：Google Sign-In API 未啟用
+**解決**：
+1. 前往 Firebase Console → **Authentication**
+2. 點擊 **Sign-in method** 標籤
+3. 啟用 **Google** provider
+4. 儲存
+---
+## 📚 參考資料
+- [Capacitor Firebase Authentication](https://github.com/capawesome-team/capacitor-firebase/tree/main/packages/authentication)
+- [Firebase Android Setup](https://firebase.google.com/docs/android/setup)
+- [Google Sign-In SHA-1](https://developers.google.com/android/guides/client-auth)
+---
+**建立時間**：2025-11-06
+**測試環境**：WSL + Android Studio + Firebase