Tavric's Blog

Hynan 介紹

Sun, 16 Aug 2026 00:00:00 GMT

App 介紹

Hynan 是一個以每日工作流為核心的任務管理 App，適合用來整理待辦、安排日期、撰寫每日筆記，並透過標籤、工作區與 Google Calendar 同步來管理不同情境下的工作內容。

這個 App 使用 Vue 3、Pinia、Vue Router、Vite、Supabase Auth、Supabase Postgres 與 Supabase Edge Functions 開發。前端支援 PWA，可以安裝到桌面或手機使用；後端透過 Supabase 儲存使用者資料，並使用 RLS 保護每位使用者只能讀寫自己的資料。

核心功能

Google 登入

使用者可以透過 Google 帳號登入。登入後，任務、標籤、每日筆記與工作區資料會與 Supabase 帳號綁定。

Demo 模式

App 提供 Demo 路由，使用者可以在不登入的情況下體驗主要功能。Demo 資料保存在本機，不會寫入正式 Supabase 資料庫。

Inbox 任務管理

Inbox 用來集中管理所有尚未完成的任務。任務會依狀態分組，例如無日期、逾期、今天與未來，方便快速判斷接下來要處理什麼。

每日任務

每日頁面可以查看指定日期的任務。使用者可以替任務設定日期、時間、時區與預估時長，並在同一天的工作流中集中處理。

每日筆記

Journal 頁面支援每日筆記。每一天都有自己的筆記內容，適合記錄日誌、會議摘要、工作回顧或臨時想法。

標籤分類

任務可以加入多個標籤。使用者可以建立、編輯、刪除標籤，並從標籤頁面查看某個標籤底下的所有任務。

多 Workspace

Hynan 支援多 workspace。每位使用者會有一個 main workspace，也可以建立其他 workspace，用來區分不同專案、生活領域或工作情境。

任務詳情面板

點選任務後可以開啟詳情面板，編輯任務標題、完成狀態、日期、時間、時長與標籤。

Google Calendar 同步

Hynan 可以連接 Google Calendar。有日期的任務會同步成 Google Calendar 事件；沒有日期的 Inbox 任務會留在 Hynan，不建立日曆事件。

主 workspace 會使用名為 Hynan 的 Google Calendar，其他 workspace 會使用 workspace 名稱建立或對應專用行事曆。

離線與本機快取

App 有本機快取與離線佇列設計。網路不穩時可以先保留本機資料，恢復連線後再同步到 Supabase。

即時同步

Supabase Realtime 會監聽 workspaces、tasks、tags、daily_entries 等資料表，讓資料更新能更即時反映在 App 中。

PWA 安裝

Hynan 支援 PWA。正式部署後，使用者可以透過瀏覽器安裝到桌面或手機，獲得接近原生 App 的使用體驗。

主要頁面

登入頁，提供 Google 登入與進入 Demo 模式。

Inbox

集中查看尚未完成的任務，包含無日期、逾期、今天與未來任務。

Daily

查看某一天的任務，也可以透過日期切換不同日期。

Journal

撰寫與查看每日筆記。

Tag Detail

查看指定標籤底下的任務。

資料表

workspaces

儲存使用者的工作區。每位使用者會有一個 main workspace，也可以新增其他 workspace。

tasks

儲存任務資料，包含標題、完成狀態、日期、時間、標籤、排序、workspace、Google Calendar 同步狀態等。

daily_entries

儲存每日筆記內容。

google_calendar_connections

儲存使用者 Google Calendar 連線狀態與加密後的 refresh token。

google_calendar_workspace_calendars

儲存每個 workspace 對應的 Google Calendar。

google_calendar_sync_queue

儲存待同步到 Google Calendar 的任務變更佇列。

Wordat 介紹

Sun, 16 Aug 2026 00:00:00 GMT

Wordat 是一個 Local-first 的英文單字學習本，適合用來建立個人字庫、整理單字意思、例句與分類，並透過搜尋、篩選、排序和統計快速回顧學習狀態。

此 App 以 Vite、React、TypeScript 和 Tailwind CSS 開發，資料預設儲存在瀏覽器的 localStorage，不需要登入或後端資料庫即可使用。專案也具備 PWA 與離線快取能力，部署後可在支援的瀏覽器中安裝成接近原生 App 的使用體驗。

核心特色

Local-first 資料儲存：單字與分類存在使用者本機瀏覽器，操作快速，不依賴伺服器。
PWA 離線支援：透過 Service Worker 快取 App 資源，已載入後可支援離線使用與更新提示。
單字 CRUD：可新增、編輯、刪除單字。
一字多義：同一個英文單字可保存多組詞性、中文意思、例句與分類。
重複單字處理：新增已存在單字時，可選擇取代既有字義、加入新字義，或只累計重複次數。
分類管理：可新增、編輯、刪除自訂分類，並為分類配置顏色。
搜尋與篩選：支援全域搜尋、分類篩選、A-Z 首字母篩選。
排序功能：可依 A-Z、最近新增、重複次數排序。
TTS 發音播放：使用瀏覽器語音合成功能播放英文單字發音。
儀表板統計：顯示總單字量、累計重複次數、最不精熟單字，以及概覽字卡。
單字清單：以表格化清單呈現單字、詞性、意思、例句、重複次數與操作按鈕。
備份匯出與匯入：可匯出 JSON 備份檔，也可匯入既有備份合併資料。
深色 / 淺色模式：支援主題切換，並記住使用者偏好。
響應式介面：桌面使用側邊欄，手機使用抽屜式導覽。

主要畫面

單字清單

單字清單是主要工作區，提供新增單字、搜尋、分類篩選、字母篩選、排序、分頁、編輯與刪除操作。每筆單字可包含多個字義，每個字義可獨立設定詞性、意思、例句與分類。

儀表板

儀表板用於快速掌握目前字庫狀態，包含總單字量、累計重複次數、最不精熟單字，並以字卡方式展示目前篩選條件下的單字概覽。

分類管理

分類管理可建立自己的學習分類，例如 TOEIC、日常、商務、學校、易混淆字等。分類可被套用到單字或單一字義上，方便後續篩選與複習。

備份與還原

Wordat 的資料存在瀏覽器本機，因此建議定期使用匯出功能保存 JSON 備份。更換瀏覽器、清除網站資料或換裝置時，可使用匯入功能恢復或合併資料。

技術架構

前端框架：React
開發工具：Vite
語言：TypeScript
樣式：Tailwind CSS
PWA：vite-plugin-pwa
資料儲存：localStorage
語音播放：Web Speech API

使用限制

資料預設只存在目前瀏覽器與目前網域，不會自動同步到其他裝置。
如果清除瀏覽器網站資料，localStorage 內的單字資料可能會被刪除。
TTS 發音品質與可用語音取決於使用者的瀏覽器與作業系統。
離線功能需先成功開啟過 App，讓瀏覽器完成必要資源快取。

Tabin 介紹

Sun, 16 Aug 2026 00:00:00 GMT

Tabin 是一個以新分頁為使用情境設計的書籤管理 App。它把常用網站整理成資料夾和圖示網格，讓使用者可以用更接近桌面啟動器的方式管理連結。

主要用途

Tabin 適合用來整理日常工作、學習、專案或個人常用連結。使用者可以建立資料夾，把書籤分門別類，並在瀏覽器新分頁中快速開啟常用網站。

核心功能

