設備線上報修系統
部署指南

本系統為開源公版，任何學校皆可免費複製使用，無需授權費。系統以 MIT License 釋出——可自由修改、二次部署，僅需保留原始版本的著作聲明即可。

需要準備的帳號與資訊

安裝必要工具

開啟終端機（Windows PowerShell 或 macOS Terminal），依序執行：

方法一：Fork（建議）

1. 1
   前往 github.com/begin0808/repair，點擊右上角 Fork
2. 2
   Repository name 填入您喜歡的名稱（例如 repair），點擊 Create fork
3. 3
   將 Fork 後的 Repository 複製到本機：
   

   git clone https://github.com/你的帳號/repository名稱.git cd repository名稱
4. 4
   安裝前端相依套件：
   

   npm install
5. 5
   安裝 Cloud Functions 相依套件：
   

   cd functions && npm install && cd ..

Step 1 — 建立專案

1. 1
   前往 console.firebase.google.com，點擊「建立專案」
2. 2
   輸入專案名稱（例如 yourschool-repair），完成建立（Google Analytics 可視需要開啟或關閉）

Step 2 — 開啟 Authentication（Google 登入）

1. 1
   左側選單 → Authentication → Get started
2. 2
   在「Sign-in method」頁籤，啟用 Google
3. 3
   填入「專案支援電子郵件」（管理員個人信箱），儲存
4. 4
   在「Settings」頁籤 → Authorized domains → Add domain，加入：
   你的GitHub帳號.github.io
   （例如 begin0808.github.io）

Step 3 — 開啟 Firestore Database

1. 1
   左側選單 → Firestore Database → 建立資料庫
2. 2
   位置選 asia-east1（台灣）
3. 3
   安全性規則暫時選「以測試模式啟動」，後面步驟會覆寫為正式規則

Step 4 — 新增 Web 應用程式並取得設定

1. 1
   專案首頁 → 點擊 </> 圖示（新增 Web App）
2. 2
   填入 App nickname（例如 repair-web），不需勾選 Firebase Hosting，點擊「Register app」
3. 3
   複製畫面上的 firebaseConfig 物件，待下一步驟使用：

   // 範例（每個專案的值都不同） const firebaseConfig = { apiKey: "AIza...", authDomain: "yourproject.firebaseapp.com", projectId: "yourproject", storageBucket: "yourproject.appspot.com", messagingSenderId: "123456789", appId: "1:123..." };

Step 5 — 升級至 Blaze 方案（Cloud Functions 必須）

Firebase 左下角 → 目前方案「Spark」→ 點擊升級 → 選擇 Blaze（隨用隨付）。需綁定信用卡，但一般學校使用量每月費用幾乎為 $0。

① src/lib/firebase.js — Firebase 設定 + 網域限制

將 firebaseConfig 替換為您在 Firebase Console 取得的設定，並修改 hd（Google OAuth hosted domain）為貴校網域：

② src/context/AuthContext.jsx — 後端網域驗證

③ firestore.rules — 資料庫存取規則

④ src/pages/Login.jsx — 登入頁顯示文字

⑤ src/components/Layout.jsx — 頁尾學校名稱

⑥ functions/index.js — Email 頁尾

⑦ vite.config.js — GitHub Pages 路徑

如果您的 Repository 名稱不是 repair，需要修改 base：

同時修改 src/App.jsx 第 17 行的 basename：

以及 public/404.html 第 12 行的路徑前綴：

完成後確認

存檔後可在本機預覽是否正常：

瀏覽器開啟 http://localhost:5173/你的Repository名稱/，應能看到登入頁面。

設定 GitHub Secrets（供 GitHub Actions 使用）

前往您的 GitHub Repository → Settings → Secrets and variables → Actions → New repository secret，依序新增以下 5 個 Secrets：

開啟 GitHub Pages

1. 1
   Repository → Settings → 左側 Pages
2. 2
   Source 選 GitHub Actions
3. 3
   推送程式碼觸發自動部署：
   

   git add . git commit -m "init: configure for yourschool" git push origin main
