課程維護者指南｜84 小時前端課程

本文件只給教材維護者使用。學生入口是 index.html、COURSE_MAP.html 與 MEETINGS.html。

唯一來源與衍生頁

課次／章節時數唯一來源： course-allocation.json。
創作階段與挑戰唯一來源： creation-path.json。
tools/build-course-navigation.mjs 由 course-allocation.json 與各章 Manifest 的 artifact.output 靜態產生 COURSE_MAP.md、COURSE_MAP.html 與 MEETINGS.html；頁面必須能在 file:// 使用，因此不可在瀏覽器執行階段用 fetch() 讀 JSON。
COURSE_MAP.md、COURSE_MAP.html 與 MEETINGS.html 是衍生的學生版資訊，不得直接手改，也不得顯示舊章來源、目錄名、原始 JSON 結構或維護指令。
MAINTAINER_GUIDE.md 與 MAINTAINER_GUIDE.html 才是課程配置、同步責任與維護指令的放置位置。

不要在首頁、課程地圖或課次頁另建第二套章節時數。若配置異動，先改唯一來源，再同步學生頁。

課次配置契約

course-allocation.json 的重要欄位：

chapterCount 與 meetingCount 都是 28。
meetingDurationMinutes 是 180。
totalMinutes 是 5040。
每個 meeting 的 segments[].minutes 加總必須等於 180。
六組跨章交棒固定為課次 05–06、10–11、13–14、18–19、24–25、27–28。

章節本身可為 120、150、180、210 或 240 分鐘；課次仍固定 180 分鐘。不可把「章節時數」改寫成「每章都是 180 分鐘」。

學生進度資料契約

共用腳本 assets/course.js 使用版本化 key frontend-course-v2-progress，只保存：

依頁徑與索引識別的 Evidence checkbox 狀態。
依頁徑與 TASK 編號識別的固定任務確認。
依章節頁徑識別的創作挑戰完成狀態。
上次由學生明確操作或點擊的章節位置。

不得保存姓名、作品內容、表單輸入、聯絡資料或其他個資。造訪頁面不代表完成；只有勾選或按鈕操作能寫入完成狀態。解析失敗的舊資料會先備份到帶時間戳的 invalid key，再回到空進度；瀏覽器停用 storage 時必須退回記憶體且不丟出錯誤。

同步與驗證

課次配置或學生入口異動後，至少執行：

node --check assets/course.js
node tools/build-student-docs.mjs
node tools/check-course-navigation.mjs
node tools/check-course.mjs
node tools/check-learning-transfer.mjs
node tools/check-practice-contract.mjs
node tools/check-session-pages.mjs
node tools/check-starter-zips.mjs
git diff --check

另以 file:// 與本機 HTTP server 各驗證一次：首頁續學、Evidence 刷新保存、TASK 確認、創作挑戰完成、重設進度、28 張課次卡、每卡 180 分鐘、六組跨章交棒、390px 手機版與鍵盤 focus。

變更邊界

課次配置變更：先改 course-allocation.json，再執行 node tools/build-student-docs.mjs；不可手動同步課次卡。
創作階段變更：先改 creation-path.json，再同步首頁、課程地圖與相關產生頁。
章節練習內容：以 sessions/*/practice-manifest.json 與章節契約為準，不在學生入口重新定義 TASK。
共用樣式不得破壞 practice guide 的淺色隔離；新增首頁或課次 UI 時使用專屬 class 範圍。