══════════════════════════════════════════════════════════════
    作 品 介 紹
    名 稱 ： penink-work（wh·penink·work）・ 學生成績管理系統
    類 型 ： 純前端網頁應用（100% 免費・開源軟體，MIT 授權）
    線 上 ： 開源版請自行部署於 Cloudflare Pages（見 README）
    技 術 ： HTML / CSS / JavaScript（vanilla，無框架無後端）
    部 署 ： Cloudflare Pages + KV（兩者皆免費方案）
══════════════════════════════════════════════════════════════


一、這是什麼
──────────────────────────────────────────────────────────────
一套專門給班級／老師使用的線上成績管理工具。不需要安裝、
不需要註冊，打開網頁就能用。介面採「白色為主體、黑色為按
鈕／輔助線／圖案」的黑白簡潔風。本版本為去除作者個人雲端
設定的開源版：任何人 clone 後建立自己的 Cloudflare 專案即
可上線，程式完全不含原作者的金鑰、帳號或網域。

  核心功能（依照需求訂做）
  ＊ 新增科目 → 每科最多 20 個章節
  ＊ 每個章節最多 60 個成績欄位、100 位學生
  ＊ 點格子即可打分與修改，分數即時自動存檔
  ＊ 平均分、排名、及格率、完成率全部自動計算
  ＊ 大目錄首頁與科目首頁都列出「哪些學生缺哪些成績」
  ＊ 未填格子自動標示、未達及格線自動標紅
  ＊ 匯出 CSV（成績／統計／空白表）與 JSON 完整備份
  ＊ 班級排行、學生搜尋、只看缺成績、列印……共 33+ 個功能
  ＊ 帳號權限：管理員／老師／小老師三種角色
  ＊ 雲端同步：多裝置共用同一份資料、即時更新、衝突自動合併
  ＊ 分班（班導）：建立自己的班、拉各科老師進班，自動彙整
    整班學生成績（全班總表＋一科科唯讀檢視）

  可支援的規模上限
  科目 500 個 ／ 每科 20 章 ／ 每章 60 欄 ／ 每章 100 生


二、製作過程
──────────────────────────────────────────────────────────────
  開發流程（一步一驗證）
  1. 資料層 store.js
      設計完整資料模型（科目→章節→欄位→學生→成績、帳號、
      班級）。撰寫 15 支單元測試自動驗證增刪改、上限、統計、
      平均（含「未填視為 0」開關）、CSV、分班等。
  2. 檢視層 UI
      大目錄首頁、科目首頁、章節成績表、分班頁四個畫面，
      加上 toast、彈窗、選單等互動元件。
  3. 互動功能
      格子快捷鍵編輯（Enter 下一行、Tab 下一欄、方向鍵移動、
      Esc 取消）、排行榜、缺成績標記、搜尋過濾、唯讀模式。
  4. 匯入匯出
      JSON 備份（合併／覆蓋）、CSV 雙向、列印版面。
  5. 自動化測試
      另寫 69 支 UI 冒煙測試（jsdom 模擬真人操作，含登入、
      帳號權限、雲端登入、即時同步、分班與唯讀流程），
      ＋ 7 支 Cloudflare Pages Functions API 測試，全部通過後
      才部署上線。
  6. 上線部署
      使用 Cloudflare Pages 免費托管，實際網址驗證成功。

  技術筆記
  ・ 純原生 JavaScript（IIFE 模組），不需任何框架。
  ・ 前端資料存在瀏覽器的 localStorage；開啟雲端同步後才會
    上傳到 Cloudflare KV，零後端、零成本。
  ・ 上架前已做「去隱私」處理：移除作者的 KV 金鑰、帳號與
    網域，將 deploy 指令改成任何人的專案名都能用。


