DEVELOPER DOCS

路線圖(2026-09-17 更新)

原始檔 docs/roadmap.md · 在 GitHub 上檢視

本文件是接手者(人或模型)的邊界:已完成什麼、下一步做什麼、刻意不做什麼。 每一項的「現況」都在 2026-09-17 回頭查過程式碼,不是照抄舊 Backlog。

上一版路線圖(v1.1 範圍,2026-07-13 定案)已全部出貨,原文見 git 歷史。

收錄標準不變:真實學校在一個學期內會實際踩到,或開源後會傷到採用信任。 新增的判斷依據:已有學校實際上線使用(國中,每週都有研習調課),他們的回饋優先於推測性的需求。

---

已出貨

各版細節見 CHANGELOG.md。

---

工程改善(原「v1.3 範圍」;v1.3.0 改做單雙週後順延,內容與順序不變)

排序原則:學校裝得快、用得順的先做,純工程衛生的後做。全部不改資料表結構。

開工時機:由專案負責人決定;組長回報的問題優先處理。

1. api 映像拆掉 ortools —— M

• 現況:ortools 在 pyproject.toml 主依賴,api 映像 674MB;排課求解只在 worker 跑,api 容器用不到。
• 影響誰:第一次安裝與每次升級的學校。校內網路或 NAS 拉映像慢,是「升級很麻煩」的主因之一。
• 做法:移到 [solver] 之類的 extra 由 worker 安裝;確認 api 端沒有任何路徑匯入 ortools (pre-flight 檢查若有用到要拆開)。預期 api 映像約 200MB。
• 驗證:api 容器內 python -c "import ortools" 應失敗、全部 API 與 e2e 照常;worker 自動排課照常。

2. 前端改按需匯入 Naive UI —— M

• 現況:main.ts 以 app.use(naive) 全量註冊,主程式 1.4MB。校內網冷載約 1 秒,可接受但偏大。
• 做法:移除全量註冊,改各頁自行匯入(多數頁面已經是具名匯入);檢查是否有模板直接用未匯入的元件。
• 驗證:建置後主程式大小、冷載時間(perf-page-load.spec.ts);e2e 全跑——漏匯入的元件只會在執行時才壞。

3. 科目匯入支援「主科」欄 —— S

• 現況:表單可勾「主科」(is_major,影響自動排課把主科排在上午),但 Excel 匯入沒有這一欄, 匯入後要一科科手動勾。
• 做法:匯入範本加「主科」欄(是/否),匯入時寫入;舊範本沒有這欄照樣可匯入。

4. 配課 API 直接擋群組節數不一致 —— S

• 現況:跑班群組成員節數不一致時,要等到自動排課前的 pre-flight 才擋(group_shape_mismatch)。
• 做法:建立/修改配課當下就回 409 並說明是哪幾門課不一致,錯誤提早出現在組長正在填的地方。

5. 還原上傳改串流落地 —— S

• 現況:restore-upload 以 await file.read() 整包讀進記憶體;Caddy 200MB 上限與「超大資料庫走 volume 複製」 文件已緩解,但 4GB 主機上仍有風險。
• 做法:分塊寫入暫存檔再驗魔數、交給 worker 還原。

6. CORS 設定文件化與格式驗證 —— S

• 現況:cors_origins 本來就能用環境變數(JSON 格式)覆寫,但沒有文件、格式錯了也不會提示。 同源部署(預設)下無實害。
• 做法:部署文件補一段;設定格式錯誤時啟動即明確報錯。

7. 工程衛生 —— S

• tests/solver/test_purity.py 目前只掃絕對匯入(level == 0),補相對匯入。
• slots_overlap、course_key 補邊界單元測試。

---

等使用學校回饋再決定

• 教師端「我的課表」顯示調課:調課成立後,教師自己的課表不會反映這次變動(看板、通知、調課單都有)。 使用學校目前以紙本調課單通知,沒有提出需求。
• 調代課處理頁的清單很長時:研習多的週,一張假單可能十幾節。目前逐節處理;若回饋操作太多, 再考慮「整張假單一次調課」。

工程改善之後(明確延後,不是忘記)

• 完整清單分頁(UI + offset):調代課紀錄、請假清單目前取最新 1000 筆並明講被截斷;整年資料變慢時再做。
• 還原溯源 restore.log + stale 警告持久徽章:presafe 檔名時戳暫可佐證。
• 求解前 hard-only 探測 + warm start;部分排課獨立短時限:解品質/速度優化,獨立可做。

單雙週的後續(v1.3.0 刻意不做)

• 跑班群組＋單雙週(例如單週社團、雙週班會):兩種「綁在一起排」的機制疊加,複雜度與風險最高; 目前沒有學校提出,等有需求再評估。
• Excel 匯入配課支援單雙週:需要新的範本欄位(單週/雙週、配對),且要與舊範本相容; 單雙週課每校通常只有幾組,先在畫面上建。等有學校提出需求再排。

v2(需要外部條件)

• LINE 通知 adapter:走 LINE OA Messaging API,各校自申請 channel token + 綁定碼流程。 等有試用學校提出需求再做——沒有真實 OA 可測之前,寫了也驗不了。
• 軟約束權重 UI:GET/PUT /api/solver/config 已在,滑桿是給進階使用者的;等有學校真的想調權重再開工。

刻意不做(除非出現真實個案)

• 「一門課逐節換教室」:現行一門課整學期一間教室,符合台灣中學實務;改成逐節換教室是為了不存在的需求付模型複雜度。
• teacher_time_rule 牆鐘化(加節次表維度):v1 已定案「以該配課班級的節次表解讀」,單節次表學校(絕大多數)無此問題。
• 沒有請假的教師互調:使用學校的調課幾乎都由研習引起,研習登記為公假/進修後走既有調課流程即可(2026-09-17 確認)。
• 自動升級:新版本提醒只提醒;升級必須由學校先備份、自己決定。

---

工作流程(每項照做)

實作 → 全品質門檻(ruff/mypy/pytest;eslint/vue-tsc/build/vitest)→ Docker 重建 → E2E(CI 也會擋)→ 真 PostgreSQL 實測、畫面截圖目視 → 開 PR(CI 全綠)→ 維護者合併 → 依 CONTRIBUTING.md 發布。