GearUp Quiz
Interactive quiz application built with Next.js, TypeScript, Tailwind CSS, and Supabase.
練習小結（每節測驗後）
- 內容：完成一節練習後，系統根據各題
question_type 正確率產生 約 50–80 字 繁體小結（鼓勵語氣、含強項、弱項與生活化建議）。目前不呼叫 LLM（純規則）；要更口語可接 OpenAI 等，仍寫入同欄位。
- 顯示：學生結果頁在整體正確率區塊下方，小香蕉對話泡泡內。
- 儲存：
quiz_sessions.session_practice_summary（學生向）、session_practice_summary_parent（老師視角給家長）；RPC save_session_practice_summaries(p_session_id, p_student_id, p_student_summary, p_parent_summary)。
- 電郵：
get_quiz_email_data 含 session_practice_summary_parent（電郵正文）；完成練習時 Body 可傳 session_summary_parent 作後備。
- Supabase：執行
supabase_session_practice_summary.sql（欄位 + 函數 + 更新 get_quiz_email_data）。
- 測試：
npm test；手動清單見 test_plan_practice_session_summary.md。
Parent dashboard: 同級排名
- 位置：家長「練習報告」內容區由上而下為：① 科目切換（
Math／Chinese／English）→ ② 同級排名（ParentGradeRankPanel，隨科目：與列表／圖表同一 p_subject）→ ③ 月份導航與列表／圖表。純前端順序；排名改為按科目需執行 supabase_grade_ranking_per_subject.sql 並重跑 recalculate_student_grade_rankings()。
- 邏輯（批次：
recalculate_student_grade_rankings()；讀取：get_parent_student_grade_rank(p_student_id, p_subject)）
student_grade_rankings 每列含 subject（Math／Chinese／English…）；Math 統計含 quiz_sessions.subject 為 Math 或 數學。- 只納入 該科目累積完成至少 100 題（
sum(questions_attempted)，僅 questions_attempted > 0 的次數）的同級學生。
- 分數＝該科目 最近 10 次練習的「每次正確率」之平均。
- 以該分數在同期
grade_level + subject 內用 RANK 排名。
- 更新：Vercel Cron（
vercel.json → /api/cron-recalculate-averages）先 recalculate_student_grade_rankings()，再 recalculate_grade_averages()。
- 讀取：
get_parent_student_grade_rank(p_student_id, p_subject) — 前端與 get_parent_sessions / get_student_chart_data 傳相同科目鍵。
- 佈署：在 Supabase 執行
supabase_grade_ranking_per_subject.sql（會清空舊排名表並改 schema），然後手動或等 cron 執行 recalculate_student_grade_rankings()。若 GRANT 失敗，再執行 supabase_grade_cron_delete_and_grants.sql 內相關 GRANT（或於該檔補上 get_parent_student_grade_rank(uuid, text)）。
- 如批次／cron 出現
DELETE requires a WHERE clause：在 Supabase 執行 supabase_fix_batch_delete_require_where.sql（將 DELETE FROM … 改為 DELETE FROM … WHERE true）。
- 如出現
canceling statement due to statement timeout：資料量較大時，原先排名批次對每位學生子查詢掃表會過慢；請在 Supabase 執行 supabase_optimize_ranking_batch_performance.sql（加索引、改寫成集合式查詢，並在函數內 SET LOCAL statement_timeout = '5min'）。Vercel 路由 /api/cron-recalculate-averages 已設 maxDuration = 300（秒），需重新部署才生效。
- 如仍超時（兩道 RPC 各跑一輪仍觸及 PostgREST 單次請求上限）：每日批次已拆成兩個 Vercel Cron——
?part=rank（0:00 UTC）與 ?part=grade（0:02 UTC），見 vercel.json。（可選）在 Vercel 專案加入 SUPABASE_SERVICE_ROLE_KEY 讓 API 以 service role 呼叫 RPC。依序執行：supabase_optimize_grade_averages_batch.sql → supabase_split_grade_averages_cron.sql → supabase_grade_averages_two_step_per_grade.sql；若**單一年級的「全部題型」**仍超時，執行 supabase_grade_by_question_type_fine.sql；若 ?part=grade 仍失敗，再執行 supabase_grade_cron_v2_query_plans.sql（索引＋從 students／questions 驅動的 overall / one_type）；務必在 Vercel 設定 SUPABASE_SERVICE_ROLE_KEY（僅專案密鑰，勿入庫）。
- 測試：見
test_plan_grade_ranking.md。
- 最後一併執行
supabase_grade_cron_delete_and_grants.sql：新增 delete_grade_averages_for_grade(grade_level)，並補齊 GRANT EXECUTE 給 cron 會呼叫的函數。API 在 fallback 到 recalculate_grade_by_type_for_grade 前可刪除該年級列，避免 unique 衝突。
Nightly batch
- Vercel env:
CRON_SECRET (bearer for /api/cron-recalculate-averages), SUPABASE_SERVICE_ROLE_KEY (strongly recommended for long RPCs). Rotate CRON_SECRET immediately if previously exposed.
- Recommended SQL order for chart/rank recalc:
…optimize_grade… → …split… → …two_step… → …by_question_type_fine… → supabase_grade_cron_v2_query_plans.sql → supabase_grade_cron_delete_and_grants.sql.
- Response includes
use_service_role: true when the service key is set.
Deployment
The app is deployed on Vercel (custom domain q.hkedutech.com; Vercel project quiz-deploy under scope colinwong-clouds-projects).
Production URL: https://q.hkedutech.com
Link once: vercel link (scope colinwong-clouds-projects, project quiz-deploy). Ship to production: npx vercel deploy --prod.
Mandatory deployment gate (must follow for every session)
- All development changes must be validated on Preview deployment first.
- Share the Preview URL for review and wait for explicit owner approval.
- Do not deploy to Production until approval is explicitly given in chat.
- After production deploy, run production smoke checks and record sign-off in the release checklist.
PWA / icons: src/app/apple-icon.png serves /apple-touch-icon (iOS “Add to Home Screen”); src/app/icon.png is the favicon. Both use the banana mascot artwork.
Latest production deploy: 2026-06-23 — deployment dpl_79DmeNLXGwFv4qYCt7iSRPyyJU7Z, alias Ready at https://q.hkedutech.com (inspect: https://vercel.com/colinwong-clouds-projects/quiz-deploy/79DmeNLXGwFv4qYCt7iSRPyyJU7Z). Release scope: Admin「教師編號維護」新增 Part 3 密碼重設（重設為 123456、清除鎖定、強制下次登入改密碼），並把成功提示訊息顯示於 Part 3 區塊底部。
Release SOP / checklist (mandatory)
- SOP:
docs/release-sop.md
- Checklist:
docs/release-deploy-checklist.md
Feature inventory + mandatory health checks (run on every new release)
Purpose: prevent any regression where older features become missing or non-functional after new development.
0) Test Preconditions (must prepare)
This is the beginning of the README. Read the rest at the original. Read the full README ↗
