rope_helper/README.md

國小學生跳繩運動紀錄與 BMI 智能建議系統 (Rope Helper)

專為台灣國小教師與體育教師量身打造的純前端跳繩體能分析與 AI 運動處方建議系統。結合衛福部國健署兒童生長 BMI 對照常模、教育部體育署 SH150 普及化運動指引與 Google AI Studio (Gemini) 免費模型。

---

🌟 核心特色

1. 純前端綠色架構：
   • 單一獨立網頁檔 index.html，無需安裝 Node.js、Python 或架設後端資料庫。
   • 所有學生資料均在老師本機瀏覽器內運算解析，確保學童個資安全。
2. 彈性 Excel 匯入與範本下載：
   • 支援「學生基本資料」與「跳繩打卡紀錄」雙工作表整合活頁簿或分開上傳。
   • 內建標準 Excel 範本下載與智慧欄位名稱對應。
   • 預設提供「載入 3 個月示範資料（三年二班 25 位學童連續 90 天打卡數據）」，開箱即用。
3. 衛福部兒童 BMI 常模智能判定：
   • 內建台灣 6~12 歲兒童生長標準，依性別與實足年齡精準判定「過輕、正常、過重、肥胖」。
4. Google AI Studio 免費 API 串接：
   • 老師可直接輸入自己的 Google AI Studio 免費 API Key（安全儲存於本機 localStorage）。
   • 支援 gemini-2.5-flash、gemini-1.5-flash 等模型。
   • 支援「一鍵全班批量生成（內建 15 RPM 速率防護間隔與即時進度條）」與「個別學生生成/重新生成/文字自訂微調」。
5. 完整報表匯出與家長通知卡列印：
   • 支援匯出含原始紀錄、統計分析與 AI 建議之完整 Excel 報告。
   • 支援一鍵列印或轉存 PDF 專用之「學生跳繩運動成長卡（A4 親職回饋聯版型）」。

---

🚀 快速開始使用

1. 直接開啟：
   • 在電腦上直接雙擊打開 index.html（建議使用 Google Chrome、Edge 或 Safari 瀏覽器）。
2. 體驗功能：
   • 點擊右上角「載入示範班級資料」即可立即查看班級數據儀表板與圖表。
3. 設定 AI Studio API Key：
   • 點擊右上角「設定 AI Studio Key」。
   • 前往 Google AI Studio 免費取得 API Key 貼上並儲存。
   • 點擊「一鍵全班 AI 運動建議生成」，系統將自動調用 Gemini 為每位學童產生量身打造的跳繩指引。
4. 匯出與列印：
   • 點擊「匯出分析 Excel」或「列印運動成長卡」發放給家長。