學校設備線上報修系統

01 · 技術架構

層面	技術選擇	說明
前端框架	React + Vite	元件化開發、建置速度快
UI / 樣式	Tailwind CSS + shadcn/ui	行動優先設計、快速切版
資料庫	Firebase Firestore	即時同步、無需自建伺服器
使用者驗證	Firebase Auth + Google OAuth	學校 Google Workspace 帳號直接登入
後端排程	Firebase Cloud Functions	寄信通知、自動封存舊資料
Email 服務	Gmail + Nodemailer	報修通知信件寄送（Cloud Functions）
佈署	GitHub Pages	原始碼存放於 GitHub，自動部署

ℹ

登入時限制僅允許學校 Google Workspace 網域帳號，其他帳號登入後自動拒絕存取並顯示錯誤提示。

02 · 使用者角色與權限

👤

一般使用者（學生 / 教師 / 行政）

Google 登入（學校帳號）
瀏覽全部報修清單（唯讀）
提交新報修單
修改或取消自己提交的「待處理」單
查看歷史紀錄與搜尋
完成時收到 Email 通知

🔧

總務處人員（管理員）

以上所有一般使用者權限
將狀態改為「處理中」或「已完成」
填寫完成修繕說明與備注
刪除任意筆報修資料
取消封存歷史紀錄
有新報修單時收到 Email 通知

⭐

超級管理員（總務主管）

以上所有管理員權限
新增 / 移除總務人員帳號
設定 / 編輯報修地點清單
新增 / 停用建築棟別與樓層房號
系統設定（學校名稱、網域）
帳號只有一位，預設寫入 Firestore

角色識別方式

採用 Firestore 管理員名單方案，在 admins/{uid} 集合中以 role 欄位區分："admin"（總務人員）與 "superadmin"（主管）。登入時查詢確認身份，無需 Google Workspace Admin SDK。

⭐

公版設計：超級管理員可在後台自行設定學校名稱、允許登入的 Google 網域、地點清單，讓此系統能直接套用至其他學校，無需改動程式碼。

03 · 報修狀態流程

📋 待處理

→

🔨 處理中

→

✅ 已完成

→

📦 封存

• 待處理 → 處理中：僅限總務人員操作

• 處理中 → 已完成：僅限總務人員操作，需填寫完成說明，系統自動 Email 通知提交者

• 待處理 → 取消：提交者本人或總務人員可操作

• 已完成 → 封存：完成滿 12 個月後由系統自動封存，總務人員可手動取消封存

04 · Firestore 資料結構

📄 repairs / {repairId}

基本資訊

id title（標題） location（地點） building（棟別） floor（樓層） room（房號） category（類別） description（說明） priority（普通/緊急）

狀態

status archived（布林）

提交者資訊

submittedBy（UID） submitterName submitterEmail submittedAt

處理資訊（總務填寫）

assignedTo inProgressAt completionNote completedBy completedAt archivedAt

👥 admins / {uid}

uid email name role（admin / superadmin） addedAt addedBy

📍 locations / {locationId}

id name（地點名稱） building（棟別） floor（樓層） room（房號/區域） active（是否啟用） createdAt createdBy

由超級管理員維護，提交報修時從清單選取，確保地點名稱統一。

🏷 categories（固定清單）

電器設備水電管線門窗玻璃桌椅傢俱空調冷氣資訊設備環境清潔其他

🔑 索引建議（Firestore Index）

• status + submittedAt（主清單排序）

• archived + completedAt（歷史封存查詢）

• submittedBy + submittedAt（個人記錄查詢）

• category + status（分類篩選）

05 · 搜尋、篩選與分頁

搜尋條件（可組合使用）

文字搜尋

標題、地點、說明關鍵字

狀態篩選

待處理 / 處理中 / 已完成

類別篩選

8 大修繕類別

日期範圍

自訂開始 / 結束日期

地點篩選

棟別 / 樓層

我的報修

僅顯示自己提交的項目

⚡

分頁機制：每頁顯示 20 筆，使用 Firestore 的 startAfter() 游標分頁，搭配「上一頁 / 下一頁」按鈕。日期範圍搜尋讓使用者可以快速找到特定月份的報修單，不需一直翻頁。

06 · Email 通知機制

📬 通知 1：新報修提交

觸發時機：任何人提交新報修單

收件者：所有總務人員

內容：報修標題、地點、類別、提交者、提交時間、報修說明、連結

技術實作：Cloud Functions onDocumentCreated 觸發器

📬 通知 2：修繕完成

