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)

1. All development changes must be validated on Preview deployment first.
2. Share the Preview URL for review and wait for explicit owner approval.
3. Do not deploy to Production until approval is explicitly given in chat.
4. 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)

• Free parent test account available
• Paid parent test account available (with payment history)
• Admin test account available
• Test student set includes P1-P6 and both genders/avatars/schools
• Test discount code exists
• Browser set: Safari + Chrome

This is the beginning of the README. Read the rest at the original. Read the full README ↗