📖 新生命聖經速讀計畫 (NewLife Bible Speed Reading)
📱 隨身讀經打卡・社群關心互動・遊戲化成就系統
本專案為 新生命小組教會（New Life Church, NLC） 會友量身打造的聖經速讀 PWA（漸進式網頁應用程式）。整合 NLC (紟道) 生態系 SSO 登入，提供流暢的聖經閱讀、進度追蹤、團隊進度管理、靈修筆記寫作與小組社群關懷功能，以遊戲化的方式激勵會友一同建立每日讀經的好習慣。
🗺️ 系統介面與架構導覽
本應用程式採用單頁式應用（PWA）架構，主要包含以下五大功能區塊：
graph TD
A[新生命聖經速讀 App] --> B[🏠 首頁 Dashboard]
A --> C[📖 讀經 Reader]
A --> D[📅 計畫 Plan]
A --> E[👤 個人 Profile]
A --> F[⚙️ 管理 Admin]
B --> B1[今日金句 & 教會公告]
B --> B2[個人靈修筆記寫作]
B --> B3[牧區靈修分享牆]
C --> C1[三種譯本切換 CUNP / RCUV / CUV]
C --> C2[語音朗讀 TTS - 台灣女聲]
C --> C3[文字大小調整 & 劃記螢光筆]
D --> D1[進行中讀經計畫詳情]
D --> D2[每日任務打卡清單]
D --> D3[讀經統計: 個人熱力圖 / 團隊進度表]
D --> D4[讀經小隊競賽]
E --> E1[個人基本資料設定]
E --> E2[主題切換: 白天 / 深色]
E --> E3[榮譽徽章牆 & 煙火特效]
E --> E4[離線快取狀態指示]
F --> F1[組織架構管理 大區/牧區/小組]
F --> F2[會友角色與權限設定]
F --> F3[讀經計畫發布與規則調整]
🚀 核心功能操作指引
以下針對系統的 6 大核心功能，提供詳細的操作步驟與設計機制說明：
1. 參與計畫
- 功能說明：瀏覽並加入教會官方發布的季度速讀計畫，或建立個人自訂計畫，開始記錄讀經進度。
- 操作步驟：
- 點擊底部導覽列的 「計畫」 頁籤。
- 系統會顯示「進行中計畫」與下方「可加入的計畫」清單。
- 選擇您想參與的計畫，點選右下角的 「加入計畫」（或點選 「預先加入」，針對尚未正式開始的計畫）。
- 系統將彈出「設定每週讀經安排」對話框，供您自訂進度。
- 點選 「確認加入」 後，系統將自動為您生成每日讀經章節清單，並可於計畫首頁開始打卡。
-
💡 小撇步：
- 固定日期計畫：教會官方的季度速讀計畫通常有明確的起訖日期，系統會自動在時間內平均分配章節。
- 非固定日期計畫：自訂計畫無時間限制，系統會依據您勾選的讀經日，按順序為您每天安排進度。
2. 加入團隊
🔹 新建團隊
- 功能說明：小隊發起人（隊長）建立一個新的讀經團隊，並生成專屬邀請碼供隊員加入，共同組隊挑戰讀經。
- 操作步驟：
- 進入 「計畫」 頁籤，點選您已加入的計畫進入詳情。
- 在團隊區塊中點選 「查看讀經小隊」。若該計畫您尚未有團隊，點選 「＋ 建立團隊」。
- 依序填入 「團隊名稱」（必填）、「團隊簡介」。
- 點選 「確認建立」，系統將即時在資料庫中註冊團隊，並在畫面上顯示一組 6 位數專屬邀請碼（如：
ABC123）。
-
💡 提示：
建立團隊的創立者將自動成為「隊長」，擁有管理團隊名單、移出成員或解散團隊的權限。
🔹 使用邀請碼加入
- 功能說明：隊員輸入隊長分享的 6 位數邀請碼，加入指定讀經團隊，與隊友一同賽跑。
- 操作步驟：
- 前往 「計畫」 頁籤的計畫詳情，在團隊區塊點選 「加入團隊」。
- 在彈出的輸入框中，輸入隊長分享的 6 位數團隊邀請碼。
- 系統會自動檢索並顯示該團隊的名稱、簡介及現有成員。
- 確認資訊無誤後，點選 「加入」 按鈕，即可完成與該團隊的綁定。
-
💡 提示：
- 在同一個讀經計畫中，一個帳號同時只能加入一個團隊。若要換隊，請先請隊長將您移出目前團隊，或聯繫系統管理員協助。
3. 調整讀經休息日
- 功能說明：根據個人的生活節奏，在設定中調整每週要讀經的天數及固定的休息日，系統將自動為您彈性重排章節。
- 操作步驟：
- 進入 「計畫」 頁籤，點選右上角的 「⋯」計畫選項 圖示。
- 從選單中點選 「調整讀經日」。
- 在彈出視窗的 「一週想讀經幾天」 下拉選單中，選擇每週的讀經天數（1 到 7 天）。
- 在下方 「固定休息星期」 網格中，勾選您要作為休息日的星期（例如週六、週日）。
- 點選 「儲存安排」，系統會提示「每週讀經安排已更新，章節已重新分配」，並立即重新運算並更新進度表。
-
💡 注意事項：
- 為確保計畫能在目標時間內完成，一週至少需要保留 1 天讀經，系統不允許將 7 天都設為休息日。
- 在休息日當天，計畫主畫面會顯示溫馨的 「休息日橫幅」（「今天是補讀與休息日，好好親近神吧」），此時可點擊補讀先前落後的章節。
4. 戳一下隊友
- 功能說明：當隊友讀經進度落後或今天尚未打卡時，利用溫馨互動機制發送關懷提醒或打氣訊息。
- 操作步驟：
- 進入 「計畫」 頁籤，點選 「查看讀經小隊」 查看成員進度列表。
- 瀏覽成員，在有落後或未打卡的隊友右側，點擊 「戳一下（紙飛機/鈴鐺）」 圖示。
- 系統將開啟 「關心提醒」 對話框，並自動依據其狀態（落後、久未打卡、進度穩定）自動推薦關心原因。
- 選擇關心類別：
- 📉 進度落後（落後時自動預設）
- 😴 很久沒打卡（多日未讀時自動預設）
- 💛 一般關心
- 🌟 特別鼓勵（對方進度超前時推薦使用）
- 系統會自動帶入對應的溫馨簡訊內容，您可以直接點擊傳送，或於框內修改自訂文字（長度限制 1 ~ 300 字）。
- 點選 「傳送關心」，送出後畫面下方會彈出 Toast 提示：「已傳送關心提醒給 [隊友姓名] 💛」。
-
💡 注意事項（次數限制）：
- 為避免頻繁通知造成打擾，系統在資料庫層設有嚴格的限制：同一個發送者每天只能對同一個隊友（就同一個計畫）發送一次關心提醒（資料庫有每日唯一性限制）。再次點擊將會提示已達到每日上限。
5. 檢視組員狀況（管理權限/隊長視角）
- 功能說明：供隊長、小組長、牧區長或系統管理員檢視所屬範圍內所有成員的讀經進度、出席狀況與詳細數據。
- 操作步驟：
- 隊長/組員視角（小隊內進度）：
- 進入 「計畫」 頁籤，點選 「查看讀經小隊」。
- 成員名單中會以極具設計感的彩色進度條，顯示每位成員的累計讀經遍數、章節進度百分比以及最後閱讀時間。
- 小組長/牧區長視角（跨組進度）：
- 前往 「計畫」 頁籤的計畫詳情，點選 「統計」 子頁籤。
- 切換篩選範圍（個人 / 小組 / 牧區）。
- 系統會顯示 「大區/牧區/小組排行表」，並載入所有成員的詳細數據表（包含姓名、所屬小組、累計讀經章節、進度百分比、最後閱讀時間）。
- 當滑動到對應成員時，亦可點擊發起關懷提醒。
-
💡 提示：
- 非管理職的一般會友僅能檢視同小隊的隊友百分比進度；具備小組長、牧區長或行政管理員權限的使用者，才能看到完整的跨組打卡名單與歷史統計圖表。
6. 白天 / 深色（晚上）模式切換
- 功能說明：快速切換應用程式佈景主題，在強光下使用明亮主題，在夜間或暗處閱讀時切換為深色主題保護眼睛。
- 操作步驟：
- 點選底部導覽列的 「個人」 分頁。
- 進入個人頁後，頂部導覽列右側會顯示 「切換主題」（太陽 / 月亮）按鈕（此按鈕在其他分頁會自動隱藏，以確保閱讀聖經時視覺的極簡無干擾）。
- 點擊該按鈕：
- 若目前為白天，點擊後會轉換為 深色模式（Dark Theme）。
- 若目前為深色，點擊後會轉換為 白天模式（Light Theme）。
-
💡 小撇步：
- 主題設定會自動寫入瀏覽器的
localStorage 中，每次重新開啟應用程式時會自動沿用。
- 暖心褐色模式（Warm Sepia）：在 「讀經」 閱讀器中，另提供專門為長時間看螢幕設計的「暖心褐色模式」，可與系統的白天/深色模式分開設定。
✨ 更多實用功能分析
除了上述核心功能外，本專案還包含以下豐富的輔助功能：
7. 沉浸式聖經閱讀與語音朗讀
- 功能說明：提供心靈平靜、專注內容的讀經頁面，支援多譯本、字型縮放及台灣語音合成（TTS）朗讀。
- 操作步驟：
- 點選底部導覽列的 「讀經」 分頁。
- 頂部工具列功能：
- 譯本切換：點擊譯本按鈕（如 CUNP），可在 「新標點和合本 (CUNP)」、「和合本修訂版 (RCUV)」 及 「官話和合本 (CUV)」 之間循環切換。
- 字型大小：點選 「A+ / A-」 即時縮放文字，提供最舒適的視覺大小。
- 語音朗讀：點擊 「喇叭」 圖示，系統會調用 Web Speech API，以流暢的台灣中文語音（
zh-TW）自動為您朗讀整章聖經，再次點擊可隨時停止。
- 螢光筆劃記：長按或用滑鼠拖曳選取經文，即可為特定經文標記彩色螢光筆，劃記記錄會即時儲存至雲端。
-
💡 小撇步：
閱讀器在無網路連線時，會自動調用本地的聖經備份文字（BIBLE_FALLBACK），確保離線時閱讀不中斷。
8. 靈修心得寫作與牧區分享牆
- 功能說明：在每日讀經任務完成後，記錄靈修心得，並可選擇將心得分享至所屬牧區，與弟兄姊妹在分享牆上互動、按讚、留言。
- 操作步驟：
- 完成當日讀經任務後，在計畫首頁點選 「寫靈修心得」。
- 輸入您的心得內容。系統會透過專門的安全性防禦控制器（
DevotionalSharingController）過濾任何惡意 HTML 標籤（XSS 防禦）。
- 勾選 「分享到牧區分享牆」 後點擊儲存。
- 儲存後，小組與牧區成員可在 「首頁」 的 「牧區靈修分享牆」 看到您的分享，並可對您的心得點擊 「愛心按讚」 或 「回覆留言」。
-
💡 小撇步：
個人首頁會特別統計您的 「每日穩定靈修天數」，幫助您記錄屬靈生命的穩定度。
9. 個人熱力圖與統計圖表
- 功能說明：以視覺化的圖表與 Github 風格的讀經熱力圖（Heatmap），完整記錄並呈現您的讀經軌跡。
- 操作步驟：
- 進入 「計畫」 分頁的計畫詳情，切換至 「統計」 子頁籤。
- 點選 「個人統計」：
- 讀經熱力圖：顯示過去 365 天每天的讀經打卡狀態，綠色格子越深代表當天讀經量越多。
- 連續天數：顯示目前的連續讀經天數（Streak）以及歷史最高紀錄，激勵您維持每日進度。
- 完成百分比：以 Chart.js 圓餅圖/進度條顯示目前計畫的總體完成率。
-
💡 提示：
熱力圖強度分為 5 個等級（monochrome ramp），隨著每日讀打卡章節數增加，顏色會從淺灰色漸進變為深綠色。
10. 遊戲化徽章牆與解鎖特效
- 功能說明：透過豐富的遊戲化機制，當完成階段性計畫或特定挑戰時，會解鎖對應的榮譽徽章，並觸發全螢幕煙火特效。
- 操作步驟：
- 當您勾選完某個計畫階段的最後一章聖經，系統會進行背景判定。
- 若判定成功晉級，畫面會即時解鎖專屬徽章（如：新生命聖經速讀計畫季度獎章），並在畫面上觸發 Canvas 全螢幕粒子煙火特效（Fireworks）。
- 解鎖的徽章會同步記錄在您的帳號中，您可隨時點選 「個人」 分頁 -> 切換至 「徽章」 頁籤，進入 「我的榮譽徽章牆」 檢視所有已解鎖與鎖定中的徽章細節與解鎖日期。
11. 離線讀經與背景自動同步 (Offline PWA)
- 功能說明：支援無網路環境下的正常操作。在離線狀態下讀經與打卡，待恢復連線後，系統會自動在背景將進度同步回雲端資料庫。
- 操作步驟：
- 當手機或電腦斷網時，頂部導覽列左側會自動亮起紅色的 「離線模式」 狀態燈（Connection Status Badge）。
- 您仍可照常使用 「讀經」 閱讀聖經，並在 「計畫」 中點選複選框進行每日打卡。
- 您的打卡記錄會被安全地暫存在瀏覽器的本地資料庫（IndexedDB）中。
- 當您的設備重新連接到網路時，狀態燈會變為綠色，系統的
PwaCoordinator 與背景同步（Background Sync）機制會自動把暫存的打卡日誌同步回 Supabase，無須手動重整。
🛠️ 開發與部署快速參考
如果您是教會的資訊同工（IT Personnel），想要在本地運行或部署此專案，請參考以下資訊：
本地開發步驟
- 複製設定檔：將根目錄的
.env.example 複製一份並命名為 .env。
- 填寫 Supabase 與 SSO 參數：
SUPABASE_URL=你的Supabase網址
SUPABASE_ANON_KEY=你的Supabase Anon Key
NLC_CLIENT_ID=你的SSO Client ID
NLC_ISSUER=你的SSO授權端點
- 建置（產生 config.js 並打包到
dist/；每次修改環境變數後都要重跑）：
npm run build
- 在瀏覽器開啟建置結果（
npm run dev 直接服務原始碼，無法載入 App）：
npx serve dist
- 跑測試：
npm test。
架構與快取防禦機制（重要）
- 原生 JS／CSS，由 esbuild 打包：沒有前端框架；
scripts/bundle.mjs 把程式打包成帶內容雜湊檔名的檔案。入口檔的 import 順序有嚴格要求，請勿隨意更動。
- 快取控制：檔名已經帶內容雜湊，不要手動在 import、
<script>、<link> 加 ?v=（有測試會擋）。細節見 docs/pwa-architecture.md。
📄 授權
- 本 repo 內的經文、注釋翻譯與圖示等第三方內容，來源與授權見
NOTICE。其中 Tyndale Open Study Notes 的中文翻譯以 CC BY-SA 4.0 釋出。
- 程式碼目前沒有附開源授權：可以閱讀，但未授權他人使用或散布。
希望這份操作手冊能幫助您快速上手 新生命聖經速讀計畫！祝您讀經有得著，與弟兄姊妹一同在真道上長進！ 💛
