# 跨課程分組與互評平台

## 目的與目前範圍

建置可跨班級、學期使用的浮動分組與學生互評平台。第一版包含名冊、活動／正式分組、成員確認、教師核定、評量輪次與名單快照、繁中／英文 BARS、自評／互評、修改版本、教師查核、低樣本回饋保護及 JSON 匯出。互評結果只作為教師判讀資料，不得由系統自動扣分、排名或替學生貼標籤。

2026-09-07 使用者決定：因 `537SONIC` Free 方案無法新增第三個專案，改用既有 Supabase 專案 `537SONIC's Project`（project ref：`EXAMPLE_SUPABASE_PROJECT`）。本平台只能使用獨立的私有 `course_team` 與 `course_team_private` schema，以及 `public.ct_*` 驗證函式；不得改動、重命名或刪除既有 `public` 看板資料、函式與政策。

## 位置與正式來源

本檔所在的 `course-team-peer-platform` 是正式原始碼根目錄。重要檔案：

- `README.md`：設定、建置、測試與部署方式。
- `PLAN.md`：已複核的產品與治理計畫。
- `SOURCE_AUDIT.md`：舊系統、量表與來源邊界查核。
- `supabase/migrations/`：可重播的資料庫結構、API、題本與索引。
- `supabase/tests/`：交易式遠端驗收腳本，必須包在 `BEGIN`／`ROLLBACK` 內。
- `HANDOFF.md`：目前雲端、本機、測試與發布狀態。

既有 SONIC-repo、BARS、GAS 與 CM216 資料只作為來源；除非另有明確授權，不複製逐筆學生資料、私人回覆或受限量表到公開位置。

## 開發與資料規則

1. 中文使用臺灣繁體中文；介面不出現開發、Agent、migration 或部署交接語言。
2. 正式程式使用名冊電子郵件與密碼登入，不提供公開註冊。教師建立帳號與設定臨時密碼必須在伺服器端處理，不得把 `service_role` 或其他管理金鑰放入瀏覽器；密碼只回傳給教師下載成 CSV，再由 Codex 透過 Gmail 逐封寄送並以回條寫回結果。原始含明文密碼的 CSV 保留在指定 Google Drive 資料夾，不刪除、不移出；補寄可重新讀取同一份 CSV，不重新設定密碼。登入不等於選課資格，所有資料操作仍由 RPC 驗證名冊、角色、班級與輪次。
3. 前端不得直接查寫 `course_team` 資料表。供瀏覽器呼叫的 `ct_*` RPC 必須是 `SECURITY DEFINER`、固定 `search_path`，明確撤銷 `PUBLIC`／`anon` 執行權，只授權 `authenticated`；帳號派發 claim、CSV 批次登錄及 Gmail 回條 RPC 只授權 `service_role`，教師名冊狀態更新則由 authenticated RPC 驗證課程管理權限。
4. 分組使用有時效的 membership；同一用途不得重疊。評量開放前建立不可被後續調組改寫的 assignment snapshot。
5. 提交採 request key 冪等、版本化修改與單一交易；觀察不足為 `null` 加理由，不得換算成 0 分。自評與同儕評量分開。
6. 正式名冊、Auth 使用者、學生回覆及評語不得作為測試資料。遠端驗收一律使用明確合成資料並確認 rollback 後為零。
7. `.env.local`、服務角色金鑰、資料庫密碼、Cookie、匯出檔及學生資料不得提交。公開前執行秘密資料掃描。

## 建置、查核與發布

此 Google Drive 路徑是正式來源；若其檔案系統造成 npm 安裝失敗，可將原始碼機械同步到本機依賴鏡像執行，但不得在鏡像手改後忘記回寫。現用鏡像位置記於 `HANDOFF.md`。

每次變更至少執行 `npm run check`。資料庫變更以新增 migration 進行，先做權限與交易測試，再套用既有專案；禁止直接手改正式 schema 後不留 migration。部署後重新確認：28 張私有表 RLS、零 anon/authenticated 直接表權限、37 個 `ct_*` RPC 的執行角色與固定 `search_path`、測試資料清除，以及既有看板資料沒有改變。

Supabase 資料庫建置已獲授權。正式學生名冊匯入、密碼帳號建立、教師寄信流程、公開前端發布、Git commit／push、付費升級及改動既有 `public` 系統，仍須有對應明確指示與可驗證的安全條件。本輪沒有公開前端網址時，不得宣稱已正式上線。

## 完成與交接

完成可獨立交接的階段、部署或結束工作前，更新 `HANDOFF.md`，記錄臺北時間、實際檔案、遠端專案、migration、測試數字、未完成事項、重現方式及 Git 狀態。發現專案內外規則衝突時，以使用者最新明確指示為準，並在交接檔保留原因與邊界。