Novae

Novae 是給校園社群使用的開源治理 PWA。學生可提出公共議題、回報設施問題、附議、討論並追蹤處理結果；校方則在同一套系統發布公告、管理分類與權限、處理案件並查看營運狀態。

系統以單一學校為部署單位。登入資格由 Google 帳號網域限制，平台管理員只由 Worker 的 ADMIN_EMAILS 決定，分類管理員則依明確的 category scope 授權。

問題與目標

校園議題常散在表單、社群貼文、私訊和紙本流程裡。提出者不知道案件走到哪一步，其他人看不到附議期限與處理進度，管理方也很難把公開提案、私密權益案件、設施回報和公告放在同一套權限模型下處理。

Novae 把這些流程收進一個可安裝的 Web App：內容狀態與期限對成員可見，管理權限綁定到明確 category，所有寫入由同一個 Worker API 進入 PostgreSQL transaction。通知、Push、Realtime 與選用的 Notion 營運副本從已落庫的 domain event 衍生，不讓外部服務成為主要資料來源。

核心功能

• 公共提案：依分類設定公開範圍、匿名顯示、附議門檻、附議期限與留言權限。
• 權益案件：支援審核後公開或僅作者與管理員可見的處理流程。
• 設施回報：追蹤受影響人數、處理狀態與結案說明。
• 公告與討論：公告、按讚、留言、回覆及圖片附件。
• 通知：站內通知、Web Push，以及透過 Durable Object WebSocket 傳遞的即時更新。
• 管理：首次分類設定、分類權限、使用者限制、資料保留政策、背景工作與稽核紀錄。
• PWA：可安裝、離線資產快取、版本更新提示、響應式導覽與中英文介面。

系統架構

flowchart LR
    U[校園成員與管理員] --> PWA[React SPA / PWA<br/>Vercel static]
    PWA -->|Firebase ID token<br/>App Check / Turnstile| API[Cloudflare Workers API]
    API -->|Hyperdrive<br/>novae_runtime| DB[(Neon PostgreSQL)]
    API --> Q[Cloudflare Queues]
    API --> DO[Durable Objects<br/>WebSocket / Rate limits]
    API --> C[Cloudinary]
    API --> F[Firebase Cloud Messaging]
    Q --> N[Notion<br/>選用的營運副本]
    Q --> DB

瀏覽器只呼叫 Worker，不持有資料庫憑證。Worker action 與 PostgreSQL RPC 共同執行權限檢查；寫入產生的 domain event 會與主要資料在同一個 transaction 中記錄，再由 Queue 分送到站內通知、Push、Realtime 或選用的 Notion 副本。完整說明見系統架構與後端及資料層。

一次一般寫入會經過這條路徑：

1. Browser 取得 Firebase ID token、App Check token，以及 write operation 的 UUID。
2. Worker 驗證 Origin、身分、rate limit、permission 和 category scope。
3. PostgreSQL transaction claim operation、執行 RPC、記錄 audit / event，再保存 canonical response。
4. Worker 回應 client，Queue 在背景處理站內通知、FCM、Realtime 和 Notion delivery。
5. Browser 收到 realtime revision 後只讓受影響 cache 失效；若 revision 出現缺口，就重新讀 authoritative data。

技術棧

層級	技術	實際用途
Web	Vite 8、React Router 8、React 19.2、TypeScript 7	靜態 SPA、每個畫面一個 lazy chunk、PWA 介面與 client state
UI	Tailwind CSS 4、Radix UI、Phosphor Icons、Motion	Design tokens、可存取元件、圖示與狀態轉場
前端資料	TanStack Query 5	讀取快取、失效重讀與每個帳號的 IndexedDB 保存
PWA	Serwist 9（@serwist/vite）	Service Worker、離線 app shell、安裝與版本更新流程
身分與裝置	Firebase Authentication、App Check、Cloud Messaging	Google 登入、app attestation、Web Push
API	Cloudflare Workers、Hyperdrive	驗證、action dispatch、資料庫連線與媒體代理
非同步與即時	Cloudflare Queues、Durable Objects	Event delivery、背景批次、WebSocket、業務 rate limit
資料庫	Neon PostgreSQL 17、pg	交易、RPC、RBAC、稽核與資料保留
媒體與整合	Cloudinary、Notion API（選用）	簽名圖片與營運紀錄副本
工具與測試	Bun 1.4、Vitest 4、ESLint 9	產物生成、靜態檢查、單元與整合測試

Novae 沒有接入生成式 AI 模型；目前的自動化集中在事件投遞、資料維護與部署驗證。

快速開始

需要 Node.js 24、Bun 1.4，以及可執行 Linux container 的 Docker。Windows 會由專案腳本透過 WSL 啟動 Docker。

bun install --frozen-lockfile
bun run test:env

test:env 會重建本機 PostgreSQL、套用 migration 和 sample seed，接著啟動 Firebase Auth Emulator、外部服務 stub、Cloudflare Worker 與 Vite dev server。Ready 後可使用：

• App：http://127.0.0.1:3000
• API：http://127.0.0.1:8787
• Auth Emulator：http://127.0.0.1:4000/auth

按 Ctrl+C 會停止這次啟動的服務。若要接真實 Firebase 或 Cloudinary 進行手動開發，改走本機開發與設定參考。

常用驗證：

bun run verify:local        # 前端、型別、lint、unit、architecture、build、audit
bun run verify:integration  # PostgreSQL、Worker、權限、RPC、Queue、Realtime
bun run verify:all          # local + integration

文件

• 文件索引
• 產品與使用流程
• 路由、角色與權限
• 系統架構
• 後端及資料層
• 事件、即時更新、通知與圖片
• 執行期政策與限制
• 設定參考
• 本機開發
• 部署與維運
• 測試與驗證
• 一般成員與管理員操作手冊
• 首頁與內容列表
• 介面設計
• 文件與程式地圖維護
• 離線程式流程地圖產生器

程式地圖把架構、資料模型、每個 action、設定生效時機和自動觸發拆成可逐步閱讀的流程，並內嵌原碼快照。執行 node tools/project-map/build.mjs 會產生桌面的 Novae-程式流程地圖.html，可離線開啟。它描述目前 checkout，正式環境的政策值仍須從管理介面確認。

現行邊界

• 每個部署服務一個學校網域，不是多租戶 SaaS。
• 登入只支援符合 ALLOWED_DOMAIN 的 Google 帳號。
• 圖片流程依賴 Cloudinary；Notion 同步可以完全關閉。
• Web Push、PWA 安裝及背景行為仍受瀏覽器與作業系統能力限制。
• 資料庫變更只接受新的 forward migration；已套用的 migration 不會回改。

第三方服務與授權

服務或素材	必要性	Novae 使用方式
Vercel	正式部署需要	靜態 frontend build、hosting 與 security header
Cloudflare Workers / Hyperdrive / Queues / Durable Objects	必要	API、PostgreSQL connection、背景工作、Realtime、業務 rate limit
Neon	必要	PostgreSQL source of record
Firebase Authentication / App Check / Cloud Messaging	必要	Google 登入、browser attestation、Web Push
Cloudinary	必要	Signed WebP upload、authenticated delivery、deletion lifecycle
Notion	選用	Domain event 與 admin audit 的營運副本
HarmonyOS Sans TC package	Build dependency	從專案實際字元產生 WOFF2 unicode-range subset

JavaScript dependency 的固定版本記錄在 bun.lock。各雲端帳號、credential 與資料由實際部署者管理；需要放進 GitHub Environment 的欄位列在設定參考。

程式碼採 MIT License 授權。