# Code Review — 智慧教室排程系統設計稿

審查對象：`design/Smart Classroom Site.dc.html`（主設計稿）＋ `design/HANDOFF.md`
對照文件：`docs/spec-source.txt`（UI/UX 功能規格 V1.2）、`docs/正興國小115學年_自然科教師課表彙整.docx`
初版：2026-08-29　｜　最後更新：2026-08-29（B1／B2／B3／H1 已修）

設計稿本身不是要上線的程式碼，但它的**資料模型與互動邏輯會被原封不動抄進實作**，所以以下問題都會直接變成產品的 bug。

## 狀態總覽

| 編號 | 問題 | 狀態 |
| --- | --- | --- |
| B1 | 20 週的日期標籤整組偏一天 | ✅ 已修 |
| **D1** | **教室指定資料是推測的，與實際課表不符** | 🔴 **待補真實資料** |
| B2 | 「自訂地點」是全域字串，所有課共用 | ✅ 已修 |
| B3 | 週次切換是假的，教室時段表看不到調課結果 | ✅ 已修 |
| H1 | 衝突檢查沒有週次維度 | ✅ 已修（隨 B3 一起） |
| H2 | 零鍵盤無障礙 | ⬜ 待處理 |
| H3 | 完全沒有手機版 | ⬜ 待設計 |
| M1 | 首頁「下一個占用」寫死節次 | ⬜ 待處理 |
| M2 | demo 日期與學期週次矛盾 | ✅ 已修（隨 B1 一起） |
| M3 | 登入頁預填真實預設密碼 | ⬜ 上線前必清 |
| L1 | `freeOf` 與 `usedOf` 不互補 | ⬜ 待處理 |

---

## ✅ B1 — 20 週的日期標籤整組偏一天（已修）

`dateOf(w, d)` 的基準原本是 `new Date(2026, 8, 1)`（＝2026-09-01），`HANDOFF.md` 也寫「第 1 週星期一 = 2026-09-01」。

**但 2026-09-01 是星期二。** 調課頁 20 週的每個日期都往後偏一天：畫面顯示「第 1 週 9/1–9/5」，
實際對到的是星期二～星期六。老師是照日期在調課的，這會直接調錯天。

**修法**：抽成具名常數並加開機檢查。

```js
const TERM_W1_MONDAY = new Date(2026, 7, 31); // 2026-08-31（星期一）
if (TERM_W1_MONDAY.getDay() !== 1) {
  console.error('[排程] TERM_W1_MONDAY 必須是星期一，目前是 ' + TERM_W1_MONDAY.toDateString());
}
```

現在第 1 週 = 8/31–9/4，星期一欄位真的是 8/31（星期一）。首頁右上的 demo 日期也一併改成 9/4（第 1 週的星期五），
不再出現「8/28 卻標第 1 週」的矛盾（M2）。

> ⚠ **`2026-08-31` 是暫定值。** 正式開學日請跟學校確認後改這一行——常數只有一處，改完全站跟著動。

## ✅ B2 — 「自訂地點」是一個全域字串，所有課共用（已修）

原本 `state.custom` 只是單一字串，`label()` 的 CUSTOM 分支直接回傳它。
指定 A 課到某個自訂地點、再改輸入框指定 B 課，**A 課會跟著被改名**。

**修法**：`assign` 的值從字串改成物件，自訂名稱在「按下按鈕的那一刻」快照進去。

```js
// 舊：assign['曾唯誠|1-1'] = 'CUSTOM'
// 新：assign['曾唯誠|1-1'] = { code: 'CUSTOM', name: '<按下當下輸入框的值>' }
mkValue(code) { return code === 'CUSTOM' ? {code, name: (this.state.custom || '自訂地點')} : {code}; }
```

配套加了 `codeOf(v)`，`label(v, cls)` 同時吃字串（按鈕、對話框）與物件（課表格子）。
右側那個輸入框現在純粹是**草稿欄位**，改它不會回頭動到已指定的課。

**已實測**：指定第 1 節為 A 名稱 → 把輸入框改成 B 名稱 → 指定第 2 節，兩格各自保留自己的名稱。

> 後端 assignments 資料表要跟著加 `location_name` 欄位。

## ✅ B3 — 週次切換是假的，教室時段表看不到調課結果（已修）

