From 27a67a9376d7e5e1434e3205dd5c2328556fd866 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E4=BD=B3=E6=81=A9?= Date: Thu, 19 Nov 2026 13:37:19 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AF=92=E6=9A=91=E5=81=87=E8=BC=94?= =?UTF-8?q?=E5=B0=8E=E5=AD=B8=E6=9C=9F(=E6=97=A5=E6=9C=9F=E4=B8=8D?= =?UTF-8?q?=E8=83=BD=E5=92=8C=E5=85=B6=E4=BB=96=E5=AD=B8=E6=9C=9F=E9=87=8D?= =?UTF-8?q?=E7=96=8A=E3=80=81=E4=B8=8D=E7=AE=97=E8=B6=85=E9=90=98=E9=BB=9E?= =?UTF-8?q?);=E5=90=84=E9=A0=81=E9=A0=90=E8=A8=AD=E9=81=B8=E4=BB=8A?= =?UTF-8?q?=E5=A4=A9=E6=89=80=E5=9C=A8=E7=9A=84=E5=AD=B8=E6=9C=9F;?= =?UTF-8?q?=E7=99=BC=E5=B8=83=20v1.4.22?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 學期別多「寒假輔導」(term 3)、「暑期輔導」(term 4),沿用 term 欄,沒有資料表變更 - 輔導學期起訖日期必填,且不能和其他學期重疊(建立、複製、修改日期都檢查;一般學期之間照舊不擋) - 學期清單改照日期由新到舊;各頁預設選今天落在起訖日期內的學期 - 輔導學期不比基本鐘點、不受超鐘點上限、排課前檢查不提示超出應授鐘點;配課畫面改列教師輔導節數 - 複製成輔導學期:預設同一學年度、年級不進位、日期清空 - 調課單抬頭「115學年暑期輔導」 - 測試:後端 7 項、前端 3 項、e2e tutoring-semester.spec.ts Co-Authored-By: Claude Opus 5.5 --- .env.example | 2 +- CHANGELOG.md | 29 +++- README.md | 6 +- backend/app/api/semesters.py | 46 +++++-- backend/app/api/timetables.py | 10 +- backend/app/models/semester.py | 37 ++++- backend/app/schemas/assignment.py | 1 + backend/app/schemas/semester.py | 5 +- backend/app/schemas/timetable.py | 3 + backend/app/services/assignments.py | 8 +- backend/app/services/slip_layout.py | 4 +- backend/app/services/solver_data.py | 1 + backend/app/solver/preflight.py | 2 +- backend/app/solver/problem.py | 1 + backend/tests/test_tutoring_semester_v1422.py | 128 ++++++++++++++++++ docs/deploy/upgrade.html | 5 +- docs/deploy/upgrade.md | 5 + docs/features.html | 12 +- docs/index.html | 20 ++- docs/roadmap.html | 5 + docs/roadmap.md | 1 + frontend/e2e/tutoring-semester.spec.ts | 95 +++++++++++++ frontend/src/api/assignments.ts | 1 + frontend/src/api/semesters.test.ts | 27 ++++ frontend/src/api/semesters.ts | 36 +++++ frontend/src/api/timetables.ts | 7 +- frontend/src/components/NotificationBell.vue | 4 +- frontend/src/views/Dashboard.vue | 8 +- frontend/src/views/TimetableQuery.vue | 3 +- frontend/src/views/basedata/BaseData.vue | 4 +- frontend/src/views/leaves/Leaves.vue | 7 +- frontend/src/views/scheduling/Assignments.vue | 22 ++- .../src/views/scheduling/AutoSchedule.vue | 4 +- frontend/src/views/scheduling/Versions.vue | 4 +- frontend/src/views/scheduling/Workbench.vue | 4 +- frontend/src/views/settings/Semesters.vue | 39 ++++-- .../src/views/substitution/DailyBoard.vue | 7 +- .../views/substitution/NotificationBoard.vue | 7 +- .../views/substitution/SubstitutionLog.vue | 7 +- .../views/substitution/SubstitutionStats.vue | 7 +- .../src/views/substitution/Substitutions.vue | 7 +- .../src/views/substitution/Suspensions.vue | 7 +- 42 files changed, 555 insertions(+), 83 deletions(-) create mode 100644 backend/tests/test_tutoring_semester_v1422.py create mode 100644 frontend/e2e/tutoring-semester.spec.ts create mode 100644 frontend/src/api/semesters.test.ts diff --git a/.env.example b/.env.example index 68a74ed7..f7702c1c 100644 --- a/.env.example +++ b/.env.example @@ -32,7 +32,7 @@ HTTP_PORT=80 # ── 預建映像版本(僅「拉取映像」部署方式需要)────────── # 用 docker compose pull 拉官方映像時,決定要拉哪一版。 # 預設 latest(最新);正式部署建議釘選版本號以利可控升級,例如: -# IMAGE_TAG=v1.4.21 +# IMAGE_TAG=v1.4.22 # 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。 IMAGE_TAG=latest diff --git a/CHANGELOG.md b/CHANGELOG.md index be1b7cf3..7c87d8a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,37 @@ 破壞性變更(需人工介入才能升級)以 ⚠️ 標註。 -> **新使用者請直接安裝 v1.4.21**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.20 是先前版本;以下條目保留作為變更紀錄。 +> **新使用者請直接安裝 v1.4.22**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.21 是先前版本;以下條目保留作為變更紀錄。 ## [Unreleased] +## [1.4.22] — 2026-11-19 + +**寒暑假輔導**(組長許願):學期多了「寒假輔導」「暑期輔導」兩種,另外排一份輔導課表, +請假、代課、調課照常使用。 + +沒有資料表變更,照一般方式升級即可(`.env` 改 `IMAGE_TAG=v1.4.22` → `docker compose pull && docker compose up -d`)。 + +官方映像(amd64 + arm64 雙架構)已發布於 GHCR: +`ghcr.io/begin0808/course_scheduling_system-{api,worker,web}:v1.4.22` + +### 新增 +- **寒暑假輔導學期**:「學期與節次表」建立學期或「複製到新學期」時,學期別可選「寒假輔導」「暑期輔導」, + 名稱寫成「115 學年度暑期輔導」。 + - 起訖日期必填,而且**不能和其他學期重疊**(請假、代課是依日期判斷屬於哪個學期);重疊時寫出撞到哪一個學期。 + - 各校差異都用現有設定:哪幾個年級(複製時帶班級、刪掉沒有輔導的班)、幾週(起訖日期)、 + 每天幾節(輔導學期自己的節次表)。併班上課就另外新增班級,或用跑班群組。 + - 複製成輔導學期時預設同一學年度、班級年級不進位,日期清空讓組長照校曆填。 + - **不管基本鐘點與超鐘點**:配課畫面改列「教師輔導節數」(每週幾節),不受「超鐘點上限」限制, + 排課前檢查也不提示「超出應授鐘點」。 + - 排課、發布、課表查詢與匯出、請假、代課、調課、併班、停課日、調代課單都和一般學期一樣; + 調課單抬頭寫「115學年暑期輔導」。 + +### 改善 +- **各頁預設選「今天所在的學期」**:學期清單改照日期由新到舊排列,請假、調代課、配課、儀表板等頁面 + 預設選今天落在起訖日期內的學期(沒有才選最新的)。先建好下學期或暑期輔導, + 每天處理的請假與代課也不會跳到還沒開始的學期。 + ## [1.4.21] — 2026-11-18 **三角調課可以指定老師,湊不成時寫出原因**(組長回報:三角調課的清單裡找不到某位老師)。 diff --git a/README.md b/README.md index 2eb63f95..65a6ca06 100644 --- a/README.md +++ b/README.md @@ -132,11 +132,11 @@ docker compose up -d # 首次會建置映像,需數分鐘 ## 專案狀態 -**v1.4.21 已發行(2026-11-18)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 808 項單元/整合測試、63 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。 +**v1.4.22 已發行(2026-11-19)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 815 項單元/整合測試、64 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。 -v1.4.21 三角調課可以**指定老師**,湊不成時寫出卡在哪一節、為什麼;v1.4.20 新增**三角調課**(同一班三位老師輪流換課,列出可行的三人組合;三位老師與班級各有調課單,撤回一起撤);v1.4.19 新增**停課日**(全校、年級或班級,整天或第幾節到第幾節;請假不必代課、不能拿來調課補課,巡堂表與週課表標停課);v1.4.18 修正調課後**重新發布課表**時補課那一節消失的問題;v1.4.17 調代課紀錄與某一週的班級課表,調課**寫出對調的另一節在哪一天**;v1.4.16 跑班 5 組以內在班級課表**列出每位老師**,先調課再請假時已調走的節次**不再重複列出**;v1.4.15 課表查詢可以**看某一週實際的課表**(含調代課,異動標色),並新增身心調適假等常用假別;v1.4.14 新增**全校教師週總表**(老師為欄、標出這週的調代課,可列印或匯出 Excel);v1.4.13 修正跑班群組在班級課表只顯示一位老師(同一格改列出每一組);v1.4.12 調課可以**從較早的週開始找**(老師提早請假、想先補課),換不了的節次會**寫出原因**,代導半天改以「次」計;v1.4.11「代課鐘點統計」可以**自訂統計區間**(每月 15 日結算的學校可選 10/16~11/15);v1.4.10 已經上過的調課可以**事後補登**(「新增調課(未請假)」勾已經上過的節次;不通知老師),調代課紀錄也能篩出「調課(未請假)」,查老師多常換課;v1.4.9 同一天好幾節要一起換(例如學校活動讓兩班的第七、八節同時對調)也**調得成**了;v1.4.8 新學期第一次進「自動排課」會**自動建立草稿**,配完課就能直接排;v1.4.7 **資安修正**:登入失敗鎖定不會再被「同時送出」繞過(建議升級);v1.4.6 全校總表與批次 zip 都可以**匯出 PDF**;v1.4.5 老師**沒請假也能調課**(調代課處理的「新增調課」);v1.4.4 登記後可以**修改假別與計費方式**(已經上過的代課也可以改計費方式),請假的假別改成一定要選;v1.4.3 修正安排代導時操作紀錄沒寫出老師名字;v1.4.2 可以**補登**事後才登記的請假(已經過去的節次補登代課,不通知老師、列入鐘點統計);v1.4.1 起改採 **AGPL-3.0 授權**(見下方「授權」;功能與資料都沒有變動);v1.4.0 新增**代導**(導師請假當天由誰代他帶班,當天沒課也算、半天也算;可印代導通知單,月結分開記全天與半天天數;⚠️ 資料表結構變更,升級前會自動備份);v1.3.5 修正**併班**選不到老師(改列出這一節正在上課的老師),調課單加上記號說明;v1.3.4 讓跑班群組、導師、任教科目等下拉選單都能**打字搜尋**;v1.3.3 的儀表板新增**即時概況**(現在這一節各班在上什麼課、誰在上,已套用當天的調代課);v1.3.2 新增**重設管理員密碼**的指令(忘了密碼或第一次就登不進去時,不必刪資料或還原備份);v1.3.1 新增**帳號管理**(系統管理員可設定教學組長、教務主任的帳號);v1.3.0 支援**單雙週課程**(同一節單週、雙週輪流上不同的課,排課、請假代課、調課、巡堂表、鐘點都分單雙週;⚠️ 首次改動資料表結構,升級前請先備份);v1.2.19 支援**日薪代課**(國小常見:月結統計把鐘點與日薪分開列)並可**整批指派代課**(整張假單或整天一次派給同一位老師);v1.2.18 可**檢查課表**(發布前列出衝堂、教師不可排時段等衝突;事後修改不可排時段時當場提示已排的課);v1.2.17 修正登入按一次送出兩筆請求(輸錯密碼約第 3 次就被鎖定);v1.2.15、v1.2.16 修正跑班群組的兩個問題(同一位老師在群組裡重複配課時自動排課會排出撞課的課表;同一格有多筆同科目配課時,手動排課把每日節數重複計算);v1.2.12~v1.2.14 可列印**巡堂表**並匯出 Excel(依當天的調代課結果產生,社團另出分組巡堂單);v1.2.10、v1.2.11 讓**國中小、完全中學**跨部上課的老師,課表與通知單都標出實際上課時間,兩部節數不同(國中七節、高中八節)也不會漏課;v1.2.9 可一次匯出**全校教師課表**(總表與批次打包);v1.2.8 可用 Excel **批次更新既有教師**(新學年職務異動),並能**停用/啟用教師登入帳號**(離職教師保留歷史紀錄又進不來);v1.2.7 補上**學期起訖日期**的填寫與修改(先前畫面上無處可填,導致請假被擋);v1.2.6 修掉第一批外部使用者回報的三個問題(教師帳號首次登入卡死、無法事後補開教師帳號、未排課務清單過長時拖不動),並可在畫面上自行修改與重設密碼;v1.2.5 可列印**教師代課通知單與班級代課通知單**(照學校紙本格式,代課時可選計費方式);v1.2.4 的調代課處理會寫出處置方式(代課或調課、哪天補課);v1.2.3 起系統會顯示目前版本,並在有新版時提醒系統管理員(只提醒、不自動升級);v1.2.2 可列印**教師調課通知單與班級調課通知單**(照學校紙本格式);v1.2.1 補上**調課**的操作畫面——請假(含研習)的節次可直接列出雙方都有空的對調節次,支援跨週(最多四週)與連堂,補課日也會出現在今日看板。v1.2.0 起另有**一鍵示範資料**,裝好後兩分鐘內就能看到一張排好的全校課表。 +v1.4.22 新增**寒暑假輔導**學期(另排輔導課表,請假代課照常,不算超鐘點);v1.4.21 三角調課可以**指定老師**,湊不成時寫出卡在哪一節、為什麼;v1.4.20 新增**三角調課**(同一班三位老師輪流換課,列出可行的三人組合;三位老師與班級各有調課單,撤回一起撤);v1.4.19 新增**停課日**(全校、年級或班級,整天或第幾節到第幾節;請假不必代課、不能拿來調課補課,巡堂表與週課表標停課);v1.4.18 修正調課後**重新發布課表**時補課那一節消失的問題;v1.4.17 調代課紀錄與某一週的班級課表,調課**寫出對調的另一節在哪一天**;v1.4.16 跑班 5 組以內在班級課表**列出每位老師**,先調課再請假時已調走的節次**不再重複列出**;v1.4.15 課表查詢可以**看某一週實際的課表**(含調代課,異動標色),並新增身心調適假等常用假別;v1.4.14 新增**全校教師週總表**(老師為欄、標出這週的調代課,可列印或匯出 Excel);v1.4.13 修正跑班群組在班級課表只顯示一位老師(同一格改列出每一組);v1.4.12 調課可以**從較早的週開始找**(老師提早請假、想先補課),換不了的節次會**寫出原因**,代導半天改以「次」計;v1.4.11「代課鐘點統計」可以**自訂統計區間**(每月 15 日結算的學校可選 10/16~11/15);v1.4.10 已經上過的調課可以**事後補登**(「新增調課(未請假)」勾已經上過的節次;不通知老師),調代課紀錄也能篩出「調課(未請假)」,查老師多常換課;v1.4.9 同一天好幾節要一起換(例如學校活動讓兩班的第七、八節同時對調)也**調得成**了;v1.4.8 新學期第一次進「自動排課」會**自動建立草稿**,配完課就能直接排;v1.4.7 **資安修正**:登入失敗鎖定不會再被「同時送出」繞過(建議升級);v1.4.6 全校總表與批次 zip 都可以**匯出 PDF**;v1.4.5 老師**沒請假也能調課**(調代課處理的「新增調課」);v1.4.4 登記後可以**修改假別與計費方式**(已經上過的代課也可以改計費方式),請假的假別改成一定要選;v1.4.3 修正安排代導時操作紀錄沒寫出老師名字;v1.4.2 可以**補登**事後才登記的請假(已經過去的節次補登代課,不通知老師、列入鐘點統計);v1.4.1 起改採 **AGPL-3.0 授權**(見下方「授權」;功能與資料都沒有變動);v1.4.0 新增**代導**(導師請假當天由誰代他帶班,當天沒課也算、半天也算;可印代導通知單,月結分開記全天與半天天數;⚠️ 資料表結構變更,升級前會自動備份);v1.3.5 修正**併班**選不到老師(改列出這一節正在上課的老師),調課單加上記號說明;v1.3.4 讓跑班群組、導師、任教科目等下拉選單都能**打字搜尋**;v1.3.3 的儀表板新增**即時概況**(現在這一節各班在上什麼課、誰在上,已套用當天的調代課);v1.3.2 新增**重設管理員密碼**的指令(忘了密碼或第一次就登不進去時,不必刪資料或還原備份);v1.3.1 新增**帳號管理**(系統管理員可設定教學組長、教務主任的帳號);v1.3.0 支援**單雙週課程**(同一節單週、雙週輪流上不同的課,排課、請假代課、調課、巡堂表、鐘點都分單雙週;⚠️ 首次改動資料表結構,升級前請先備份);v1.2.19 支援**日薪代課**(國小常見:月結統計把鐘點與日薪分開列)並可**整批指派代課**(整張假單或整天一次派給同一位老師);v1.2.18 可**檢查課表**(發布前列出衝堂、教師不可排時段等衝突;事後修改不可排時段時當場提示已排的課);v1.2.17 修正登入按一次送出兩筆請求(輸錯密碼約第 3 次就被鎖定);v1.2.15、v1.2.16 修正跑班群組的兩個問題(同一位老師在群組裡重複配課時自動排課會排出撞課的課表;同一格有多筆同科目配課時,手動排課把每日節數重複計算);v1.2.12~v1.2.14 可列印**巡堂表**並匯出 Excel(依當天的調代課結果產生,社團另出分組巡堂單);v1.2.10、v1.2.11 讓**國中小、完全中學**跨部上課的老師,課表與通知單都標出實際上課時間,兩部節數不同(國中七節、高中八節)也不會漏課;v1.2.9 可一次匯出**全校教師課表**(總表與批次打包);v1.2.8 可用 Excel **批次更新既有教師**(新學年職務異動),並能**停用/啟用教師登入帳號**(離職教師保留歷史紀錄又進不來);v1.2.7 補上**學期起訖日期**的填寫與修改(先前畫面上無處可填,導致請假被擋);v1.2.6 修掉第一批外部使用者回報的三個問題(教師帳號首次登入卡死、無法事後補開教師帳號、未排課務清單過長時拖不動),並可在畫面上自行修改與重設密碼;v1.2.5 可列印**教師代課通知單與班級代課通知單**(照學校紙本格式,代課時可選計費方式);v1.2.4 的調代課處理會寫出處置方式(代課或調課、哪天補課);v1.2.3 起系統會顯示目前版本,並在有新版時提醒系統管理員(只提醒、不自動升級);v1.2.2 可列印**教師調課通知單與班級調課通知單**(照學校紙本格式);v1.2.1 補上**調課**的操作畫面——請假(含研習)的節次可直接列出雙方都有空的對調節次,支援跨週(最多四週)與連堂,補課日也會出現在今日看板。v1.2.0 起另有**一鍵示範資料**,裝好後兩分鐘內就能看到一張排好的全校課表。 -**請直接從最新版開始安裝**(見上方快速開始);`v1.4.21` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。 +**請直接從最新版開始安裝**(見上方快速開始);`v1.4.22` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。 系統仍在實際校園環境試用中,若你是第一批使用者,歡迎加入 [LINE 社群](https://line.me/ti/g2/hP0Lg7mqvE5rvWg0sE9MHI-QsLkd94Cfp3wKcg) 或透過 [Issues](https://github.com/begin0808/Course_Scheduling_System/issues) 回報任何問題。 diff --git a/backend/app/api/semesters.py b/backend/app/api/semesters.py index 67ad31e6..ec22b2b6 100644 --- a/backend/app/api/semesters.py +++ b/backend/app/api/semesters.py @@ -3,6 +3,8 @@ 權限:讀取 = 教學組長/教務主任;寫入 = 教學組長(admin 一律通過)。 """ +from datetime import date + from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy import func, select from sqlalchemy.orm import Session @@ -11,7 +13,7 @@ from app.core.db import get_db from app.models.basedata import ClassUnit, Room, Subject, Teacher from app.models.period import Period, PeriodTable -from app.models.semester import Semester +from app.models.semester import TUTORING_TERMS, Semester, sorted_semesters from app.models.user import Role from app.schemas.semester import ( AvailableSlot, @@ -52,6 +54,32 @@ def _get_period_table(db: Session, table_id: int) -> PeriodTable: return table +def _check_dates( + db: Session, term: int, start: date | None, end: date | None, exclude_id: int | None = None +) -> None: + """寒暑假輔導(v1.4.22)要填起訖日期,且不能和其他學期重疊。 + + 請假、代課是依日期落在哪個學期來判斷;輔導學期通常在學期進行中就先建好, + 日期一重疊就分不清楚。只檢查「有一邊是輔導」的組合,一般學期之間照舊不擋。 + """ + tutoring = term in TUTORING_TERMS + if tutoring and (start is None or end is None): + raise HTTPException(status.HTTP_400_BAD_REQUEST, "寒暑假輔導要填開始日與結束日") + if start is None or end is None: + return + for other in db.scalars(select(Semester).where(Semester.id != (exclude_id or 0))): + if other.start_date is None or other.end_date is None: + continue + if not tutoring and not other.is_tutoring: + continue + if start <= other.end_date and other.start_date <= end: + raise HTTPException( + status.HTTP_409_CONFLICT, + f"日期和「{other.label}」({other.start_date:%Y/%m/%d}~{other.end_date:%Y/%m/%d})" + "重疊;寒暑假輔導的日期不能和其他學期重疊", + ) + + def _unset_other_defaults(db: Session, semester_id: int, keep_id: int | None) -> None: others = db.scalars( select(PeriodTable).where( @@ -80,9 +108,7 @@ def list_templates(_: object = Depends(viewer)) -> list[TemplateOut]: # ── 學期 ────────────────────────────── @router.get("/semesters", response_model=list[SemesterListItem]) def list_semesters(db: Session = Depends(get_db), _: object = Depends(viewer)): - return db.scalars( - select(Semester).order_by(Semester.academic_year.desc(), Semester.term.desc()) - ).all() + return sorted_semesters(db.scalars(select(Semester)).all()) @router.post("/semesters", response_model=SemesterOut, status_code=status.HTTP_201_CREATED) @@ -96,6 +122,7 @@ def create_semester( ) if exists: raise HTTPException(status.HTTP_409_CONFLICT, "該學年度學期已存在") + _check_dates(db, body.term, body.start_date, body.end_date) if body.template_key: if tpl.get_template(body.template_key) is None: @@ -138,6 +165,7 @@ def copy_to_new_semester( ) if exists: raise HTTPException(status.HTTP_409_CONFLICT, "目標學年度學期已存在") + _check_dates(db, body.term, body.start_date, body.end_date) opts = CopyOptions( period_tables=body.period_tables, subjects=body.subjects, @@ -191,10 +219,12 @@ def update_semester( data = body.model_dump(exclude_unset=True) if "status" in data and data["status"] is not None: semester.status = data["status"].value - if "start_date" in data: - semester.start_date = data["start_date"] - if "end_date" in data: - semester.end_date = data["end_date"] + start = data["start_date"] if "start_date" in data else semester.start_date + end = data["end_date"] if "end_date" in data else semester.end_date + if "start_date" in data or "end_date" in data: + _check_dates(db, semester.term, start, end, exclude_id=semester.id) + semester.start_date = start + semester.end_date = end db.commit() db.refresh(semester) return semester diff --git a/backend/app/api/timetables.py b/backend/app/api/timetables.py index 9521a269..a89048c8 100644 --- a/backend/app/api/timetables.py +++ b/backend/app/api/timetables.py @@ -16,7 +16,7 @@ from app.models.assignment import CourseAssignment from app.models.basedata import ClassUnit, Room, Teacher from app.models.period import PeriodTable -from app.models.semester import Semester +from app.models.semester import Semester, sorted_semesters from app.models.timetable import ScheduleEntry, Timetable, TimetableStatus from app.models.user import Role, User from app.schemas.timetable import ( @@ -306,9 +306,11 @@ def published_semesters(db: Session = Depends(get_db), _: User = Depends(get_act select(Semester) .join(Timetable, Timetable.semester_id == Semester.id) .where(Timetable.status == TimetableStatus.published.value) - .order_by(Semester.academic_year.desc(), Semester.term.desc()) - ).all() - return [PublicSemester(id=s.id, label=s.label) for s in rows] + ).unique().all() + return [ + PublicSemester(id=s.id, label=s.label, start_date=s.start_date, end_date=s.end_date) + for s in sorted_semesters(rows) + ] @router.get("/published/my-teacher", response_model=NamedBrief | None) diff --git a/backend/app/models/semester.py b/backend/app/models/semester.py index 3385c2ff..da3b2c49 100644 --- a/backend/app/models/semester.py +++ b/backend/app/models/semester.py @@ -4,6 +4,7 @@ """ import enum +from collections.abc import Sequence from datetime import date, datetime from typing import TYPE_CHECKING @@ -22,6 +23,23 @@ class SemesterStatus(enum.StrEnum): archived = "archived" # 已封存(歷史保存) +# 學期類型(term 欄)。3、4 是 v1.4.22 的寒暑假輔導:日期必填、不能和其他學期重疊、 +# 不管基本鐘點與超鐘點(上幾節給幾節)。沿用 term 欄,(學年度, term) 一樣不能重複。 +TERM_WINTER = 3 # 寒假輔導 +TERM_SUMMER = 4 # 暑期輔導 +TUTORING_TERMS = frozenset({TERM_WINTER, TERM_SUMMER}) +TERM_NAMES = {1: "第 1 學期", 2: "第 2 學期", TERM_WINTER: "寒假輔導", TERM_SUMMER: "暑期輔導"} + + +def approx_start(academic_year: int, term: int) -> date: + """沒填起訖日期時,用學年度推估開始日,只拿來排序(民國學年度從 8 月開始)。""" + ad = academic_year + 1911 + return { + 1: date(ad, 8, 1), 2: date(ad + 1, 2, 1), + TERM_WINTER: date(ad + 1, 1, 20), TERM_SUMMER: date(ad + 1, 7, 1), + }.get(term, date(ad, 8, 1)) + + class Semester(Base): __tablename__ = "semesters" __table_args__ = ( @@ -30,7 +48,7 @@ class Semester(Base): id: Mapped[int] = mapped_column(primary_key=True) academic_year: Mapped[int] = mapped_column(Integer) # 學年度,如 115 - term: Mapped[int] = mapped_column(Integer) # 學期,1 或 2 + term: Mapped[int] = mapped_column(Integer) # 1、2 學期;3 寒假輔導、4 暑期輔導 # 領域日期,無時區(見 architecture.md D6) start_date: Mapped[date | None] = mapped_column(Date, nullable=True) end_date: Mapped[date | None] = mapped_column(Date, nullable=True) @@ -45,6 +63,23 @@ class Semester(Base): back_populates="semester", cascade="all, delete-orphan", lazy="selectin" ) + @property + def is_tutoring(self) -> bool: + """寒暑假輔導(v1.4.22)。""" + return self.term in TUTORING_TERMS + @property def label(self) -> str: + if self.is_tutoring: + return f"{self.academic_year} 學年度{TERM_NAMES[self.term]}" return f"{self.academic_year} 學年度第 {self.term} 學期" + + @property + def sort_date(self) -> date: + """學期清單由新到舊的排序依據:有開始日用開始日,否則用學年度推估。""" + return self.start_date or approx_start(self.academic_year, self.term) + + +def sorted_semesters(rows: Sequence[Semester]) -> list[Semester]: + """由新到舊:有開始日用開始日,否則用學年度推估(寒假輔導排在同學年上下學期之間)。""" + return sorted(rows, key=lambda x: (x.sort_date, x.id), reverse=True) diff --git a/backend/app/schemas/assignment.py b/backend/app/schemas/assignment.py index f9bfca06..0c6af356 100644 --- a/backend/app/schemas/assignment.py +++ b/backend/app/schemas/assignment.py @@ -119,6 +119,7 @@ class TeacherLoad(BaseModel): delta: float # assigned - target(正=超鐘點,負=不足) max_overtime: int # 超鐘點上限(節);0 = 學校未設限 over_limit: bool # delta 已超過上限 + tutoring: bool = False # 寒暑假輔導學期:不比應授、不算超鐘點(v1.4.22) class ClassLoad(BaseModel): diff --git a/backend/app/schemas/semester.py b/backend/app/schemas/semester.py index 87bfe5c3..3ea5aba8 100644 --- a/backend/app/schemas/semester.py +++ b/backend/app/schemas/semester.py @@ -66,7 +66,7 @@ class PeriodTableUpdate(BaseModel): # ── 學期 ────────────────────────────── class SemesterCreate(BaseModel): academic_year: int = Field(ge=100, le=200) # 民國學年度 - term: int = Field(ge=1, le=2) + term: int = Field(ge=1, le=4) # 1、2 學期;3 寒假輔導、4 暑期輔導(v1.4.22) start_date: date | None = None end_date: date | None = None # 若指定,依此學制範本帶入預設節次表 @@ -81,7 +81,7 @@ class SemesterUpdate(BaseModel): class SemesterCopyRequest(BaseModel): academic_year: int = Field(ge=100, le=200) - term: int = Field(ge=1, le=2) + term: int = Field(ge=1, le=4) # 1、2 學期;3 寒假輔導、4 暑期輔導(v1.4.22) # 新學期的起訖日:不能沿用來源學期(那是上學期的日期)。少了它,請假展開、今日看板、 # 代課的「已上過」判定全部失準,而且畫面上看不出哪裡不對(M6-4)。 start_date: date | None = None @@ -110,6 +110,7 @@ class SemesterListItem(BaseModel): status: SemesterStatus start_date: date | None = None end_date: date | None = None + is_tutoring: bool = False # 寒暑假輔導:不管基本鐘點與超鐘點 class SemesterOut(SemesterListItem): diff --git a/backend/app/schemas/timetable.py b/backend/app/schemas/timetable.py index 872d135a..84d70d3b 100644 --- a/backend/app/schemas/timetable.py +++ b/backend/app/schemas/timetable.py @@ -139,6 +139,9 @@ class UnavailableHitOut(BaseModel): class PublicSemester(BaseModel): id: int label: str + # v1.4.22:前端預設選「今天落在起訖日期內」的學期 + start_date: _WeekDate | None = None + end_date: _WeekDate | None = None class NamedBrief(BaseModel): diff --git a/backend/app/services/assignments.py b/backend/app/services/assignments.py index cd590913..fd99ecb6 100644 --- a/backend/app/services/assignments.py +++ b/backend/app/services/assignments.py @@ -13,6 +13,7 @@ SchedulingUnitType, ) from app.models.basedata import ClassUnit, Teacher +from app.models.semester import Semester from app.services import period_tables as pt_service from app.services import settings as settings_service @@ -165,6 +166,9 @@ def teacher_loads(db: Session, semester_id: int) -> list[dict]: select(Teacher).where(Teacher.semester_id == semester_id).order_by(Teacher.name) ) limit = settings_service.max_overtime(db) + # 寒暑假輔導(v1.4.22)不管基本鐘點與超鐘點:上幾節給幾節 + semester = db.get(Semester, semester_id) + tutoring = semester is not None and semester.is_tutoring out: list[dict] = [] for t in teachers: target = max(t.base_periods - t.admin_reduction, 0) @@ -174,13 +178,13 @@ def teacher_loads(db: Session, semester_id: int) -> list[dict]: "teacher_id": t.id, "name": t.name, "base_periods": t.base_periods, "admin_reduction": t.admin_reduction, "target": target, "assigned": assigned, "delta": delta, - "max_overtime": limit, + "max_overtime": limit, "tutoring": tutoring, # 兩種情況不算違規: # limit=0 → 學校未設上限 # base=0 → 這位教師沒填基本鐘點。「應授 0 節」不是真的不用上課, # 而是資料還沒建;此時談超鐘點沒有意義,硬擋會讓沒有 # 維護基鐘的學校連一般配課都做不了。 - "over_limit": limit > 0 and t.base_periods > 0 and delta > limit, + "over_limit": not tutoring and limit > 0 and t.base_periods > 0 and delta > limit, }) return out diff --git a/backend/app/services/slip_layout.py b/backend/app/services/slip_layout.py index 1786e843..323dd415 100644 --- a/backend/app/services/slip_layout.py +++ b/backend/app/services/slip_layout.py @@ -16,7 +16,7 @@ from app.models.assignment import CourseAssignment from app.models.period import Period, PeriodType -from app.models.semester import Semester +from app.models.semester import TERM_NAMES, Semester from app.services import period_tables as pt_service from app.services import settings as app_settings @@ -166,6 +166,8 @@ def school_title(db: Session, semester_id: int | None = None) -> str: sem = db.get(Semester, semester_id) if semester_id else None if sem is None: return school + if sem.is_tutoring: # v1.4.22:「115學年暑期輔導」 + return f"{school}{sem.academic_year}學年{TERM_NAMES[sem.term]}" return f"{school}{sem.academic_year}學年第{_TERM_CN.get(sem.term, str(sem.term))}學期" diff --git a/backend/app/services/solver_data.py b/backend/app/services/solver_data.py index 6b09c29a..de48881e 100644 --- a/backend/app/services/solver_data.py +++ b/backend/app/services/solver_data.py @@ -264,6 +264,7 @@ def load_problem( return Problem( semester_id=semester_id, semester_label=semester.label, + is_tutoring=semester.is_tutoring, tables=tables, classes=classes, teachers=teachers, diff --git a/backend/app/solver/preflight.py b/backend/app/solver/preflight.py index 8d00cc7b..68e307f0 100644 --- a/backend/app/solver/preflight.py +++ b/backend/app/solver/preflight.py @@ -231,7 +231,7 @@ def _check_teachers(problem: Problem, issues: list[Issue]) -> None: "teacher", teacher.id, {"assigned": assigned, "available": available, "unavailable": blocked}, )) - if assigned > teacher.target_periods: + if assigned > teacher.target_periods and not problem.is_tutoring: issues.append(Issue( "warning", "teacher_over_hours", f"教師{teacher.name} 配課 {fmt_periods(assigned)} 節,超出應授鐘點 " diff --git a/backend/app/solver/problem.py b/backend/app/solver/problem.py index 0ed6dc2f..c6261644 100644 --- a/backend/app/solver/problem.py +++ b/backend/app/solver/problem.py @@ -189,6 +189,7 @@ class Problem: units: Mapping[int, UnitSpec] assignments: tuple[AssignmentSpec, ...] fixed_entries: tuple[FixedEntry, ...] = () + is_tutoring: bool = False # 寒暑假輔導(v1.4.22):不檢查超出應授鐘點 # ── 導覽 ──────────────────────── def classes_of(self, a: AssignmentSpec) -> tuple[ClassSpec, ...]: diff --git a/backend/tests/test_tutoring_semester_v1422.py b/backend/tests/test_tutoring_semester_v1422.py new file mode 100644 index 00000000..5ec44994 --- /dev/null +++ b/backend/tests/test_tutoring_semester_v1422.py @@ -0,0 +1,128 @@ +"""v1.4.22 寒暑假輔導:學期多兩種類型(term 3 寒假輔導、4 暑期輔導)。 + +規則(使用者 2026-11-19 定案):起訖日期必填、不能和其他學期重疊;清單照日期由新到舊; +不管基本鐘點與超鐘點(上幾節給幾節);其餘排課、請假、代課全部沿用一般學期。 +""" + +from app.models.basedata import ClassTrack +from app.services import settings as settings_service +from app.services.assignments import assert_within_overtime_limit, teacher_loads +from app.services.slip_layout import school_title +from app.services.solver_data import load_problem +from app.solver import preflight +from tests.fixtures import Builder +from tests.test_semesters import login + +FIRST = {"academic_year": 115, "term": 1, "start_date": "2026-08-31", "end_date": "2027-01-20"} +SECOND = {"academic_year": 115, "term": 2, "start_date": "2027-02-11", "end_date": "2027-06-30"} +WINTER = {"academic_year": 115, "term": 3, "start_date": "2027-01-25", "end_date": "2027-02-05"} +SUMMER = {"academic_year": 115, "term": 4, "start_date": "2027-07-05", "end_date": "2027-07-30"} + + +def _post(client, body): + return client.post("/api/semesters", json=body) + + +def test_labels_and_list_sorted_by_date(env): + client, db = env + login(client, db) + for body in (FIRST, SUMMER, WINTER, SECOND): + assert _post(client, body).status_code == 201, body + # 沒填日期的舊學期,照學年度推估排在後面 + assert _post(client, {"academic_year": 114, "term": 2}).status_code == 201 + assert _post(client, {"academic_year": 114, "term": 1}).status_code == 201 + + items = client.get("/api/semesters").json() + assert [s["label"] for s in items] == [ + "115 學年度暑期輔導", "115 學年度第 2 學期", "115 學年度寒假輔導", + "115 學年度第 1 學期", "114 學年度第 2 學期", "114 學年度第 1 學期", + ] + assert [s["is_tutoring"] for s in items[:4]] == [True, False, True, False] + + +def test_tutoring_needs_dates(env): + client, db = env + login(client, db) + r = _post(client, {"academic_year": 115, "term": 4}) + assert r.status_code == 400 + assert "寒暑假輔導要填開始日與結束日" in r.json()["detail"] + sid = _post(client, SUMMER).json()["id"] + r = client.patch(f"/api/semesters/{sid}", json={"end_date": None}) + assert r.status_code == 400 + + +def test_tutoring_cannot_overlap_other_semesters(env): + client, db = env + login(client, db) + assert _post(client, FIRST).status_code == 201 + second_id = _post(client, SECOND).json()["id"] + + r = _post(client, {**WINTER, "start_date": "2027-01-15"}) + assert r.status_code == 409 + assert "115 學年度第 1 學期" in r.json()["detail"] + assert "不能和其他學期重疊" in r.json()["detail"] + + assert _post(client, WINTER).status_code == 201 + # 一般學期改日期,撞到輔導學期也要擋 + r = client.patch(f"/api/semesters/{second_id}", json={"start_date": "2027-02-01"}) + assert r.status_code == 409 + assert "115 學年度寒假輔導" in r.json()["detail"] + # 一般學期之間照舊不擋(既有資料可能本來就重疊) + assert _post(client, {"academic_year": 116, "term": 1, + "start_date": "2027-06-01", "end_date": "2027-06-20"}).status_code == 201 + + +def test_copy_to_tutoring_semester(env): + client, db = env + login(client, db) + src = _post(client, {**SECOND, "template_key": "junior_high"}).json()["id"] + r = client.post(f"/api/semesters/{src}/copy", json={ + "academic_year": 115, "term": 4, "grade_promotion": False, + "start_date": SUMMER["start_date"], "end_date": SUMMER["end_date"]}) + assert r.status_code == 201 + assert r.json()["label"] == "115 學年度暑期輔導" + assert r.json()["is_tutoring"] is True + # 複製也要檢查重疊 + r = client.post(f"/api/semesters/{src}/copy", json={ + "academic_year": 115, "term": 3, "start_date": "2027-06-20", "end_date": "2027-07-10"}) + assert r.status_code == 409 + + +def _overworked(db, term): + """王師基本鐘點 4 節,配了 10 節(超鐘點上限 2 節)。""" + settings_service.save_max_overtime(db, 2) + b = Builder(db, 120, term, "junior_high") + b.teacher("王師", base_periods=4) + b.klass("901", grade=9, track=ClassTrack.junior_high.value) + b.subject("數學") + b.assign(subject="數學", teachers=["王師"], periods=10, classes=["901"]) + fx = b.build() + return b, fx.semester_id + + +def test_regular_semester_still_checks_overtime(db): + b, sid = _overworked(db, 1) + row = next(r for r in teacher_loads(db, sid) if r["name"] == "王師") + assert row["over_limit"] and not row["tutoring"] + codes = {i.code for i in preflight.run(load_problem(db, sid)).issues} + assert "teacher_over_hours" in codes + + +def test_tutoring_ignores_base_hours_and_overtime(db): + b, sid = _overworked(db, 4) + row = next(r for r in teacher_loads(db, sid) if r["name"] == "王師") + assert row["tutoring"] and not row["over_limit"] + assert row["assigned"] == 10 + # 配課與匯入共用的上限檢核不擋 + assert_within_overtime_limit(db, sid, {b.teachers["王師"].id}) + problem = load_problem(db, sid) + assert problem.is_tutoring + codes = {i.code for i in preflight.run(problem).issues} + assert "teacher_over_hours" not in codes + + +def test_slip_title_for_tutoring(db): + b, sid = _overworked(db, 4) + assert school_title(db, sid).endswith("120學年暑期輔導") + b1, sid1 = _overworked(db, 1) + assert school_title(db, sid1).endswith("120學年第一學期") diff --git a/docs/deploy/upgrade.html b/docs/deploy/upgrade.html index 1cf1bbe8..ff5ab504 100644 --- a/docs/deploy/upgrade.html +++ b/docs/deploy/upgrade.html @@ -172,7 +172,7 @@ 路線圖開發用 開發任務卡開發用 -
本頁目錄
+
本頁目錄
@@ -190,6 +190,9 @@

