penink-work — WH-penink

作品介紹

名稱： 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」。

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