原本第 92、214 行的「‹ 上週 / 本週 / 下週 ›」是純 `<span>`，**沒有 onClick**；
更底層的問題是 `cell(code, p, d)` 和 `mkWeek(name)` 都不吃週次，`assign` 的 key 也只有 `教師|節-星期`。
結果：老師在調課頁把課移到第 5 週，切到教室時段表看那間教室**跟沒調一樣**。

**修法**：

1. state 加 `roomWeek`、`schWeek` 兩個游標
2. `cell(code, p, d, week)` 與 `mkWeek(name, week)` 改走 `occ()` — `occ()` 本來就會先查 `moves`／`removed` 再回落到固定課表
3. `freeOf(code, week)` / `usedOf(code, week)` 跟著帶週次
4. 兩頁的上週／本週／下週改成真的可點，標題顯示「第 N 週（起–迄）」
5. 首頁「今日課程」也改走 `occ()`，才不會跟調課結果打架（調入的課標「調課移入」）

**已實測**：把第 1 週星期二第 1 節的課調到第 3 週星期三第 1 節、指定自然教室一之後——
自然教室一第 1 週該格是「空閒」，第 3 週該格是「已占用 · 507 班 · 曾唯誠」；我的課表第 1 週來源格清空、
第 3 週出現「↷ 自然 507 · 自然教室一」。

## ✅ H1 — 衝突檢查沒有週次維度（已修）

`clashList()` 原本只掃 `SCHED`（固定課表），不看 `moves`，所以調課不會檢查「其他老師也調課到那個時段」。

**修法**：簽章改成 `clashList(name, code, p, d, week)`，內部改走 `occ()`；調課的檢查用**目標週次** `tgt.w`，
選教室因為是學期範圍指定，用 `CUR_WEEK`。

> 後端的 `GET /assignments/conflicts` 也要加 `week` 參數，否則會漏掉調課製造出來的衝突。

---

## 🔴 D1 — 教室指定資料是推測的，與實際課表不符（待補真實資料）

`initAssign()` 目前把**每位老師的所有課都自動指定到他自己的固定教室**。這個規則是舊 handoff 帶下來的推測，
不是學校的真實資料。

曾唯誠的實際課表（使用者提供的課表圖）顯示事情不是這樣：他**沒有自己的教室，而是逐節借用 341／541／542**，
其中 604 班第三、四節是**分組課，同時使用 541 和 542 兩間**。

把他的真實教室資料填進去，再搭配「其他四位都用自己固定教室」這個推測，會產生 **7 筆衝突**：

| 教室 | 時段 | 撞到誰 |
| --- | --- | --- |
| 341 | 星期四 第 5 節 | 曾唯誠(603) vs 曾喬笠(606) |
| 341 | 星期四 第 6 節 | 曾唯誠(602) vs 曾喬笠(606) |
| 541 | 星期一 第 5 節 | 曾唯誠(601) vs 彭靖雯(404) |
| 541 | 星期二 第 3 節 | 曾唯誠(604) vs 彭靖雯(402) |
| 541 | 星期二 第 4 節 | 曾唯誠(604) vs 彭靖雯(402) |
| 542 | 星期二 第 3 節 | 曾唯誠(604) vs 柯協佳(505) |
| 542 | 星期二 第 4 節 | 曾唯誠(604) vs 柯協佳(505) |

七筆全部涉及曾唯誠，代表**「每位老師所有課都用自己固定教室」這個推測是錯的**——其他四位老師應該也跟曾唯誠一樣，
是逐節各自有教室，只是我們還沒有他們的資料。

**待辦**：取得田麗娟、彭靖雯、柯協佳、曾喬笠四位的課表（含教室欄位），把 `initAssign()` 換成真實的逐節指定。
在那之前，畫面上看到的教室占用狀況都不可信。

**連帶的資料模型問題**：分組課一個時段要對應**兩間教室**，現在 `assign` 一格只能存一間。

## ⬜ H2 — 零鍵盤無障礙（待處理）

全檔統計：`onClick` 28 個，全部掛在 `<div>` / `<span>` 上；`<button>` **0 個**；`tabindex` / `role` / `aria-*` **0 個**；`<form>` **0 個**。

規格第 7 節明訂「鍵盤可操作；焦點狀態清楚」，4.1 明訂「按 Enter 可登入」——**現在登入頁沒有 form，按 Enter 不會送出**。

設計稿沒改（改了會動到整份版面結構，該在實作端一次做對）。實作時互動元素一律用 `<button>` / `<form>`，
`<label for>` 綁到 input，**不要照抄 div 結構**。這是設計稿最容易被無腦複製的地方。