書籤管理：新增、編輯、刪除書籤。
資料夾管理：新增、編輯、刪除資料夾。
分類檢視：可切換「所有」或指定資料夾查看書籤。
圖示網格：書籤以 favicon 圖示和名稱呈現，方便快速辨識。
favicon 來源 fallback：會依序嘗試 Apple touch icon、SVG favicon、ICO favicon、DuckDuckGo 與 Google favicon 來源。
拖曳排序：書籤可以在目前檢視中拖曳排序。
匯入/匯出備份：可匯出 JSON 備份，也可匯入備份恢復資料。
本機資料保存：App 資料儲存在瀏覽器本機，不需要後端服務。
Chrome 新分頁導向：extension 資料夾提供一個簡單 Chrome extension，可把新分頁導向部署後的 Tabin 網址。

技術架構

前端框架：React
建置工具：Vite
語言：TypeScript
圖示：lucide-react
資料儲存：瀏覽器 localStorage
部署目標：Vercel 或其他靜態網站平台

資料與隱私

Tabin 預設不需要登入，也不會把書籤資料送到伺服器。書籤、資料夾與設定會存在使用者目前瀏覽器的 localStorage。若更換裝置或清除瀏覽器資料，請先使用匯出功能備份。

適合的使用方式

作為個人的瀏覽器新分頁首頁。
管理工作常用工具、文件、服務後台和專案連結。
透過 JSON 備份在不同環境間搬移書籤資料。
部署成公開或私人 Vercel 網址，再搭配 Chrome extension 使用。

部署教學

Sun, 16 Aug 2026 00:00:00 GMT

1. Fork GitHub repo

步驟	操作	推薦
1	Fork 這個 repo 到自己的 GitHub	用要部署的 GitHub 帳號
2	確認 repo 有 `main` / `dev` 分支	之後 push 會觸發 GitHub Actions
3	先不要急著 deploy	先把 Firebase、GCP、IAM、Secrets 設好

2. 建 Firebase / Google Cloud project

步驟	操作	推薦
1	在 Google Cloud Console 建 project	Project ID 用正式、短、好辨識的名字
2	綁定 Billing	Functions / Cloud Build / Artifact Registry 會需要
3	到 Firebase Console，把 Firebase 加到同一個 project	不要另開不同 project
4	建立 Firebase Web App	之後要複製 config 到 GitHub Secrets

3. Firebase Console 要自己建立或啟用的項目

項目	操作	推薦
Authentication	啟用 Google provider	Authorized domains 加上正式 Hosting 網域
Firestore Database	建 Native mode database	台灣使用者建議 `asia-east1`
Cloud Storage for Firebase	建預設 bucket	要 Always Free 選 `us-central1`、`us-east1`、`us-west1`；要台灣延遲才選亞洲
Hosting	啟用 Firebase Hosting	用 default site 即可
Functions	啟用 Cloud Functions for Firebase	跟同一個 Firebase project 綁定

4. Google Cloud Console 要啟用的 API

API

Firebase Management API

Firebase Hosting API

Firebase Rules API

Identity Toolkit API

Cloud Firestore API

Cloud Storage API

Cloud Functions API

Cloud Build API

Artifact Registry API

Cloud Run Admin API

Eventarc API

Pub/Sub API

Cloud Scheduler API

Cloud Tasks API

Secret Manager API

IAM Credentials API

Service Usage API

5. GitHub Actions deploy account

Firebase Hosting GitHub integration 會建立 GitHub Actions 用的 service account，也可以自己手動建一個。這個專案建議直接用同一個 deploy account，然後補下面權限。

權限	角色
Firebase 管理	`roles/firebase.admin`
Hosting	`roles/firebasehosting.admin`
Firestore rules	`roles/firebaserules.admin`
Firestore indexes	`roles/datastore.indexAdmin`
Storage	`roles/storage.admin`
Functions	`roles/cloudfunctions.admin`
Cloud Run	`roles/run.admin`
Cloud Build	`roles/cloudbuild.builds.editor`
Artifact Registry	`roles/artifactregistry.admin`
Eventarc	`roles/eventarc.admin`
Pub/Sub	`roles/pubsub.admin`
Scheduler	`roles/cloudscheduler.admin`
Tasks	`roles/cloudtasks.admin`
Secret Manager	`roles/secretmanager.admin`
使用 runtime service account	`roles/iam.serviceAccountUser`

6. Functions runtime account

到 Cloud Functions 或 Cloud Run 詳情頁確認 runtime service account，然後給它下面權限。

權限	角色
Firestore	`roles/datastore.user`
Storage object	`roles/storage.objectAdmin`
Secret 讀取	`roles/secretmanager.secretAccessor`
Cloud Tasks enqueue	`roles/cloudtasks.enqueuer`
清舊 Secret versions	`roles/secretmanager.admin`

7. GitHub Secrets

到 GitHub repo 的 Settings -> Secrets and variables -> Actions 新增：

Secret	值
`FIREBASE_PROJECT_ID`	Firebase / GCP project id
`FIREBASE_SERVICE_ACCOUNT`	GitHub Actions deploy service account JSON
`VITE_APP_TITLE`	App 標題
`VITE_ALLOWED_DOMAIN`	校內 email 網域
`VITE_ADMIN_EMAILS`	管理員 email，逗號分隔
`VITE_FIREBASE_API_KEY`	Firebase Web App config
`VITE_FIREBASE_AUTH_DOMAIN`	Firebase Web App config
`VITE_FIREBASE_PROJECT_ID`	Firebase Web App config
`VITE_FIREBASE_APP_ID`	Firebase Web App config
`VITE_FIREBASE_STORAGE_BUCKET`	Firebase Web App config
`VITE_FIREBASE_MESSAGING_SENDER_ID`	Firebase Web App config
`NOTION_DATABASE_ID`	Notion database id
`NOTION_TOKEN`	Notion integration token

8. 部署順序

順序	操作
1	Fork repo
2	建 Google Cloud project 並綁 Billing
3	加 Firebase project
4	建 Firebase Web App
5	啟用 Auth、Firestore、Storage、Hosting、Functions
6	啟用 Google Cloud API
7	建或確認 GitHub Actions deploy service account
8	設 IAM
9	設 GitHub Secrets
10	push 到 `dev` 或 `main`，讓 GitHub Actions 部署

官方參考

主題	連結
Firebase CLI	firebase.google.com/docs/cli
Hosting GitHub integration	firebase.google.com/docs/hosting/github-integration
Cloud Storage Always Free	cloud.google.com/free/docs/free-cloud-features#cloud-storage
Cloud Functions IAM	cloud.google.com/functions/docs/concepts/iam
GitHub Actions Secrets	docs.github.com/…/use-secrets-in-github-actions

Wordmem 介紹

Sun, 16 Aug 2026 00:00:00 GMT

App 介紹

Wordmem 是一個以單字集為核心的英文單字練習 App，適合把課本、考試範圍、自訂生字或 AI 產生的單字資料整理成可反覆練習的題庫。

App 採用 Vue 3、Pinia、Vite 與 Tailwind CSS 建置，資料主要儲存在瀏覽器本機，並提供 ZIP 匯出匯入與 Google Drive 手動備份。使用者不需要登入帳號也能建立與練習單字集；只有使用 Google Drive 備份功能時，才需要授權 Google 帳號。

核心特色

單字集管理

建立多個單字集，依照課程、考試、主題或難度分類。
每個單字項目可包含：
- 英文單字
- 詞性
- 中文字義
- 英文例句
- 選擇題題幹
- 選項與正確答案
可編輯既有單字集與單字內容。
可刪除不再需要的單字集。
首頁會顯示目前擁有的單字集數量與總單字數。

AI 匯入單字集

Wordmem 內建 AI 匯入流程，協助使用者把單字清單轉成 App 可讀取的 JSON 格式。

流程如下：