升級指南

開始前先備份。 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見備份指南。

+

升級到 v1.4.22:寒暑假輔導

+

v1.4.22 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可。要退回 v1.4.21,把 IMAGE_TAG 改回 v1.4.21 + 再 pull、up -d 即可;但退回前請先刪除建好的寒暑假輔導學期(舊版不認得這兩種學期別)。

升級到 v1.4.21:三角調課指定老師

v1.4.21 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可;從 v1.4.19 或更早的版本升上來,一樣會經過 v1.4.20 的資料表變更(會先自動備份)。要退回 v1.4.20,把 IMAGE_TAG 改回 v1.4.20 再 pull、up -d 即可。

diff --git a/docs/deploy/upgrade.md b/docs/deploy/upgrade.md index f558811c..02cecf62 100644 --- a/docs/deploy/upgrade.md +++ b/docs/deploy/upgrade.md @@ -8,6 +8,11 @@ > **開始前先備份。** 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見[備份指南](backup.md)。 +## 升級到 v1.4.22:寒暑假輔導 + +v1.4.22 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可。要退回 v1.4.21,把 `IMAGE_TAG` 改回 v1.4.21 +再 `pull`、`up -d` 即可;但退回前請先刪除建好的寒暑假輔導學期(舊版不認得這兩種學期別)。 + ## 升級到 v1.4.21:三角調課指定老師 v1.4.21 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可;從 v1.4.19 或更早的版本升上來,一樣會經過 diff --git a/docs/features.html b/docs/features.html index e7fc2f9f..7b7bb839 100644 --- a/docs/features.html +++ b/docs/features.html @@ -3,7 +3,7 @@ - + 功能總覽 · 排課與調代課系統