## ⬜ H3 — 完全沒有手機版（待設計）

全檔 `@media` **0 個**，而且用的是硬值 grid：登入頁 `44% 56%`、教室列表 `1fr 1fr`、
選教室／調課右欄 `minmax(0,1fr) 268px`（`HANDOFF.md` 還特別註明「不可讓它換行到下方」）。

規格第 7 節要求「手機優先採單日／單教室檢視」。探索稿 `Smart Classroom Scheduling (mockups).dc.html`
裡已有 8 個 390px 手機畫面（登入、帳號設定、首頁、教室列表、教室週表單日分頁），這些可沿用。

**真正缺的是「選教室」與「調課系統」兩個畫面**——兩者在桌機版都依賴右側固定 268px 面板，
390px 沒有這個空間，必須重新安排版面。功能書見 `docs/手機版功能描述_選教室與調課.md`，
設計稿由使用者補齊後再接進主設計稿。

## ⬜ M1 — 首頁「下一個占用」寫死節次

```js
const nextOf = (rc) => { for (let i = 6; i <= 7; i++) { ... } };
```

寫死只掃第 6、7 節，因為 demo 的「現在」被固定成星期五第 5 節（`TODAY = 4`）。
實作要改成從當前節次 +1 掃到第 7 節。

## ⬜ M3 — 登入頁預填真實預設密碼

```js
state = { page:'login', acct:'tseng.wc', pwd:'SmartClass2026!', ... }
```

設計稿方便展示沒問題，但**這組密碼不該進正式環境、也不該當成實際初始密碼沿用**。

## ⬜ L1 — `freeOf` 與 `usedOf` 不互補

`freeOf` 只算 `free`、`usedOf` 只算 `busy`，`paused` 和 `conflict` 兩邊都不算，
所以「35 格中 N 格空閒 / N 格固定課占用」在有衝突格時相加不等於 35 − 暫停數。

---

## 資料來源與可信度

| 資料 | 來源 | 可信度 |
| --- | --- | --- |
| 5 位教師、逐節課表（共 75 節） | `docs/正興國小115學年_自然科教師課表彙整.docx` | ✅ **已逐格程式比對，零差異**。無同一老師同時段重複、無班級被排兩次 |
| 教師角色、授課班級、每週節數、排列順序 | 同上 | ✅ 一致 |
| 節次時間、作息時間 | 同上 ＋ 規格 V1.2 | ✅ 一致 |
| 4 間教室代號與教師對應 | 使用者確認 | ✅ 341→曾喬笠、541→彭靖雯、542→柯協佳、543→田麗娟 |
| **每一堂課實際用哪間教室** | 推測 | 🔴 **只有曾唯誠有真實資料（來自課表圖），其餘四位是推測的** — 見 D1 |
| 教師帳號（`tien.lc` 等） | 舊版 handoff | ⚠ 課表 docx 無此欄位，暫定命名規則 |
| 曾唯誠的教室 | — | ✅ 依指示維持「待指定」 |
| 暫停使用時段 | 無 | ✅ 已刪除，`PAUSED` 為空陣列。畫面仍支援該狀態，由管理者維護 |
| 自訂地點預設名稱 | 無 | ✅ 已清空（原本預填「圖書館」，是憑空來的） |

---

## 與規格書 V1.2 的落差

設計稿把規格書裡的**預約功能整個拿掉**，改成「選教室 + 調課」。這是使用者自己決定的方向，但連帶影響：

| 規格書內容 | 設計稿現況 |
| --- | --- |
| 4.5 預約視窗 | 不存在 |
| 4.6 我的預約 + 取消確認 | 不存在 |
| 6. 防止衝堂的四種情境 | 只實作「同一教室同一時段已有人使用」 |
| UX-01～UX-05 驗收條件 | 講的都是預約流程，對不上 |

驗收條件已重寫，見 `docs/驗收條件.md`（V2.0）。規格書本體要不要跟著改版，請跟學校確認。

## 建議處理順序

1. **取得其餘四位老師的課表（含教室欄位）**，把推測的教室指定換成真實資料（D1）
2. 跟學校確認：**正式開學日**（B1 的常數）、分組課要不要支援、規格書要不要改版
2. 補手機版設計（H3）
3. 實作時把互動元素換成 `<button>` / `<form>`（H2）
4. 後端衝突 API 補 `week` 參數（H1 的伺服器端對應）
5. M1 / M3 / L1 實作時順手處理