在 App 內輸入想學習的單字。
選擇難度。
複製 App 產生的 AI 指令。
貼到 ChatGPT、Claude 或其他 AI 平台。
將 AI 回傳的 JSON 貼回 Wordmem。
預覽並建立新的單字集。

難度目前分為：

難度	適用情境
簡單	基礎單字、初學複習
中等	段考、一般測驗
困難	大考、進階練習

單字卡模式

單字卡模式適合快速瀏覽與記憶。

逐張查看單字。
顯示字義、詞性與例句。
支援接續上次未完成的進度。
適合正式測驗前快速複習。

選擇題練習

選擇題練習會根據單字集內的題目與選項進行測驗。

可自訂本輪練習題數。
題目順序會重新排列。
每題可選擇答案，也可略過。
完成後產生測驗結果。
錯題可再次複習。

拼字測試

拼字測試用來訓練英文單字輸出能力。

根據提示輸入完整英文單字。
判定時會忽略大小寫與前後空白。
留空送出會被視為略過。
完成後顯示正確答案與作答狀態。
可針對錯題再次練習。

測驗結果與錯題複習

每輪練習完成後，Wordmem 會整理結果。

顯示總題數、答對題數、錯題數與分數。
標示正確、錯誤與略過題目。
顯示使用者答案與正確答案。
可針對錯題重新練習。
可在選擇題與拼字模式之間切換。
可複製錯題解析指令，貼到 AI 平台取得補充說明。

本機資料保存

Wordmem 主要以瀏覽器本機儲存資料。

單字集會保存在本機瀏覽器。
練習進度可保存並接續。
主題偏好會保留。
不需要後端伺服器或資料庫。

注意：清除瀏覽器資料、換瀏覽器、換裝置或使用無痕模式，都可能導致本機資料消失。重要資料建議定期匯出 ZIP 或備份到 Google Drive。

ZIP 匯出與匯入

Wordmem 支援離線備份。

可選擇要匯出的單字集。
下載 Wordmem 專用 ZIP 備份檔。
可從 ZIP 備份匯入資料。
匯入時可選擇追加或覆蓋本機資料。
同名單字集可選擇保留本機版本或使用匯入版本。

匯入模式比較：

模式	說明	適合情境
追加到本機	保留現有資料，將備份內容加入本機	合併不同來源的單字集
覆蓋本機	用備份完整取代目前資料並清除練習進度	換裝置或完整還原

Google Drive 手動備份

設定 Google OAuth Client ID 後，Wordmem 可以手動備份到 Google Drive。

使用 Google Identity Services 進行授權。
使用 Google Drive API 儲存備份檔。
備份檔會放在 Google Drive 的 Wordmem 資料夾。
備份格式為 ZIP。
App 會保留最近的備份，並清理過舊備份。
可從 Google Drive 選擇備份檔並匯入。

Wordmem 使用的 Google Drive 權限範圍為：

<https://www.googleapis.com/auth/drive.file>

這代表 App 只能存取由 Wordmem 建立或由使用者透過授權流程選用的檔案，並非完整讀取整個 Google Drive。

使用流程

第一次使用

開啟 Wordmem。
點選新增單字集或 AI 匯入。
建立第一個單字集。
從首頁選擇單字卡、選擇練習或拼字測試。
完成練習後查看結果。
定期使用 ZIP 或 Google Drive 備份。

日常複習

選擇今天要練習的單字集。
先用單字卡快速看過。
使用選擇題測驗理解程度。
使用拼字測試檢查是否真的記住英文拼法。
對錯題進行複習。
必要時複製錯題解析指令到 AI 平台。

技術概覽

前端架構

項目	技術
框架	Vue 3
語法	`<script setup lang="ts">`
狀態管理	Pinia
路由	Vue Router
樣式	Tailwind CSS v4
建置工具	Vite
測試	Vitest
PWA	vite-plugin-pwa

資料與備份

功能	實作
本機儲存	IndexedDB、localStorage
ZIP 備份	fflate、Web Worker
Google 登入	Google Identity Services
雲端備份	Google Drive API
匯入驗證	TypeScript 型別與驗證邏輯

適用對象

學生

整理課本單字。
準備段考、會考、學測、分科測驗或英文檢定。
針對錯題反覆練習。

老師與家教

建立課程單字集。
產生可分享的 ZIP 備份。
搭配 AI 快速建立題庫。

自學者

建立個人英文詞庫。
用拼字測試訓練輸出能力。
將錯題交給 AI 補充語法、用法與例句。

邏輯介紹

Sun, 16 Aug 2026 00:00:00 GMT

角色與使用情境

角色	可以做什麼	看不到什麼	主要入口
未登入訪客	看到登入提示	所有提案、公告、通知、留言	登入面板
校內一般使用者	看公共議題、設備提案、公告；建立提案；留言；附議公共議題	其他人的學生權益維護提案、其他人的通知、其他人的私有作者資料	提案看板、公告頁
提案作者	管理自己的提案；在「我的提案」看到自己發過的內容	其他人的私密提案	我的提案分頁、提案詳情
公共議題附議者	對公共議題附議或取消附議	其他使用者是否附議	公共議題卡片、提案詳情
管理員	調整提案狀態、建立公告、刪除不適合內容、看平台統計		管理員狀態選單、公告管理、Dashboard

使用者功能總覽

功能	使用者會看到的行為	背後邏輯
Google 校內登入	只能用已驗證的校內 Google 帳號登入	前端與 Cloud Functions 都檢查 Google provider、email verified、指定網域
提案分類分頁	公共議題、學生權益維護、設備、我的提案	路由 `/issues/:filter` 控制目前分頁，不靠單一畫面內部狀態硬切
提案看板	卡片與列表模式切換、搜尋、分頁	Firestore 即時訂閱加上前端分頁與搜尋狀態
新增提案	填標題、內容、分類，可插入圖片	送出時統一呼叫 `backendAction`，由後端驗證與寫入
公共議題附議	按下附議後數字立即更新，失敗會回復	前端 optimistic UI，後端 transaction 防止重複附議
提案留言	在提案詳情內留言，可附圖片	留言讀寫都經 Cloud Functions，Firestore client 不直接讀寫留言集合
狀態通知	狀態變更、留言、附議達標會通知	`user_notifications` 只讓收件人讀取，最多保留最新 15 則
公告	校內使用者可看公告、留言、按讚	公告由管理員建立，互動也走 callable
管理員 Dashboard	看使用者、提案、留言、附議與分類統計	後端累加平台統計，Dashboard callable 僅 admin 可取
Notion 備份	提案、公告與互動事件可同步到 Notion	Cloud Tasks 排隊，失敗可重試並記錄狀態

提案分類與差異

分類	適合內容	誰看得到	是否可附議	作者顯示	期限邏輯
公共議題	影響多數學生的制度、環境、流程問題	校內使用者都可看	是，目標 50 人	一般使用者看不到作者真實資訊；本人與管理員可看私有作者資料	14 天內未達 50 人會自動轉為「未通過」；達標後有 7 天回覆期限
學生權益維護	個別權益、敏感事件、需要私下處理的問題	只有作者本人與管理員可看	否	只在本人與管理員情境可辨識	建立後直接進入待回覆流程，回覆期限 7 天
設備	設備損壞、空間問題、修繕需求	校內使用者都可看	否	可顯示校內作者資訊	建立後直接進入待回覆流程，回覆期限 7 天
我的提案	使用者自己發出的全部提案	只列出目前登入者自己的提案	依原分類規則	使用者可以知道哪些是自己送出的	用路由 filter 顯示，不是獨立分類

提案狀態