三、使用教學
──────────────────────────────────────────────────────────────
  ① 建立科目
     頂欄「新增科目」→ 輸入名稱 → 確定。
  ② 建立章節
     進入科目 →「新增章節」→ 命名，可勾選常用欄位
     （小考、作業、期中考…）或沿用上一章的欄位與名單。
  ③ 新增學生
     進入章節 →「新增學生」→ 一次輸入一排一個名字。
     也可「從其它章節帶入名單」。
  ④ 打成績
     點格子直接輸入分數，Enter 換下一行、Tab 換下一欄。
     平均、排名、缺繳名單全部自動更新。
  ⑤ 匯出與備份
     頂欄「備份」下載完整 JSON；「匯出 CSV」下載試算表。
     每次存檔自動保留一份備份，可在「設定」中回復。
  ⑥ 列印
     章節頁按「列印」，印出乾淨的黑白成績表。
  ⑦ 登入與帳號權限
     開啟網站先登入。分三種角色：
      管理員   admin／123（預設），可看全部科目，
              可新增／修改／刪除任何帳號與密碼。
      老師     只看指派給自己的科目，
              可新增小老師並設定其姓名、暱稱、負責科目。
      小老師   只看自己負責的那一科，負責打分與看成績。
     登出後回登入頁，換帳號即可切換角色權限。
  ⑧ 雲端同步
     管理員登入 → 設定 →「啟用雲端同步」：
       ＊ 科目、成績、帳號會上傳到 Cloudflare（免費的
         KV 雲端儲存），並在一次存檔後自動同步。
       ＊ 任何裝置用同一個帳號密碼登入，看到的就是
         同一份資料——老師的手機、小老師的平板、
         班級公用電腦，全部相通；每 30 秒自動抓最新資料。
       ＊ 多人同時改時，以「較新的一方」為準自動處理。
     不啟用時，資料仍只存在本機瀏覽器。
  ⑨ 分班（班導）
     老師可建立自己的班級 →「編輯班級」把各科老師拉進班 →
     「看全班成績」自動彙整整班學生；點任一科可唯讀檢視。

  鍵盤快速鍵
     Enter       下一行       Tab        下一欄
     ↑ ↓ ← →    移動格子     Esc        取消編輯


四、注意事項（重要）
──────────────────────────────────────────────────────────────
  ＊ 預設「本機模式」：資料只存在「開啟網頁的那台裝置 / 瀏
    覽器」，換裝置前請先按「備份」匯出 JSON 檔保存。
  ＊ 啟用「雲端同步」前，請先在 wrangler.toml 填入你自己的
    KV namespace（指令見 README / wrangler.toml 註解）。
  ＊ 系統是全免費的線上服務，且本專案不收集任何個人資料。
  ＊ 開源版不含作者的任何雲端金鑰，部署前請務必建立專屬於
    你自己的 Cloudflare 專案與 KV，切勿沿用他人設定。
  ＊ 若要轉移到另一台裝置：先備份 → 換裝置 → 按「匯入」。
  ＊ 登入密碼存瀏覽器（僅輕量區隔），請務必把預設的
    admin／123 改掉，改用不易猜的密碼。
  ＊ 授權為 MIT，可自由使用、修改、散佈、商用（見 LICENSE）。


五、保存資訊
──────────────────────────────────────────────────────────────
  本資料夾內容即專案完整原始碼（public 樣式與程式、
  functions 雲端 API、test 自動化測試、scripts 與部署設定），
  可直接在本機執行：

      npm install    安裝測試工具
      npm test       跑全部自動測試（預期全部通過）
      npm run serve  本機預覽 → http://localhost:8788

  部署方式（二擇一）：
  ・ 方式 A：npx wrangler login → 建立自己的 KV →
    npm run deploy（專案名可透過 PROJECT_NAME 環境變數設定）。
  ・ 方式 B：推到 GitHub → Cloudflare「Connect to Git」自動部署。
  詳細步驟見 README「部署到 Cloudflare Pages」。

══════════════════════════════════════════════════════════════
  文件完成・以上為公開資訊，不含任何私密資料
══════════════════════════════════════════════════════════════