4. 4
   等待約 2 分鐘，前往 https://你的帳號.github.io/你的Repository名稱/ 確認頁面正常

Step 1 — 取得 Gmail 應用程式密碼

1. 1
   使用個人 Gmail 帳號（不是學校帳號），前往 Google 帳號安全性頁面
2. 2
   確認已開啟「兩步驟驗證」
3. 3
   搜尋「應用程式密碼」→ 輸入應用程式名稱（例如：報修系統）→ 產生 16 位密碼（去除空格後複製）

Step 2 — 登入 Firebase CLI 並設定環境變數

Step 3 — 部署所有 Cloud Functions 與 Firestore 規則

全部成功後會顯示 Deploy complete!。若遇到 IAM 權限錯誤，請參考常見問題 Q1。

建立第一位超級管理員

系統上線後，需在 Firebase Console 手動建立第一筆管理員記錄。

1. 1
   用學校帳號登入系統一次（這樣 Firebase Auth 才會有您的 UID）
2. 2
   前往 Firebase Console → Authentication → 找到您的帳號，複製 User UID（一串字母數字）
3. 3
   前往 Firestore Database → 點擊「+ 新增集合」，集合 ID 填 admins
4. 4
   文件 ID 填入剛才複製的 User UID，新增一個欄位：
   role（字串）= superadmin
5. 5
   儲存後，重新整理系統頁面，您的帳號即具備超級管理員權限

初始化地點清單

登入系統後，前往導覽列「📍 地點」，新增貴校的大樓與場域名稱。建議項目：

• 各教學大樓（例如：行政大樓、圖書館、各棟教室大樓）
• 各室外場域（操場、籃球場、網球場、停車場…）
• 其他重要地點（游泳池、禮堂、體育館…）

報修者選擇大樓後，可在「詳細位置」欄自由填寫，不需為每間教室都建一筆資料。

新增總務人員帳號

1. 1
   請總務人員先以學校帳號登入系統一次
2. 2
   超級管理員前往「👥 帳號」頁面
3. 3
   輸入總務人員的學校 Email，選擇角色「總務人員（admin）」，點擊新增

Q1：部署 Cloud Functions 時出現 IAM 權限錯誤

錯誤訊息通常為「Access to bucket gcf-sources-... denied」。解決步驟：

1. 1
   前往 GCP IAM Console，選擇您的 Firebase 專案
2. 2
   找到 XXXXXXXX-compute@developer.gserviceaccount.com 這個服務帳號
3. 3
   點擊編輯，新增角色：Storage 物件檢視者（Storage Object Viewer）
4. 4
   儲存後重新執行 firebase deploy --only functions

Q2：登入後出現「登入失敗」或 OAuth 錯誤

請確認 Firebase Authentication → Settings → Authorized domains 中已加入 你的帳號.github.io（不含 https://）。若使用自訂網域，也需要加入自訂網域。

Q3：Email 通知未收到

• 確認 firebase functions:config:set 時 Gmail 密碼已去除空格（16 碼，無空格）
• 確認 Gmail 帳號已開啟「兩步驟驗證」再產生應用程式密碼
• 到 Firebase Console → Functions → Logs 查看錯誤訊息
• Email 可能被歸類到垃圾郵件，請通知收件人檢查

Q4：部署後頁面空白或路由錯誤

• 確認 vite.config.js 的 base 與 Repository 名稱完全一致
• 確認 src/App.jsx 的 basename 也一致
• 確認 public/404.html 中的路徑前綴也已修改
• 修改後需重新 git push 觸發重新部署

Q5：學校使用 Microsoft 帳號，能否支援？

目前版本僅支援 Google Workspace 帳號。若學校使用 Microsoft 365 / Outlook，需要將 Firebase Auth 的 Google Provider 改為 Microsoft Provider，並對應修改網域驗證邏輯。這屬於較進階的修改，建議有開發能力的人員協助處理。

Q6：如何取得原始 Repository 的最新更新？

合併後請重新檢查您自訂的學校設定是否被覆蓋，必要時重新修改。