狀態代碼	顯示文字	代表意義	誰能造成狀態變化
`pending`	未回覆	新提案等待管理方處理；公共議題可能仍在附議期	使用者建立提案後產生
`processing`	處理中	管理方已接手處理	管理員
`auto-rejected`	未通過	公共議題附議期到期但未達門檻	排程函式或維護 callable
`infeasible`	無法實行	管理方判定目前無法執行	管理員
`completed`	已完成	已處理或完成回覆	管理員

提案生命週期

階段	公共議題	學生權益維護	設備
建立	檢查標題、內容、分類、圖片；產生附議期限	檢查標題、內容、分類、圖片；標記私密可見性	檢查標題、內容、分類、圖片
初始狀態	`pending`	`pending`	`pending`
附議	可附議，可取消，重複附議被後端拒絕	不開放	不開放
達標	達 50 人後記錄 `support_met_at`，設定回覆期限	不適用	不適用
未達標	14 天後自動轉為 `auto-rejected`	不適用	不適用
管理員處理	可改為處理中、無法實行、已完成	可改為處理中、無法實行、已完成	可改為處理中、無法實行、已完成
通知	留言、狀態更新、附議達標都可通知	留言與狀態更新通知作者	留言與狀態更新通知作者
備份	Notion 事件同步	Notion 事件同步，但依資料設計保護私密資訊	Notion 事件同步

權限模型總表

動作	未登入	校內使用者	作者本人	管理員
讀取公共議題	否	是	是	是
讀取學生權益維護提案	否	否	是	是
讀取設備提案	否	是	是	是
新增提案	否	是	是	是
刪除自己的提案	否	否	否	是
調整提案狀態	否	否	否	是
附議公共議題	否	是	是	是
附議學生權益維護或設備	否	否	否	否
讀取留言	否	透過 callable 依提案權限讀取	是	是
新增留言	否	透過 callable 依提案權限新增	是	是
讀取通知	否	只能讀自己的	只能讀自己的	只能讀自己的
建立公告	否	否	否	是
讀取 Dashboard	否	否	否	是

登入與校內身分驗證

檢查項目	前端用途	後端用途	原因
Google 登入 provider	引導使用者用正確方式登入	`validateAuthAndDomain` 拒絕非 Google provider	避免用其他 provider 繞過校內帳號政策
Email 已驗證	顯示登入狀態前先驗證	callable 每次操作都驗證 token	避免未驗證 email 被當成有效校內身分
Email 網域	顯示校內網域限制	比對 `ALLOWED_DOMAIN`	平台只服務指定學校網域
管理員 email	顯示管理 UI	比對 `ADMIN_EMAILS`	管理員身份不靠前端判斷
UID	訂閱自己的通知與提案	寫入作者、附議、留言紀錄	保持每個操作可追蹤

資料讀寫邊界

資料	前端可直接讀嗎	前端可直接寫嗎	實際寫入方式
`issues`	可讀，但學生權益維護只限作者與管理員	否	`backendAction.createIssue`、`deleteIssue`、`moderateIssueStatus`
`issues/{issueId}/votes/{uid}`	只可讀自己的投票狀態或管理員讀取	否	`backendAction.toggleSupport`、`removeSupport`
`private_issue_authors`	只限作者與管理員	否	建立公共議題時由後端同步寫入
`issue_comments`	否	否	`backendAction.listComments`、`createComment`、`deleteComment`
`announcements`	校內使用者可讀	否	管理員 callable 建立、更新、刪除
`announcements/{id}/likes/{uid}`	只可讀自己的讚狀態或管理員讀取	否	`backendAction.toggleAnnouncementLike`
`announcement_comments`	否	否	公告留言 callable
`uploads`	否	否	圖片上傳、解析、刪除 callable
`user_notifications`	只可讀自己的通知	否	後端事件建立通知
`platform_stats`	否	否	管理員 Dashboard callable

為什麼所有寫入都走 Cloud Functions

風險	如果讓前端直接寫入會怎樣	現在的做法
偽造作者	使用者可能改掉 `author_uid` 或管理欄位	後端從 Firebase Auth token 取 uid/email/name
偽造管理員	前端 UI 隱藏不代表安全	後端每次 callable 都比對 `ADMIN_EMAILS`
重複附議	同一人可能送出多次寫入	Firestore transaction 與 votes 子集合防重
私密提案外洩	client query 寫錯就可能列出敏感資料	Firestore Rules 先擋，再由查詢服務按分類取資料
圖片任意讀寫	Storage URL 若公開會擴散	Storage 規則拒絕 uploads 直接讀寫，只用短效 signed URL
Notion 同步失敗	直接同步容易讓使用者操作卡住	Cloud Tasks 排隊、重試、限速

圖片與 Markdown