觸發時機：總務人員將狀態改為「已完成」

收件者：原始提交者

內容：報修標題、完成時間、完成說明、處理人員、連結

技術實作：Cloud Functions onDocumentUpdated 觸發器（偵測 status 欄位變更）

✉

Email 服務：使用 SendGrid 免費方案（每天 100 封，每月 3,000 封），以學校報修量完全足夠。透過 Firebase Cloud Functions 呼叫 SendGrid API 發送。

07 · 歷史紀錄與自動封存

封存策略：軟封存（推薦）

所有資料永久保留於 Firestore，僅以 archived: true 標記，主清單預設不顯示封存資料。

自動封存觸發

Firebase Cloud Functions 每週一凌晨 2:00 執行排程
查詢 status = "completed" 且 completedAt 超過 12 個月 的資料
批次寫入 archived: true 與 archivedAt 時間戳

歷史紀錄頁面

顯示所有 archived: true 的資料
支援完整搜尋、篩選、分頁（同主清單）
所有人均可查看（唯讀）
總務人員可手動「取消封存」，讓資料回到已完成清單

未來擴充（選配）

統計報表：每月報修量、平均處理天數、常見類別圖表
匯出 CSV 供行政使用

08 · 頁面規劃

登入頁公開

Google 帳號登入按鈕、學校名稱、說明文字。非學校帳號顯示拒絕訊息。

報修清單（主頁）登入後

顯示所有未封存報修單，支援篩選、搜尋、分頁（20筆/頁）。各狀態以顏色區分。

提交報修單登入後

填寫表單：標題、地點（從清單選取）、類別、優先級、說明。地點清單由超級管理員維護。

報修詳情登入後

完整顯示報修資訊與處理紀錄。提交者可修改/取消（待處理狀態）。總務人員可更新狀態、填寫完成說明、刪除。

歷史紀錄登入後

封存資料查詢頁，支援日期範圍、狀態、類別篩選。總務人員可取消封存。

管理員後台總務專用超級管理員

總務人員帳號管理（新增/移除/角色設定）。超級管理員專屬：報修地點清單維護（新增/編輯/停用棟別與房號）、系統基本設定（學校名稱、允許登入網域）。未來可擴充報修統計圖表。

09 · Firebase 費用分析

服務	免費額度	預估用量（月）	狀態
Firestore 讀取	50,000 次/天	~5,000 次	✓ 免費
Firestore 寫入	20,000 次/天	~500 次	✓ 免費
Cloud Functions	125,000 次/月	~200 次	✓ 免費
Auth 驗證	無限制	—	✓ 免費
Gmail 寄信（Nodemailer）	無上限（Gmail App Password）	~60 封	✓ 免費
GitHub Pages	無限制（公開專案）	—	✓ 免費

💰

整體費用：$0。以一所高中的報修量，所有服務皆在 Firebase 免費方案（Spark）額度範圍內。本系統不使用 Firebase Storage（無照片功能），費用更低。

10 · 佈署與開發流程

📦 GitHub 專案結構

          repair-system/

          ├── src/

          │   ├── components/

          │   ├── pages/

          │   ├── hooks/

          │   └── lib/ (firebase)

          ├── functions/ (Cloud Functions)

          ├── public/

          └── firebase.json

🚀 自動部署流程

1. 開發者 push 到 main 分支

2. GitHub Actions 自動執行 build

3. 建置產物推送至 gh-pages 分支

4. GitHub Pages 自動發布

Firebase 規則（Security Rules）也納入版本控管，透過 CI/CD 自動部署。

11 · 建議開發分期

核心功能（第一期）

Google 登入 + 網域驗證
報修清單（主頁）+ 分頁
提交報修單（含地點選單）
報修詳情 + 狀態更新
管理員識別與刪除權限

通知與搜尋（第二期）

Cloud Functions Email 通知（新報修 + 完成通知）
搜尋與多條件篩選
歷史紀錄頁面
自動封存排程

進階功能（第三期，選配）

管理員後台：總務人員帳號管理
地點管理：棟別 / 樓層 / 房號 CRUD（超級管理員）
系統設定：學校名稱、允許登入網域（公版化）
報修統計圖表 / 匯出 CSV
PWA 支援（手機可加入主畫面）

12 · 響應式設計斷點

📱

手機

< 640px
單欄佈局
底部導航列
大觸控按鈕

📟

平板

640px – 1024px
雙欄佈局
側邊抽屜選單

🖥

桌機

> 1024px
側邊欄固定
三欄卡片清單