項目	設計
圖片格式	上傳前端先壓縮，後端接受 WebP
單張大小	後端限制最大 2 MB
預覽圖	後端用 `sharp` 產生最大 480px preview
Markdown 語法	支援 `![alt
Storage 權限	`/uploads/**` 不允許前端直接 read/write/delete
圖片讀取	前端解析 `srp-upload://` 後，透過 callable 換短效 signed URL
signed URL 有效期	15 分鐘
可見性	`school` 或 `private`，由 registry 與權限 helper 判斷
刪除	刪提案、留言或公告時，後端清理關聯圖片

公共議題附議邏輯

規則	說明
只限公共議題	學生權益維護與設備不需要附議流程
目標人數	`PUBLIC_SUPPORT_GOAL = 50`
附議期限	建立後 14 天
達標效果	寫入 `support_met_at`，設定 7 天回覆期限，通知作者
未達標效果	排程每 60 分鐘掃描，到期且未達標轉成 `auto-rejected`
防止重複	votes 子集合以 uid 當文件 ID，交易內同步 `support_count`
使用者狀態	`users.supported_issue_ids` 保留使用者目前附議過的提案 ID

通知與公告

模組	功能	權限
通知鈴鐺	顯示最新通知與未讀數	只讀目前登入者的通知
提案留言通知	有人留言時通知相關使用者	後端決定收件人
狀態變更通知	管理員改狀態後通知作者	後端建立
附議達標通知	公共議題達標時通知作者	後端建立
公告列表	校內使用者可讀全站公告	管理員才可新增、編輯、刪除
公告留言與讚	校內使用者互動	透過 callable 寫入，非 client 直寫

Notion 備份邏輯

事件類型	備份內容	同步方式
提案建立	標題、分類、狀態、作者資訊、內容	建立或更新 Notion page
提案狀態變更	舊狀態、新狀態、時間	追加事件紀錄
提案留言	留言摘要、圖片 block	追加到 Notion
公告建立或更新	公告標題、內容、互動狀態	建立或更新 Notion page
公告留言或讚	互動事件	追加到 Notion
刪除事件	將 Notion 對應頁或事件標記處理	透過 event handler

Notion 同步不直接卡住使用者操作。後端會先寫入 Firestore，再把同步事件丟進 Cloud Tasks。任務最多重試 5 次，限速為每秒 1 個、同時最多 2 個，避免打爆 Notion API 或因短暫失敗造成資料遺失。

主要資料集合

Collection	主要用途	讀取者	寫入者
`issues`	提案主資料	校內使用者依分類與作者權限讀取	Cloud Functions
`private_issue_authors`	公共議題私有作者資訊	作者本人、管理員	Cloud Functions
`issue_comments`	提案留言	只能透過 callable 取得	Cloud Functions
`announcements`	公告	校內使用者	Cloud Functions
`announcement_comments`	公告留言	只能透過 callable 取得	Cloud Functions
`users`	使用者附議 ID、頭像快取等	本人	Cloud Functions
`uploads`	圖片 registry	不開放 client 直接讀	Cloud Functions
`user_notifications`	站內通知	收件人本人	Cloud Functions
`platform_stats`	平台成果統計	管理員 callable	Cloud Functions
`notion_pages` / `notion_issue_pages`	Firestore 與 Notion 頁面對應	後端內部	Cloud Functions
`notion_sync_jobs`	Notion 同步任務狀態	後端內部	Cloud Functions
`rate_limits`	發文與留言限流 bucket	後端內部	Cloud Functions

使用者常見問題

問題	回答
為什麼我看不到別人的學生權益維護提案？	這個分類是私密用途，只能看到自己發出的提案；如果目前是空的，代表你還沒有在這個分類送出提案。
為什麼公共議題看不到作者？	公共議題希望降低提案者被針對的風險，因此一般使用者看議題內容與附議狀態即可，作者資訊由後端保存給本人與管理員使用。
為什麼設備提案不能附議？	設備問題通常是明確修繕或回報流程，不需要用附議達標來判斷是否處理。
為什麼圖片有時需要重新載入？	圖片不是永久公開 URL，而是短效 signed URL；過期後前端會再向後端解析。
為什麼送出失敗時圖片不會留下公開連結？	圖片先進 registry，送出失敗或刪除內容時後端會清理，降低孤兒檔案與外洩風險。
管理員是不是可以在前端直接改資料？	不行。前端只能呼叫後端 action，真正的 admin 判斷在 Cloud Functions。
提案內容支援 Markdown 嗎？	支援，並會用 DOMPurify 過濾渲染後 HTML，降低 XSS 風險。

前端模組責任

模組	責任
`src/router`	將提案、公告、管理員頁面路由化；提案 filter 由 URL 控制
`src/views`	頁面入口，只組合資料流程與主要元件
`src/components`	UI 呈現與互動元件，避免直接寫 Firestore 邏輯
`src/components/ui`	純展示共用元件，不 import composable 或 service
`src/composables`	狀態、表單、訂閱、分頁、搜尋、對話框、通知等邏輯
`src/services`	Firestore 讀取與 Cloud Functions callable 包裝
`src/lib`	無 Vue 相依的純函式，例如 Markdown 圖片解析、日期格式化、搜尋正規化
`src/constants`	分類、狀態、路由選項
`src/types`	TypeScript 型別，作為資料模型文件

後端模組責任

模組	責任
`functions/src/index.ts`	只匯出部署入口
`functions/src/entrypoints/backend-action.ts`	單一 callable router，依 action 分派 handler
`functions/src/core`	Firebase Admin 初始化、環境變數、身分驗證、限流
`functions/src/issues`	提案建立、刪除、留言、附議、狀態管理、過期同步
`functions/src/announcements`	公告 CRUD、公告留言、讚、Notion retry
`functions/src/uploads`	圖片建立、解析、刪除、Storage 與 registry 權限
`functions/src/notifications`	通知建立與已讀時間
`functions/src/stats`	平台統計與 Dashboard
`functions/src/notion`	Notion client、Markdown 轉 block、事件同步與 page mapping
`functions/src/scheduled`	每小時自動駁回、每日清理 Secret Manager 舊版本

一句話流程圖

flowchart TD
  A["校內 Google 登入"] --> B["選擇提案分類"]
  B --> C["送出提案與圖片"]
  C --> D["Cloud Functions 驗證與寫入"]
  D --> E{"公共議題？"}
  E -->|是| F["14 天附議期"]
  F --> G{"達 50 人？"}
  G -->|是| H["設定 7 天回覆期限並通知"]
  G -->|否| I["排程自動轉未通過"]
  E -->|否| J["直接等待管理員回覆"]
  H --> K["管理員處理狀態"]
  I --> K
  J --> K
  K --> L["通知使用者並同步 Notion"]

部署

Sun, 16 Aug 2026 00:00:00 GMT

準備工作

在開始之前，請確保您已擁有以下平台的帳號：

GitHub：託管原始碼
Supabase：後端服務（認證、資料庫、Edge Functions）
Vercel：前端網站部署
Google Cloud Console：設定 Google 登入與 Google Calendar API

Step 1. 本機環境驗證

請確保本機已安裝 Node.js 18+ (建議24 LTS)。

安裝依賴：Bash

npm install

設定環境變數：程式碼片段

複製 .env.example 並命名為 .env：

VITE_SUPABASE_URL=https://你的-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=你的-supabase-publishable-anon-key

啟動本地開發伺服器：Bash

npm run dev

注意：預設網址通常為 http://localhost:5173。確認畫面可正常開啟後再進行下一步。

Step 2. 建立 GitHub Repository

將專案推送到您的 GitHub 儲存庫：

Bash

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/你的帳號/hynan.git
git push -u origin main

注意：請務必確認 .env 已列入 .gitignore 中，切勿推送到 GitHub 公開儲存庫。

Step 3. Supabase 基礎設定

1. 建立專案

前往 Supabase Dashboard 建立新專案。
設定 Project name（如 hynan）、強密碼，並選擇合適的 Region。

2. 獲取 API 金鑰

前往 Project Settings > API，複製 Project URL 與 publishable anon key，更新至本機 .env 及保留給後續 Vercel 使用。

3. 初始化資料庫結構

前往 SQL Editor，開啟新查詢。
複製專案中 supabase/schema.sql 的完整內容，貼入並執行。
執行後，至 Table Editor 確認以下資料表已成功建立並啟動 RLS (Row Level Security)：

workspaces, tasks, tags, daily_entries, google_calendar_connections, google_calendar_workspace_calendars, google_calendar_sync_queue

Step 4. Google Cloud Console 設定

1. 建立專案與啟用 API

前往 Google Cloud Console 建立名為 Hynan 的專案。
搜尋 Google Calendar API 並點擊 啟用 (Enable)。

進入 APIs & Services > OAuth consent screen，User Type 選擇 External。
填寫 App name (Hynan)、支援與開發者 Email。
測試使用者 (Test users)：若 App 處於 Testing 狀態，請務必將您要用來登入測試的 Google 帳號加入列表中，否則將無法通過認證。

3. 建立 OAuth 憑證

進入 APIs & Services > Credentials，點擊 Create Credentials > OAuth client ID。
Application type：選擇 Web application。
Authorized JavaScript origins：
- 本地：http://localhost:5173
- 正式：https://你的-vercel-app.vercel.app
Authorized redirect URIs（注意結尾必須帶 /）：
- 本地：http://localhost:5173/
- 正式：https://你的-vercel-app.vercel.app/
建立完成後，複製 Client ID 與 Client Secret。

Step 5. 對接 Supabase 與 Google Auth

1. 啟用 Google Provider

回到 Supabase Dashboard > Authentication > Providers > Google。
啟用開關，填入剛剛獲取的 Google Client ID 與 Client Secret 並儲存。

2. 設定重導向網址 (URL Configuration)

前往 Authentication > URL Configuration：
- Site URL：https://你的-vercel-app.vercel.app (本機測試時可先填 http://localhost:5173)
- Redirect URLs：
  - http://localhost:5173/
  - https://你的-vercel-app.vercel.app/

Step 6. 部署 Supabase Edge Function

全域安裝 Supabase CLI 并登入：Bash

npm install -g supabase
supabase login

連結專案（project-ref 可從 Supabase URL 中取得）：Bash

supabase link --project-ref 你的-project-ref

設定 Edge Function 密鑰：Bash

supabase secrets set GOOGLE_CLIENT_ID="你的-google-client-id"
supabase secrets set GOOGLE_CLIENT_SECRET="你的-google-client-secret"
supabase secrets set GOOGLE_TOKEN_ENCRYPTION_KEY="請換成一組32字元以上的隨機長字串"

注意：GOOGLE_TOKEN_ENCRYPTION_KEY 用於加密 Google Token，請妥善保管，勿用範例弱密碼。

部署 Function（專案路徑需為 supabase/functions/google-calendar/index.ts）：Bash

supabase functions deploy google-calendar

Step 7. Vercel 前端部署

登入 Vercel，點擊 Add New > Project，導入您的 GitHub hynan 儲存庫。
Framework Preset 選擇 Vite。
設定環境變數 (Environment Variables)，務必勾選 Production, Preview, Development：

VITE_SUPABASE_URL = 你的 Supabase URL
VITE_SUPABASE_ANON_KEY = 你的 Supabase Anon Key

點擊 Deploy。部署成功後複製 Vercel 提供的正式網址。
注意事項：請將此正式網址同步更新回 Supabase Auth URL 與 Google OAuth Credentials 的允許清單中（參見 Step 4 與 Step 5）。如有變更環境變數，記得在 Vercel 點選 Redeploy。

驗證與自我測試

部署完成後，請依序執行以下測試以確保功能完整：

[ ] Google 登入：是否能正常跳轉、成功登入，且 Supabase 後台有產生對應 User。
[ ] 資料庫讀寫：新增任務、標籤、每日筆記，檢查 Supabase Table Editor 是否有即時寫入資料。
[ ] 行事曆連動：在設定中點擊「連接 Google Calendar」，確認是否成功跳出授權並於 Google Calendar 中建立 Hynan 行事曆。
[ ] 雙向同步：建立有日期的任務，點擊立即同步，檢查 Google Calendar 是否出現事件；反之於 Google 修改，確認能同步回 App。

常見問題排查 (FAQ)

Google 登入失敗？

檢查 Google Cloud 的 Authorized redirect URIs 結尾是否有加 /。
檢查 Supabase 的 Site URL 與 Redirect URLs 是否包含完整的部署網址與 /。
確認測試帳號是否有加入 Google OAuth Consent Screen 的 Test users 中。

Google Calendar 連接或同步失敗？

確認 Google Cloud 專案中已啟動 Google Calendar API。
檢查 Supabase Edge Function 是否成功部署，且名稱精確為 google-calendar。
前往 Supabase Dashboard > Edge Functions > google-calendar > Logs 查看具體報錯訊息（如：Missing secret 代表環境變數未設定成功）。

重新整理頁面後出現 Vercel 404 錯誤？

專案根目錄必須包含 vercel.json 檔案。其內容需設定將所有路由導回 /index.html（SPA 路由支援）。請確認該檔案是否有被推送到 Git 並成功部署。

資料看得見，但無法新增或修改？

這通常是資料庫 schema 沒有完整建立，或是 RLS Policy 阻擋了寫入。請前往 Supabase SQL Editor 重新完整執行一遍 schema.sql。

部署

Sun, 16 Aug 2026 00:00:00 GMT

本文件說明如何將 Wordat 部署到 Vercel。專案是 Vite React 靜態前端 App，部署時不需要後端伺服器或資料庫。

部署前準備

請先確認本機已安裝：

Node.js
Git
GitHub 帳號
Vercel 帳號

專案主要指令：

npm install
npm run dev
npm run build
npm run lint

Vercel 部署設定：

Framework Preset：Vite
Build Command：npm run build
Output Directory：dist
Install Command：npm install

1. 本機確認專案可建置

在專案根目錄執行：

npm install
npm run lint
npm run build

如果 npm run build 成功，專案根目錄會產生 dist 資料夾，Vercel 會使用這個資料夾作為正式網站內容。

2. 建立 GitHub Repository

到 GitHub 建立一個新的 repository，例如：

wordat

可以選擇 Public 或 Private。Vercel 兩者都支援，但 Private repository 需要授權 Vercel 存取。

3. 將專案推送到 GitHub

如果專案尚未初始化 Git：

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <https://github.com/><你的帳號>/wordat.git
git push -u origin main

如果專案已經有 Git，只需要確認 remote 後推送：

git remote -v
git add .
git commit -m "Update Wordat"
git push

請將 <你的帳號> 換成自己的 GitHub username。

4. 在 Vercel 匯入專案

前往 Vercel Dashboard。
點選 Add New Project。
選擇剛剛建立的 GitHub repository。
確認 Framework Preset 為 Vite。
確認設定：

Build Command：npm run build
Output Directory：dist
Install Command：npm install

點選 Deploy。

部署完成後，Vercel 會提供一個網址，例如：

<https://wordat.vercel.app>

5. 後續更新部署

之後只要將更新推送到 GitHub，Vercel 就會自動重新部署：

git add .
git commit -m "Update app"
git push

Vercel 會針對 production branch 自動建立正式部署。通常 production branch 是 main。

6. 自訂網域

如果要使用自己的網域：

進入 Vercel 專案頁面。
開啟 Settings。
進入 Domains。
輸入自訂網域。
依照 Vercel 顯示的 DNS 指示，到網域商後台設定 DNS。

常見設定方式：

根網域使用 A record 指向 Vercel 提供的 IP。
子網域使用 CNAME 指向 Vercel 提供的目標網域。

DNS 生效可能需要數分鐘到數小時。

7. PWA 與離線功能注意事項

Wordat 使用 PWA 快取機制。部署到 Vercel 後，正式環境會以 HTTPS 提供網站，符合 Service Worker 與 PWA 安裝需求。

注意事項：

第一次開啟網站時需要網路連線。
App 資源快取完成後，瀏覽器才可支援離線開啟。
如果發布新版本，使用者可能會看到更新提示。
PWA 快取與 localStorage 都是瀏覽器端資料，不等於雲端同步。

8. 資料備份建議

Wordat 的單字資料存在使用者瀏覽器 localStorage。部署到 Vercel 後，資料仍然不會上傳到 Vercel 或 GitHub。

建議使用者定期在 App 內點選匯出，下載 JSON 備份檔。更換裝置、換瀏覽器或清除網站資料前，請先匯出備份。

9. 常見問題

部署後畫面空白

先確認本機 npm run build 是否成功。如果本機成功但 Vercel 失敗，請到 Vercel 的 Deployment Logs 查看錯誤訊息。

Vercel 找不到 build output

確認 Output Directory 是：

dist

TypeScript 錯誤導致部署失敗

先在本機執行：

npm run lint

依照錯誤訊息修正後再推送。

使用者資料沒有同步到另一台裝置

這是目前設計。Wordat 採 Local-first 架構，資料存在本機瀏覽器。若要移動資料，請使用匯出 / 匯入 JSON 備份。

部署

Sun, 16 Aug 2026 00:00:00 GMT

這份文件說明如何把 Tabin 推到 GitHub，並使用 Vercel 部署成可公開存取的網站。

前置需求

已安裝 Node.js。
已有 GitHub 帳號。
已有 Vercel 帳號。
本機可以執行 npm install 和 npm run build。

1. 確認專案可以建置

在專案根目錄執行：

npm install
npm run build

建置成功後，Vite 會產生 dist 資料夾。這個資料夾是部署後的靜態網站輸出。

2. 建立 GitHub Repository

在 GitHub 建立一個新的 repository，例如：

tabin

建立時可以不要勾選 README、.gitignore 或 license，避免和本機專案內容衝突。

3. 推送專案到 GitHub

如果本機尚未設定 remote：

git remote add origin <https://github.com/YOUR_USERNAME/tabin.git>

提交並推送：

git add .
git commit -m "Initial Tabin deployment"
git branch -M main
git push -u origin main

之後每次修改完成，都可以用：

git add .
git commit -m "Update Tabin"
git push

4. 在 Vercel 匯入 GitHub 專案

前往 Vercel。
登入後選擇 Add New Project。
選擇剛剛建立的 GitHub repository。
Vercel 通常會自動偵測這是 Vite 專案。

設定值建議如下：

Framework Preset: Vite
Build Command: npm run build
Output Directory: dist
Install Command: npm install

確認後按下 Deploy。

5. 取得部署網址

部署完成後，Vercel 會提供一個網址，例如：

<https://tabin-yourname.vercel.app>

之後 GitHub 的 main 分支有新 commit 時，Vercel 會自動重新部署。

6. 設定 Chrome 新分頁 Extension

如果要讓 Chrome 新分頁自動打開 Tabin，請修改：

extension/newtab.html

把裡面的網址：

const TABIN_URL = "<https://your-tabin-vercel-url.vercel.app>";

改成你的 Vercel 部署網址，例如：

const TABIN_URL = "<https://tabin-yourname.vercel.app>";

noscript 裡的連結也可以同步改成相同網址。

7. 載入 Chrome Extension

開啟 Chrome。
前往 chrome://extensions/。
開啟右上角 Developer mode。
點選 Load unpacked。
選擇專案內的 extension 資料夾。

載入後，Chrome 的新分頁會導向你部署好的 Tabin 網站。

8. 更新部署

修改 App 後，先在本機確認：

npm run build

確認成功後推送到 GitHub：

git add .
git commit -m "Update layout"
git push

Vercel 會自動偵測 GitHub 更新並重新部署。

注意事項

Tabin 的資料存在瀏覽器 localStorage，不會因為重新部署而自動同步到其他裝置。
如果清除瀏覽器資料，書籤也可能被清掉，建議定期使用匯出功能備份。
如果 Vercel 部署網址改變，記得同步更新 extension/newtab.html。
如果 Chrome extension 修改後沒有生效，回到 chrome://extensions/ 點擊重新載入 extension。

部署

Sun, 16 Aug 2026 00:00:00 GMT

部署前準備

這份教學會帶你把 Wordmem 放到 GitHub，並部署到 Vercel，同時設定 Google Cloud，讓 Google Drive 備份功能可以正常使用。

你需要準備：

一個 GitHub 帳號
一個 Vercel 帳號
一個 Google 帳號
本機已安裝 Git
本機已安裝 Node.js 與 npm
專案原始碼

建議版本：

工具	建議
Node.js	使用目前 LTS 版本
npm	隨 Node.js 安裝即可
Git	使用最新版

檢查本機工具：

node -v
npm -v
git --version

本機專案檢查

進入專案資料夾：

cd C:\\Users\\Tavric\\Documents\\projects\\Wordmem

安裝套件：

npm install

建立本機環境變數檔：

Copy-Item .env.example .env.local

.env.local 先保留範例值也可以，等 Google Cloud 設定完成後再回來填入。

啟動本機開發伺服器：

npm run dev

瀏覽器開啟 Vite 顯示的網址，通常是：

<http://localhost:5173>

正式部署前，建議先跑一次檢查：

npm run typecheck
npm run lint
npm run test
npm run build

如果以上指令都成功，代表專案基本狀態正常。

建立 GitHub Repository

在 GitHub 建立空 Repository

開啟 GitHub。
點右上角 +。
選擇 New repository。
Repository name 可填：

Wordmem

Visibility 可選 Public 或 Private。
不要勾選 Add a README file。
不要勾選 .gitignore。
不要勾選 Choose a license。
點 Create repository。

這樣 GitHub 會建立一個空的遠端 Repository。

將本機專案推上 GitHub

回到 PowerShell，確認目前在專案根目錄：

cd C:\\Users\\Tavric\\Documents\\projects\\Wordmem

確認 Git 狀態：

git status

如果專案還沒有初始化 Git：

git init

加入檔案：

git add .

建立第一次 commit：

git commit -m "Initial commit"

把遠端 Repository 加進來。請把網址換成你的 GitHub Repository URL：

git remote add origin <https://github.com/你的帳號/Wordmem.git>

設定主要分支名稱：

git branch -M main

推送到 GitHub：

git push -u origin main

推送完成後，重新整理 GitHub Repository 頁面，應該會看到專案檔案。

Google Cloud 設定

Wordmem 的 Google Drive 備份功能需要 Google OAuth 2.0 Client ID。這個 Client ID 會放在 Vercel 的環境變數 VITE_GOOGLE_CLIENT_ID。

建立 Google Cloud Project

開啟 Google Cloud Console：

<https://console.cloud.google.com/>

登入 Google 帳號。
點上方專案選擇器。
點 New Project。
Project name 可填：

Wordmem

Organization 沒有也沒關係。
點 Create。
等待專案建立完成。
確認目前選到剛建立的 Wordmem 專案。

啟用 Google Drive API

在 Google Cloud Console 左上角選單打開 APIs & Services。
進入 Library。
搜尋：

Google Drive API

點進 Google Drive API。
點 Enable。

啟用完成後，Wordmem 才能透過 Drive API 建立資料夾、上傳備份、列出備份與下載備份。

到 APIs & Services。
進入 OAuth consent screen。
如果看到使用者類型，選擇 External。
點 Create。

填寫 App 資訊：

欄位	建議填寫
App name	Wordmem
User support email	你的 email
App logo	可先不填
App domain	部署完成前可先空著
Developer contact information	你的 email

儲存後繼續。

設定 Scopes

Wordmem 使用的 Google Drive scope 是：

<https://www.googleapis.com/auth/drive.file>

設定方式：

在 OAuth consent screen 的 Scopes 步驟點 Add or Remove Scopes。
搜尋 drive.file。
勾選 Google Drive API 的 .../auth/drive.file。
點 Update。
儲存並繼續。

drive.file 的用途是讓 Wordmem 建立與管理自己的備份檔，不需要完整讀取使用者整個 Google Drive。

加入測試使用者

如果 OAuth App 還在 Testing 狀態，只有測試使用者能登入。

在 OAuth consent screen 找到 Test users。
點 Add users。
輸入你的 Google 帳號 email。
儲存。

如果你要給其他人測試，也要把對方的 Google 帳號加入測試使用者。

建立 OAuth Client ID

到 APIs & Services。
進入 Credentials。
點 Create Credentials。
選擇 OAuth client ID。
Application type 選：

Web application

Name 可填：

Wordmem Web

設定 Authorized JavaScript Origins

這裡要填允許載入 Google 登入服務的網站來源。

本機開發先加入：

<http://localhost:5173>

Vercel 正式網址稍後部署完成才會知道，之後要回來加入，例如：

<https://wordmem.vercel.app>

如果 Vercel 給你的網址不同，請填你的實際網址。

設定 Authorized Redirect URIs

Wordmem 目前使用 Google Identity Services 的 token client，不需要傳統 redirect callback 頁面。

一般情況下，Authorized redirect URIs 可以不填。

如果 Google Cloud 介面要求你填寫，或你之後改成 redirect flow，才需要額外設定 callback URL。

複製 Client ID

建立完成後，Google Cloud 會顯示 OAuth Client。

複製 Client ID，格式大約像：

1234567890-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com

這個值等等會填到：

VITE_GOOGLE_CLIENT_ID

本機設定 Google Client ID

打開 .env.local，填入剛剛複製的 Client ID：

VITE_GOOGLE_CLIENT_ID=你的-client-id.apps.googleusercontent.com

重新啟動開發伺服器：

npm run dev

測試流程：

開啟 Wordmem。
建立至少一個單字集。
開啟備份與匯入。
點登入 Google。
完成授權。
點備份到 Drive。
到 Google Drive 確認是否出現 Wordmem 資料夾與 ZIP 備份檔。

如果看到 尚未設定 VITE_GOOGLE_CLIENT_ID，代表 .env.local 沒有設定成功或開發伺服器沒有重新啟動。

Vercel 部署

匯入 GitHub 專案

開啟 Vercel：

<https://vercel.com/>

使用 GitHub 帳號登入。
點 Add New。
選擇 Project。
找到 Wordmem Repository。
點 Import。

設定 Framework 與 Build

Vercel 通常會自動偵測為 Vite 專案。

確認設定如下：

項目	值
Framework Preset	Vite
Build Command	`npm run build`
Output Directory	`dist`
Install Command	`npm install`

Root Directory 如果專案就在 Repository 根目錄，保持預設即可。

設定 Vercel 環境變數

在部署前，找到 Environment Variables 區塊。

新增：

Name	Value
`VITE_GOOGLE_CLIENT_ID`	你的 Google OAuth Client ID

Environment 建議全部勾選：

Production
Preview
Development

填好後再部署。

開始部署

點 Deploy。
等待 Vercel 安裝套件與執行 build。
部署成功後，Vercel 會提供網址，例如：

<https://wordmem.vercel.app>

請複製你的實際網址。

回到 Google Cloud 加入正式網域

Vercel 部署完成後，必須把正式網址加入 Google OAuth Client 的 Authorized JavaScript Origins。

回到 Google Cloud Console。
進入你的 Wordmem Project。
到 APIs & Services。
進入 Credentials。
點剛剛建立的 OAuth 2.0 Client ID。
在 Authorized JavaScript origins 加入 Vercel 網址，例如：

<https://wordmem.vercel.app>

儲存。

注意：

不要在網址最後加 /。
必須使用 https://。
必須填實際部署網址。
如果你使用自訂網域，也要把自訂網域加入。

Google Cloud 設定更新後可能需要幾分鐘才完全生效。

驗證正式站

打開 Vercel 正式網址，逐項確認。

基本功能

首頁可正常載入。
可新增單字集。
可編輯單字集。
可進入單字卡。
可進入選擇題練習。
可進入拼字測試。
測驗完成後可看到結果頁。

路由重新整理

Wordmem 使用 Vue Router，vercel.json 已設定 rewrite：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

請測試：

進入任一練習頁。
重新整理瀏覽器。
確認不會出現 404。

PWA 與快取

vercel.json 也針對以下檔案設定重新驗證：

sw.js
version.json
index.html

這能降低使用者卡在舊版本的機率。

部署新版本後，如果畫面沒有更新，可以嘗試：

重新整理頁面。
關閉再打開瀏覽器分頁。
清除該網站快取。

Google Drive 備份

正式站測試：

開啟 Wordmem 正式網址。
建立一個測試單字集。
開啟備份與匯入。
點登入 Google。
選擇已加入測試使用者的 Google 帳號。
完成授權。
點備份到 Drive。
到 Google Drive 檢查是否有 Wordmem 資料夾與 ZIP 檔。
回到 App，點讀取 Drive 備份。
確認可以列出備份並選擇匯入。

常見問題

Google 登入顯示 access blocked

可能原因：

OAuth consent screen 還在 Testing，但你的 Google 帳號沒有加入 Test users。
OAuth App 設定不完整。
使用了未授權的網域。

處理方式：

到 Google Cloud 的 OAuth consent screen。
確認你的 email 已加入 Test users。
確認 Authorized JavaScript origins 有正式 Vercel 網址。
等幾分鐘後再重試。

Google 登入顯示 origin mismatch

代表目前網站網址沒有被加入 Authorized JavaScript origins。

請檢查：

本機開發是否加入 http://localhost:5173
正式站是否加入你的 Vercel 網址
網址是否多了結尾 /
http 與 https 是否填錯

App 顯示尚未設定 VITE_GOOGLE_CLIENT_ID

代表環境變數沒有正確注入。

本機請檢查：

.env.local

Vercel 請檢查：

Project Settings -> Environment Variables

修改 Vercel 環境變數後，需要重新部署。

Vercel 部署成功但 Google Drive 仍不能用

請確認：

Vercel 有設定 VITE_GOOGLE_CLIENT_ID。
修改環境變數後已重新部署。
Google Cloud 已啟用 Google Drive API。
OAuth Client ID 的 Authorized JavaScript origins 有正式網址。
使用的 Google 帳號已加入 Test users，或 OAuth App 已正式發布。

重新整理練習頁出現 404

請確認 Repository 內有 vercel.json，且內容包含：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

如果你剛新增或修改 vercel.json，請 commit、push，並讓 Vercel 重新部署。

npm run build 在 Vercel 失敗

先在本機執行：

npm run typecheck
npm run lint
npm run test
npm run build

本機如果也失敗，先修本機錯誤。

本機成功但 Vercel 失敗時，檢查：

Node.js 版本是否差太多。
package-lock.json 是否已 commit。
是否有缺少環境變數。
Vercel Build Logs 的第一個錯誤訊息。

更新部署

日後修改程式後，照以下流程更新正式站。

檢查狀態：

git status

加入變更：

git add .

建立 commit：

git commit -m "Update Wordmem"

推送到 GitHub：

git push

Vercel 會自動偵測 GitHub 的新 commit，並開始重新部署。

自訂網域

如果你不想使用 Vercel 預設網址，可以設定自訂網域。

在 Vercel 加入網域

到 Vercel 專案。
進入 Settings。
進入 Domains。
輸入你的網域，例如：

wordmem.example.com

依照 Vercel 顯示的 DNS 指示設定。

在 Google Cloud 加入自訂網域

自訂網域啟用後，回到 Google Cloud OAuth Client。

在 Authorized JavaScript origins 加入：

<https://wordmem.example.com>

如果使用裸網域，也加入：

<https://example.com>

只加入你實際會使用的網址即可。

上線前檢查清單

建議維護方式

每次功能修改後先跑 npm run typecheck、npm run lint、npm run test、npm run build。
每次正式部署後測一次 Google Drive 登入與備份。
定期確認 Google Cloud OAuth 設定沒有被改動。
如果要開放給更多使用者，需評估是否把 OAuth App 從 Testing 發布到 Production。
重要單字資料請定期匯出 ZIP，避免只依賴瀏覽器本機資料。

Tavric's Blog

Hynan 介紹

App 介紹

核心功能

Google 登入

Demo 模式

Inbox 任務管理

每日任務

每日筆記

標籤分類

多 Workspace

任務詳情面板

Google Calendar 同步

離線與本機快取

即時同步

PWA 安裝

主要頁面

Login

Inbox

Daily

Journal

Tags

Tag Detail

資料表

workspaces

tasks

tags

daily_entries

google_calendar_connections

google_calendar_workspace_calendars

google_calendar_sync_queue

Wordat 介紹

核心特色

主要畫面

單字清單

儀表板

分類管理

備份與還原

技術架構

使用限制

Tabin 介紹

主要用途

核心功能

技術架構

資料與隱私

適合的使用方式

部署教學

1. Fork GitHub repo

2. 建 Firebase / Google Cloud project

3. Firebase Console 要自己建立或啟用的項目

4. Google Cloud Console 要啟用的 API

5. GitHub Actions deploy account

6. Functions runtime account

7. GitHub Secrets

8. 部署順序

官方參考

Wordmem 介紹

App 介紹

核心特色

單字集管理

AI 匯入單字集

單字卡模式

選擇題練習

拼字測試

測驗結果與錯題複習

本機資料保存

ZIP 匯出與匯入

Google Drive 手動備份

使用流程

第一次使用

日常複習

技術概覽

前端架構

資料與備份

適用對象

學生

老師與家教

自學者

邏輯介紹

角色與使用情境