From b50fe1be62f59fb3cdd3992964f6e8fc6d9c122f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E4=BD=B3=E6=81=A9?= Date: Tue, 17 Nov 2026 23:58:39 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=81=9C=E8=AA=B2=E6=97=A5(=E5=85=A8?= =?UTF-8?q?=E6=A0=A1=E3=80=81=E5=B9=B4=E7=B4=9A=E6=88=96=E7=8F=AD=E7=B4=9A?= =?UTF-8?q?,=E6=95=B4=E5=A4=A9=E6=88=96=E6=8C=87=E5=AE=9A=E7=AF=80?= =?UTF-8?q?=E6=AC=A1);=E8=AB=8B=E5=81=87=E4=B8=8D=E5=88=97=E5=85=A5?= =?UTF-8?q?=E3=80=81=E4=B8=8D=E8=83=BD=E8=AA=BF=E8=AA=B2=E8=A3=9C=E8=AA=B2?= =?UTF-8?q?,=E5=B7=A1=E5=A0=82=E8=A1=A8=E8=88=87=E9=80=B1=E8=AA=B2?= =?UTF-8?q?=E8=A1=A8=E6=A8=99=E5=81=9C=E8=AA=B2;=E7=99=BC=E5=B8=83=20v1.4.?= =?UTF-8?q?19?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 組長回報「停課日在哪邊可以設定?」。系統原本只有請假節次的「不處理(當天停課)」, 不知道全校或整個班停課。 - 新增 class_suspensions / class_suspension_classes(遷移 0021,只新增資料表) - services/suspensions.py:一門課的每一個班都停課才算停課;第幾節依各班節次表換算 - 請假展開不列停課節次(回傳 skipped「停課(…)」),整天停課的班不產生代導 - 調課清單:停課的那一節不能拿來補課(SwapChecker.reason,送出時同一套檢查) - patrol_sheets.Day 標「停課」並優先於當天調代課;全校整天停課的日子巡堂表、教師週總表略過 - 事後設的停課不自動改已安排的調代課,儲存時回傳 conflicts - 前端「調代課 → 停課日」頁;請假登記訊息寫出停課節次 - e2e 系統管理備份測試改為不依賴備份數量(滿 30 份時會輪替) - 文件:手冊 8.11 與 FAQ、架構、升級指南(含退回 v1.4.18)、CHANGELOG、功能總覽 Co-Authored-By: Claude Opus 5.5 --- .env.example | 2 +- CHANGELOG.md | 21 +- README.md | 6 +- .../versions/0021_class_suspensions.py | 51 ++++ backend/app/api/suspensions.py | 154 ++++++++++ backend/app/main.py | 2 + backend/app/models/__init__.py | 2 + backend/app/models/suspension.py | 70 +++++ backend/app/schemas/suspension.py | 40 +++ backend/app/services/leaves.py | 21 +- backend/app/services/patrol_sheets.py | 27 +- backend/app/services/suspensions.py | 247 ++++++++++++++++ backend/app/services/swap_options.py | 7 + backend/app/services/teacher_week_sheets.py | 11 +- backend/app/services/timetable_week.py | 2 + backend/tests/conftest.py | 2 + backend/tests/test_suspensions_v1419.py | 223 ++++++++++++++ docs/architecture.html | 5 + docs/architecture.md | 1 + docs/deploy/upgrade.html | 16 +- docs/deploy/upgrade.md | 20 ++ docs/features.html | 10 +- docs/index.html | 30 +- docs/roadmap.html | 5 + docs/roadmap.md | 1 + frontend/e2e/suspensions.spec.ts | 99 +++++++ frontend/e2e/system-settings.spec.ts | 10 +- frontend/src/api/suspensions.ts | 43 +++ frontend/src/layouts/MainLayout.vue | 1 + frontend/src/router/index.ts | 6 + frontend/src/views/leaves/leaveText.test.ts | 16 + frontend/src/views/leaves/leaveText.ts | 25 +- .../src/views/substitution/Suspensions.vue | 279 ++++++++++++++++++ .../views/substitution/suspensionText.test.ts | 30 ++ .../src/views/substitution/suspensionText.ts | 45 +++ 35 files changed, 1501 insertions(+), 29 deletions(-) create mode 100644 backend/alembic/versions/0021_class_suspensions.py create mode 100644 backend/app/api/suspensions.py create mode 100644 backend/app/models/suspension.py create mode 100644 backend/app/schemas/suspension.py create mode 100644 backend/app/services/suspensions.py create mode 100644 backend/tests/test_suspensions_v1419.py create mode 100644 frontend/e2e/suspensions.spec.ts create mode 100644 frontend/src/api/suspensions.ts create mode 100644 frontend/src/views/substitution/Suspensions.vue create mode 100644 frontend/src/views/substitution/suspensionText.test.ts create mode 100644 frontend/src/views/substitution/suspensionText.ts diff --git a/.env.example b/.env.example index a8d5f9d9..28979a89 100644 --- a/.env.example +++ b/.env.example @@ -32,7 +32,7 @@ HTTP_PORT=80 # ── 預建映像版本(僅「拉取映像」部署方式需要)────────── # 用 docker compose pull 拉官方映像時,決定要拉哪一版。 # 預設 latest(最新);正式部署建議釘選版本號以利可控升級,例如: -# IMAGE_TAG=v1.4.18 +# IMAGE_TAG=v1.4.19 # 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。 IMAGE_TAG=latest diff --git a/CHANGELOG.md b/CHANGELOG.md index 02632cbd..1946b4e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,29 @@ 破壞性變更(需人工介入才能升級)以 ⚠️ 標註。 -> **新使用者請直接安裝 v1.4.18**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.17 是先前版本;以下條目保留作為變更紀錄。 +> **新使用者請直接安裝 v1.4.19**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.18 是先前版本;以下條目保留作為變更紀錄。 ## [Unreleased] +## [1.4.19] — 2026-11-17 + +**新功能:停課日**(LINE 社群組長:「停課日在哪邊可以設定?」)。 + +**新增兩張資料表**(既有的資料表與資料都不動)。升級時系統會先自動備份再升級,照一般方式即可(`.env` 改 `IMAGE_TAG=v1.4.19` → `docker compose pull && docker compose up -d`)。 + +官方映像(amd64 + arm64 雙架構)已發布於 GHCR: +`ghcr.io/begin0808/course_scheduling_system-{api,worker,web}:v1.4.19` + +### 新增 +- **停課日**(「調代課 → 停課日」):校慶補假、颱風假、段考下午、戶外教學、探索活動……設定哪幾天、哪些班、哪幾節不上課。 + - 對象:全校,或指定年級、班級(勾年級 = 勾整個年級的班)。 + - 範圍:整天,或第幾節到第幾節(只算一般上課節次;國中小兩部作息不同時各依自己的節次表)。 + - 停課的課:**請假時不列入**(不必找人代,登記完成的訊息會寫出哪幾節停課)、整天停課的班**不必代導**、**不能拿來調課補課**(調課清單寫「這節停課(…),不能補課」)。 + - 巡堂表、課表查詢的某一週課表、全校教師週總表、儀表板即時概況標「停課」;全校整天停課的日子,巡堂表與教師週總表略過。 + - 合班、跑班的課要**每一個班都停課**才算停課(還有一班要上,老師就要去)。 + - 停課是事後才設的話,那段時間已經安排的請假節次、調課補課、代導**不會自動更改**(可能已通知老師),儲存時會列出來,請到「調代課處理」撤回或改成「不處理」。 + + ## [1.4.18] — 2026-11-11 **修正:調課之後重新發布課表,補課那一節不見了**(LINE 社群組長回報,**建議升級**)。 diff --git a/README.md b/README.md index 992bc840..51e9f797 100644 --- a/README.md +++ b/README.md @@ -132,11 +132,11 @@ docker compose up -d # 首次會建置映像,需數分鐘 ## 專案狀態 -**v1.4.18 已發行(2026-11-11)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 783 項單元/整合測試、61 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。 +**v1.4.19 已發行(2026-11-17)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 792 項單元/整合測試、62 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。 -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.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.18` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。 +**請直接從最新版開始安裝**(見上方快速開始);`v1.4.19` 是目前建議使用的版本。各版變更見 [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/alembic/versions/0021_class_suspensions.py b/backend/alembic/versions/0021_class_suspensions.py new file mode 100644 index 00000000..58b32caa --- /dev/null +++ b/backend/alembic/versions/0021_class_suspensions.py @@ -0,0 +1,51 @@ +"""v1.4.19:停課日(全校、年級或指定班級,整天或第幾節到第幾節不上課)。 + +新增兩張表,不改既有資料表與資料。升級前已登記的請假節次不會因此改變; +之後新設的停課,設定時會列出時段裡已經安排的調代課,由組長自行處理。 + +Revision ID: 0021_class_suspensions +Revises: 0020_relink_swaps +""" + +import sqlalchemy as sa + +from alembic import op + +revision = "0021_class_suspensions" +down_revision = "0020_relink_swaps" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "class_suspensions", + sa.Column("id", sa.Integer(), primary_key=True), + sa.Column("semester_id", sa.Integer(), + sa.ForeignKey("semesters.id", ondelete="CASCADE"), nullable=False), + sa.Column("start_date", sa.Date(), nullable=False), + sa.Column("end_date", sa.Date(), nullable=False), + sa.Column("whole_school", sa.Boolean(), nullable=False), + sa.Column("from_ordinal", sa.Integer(), nullable=True), + sa.Column("to_ordinal", sa.Integer(), nullable=True), + sa.Column("reason", sa.String(length=64), nullable=False), + sa.Column("created_by_name", sa.String(length=64), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), + server_default=sa.func.now(), nullable=False), + ) + for col in ("semester_id", "start_date", "end_date"): + op.create_index(f"ix_class_suspensions_{col}", "class_suspensions", [col]) + op.create_table( + "class_suspension_classes", + sa.Column("suspension_id", sa.Integer(), + sa.ForeignKey("class_suspensions.id", ondelete="CASCADE"), primary_key=True), + sa.Column("class_unit_id", sa.Integer(), + sa.ForeignKey("class_units.id", ondelete="CASCADE"), primary_key=True), + ) + op.create_index("ix_class_suspension_classes_class_unit_id", + "class_suspension_classes", ["class_unit_id"]) + + +def downgrade() -> None: + op.drop_table("class_suspension_classes") + op.drop_table("class_suspensions") diff --git a/backend/app/api/suspensions.py b/backend/app/api/suspensions.py new file mode 100644 index 00000000..0ce4a7cd --- /dev/null +++ b/backend/app/api/suspensions.py @@ -0,0 +1,154 @@ +"""停課日(v1.4.19):全校、年級或指定班級,整天或第幾節到第幾節不上課。 + +RBAC:看,所有登入的人(老師在課表查詢也會看到停課);設定,教學組長與教務主任。 +""" + +from fastapi import APIRouter, Depends, HTTPException, Query, status +from sqlalchemy import select +from sqlalchemy.orm import Session + +from app.core.auth import get_active_user, require_roles +from app.core.db import get_db +from app.models.audit import AuditLog +from app.models.basedata import ClassUnit +from app.models.semester import Semester +from app.models.suspension import ClassSuspension +from app.models.user import Role, User +from app.schemas.suspension import SuspensionIn, SuspensionOut, SuspensionSaved +from app.services import suspensions as suspension_service + +router = APIRouter(tags=["suspensions"]) + +registrar = require_roles(Role.scheduler, Role.director) + +MAX_DAYS = 180 # 和單張假單同一個上限,擋住手殘輸入的 2099 年 + + +def _classes(db: Session, semester_id: int) -> list[ClassUnit]: + return list(db.scalars( + select(ClassUnit).where(ClassUnit.semester_id == semester_id) + .order_by(ClassUnit.grade, ClassUnit.name))) + + +def _out(s: ClassSuspension, all_classes: list[ClassUnit]) -> SuspensionOut: + return SuspensionOut( + id=s.id, start_date=s.start_date, end_date=s.end_date, whole_school=s.whole_school, + class_ids=[c.id for c in s.classes], all_day=s.all_day, + from_ordinal=s.from_ordinal, to_ordinal=s.to_ordinal, reason=s.reason, + target_text=suspension_service.target_text(s, all_classes), + period_text=suspension_service.period_text(s), + created_by_name=s.created_by_name, + ) + + +def _apply(db: Session, s: ClassSuspension, body: SuspensionIn, semester: Semester) -> None: + """檢查並寫入;不合法時丟 400。""" + if body.end_date < body.start_date: + raise HTTPException(status.HTTP_400_BAD_REQUEST, "結束日期不可早於開始日期") + if (body.end_date - body.start_date).days + 1 > MAX_DAYS: + raise HTTPException(status.HTTP_400_BAD_REQUEST, f"一筆停課最長 {MAX_DAYS} 天") + if ((semester.start_date and body.start_date < semester.start_date) + or (semester.end_date and body.end_date > semester.end_date)): + raise HTTPException(status.HTTP_400_BAD_REQUEST, "停課日期要在學期期間內") + if body.all_day: + lo = hi = None + else: + if body.from_ordinal is None: + raise HTTPException(status.HTTP_400_BAD_REQUEST, "請選擇從第幾節開始停課") + lo, hi = body.from_ordinal, body.to_ordinal or body.from_ordinal + if hi < lo: + raise HTTPException(status.HTTP_400_BAD_REQUEST, "結束節次不可早於開始節次") + classes: list[ClassUnit] = [] + if not body.whole_school: + ids = set(body.class_ids) + if not ids: + raise HTTPException(status.HTTP_400_BAD_REQUEST, "請選擇停課的年級或班級") + classes = list(db.scalars( + select(ClassUnit).where(ClassUnit.id.in_(ids), ClassUnit.semester_id == semester.id))) + if len(classes) != len(ids): + raise HTTPException(status.HTTP_400_BAD_REQUEST, "班級清單含無效或跨學期的班級") + s.start_date, s.end_date = body.start_date, body.end_date + s.whole_school = body.whole_school + s.classes = classes + s.from_ordinal, s.to_ordinal = lo, hi + s.reason = body.reason.strip() + + +def _saved(db: Session, s: ClassSuspension, user: User, action: str) -> SuspensionSaved: + all_classes = _classes(db, s.semester_id) + item = _out(s, all_classes) + db.add(AuditLog( + user_id=user.id, username=user.username, action=action, + target_type="class_suspension", target_id=s.id, + detail=(f"{s.start_date}~{s.end_date} {item.target_text} {item.period_text}" + f" {s.reason}")[:500], + )) + conflicts = [c.text for c in suspension_service.conflicts(db, s)] + db.commit() + return SuspensionSaved(item=item, conflicts=conflicts) + + +@router.get("/suspensions", response_model=list[SuspensionOut]) +def list_suspensions( + semester_id: int = Query(...), + db: Session = Depends(get_db), + _: User = Depends(get_active_user), +) -> list[SuspensionOut]: + all_classes = _classes(db, semester_id) + rows = db.scalars( + select(ClassSuspension).where(ClassSuspension.semester_id == semester_id) + .order_by(ClassSuspension.start_date, ClassSuspension.id)) + return [_out(s, all_classes) for s in rows] + + +@router.post("/suspensions", response_model=SuspensionSaved, + status_code=status.HTTP_201_CREATED) +def create_suspension( + body: SuspensionIn, + semester_id: int = Query(...), + db: Session = Depends(get_db), + user: User = Depends(registrar), +) -> SuspensionSaved: + semester = db.get(Semester, semester_id) + if semester is None: + raise HTTPException(status.HTTP_404_NOT_FOUND, "找不到學期") + s = ClassSuspension(semester_id=semester_id, created_by_name=user.username) + _apply(db, s, body, semester) + db.add(s) + db.flush() + return _saved(db, s, user, "create_suspension") + + +@router.put("/suspensions/{suspension_id}", response_model=SuspensionSaved) +def update_suspension( + suspension_id: int, + body: SuspensionIn, + db: Session = Depends(get_db), + user: User = Depends(registrar), +) -> SuspensionSaved: + s = db.get(ClassSuspension, suspension_id) + if s is None: + raise HTTPException(status.HTTP_404_NOT_FOUND, "找不到這筆停課") + semester = db.get(Semester, s.semester_id) + assert semester is not None + _apply(db, s, body, semester) + db.flush() + return _saved(db, s, user, "update_suspension") + + +@router.delete("/suspensions/{suspension_id}", status_code=status.HTTP_204_NO_CONTENT) +def delete_suspension( + suspension_id: int, + db: Session = Depends(get_db), + user: User = Depends(registrar), +) -> None: + s = db.get(ClassSuspension, suspension_id) + if s is None: + raise HTTPException(status.HTTP_404_NOT_FOUND, "找不到這筆停課") + db.add(AuditLog( + user_id=user.id, username=user.username, action="delete_suspension", + target_type="class_suspension", target_id=s.id, + detail=f"{s.start_date}~{s.end_date} {s.reason}"[:500], + )) + db.delete(s) + db.commit() diff --git a/backend/app/main.py b/backend/app/main.py index 775addeb..9734bf93 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -25,6 +25,7 @@ substitution_log, substitution_stats, substitutions, + suspensions, system, timetables, users, @@ -107,6 +108,7 @@ async def lifespan(_app: FastAPI): app.include_router(homeroom_covers.router, prefix="/api") app.include_router(substitution_log.router, prefix="/api") app.include_router(substitution_stats.router, prefix="/api") +app.include_router(suspensions.router, prefix="/api") app.include_router(notifications.router, prefix="/api") app.include_router(settings_api.router, prefix="/api") app.include_router(backups.router, prefix="/api") diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index d3bfa331..cb80f86b 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -41,6 +41,7 @@ Substitution, SubstitutionType, ) +from app.models.suspension import ClassSuspension from app.models.timetable import ScheduleEntry, Timetable, TimetableStatus from app.models.user import Role, User, UserRole from app.models.wizard import WizardState @@ -87,4 +88,5 @@ "Substitution", "SubstitutionType", "SUBSTITUTION_TYPE_CN", + "ClassSuspension", ] diff --git a/backend/app/models/suspension.py b/backend/app/models/suspension.py new file mode 100644 index 00000000..7734be60 --- /dev/null +++ b/backend/app/models/suspension.py @@ -0,0 +1,70 @@ +"""停課日 model(v1.4.19)。 + +組長回報:「停課日在哪邊可以設定?」——校慶補假、颱風假、段考下午、某個年級的戶外教學、 +特定班級的探索活動,這些時段那幾個班不上課。系統原本只有請假時的「不處理(當天停課)」, +那只管請假老師的那一節,不知道全校或整個班停課。 + +一筆停課 = 一段日期 × 對象(全校,或指定班級)× 範圍(整天,或第幾節到第幾節)。 +「第幾節」只數一般課(與調課單、巡堂表相同),各班依自己的節次表對應,國中小兩部作息 +不同也各自對得上。指定年級在畫面上是「一次勾選整個年級的班」,存的仍是班級。 + +停課的課: +- 請假時不列為受影響節次(那節本來就不上課,不必找人代);整天停課的班也不必代導。 +- 找調課補課節次時,停課的那一節不能拿來補課。 +- 巡堂表、週課表、教師週總表、即時概況標「停課」;全校整天停課的日子巡堂表略過。 + +判斷規則集中在 `app.services.suspensions`。 +""" + +from datetime import date, datetime + +from sqlalchemy import ( + Boolean, + Column, + Date, + DateTime, + ForeignKey, + Integer, + String, + Table, + func, +) +from sqlalchemy.orm import Mapped, mapped_column, relationship + +from app.core.db import Base +from app.models.basedata import ClassUnit + +suspension_classes = Table( + "class_suspension_classes", + Base.metadata, + Column("suspension_id", ForeignKey("class_suspensions.id", ondelete="CASCADE"), + primary_key=True), + Column("class_unit_id", ForeignKey("class_units.id", ondelete="CASCADE"), + primary_key=True, index=True), +) + + +class ClassSuspension(Base): + __tablename__ = "class_suspensions" + + id: Mapped[int] = mapped_column(primary_key=True) + semester_id: Mapped[int] = mapped_column( + ForeignKey("semesters.id", ondelete="CASCADE"), index=True + ) + start_date: Mapped[date] = mapped_column(Date, index=True) + end_date: Mapped[date] = mapped_column(Date, index=True) + whole_school: Mapped[bool] = mapped_column(Boolean, default=True) + # 第幾節到第幾節(只數一般課,含頭尾);兩個都空 = 整天 + from_ordinal: Mapped[int | None] = mapped_column(Integer, nullable=True) + to_ordinal: Mapped[int | None] = mapped_column(Integer, nullable=True) + reason: Mapped[str] = mapped_column(String(64), default="") + created_by_name: Mapped[str] = mapped_column(String(64), default="") + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + + classes: Mapped[list[ClassUnit]] = relationship( + secondary=suspension_classes, lazy="selectin", + order_by=[ClassUnit.grade, ClassUnit.name]) + + @property + def all_day(self) -> bool: + return self.from_ordinal is None and self.to_ordinal is None diff --git a/backend/app/schemas/suspension.py b/backend/app/schemas/suspension.py new file mode 100644 index 00000000..b26582b6 --- /dev/null +++ b/backend/app/schemas/suspension.py @@ -0,0 +1,40 @@ +"""停課日 schema(v1.4.19)。""" + +from datetime import date + +from pydantic import BaseModel, Field + +_Date = date + + +class SuspensionIn(BaseModel): + start_date: date + end_date: _Date + whole_school: bool = True + # 不是全校時的班級(年級在畫面上一次勾整個年級的班) + class_ids: list[int] = Field(default_factory=list) + all_day: bool = True + from_ordinal: int | None = Field(default=None, ge=1, le=20) # 第幾節(只數一般課) + to_ordinal: int | None = Field(default=None, ge=1, le=20) + reason: str = Field(default="", max_length=64) + + +class SuspensionOut(BaseModel): + id: int + start_date: _Date + end_date: _Date + whole_school: bool + class_ids: list[int] + all_day: bool + from_ordinal: int | None = None + to_ordinal: int | None = None + reason: str + target_text: str # 「全校」「七年級」「801、802」 + period_text: str # 「整天」「第 5~7 節」 + created_by_name: str = "" + + +class SuspensionSaved(BaseModel): + item: SuspensionOut + # 停課時段裡已經安排好的請假節次、調課補課、代導;組長要自己撤回或改成「不處理」 + conflicts: list[str] = Field(default_factory=list) diff --git a/backend/app/services/leaves.py b/backend/app/services/leaves.py index f3130205..897ebd18 100644 --- a/backend/app/services/leaves.py +++ b/backend/app/services/leaves.py @@ -41,6 +41,7 @@ from app.models.timetable import ScheduleEntry, Timetable, TimetableStatus from app.services import notifications from app.services import period_tables as pt_service +from app.services import suspensions as suspension_service MAX_LEAVE_DAYS = 180 # 產假上限約 8 週;180 天足夠,同時擋住手殘輸入的 2099 年 @@ -146,10 +147,13 @@ def describe(self, a: CourseAssignment, entry: ScheduleEntry) -> tuple[str, str, return (subject.name if subject else ""), classes, (room.name if room else "") -def expand(db: Session, leave: LeaveRequest) -> list[AffectedPeriod]: +def expand( + db: Session, leave: LeaveRequest, suspended: list["Skipped"] | None = None, +) -> list[AffectedPeriod]: """依已發布課表展開受影響節次。呼叫端負責 commit。 課表尚未發布時回傳空清單——假單照樣成立,只是沒有課要處理。 + 停課的節次不列入(v1.4.19:那節本來就不上課);給了 `suspended` 就把它們記在裡面。 """ timetable = _published_timetable(db, leave.semester_id) if timetable is None: @@ -160,6 +164,7 @@ def expand(db: Session, leave: LeaveRequest) -> list[AffectedPeriod]: return [] exp = _Expander(db) + cal = suspension_service.Calendar(db, leave.semester_id, leave.start_date, leave.end_date) out: list[AffectedPeriod] = [] seen: set[tuple[date, int, str]] = set() semester = db.get(Semester, leave.semester_id) @@ -191,6 +196,11 @@ def expand(db: Session, leave: LeaveRequest) -> list[AffectedPeriod]: if key in seen: continue seen.add(key) + off = cal.for_assignment(a, day, period.period_no) + if off is not None: + if suspended is not None: + suspended.append(Skipped(day, period.name, suspension_service.label(off))) + continue out.append(AffectedPeriod( leave_request_id=leave.id, semester_id=leave.semester_id, date=day, weekday=weekday, period_no=period.period_no, @@ -225,6 +235,7 @@ def expand_covers(db: Session, leave: LeaveRequest) -> list[HomeroomCover]: return [] exp = _Expander(db) + cal = suspension_service.Calendar(db, leave.semester_id, leave.start_date, leave.end_date) out: list[HomeroomCover] = [] for klass in classes: table = pt_service.resolve_period_table(db, klass) @@ -234,6 +245,8 @@ def expand_covers(db: Session, leave: LeaveRequest) -> list[HomeroomCover]: continue elif day.isoweekday() > _DEFAULT_WEEKDAYS: continue + if cal.all_day_for_class(klass.id, day) is not None: + continue # 這班整天停課,不必代導(v1.4.19) begin, finish = _leave_window(leave, day) out.append(HomeroomCover( leave_request_id=leave.id, semester_id=leave.semester_id, @@ -247,11 +260,11 @@ def expand_covers(db: Session, leave: LeaveRequest) -> list[HomeroomCover]: @dataclass(frozen=True, slots=True) class Skipped: - """登記請假時沒列入的一節:它已經在別張假單或調課裡(v1.4.16)。""" + """登記請假時沒列入的一節:它已經在別張假單或調課裡(v1.4.16),或那一節停課(v1.4.19)。""" day: date period_name: str - taken_by: str # 那張的假別名稱,例如「調課(未請假)」 + taken_by: str # 那張的假別名稱,例如「調課(未請假)」;停課時是「停課(校慶補假)」 def cover_is_past(day: date) -> bool: @@ -311,7 +324,7 @@ def create( taken = taken_slots(db, teacher.id, start_date, end_date) skipped: list[Skipped] = [] - for period in expand(db, leave): + for period in expand(db, leave, suspended=skipped): label = taken.get((period.date, period.period_no)) if label: skipped.append(Skipped(period.date, period.period_name, label)) diff --git a/backend/app/services/patrol_sheets.py b/backend/app/services/patrol_sheets.py index 350b66ba..7dcdbf6e 100644 --- a/backend/app/services/patrol_sheets.py +++ b/backend/app/services/patrol_sheets.py @@ -31,9 +31,11 @@ from app.models.period import Period, PeriodTable, PeriodType from app.models.semester import Semester from app.models.substitution import Substitution, SubstitutionType +from app.models.suspension import ClassSuspension from app.models.timetable import ScheduleEntry from app.services import period_tables as pt_service from app.services import settings as app_settings +from app.services import suspensions as suspension_service from app.services.availability import published_timetable from app.services.slip_layout import school_title @@ -125,6 +127,7 @@ class _Lesson: note: str original: str = "" # 有異動時,課表上原本的老師(v1.4.15 課表查詢的週課表用) swap_with: str = "" # 調課:對調的另一節「11/20 第三節」(v1.4.17 週課表用) + reason: str = "" # 停課的說明「校慶補假」(v1.4.19 週課表用) def _days(date_from: date, date_to: date) -> Iterator[date]: @@ -215,6 +218,19 @@ def __init__(self, db: Session, semester_id: int, timetable_id: int, on: date) - ap = db.get(AffectedPeriod, sub.affected_period_id) if ap is not None: self.makeup[(sub.swap_entry_id, sub.swap_period_no)] = (ap, sub) + # 停課日(v1.4.19):停課的課不上,優先於當天的調代課(停課是事後設的,設定時已提醒組長) + self.calendar = suspension_service.Calendar(db, semester_id, on, on) + + def suspended(self, entry: ScheduleEntry, period_no: int) -> ClassSuspension | None: + """這一格的這一節停課嗎(這門課的每一班都停課才算)。""" + return self.calendar.for_entry(entry, self.on, period_no) if self.calendar else None + + @property + def all_off(self) -> bool: + """這一天所有的課都停課(例如全校校慶補假):巡堂表、教師週總表略過這一天。""" + return bool(self.calendar) and all( + self.suspended(e, p) is not None + for e in self.entries for p in range(e.period_no, e.period_no + e.span)) def _lesson(self, entry: ScheduleEntry, period_no: int) -> _Lesson: a = entry.assignment @@ -223,6 +239,13 @@ def _lesson(self, entry: ScheduleEntry, period_no: int) -> _Lesson: names = [at.teacher.name for at in a.teachers] original = "、".join(names) subject, note, swap_with = a.subject.name, "", "" + off = self.suspended(entry, period_no) + if off is not None: + return _Lesson( + unit_id=unit.id, unit_name=unit.name, is_group=unit.unit_type == "group", + subject=subject, teacher=original, room=room.name if room else "", + note=_NOTE[SubstitutionType.cancel.value], reason=off.reason, + ) def replace(absent_name: str, by: str) -> None: """只換掉請假的那一位;協同教學的另一位老師照常上課。""" @@ -331,7 +354,7 @@ def build(db: Session, semester_id: int, date_from: date, date_to: date) -> Patr result = PatrolSheets(title=school_title(db, semester_id), legend=legend(db)) for on in _days(date_from, date_to): day = Day(db, semester_id, timetable.id, on) - if not day.entries: + if not day.entries or day.all_off: continue listed: set[tuple[int, int]] = set() # 已出過分組單的 (群組, 節次) for table, members in by_table.values(): @@ -362,5 +385,5 @@ def build(db: Session, semester_id: int, date_from: date, date_to: date) -> Patr page.rows.append(row) result.pages.append(page) if not result.pages: - raise PatrolError("這段期間沒有任何課(可能是假日,或課表尚未排入)") + raise PatrolError("這段期間沒有任何課(可能是假日、停課,或課表尚未排入)") return result diff --git a/backend/app/services/suspensions.py b/backend/app/services/suspensions.py new file mode 100644 index 00000000..7274b1c0 --- /dev/null +++ b/backend/app/services/suspensions.py @@ -0,0 +1,247 @@ +"""停課日的判斷(v1.4.19)。資料表見 `app.models.suspension`。 + +**一門課什麼時候算停課?** 這門課的「每一個班」在那一節都停課。跑班、合班的課只要還有 +一個班照常上課,老師就還是要去上——例如只有 801 去戶外教學,801、802 合上的體育照常。 + +「第幾節」只數一般課,依每一班自己的節次表換算(國中小兩部作息不同也各自對得上); +早自習、午休這類時段只有「整天停課」才算在內。 + +本模組只讀;寫入在 `app.api.suspensions`。 +""" + +from collections.abc import Iterable +from dataclasses import dataclass +from datetime import date + +from sqlalchemy import select +from sqlalchemy.orm import Session + +from app.models.assignment import CourseAssignment +from app.models.basedata import ClassUnit +from app.models.leave import ( + LEAVE_TYPE_CN, + AffectedPeriod, + AffectedStatus, + HomeroomCover, + LeaveRequest, + LeaveStatus, +) +from app.models.period import Period, PeriodType +from app.models.substitution import Substitution, SubstitutionType +from app.models.suspension import ClassSuspension +from app.models.timetable import ScheduleEntry +from app.services import period_tables as pt_service + + +def label(s: ClassSuspension) -> str: + """「停課(校慶補假)」;沒寫說明就只寫「停課」。""" + return f"停課({s.reason})" if s.reason else "停課" + + +def period_text(s: ClassSuspension) -> str: + """「整天」「第 5 節」「第 5~7 節」。""" + if s.all_day: + return "整天" + lo, hi = s.from_ordinal or 1, s.to_ordinal or s.from_ordinal or 1 + return f"第 {lo} 節" if lo == hi else f"第 {lo}~{hi} 節" + + +def target_text(s: ClassSuspension, all_classes: list[ClassUnit]) -> str: + """「全校」「七年級」「七年級、801」:整個年級都選了就寫年級,其餘寫班名。 + + 年級依學制分開算(國中小:國小一年級與國中一年級是不同的年級)。 + """ + if s.whole_school: + return "全校" + chosen = {c.id for c in s.classes} + grades: dict[tuple[str, int], list[ClassUnit]] = {} + for c in all_classes: + grades.setdefault((c.track, c.grade), []).append(c) + multi_track = len({t for t, _ in grades}) > 1 + parts: list[str] = [] + for (track, grade), members in sorted(grades.items(), key=lambda x: (x[0][1], x[0][0])): + picked = [c for c in members if c.id in chosen] + if not picked: + continue + if len(picked) == len(members): + parts.append(f"{_track_cn(track) if multi_track else ''}{_grade_cn(grade)}年級") + else: + parts.extend(c.name for c in picked) + return "、".join(parts) or "(沒有班級)" + + +# 與前端 TRACK_LABELS 相同 +_TRACK_CN = { + "elementary": "國小", "junior_high": "國中", "senior_high": "普通型高中", + "comprehensive": "綜合型高中", "vocational": "技術型高中", +} + + +def _track_cn(track: str) -> str: + return _TRACK_CN.get(track, "") + + +def _grade_cn(grade: int) -> str: + digits = "零一二三四五六七八九十" + return digits[grade] if 0 <= grade <= 10 else str(grade) + + +@dataclass(frozen=True, slots=True) +class Conflict: + """停課時段裡已經安排好的調代課:要組長自己決定撤回或改成「不處理」。""" + + date: date + text: str + + +class Calendar: + """一段期間的停課設定;依班級、日期、節次查詢。只建構一次、重複查詢。""" + + def __init__( + self, db: Session, semester_id: int, start: date, end: date, + rows: list[ClassSuspension] | None = None, + ) -> None: + self.db = db + self.rows = rows if rows is not None else list(db.scalars( + select(ClassSuspension).where( + ClassSuspension.semester_id == semester_id, + ClassSuspension.start_date <= end, + ClassSuspension.end_date >= start, + ).order_by(ClassSuspension.id) + )) + self._class_ids = {s.id: {c.id for c in s.classes} for s in self.rows} + self._table_of: dict[int, int | None] = {} + self._ordinals: dict[tuple[int, int], dict[int, int]] = {} + + def __bool__(self) -> bool: + return bool(self.rows) + + def _ordinal(self, class_id: int, weekday: int, period_no: int) -> int | None: + """這一班節次表裡,這一節是第幾節(只數一般課);不是一般課回 None。""" + if class_id not in self._table_of: + klass = self.db.get(ClassUnit, class_id) + table = pt_service.resolve_period_table(self.db, klass) if klass else None + self._table_of[class_id] = table.id if table else None + table_id = self._table_of[class_id] + if table_id is None: + return period_no # 沒有節次表:保守當作節次號就是第幾節 + key = (table_id, weekday) + if key not in self._ordinals: + regular = self.db.scalars( + select(Period.period_no).where( + Period.period_table_id == table_id, Period.weekday == weekday, + Period.type == PeriodType.regular.value, + ).order_by(Period.period_no) + ).all() + self._ordinals[key] = {no: i for i, no in enumerate(regular, start=1)} + return self._ordinals[key].get(period_no) + + def _applies(self, s: ClassSuspension, class_id: int, day: date) -> bool: + return (s.start_date <= day <= s.end_date + and (s.whole_school or class_id in self._class_ids[s.id])) + + def for_class(self, class_id: int, day: date, period_no: int) -> ClassSuspension | None: + """這一班這一天的這一節停課嗎?停課就回那一筆。""" + for s in self.rows: + if not self._applies(s, class_id, day): + continue + if s.all_day: + return s + ordinal = self._ordinal(class_id, day.isoweekday(), period_no) + lo = s.from_ordinal or 1 + hi = s.to_ordinal or lo + if ordinal is not None and lo <= ordinal <= hi: + return s + return None + + def for_classes( + self, class_ids: Iterable[int], day: date, period_no: int, + ) -> ClassSuspension | None: + """每一個班都停課才算(合班、跑班還有一班要上,老師就要去)。""" + if not self.rows: + return None + hits = [self.for_class(c, day, period_no) for c in class_ids] + return hits[0] if hits and all(hits) else None + + def for_assignment( + self, assignment: CourseAssignment | None, day: date, period_no: int, + ) -> ClassSuspension | None: + if assignment is None or not self.rows: + return None + return self.for_classes( + [m.class_unit_id for m in assignment.scheduling_unit.members], day, period_no) + + def for_entry(self, entry: ScheduleEntry, day: date, period_no: int) -> ClassSuspension | None: + return self.for_assignment(entry.assignment, day, period_no) if self.rows else None + + def all_day_for_class(self, class_id: int, day: date) -> ClassSuspension | None: + """這一班這一天整天停課嗎?(代導以天為單位,整天停課才不必代導)""" + return next((s for s in self.rows if s.all_day and self._applies(s, class_id, day)), None) + + +def _md(d: date) -> str: + return f"{d.month}/{d.day}" + + +def conflicts(db: Session, s: ClassSuspension) -> list[Conflict]: + """這筆停課的時段裡,已經登記的請假節次、調課補課與代導。 + + 停課是事後才設的,之前安排的不自動改——可能已經通知了老師。列出來讓組長到 + 「調代課處理」撤回,或改成「不處理(當天停課)」。 + """ + cal = Calendar(db, s.semester_id, s.start_date, s.end_date, rows=[s]) + out: list[Conflict] = [] + live = ( + LeaveRequest.status == LeaveStatus.registered.value, + AffectedPeriod.status != AffectedStatus.cancelled.value, + AffectedPeriod.semester_id == s.semester_id, + ) + for ap in db.scalars( + select(AffectedPeriod) + .join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id) + .where(AffectedPeriod.date >= s.start_date, AffectedPeriod.date <= s.end_date, *live) + .order_by(AffectedPeriod.date, AffectedPeriod.period_no) + ): + a = db.get(CourseAssignment, ap.course_assignment_id) if ap.course_assignment_id else None + if cal.for_assignment(a, ap.date, ap.period_no) is None: + continue + who = ap.leave_request.teacher.name if ap.leave_request.teacher else "" + out.append(Conflict(ap.date, ( + f"{_md(ap.date)} {ap.period_name} {ap.class_names} {ap.subject_name}:" + f"{who} {LEAVE_TYPE_CN.get(ap.leave_request.leave_type, '請假')}"))) + + for sub in db.scalars( + select(Substitution) + .join(AffectedPeriod, Substitution.affected_period_id == AffectedPeriod.id) + .join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id) + .where( + Substitution.type == SubstitutionType.swap.value, + Substitution.swap_date >= s.start_date, Substitution.swap_date <= s.end_date, *live) + ): + entry = db.get(ScheduleEntry, sub.swap_entry_id) if sub.swap_entry_id else None + if (entry is None or sub.swap_date is None or sub.swap_period_no is None + or cal.for_entry(entry, sub.swap_date, sub.swap_period_no) is None): + continue + absent = db.get(AffectedPeriod, sub.affected_period_id) + who = absent.leave_request.teacher.name if absent and absent.leave_request.teacher else "" + out.append(Conflict(sub.swap_date, ( + f"{_md(sub.swap_date)} {sub.swap_period_name} {sub.swap_class_names}:" + f"{who} 調課回來補課"))) + + for cover in db.scalars( + select(HomeroomCover) + .join(LeaveRequest, HomeroomCover.leave_request_id == LeaveRequest.id) + .where( + HomeroomCover.semester_id == s.semester_id, + HomeroomCover.date >= s.start_date, HomeroomCover.date <= s.end_date, + HomeroomCover.status != AffectedStatus.cancelled.value, + LeaveRequest.status == LeaveStatus.registered.value, + ).order_by(HomeroomCover.date, HomeroomCover.class_name) + ): + if cover.class_id is None or cal.all_day_for_class(cover.class_id, cover.date) is None: + continue + who = cover.leave_request.teacher.name if cover.leave_request.teacher else "" + out.append(Conflict(cover.date, f"{_md(cover.date)} {cover.class_name} 代導:{who}請假")) + + out.sort(key=lambda c: c.date) + return out diff --git a/backend/app/services/swap_options.py b/backend/app/services/swap_options.py index 4de7822d..bb482d64 100644 --- a/backend/app/services/swap_options.py +++ b/backend/app/services/swap_options.py @@ -29,6 +29,7 @@ from app.models.semester import Semester from app.models.substitution import Substitution, SubstitutionType from app.models.timetable import ScheduleEntry +from app.services import suspensions as suspension_service from app.services.availability import Availability, Interval @@ -65,6 +66,9 @@ def __init__(self, db: Session, affected: AffectedPeriod, av: Availability) -> N self.semester = db.get(Semester, affected.semester_id) self._taken: set[tuple[int, date, int]] | None = None self._labels: dict[int, str] = {} + # 停課的那一節不上課,不能拿來補課(v1.4.19) + self.calendar = suspension_service.Calendar( + db, affected.semester_id, date.min, date.max) # 補登已經上過的調課(v1.4.10,組長回報:事後補登,留紀錄查老師多常換課): # 兩邊都已經上完了,補課那節也可以是過去的。只限「調課(未請假)」—— # 請假的節次過去了只能補登代課(`substitutions.assign`)。 @@ -136,6 +140,9 @@ def reason( v1.4.12:組長兩度回報「調課清單抓不到某一節」,兩次系統都對,只是看不出原因 (補課老師那節自己有課;請假時段蓋住那一節)。所以換不了的也列出來、寫原因。 """ + off = self.calendar.for_entry(entry, when, period_no) + if off is not None: + return f"這節{suspension_service.label(off)},不能補課" slot = self.av.entry_slot(entry, period_no) if self.av.is_on_leave(partner.id, when, slot): return f"{partner.name}這節也請假,這節課本身就需要安排,不能拿來對調" diff --git a/backend/app/services/teacher_week_sheets.py b/backend/app/services/teacher_week_sheets.py index b64e67cb..57cd1e8f 100644 --- a/backend/app/services/teacher_week_sheets.py +++ b/backend/app/services/teacher_week_sheets.py @@ -28,6 +28,7 @@ from app.models.semester import Semester from app.models.substitution import Substitution, SubstitutionType from app.models.timetable import ScheduleEntry +from app.services import suspensions as suspension_service from app.services.availability import published_timetable from app.services.patrol_sheets import Day, classes_by_period_table from app.services.slip_layout import Tables, school_title @@ -202,7 +203,11 @@ def put(teacher_id: int | None, ordinal: int, item: Item) -> None: label = _label(e) for p in range(e.period_no, e.period_no + e.span): ordinal = b.ordinal(a.id, wd, p) - if (a.id, p) in day.absent: + off = day.suspended(e, p) + if off is not None: # 停課(v1.4.19):原本的課沒上 + for t in teacher_ids: + put(t, ordinal, Item(label, OFF, suspension_service.label(off))) + elif (a.id, p) in day.absent: ap, sub = day.absent[(a.id, p)] absent_id = ap.leave_request.teacher_id for t in teacher_ids: # 協同教學的另一位照常上課 @@ -280,7 +285,7 @@ def build(db: Session, semester_id: int, on: date, weeks: int = 1) -> TeacherWee if semester and semester.end_date and d > semester.end_date: continue day = Day(db, semester_id, timetable.id, d) - if not day.entries: + if not day.entries or day.all_off: continue cells = day_cells(b, day) for ordinal, name in enumerate(_row_names(b, tables, d.isoweekday()), 1): @@ -290,5 +295,5 @@ def build(db: Session, semester_id: int, on: date, weeks: int = 1) -> TeacherWee if week.rows: result.weeks.append(week) if not result.weeks: - raise TeacherWeekError("這段期間沒有任何課(可能是假日、不在學期內,或課表尚未排入)") + raise TeacherWeekError("這段期間沒有任何課(可能是假日、停課、不在學期內,或課表尚未排入)") return result diff --git a/backend/app/services/timetable_week.py b/backend/app/services/timetable_week.py index d8792a7b..75776f89 100644 --- a/backend/app/services/timetable_week.py +++ b/backend/app/services/timetable_week.py @@ -70,6 +70,8 @@ def _note(x: _Lesson) -> str: extra = [f"原:{x.original}"] if x.original and x.teacher != x.original else [] if x.swap_with: extra.append(f"與 {x.swap_with}對調") + if x.reason: + extra.append(x.reason) # 停課的說明「校慶補假」(v1.4.19) return f"{x.note}({','.join(extra)})" if extra else x.note diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py index 307b94cd..a3ad005a 100644 --- a/backend/tests/conftest.py +++ b/backend/tests/conftest.py @@ -30,6 +30,7 @@ substitution_log, substitution_stats, substitutions, + suspensions, system, timetables, users, @@ -96,6 +97,7 @@ def override_get_db(): application.include_router(homeroom_covers.router, prefix="/api") application.include_router(substitution_log.router, prefix="/api") application.include_router(substitution_stats.router, prefix="/api") + application.include_router(suspensions.router, prefix="/api") application.include_router(notifications.router, prefix="/api") application.include_router(settings_api.router, prefix="/api") application.include_router(backups.router, prefix="/api") diff --git a/backend/tests/test_suspensions_v1419.py b/backend/tests/test_suspensions_v1419.py new file mode 100644 index 00000000..4ac912ee --- /dev/null +++ b/backend/tests/test_suspensions_v1419.py @@ -0,0 +1,223 @@ +"""停課日(v1.4.19,組長回報:「停課日在哪邊可以設定?」)。 + +全校、年級或指定班級,整天或第幾節到第幾節不上課。停課的課: +請假時不列為受影響節次、整天停課不必代導、不能拿來調課補課; +巡堂表、週課表、教師週總表標「停課」,全校整天停課的日子巡堂表略過。 +""" + +from datetime import timedelta + +from app.models.user import Role +from app.services import suspensions as suspension_service +from tests.conftest import make_user +from tests.dates import WED +from tests.test_homeroom_cover import _homeroom +from tests.test_substitutions import _options, _World, env2 # noqa: F401 - env2 為 fixture + +PW = "password123" +THU = WED + timedelta(days=1) + + +def _suspend(w: _World, day=WED, end=None, *, classes=None, lo=None, hi=None, reason="校慶補假"): + body = { + "start_date": day.isoformat(), "end_date": (end or day).isoformat(), + "whole_school": classes is None, + "class_ids": [w.classes[c] for c in (classes or [])], + "all_day": lo is None, "from_ordinal": lo, "to_ordinal": hi, "reason": reason, + } + r = w.client.post(f"/api/suspensions{w.q}", json=body) + assert r.status_code == 201, r.json() + return r.json() + + +def _week(w, view, target, day=WED): + r = w.client.get(f"/api/published/week{w.q}&view={view}&target_id={target}" + f"&on={day.isoformat()}") + assert r.status_code == 200, r.json() + return r.json() + + +def _at(body, day, ordinal): + return [(c["subject"], c["teacher"], c["kind"], c["note"]) for c in body["cells"] + if c["date"] == day.isoformat() and c["ordinal"] == ordinal] + + +def test_settings_describe_target_and_periods(env2): # noqa: F811 + w = env2 + w.klass("701") + w.klass("702") + w.classes["801"] = w.client.post(f"/api/class-units{w.q}", json={ + "grade": 8, "name": "801", "track": "junior_high"}).json()["id"] + school = _suspend(w)["item"] + assert (school["target_text"], school["period_text"]) == ("全校", "整天") + grade = _suspend(w, classes=["701", "702", "900"], lo=5, hi=7, reason="探索活動")["item"] + assert (grade["target_text"], grade["period_text"]) == ("七年級", "第 5~7 節") + some = _suspend(w, classes=["701", "801"], lo=3)["item"] + # 八年級只有 801 一班:勾了就是整個八年級 + assert (some["target_text"], some["period_text"]) == ("701、八年級", "第 3 節") + + listed = w.client.get(f"/api/suspensions{w.q}").json() + assert [x["id"] for x in listed] == [school["id"], grade["id"], some["id"]] + + r = w.client.put(f"/api/suspensions/{some['id']}", json={ + "start_date": THU.isoformat(), "end_date": THU.isoformat(), "whole_school": False, + "class_ids": [w.classes["801"]], "all_day": True, "reason": "戶外教學"}) + assert r.status_code == 200, r.json() + assert r.json()["item"]["target_text"] == "八年級" + assert w.client.delete(f"/api/suspensions/{some['id']}").status_code == 204 + assert len(w.client.get(f"/api/suspensions{w.q}").json()) == 2 + + +def test_invalid_settings_are_explained(env2): # noqa: F811 + w = env2 + w.klass("701") + + def post(**over): + body = {"start_date": WED.isoformat(), "end_date": WED.isoformat(), + "whole_school": True, "class_ids": [], "all_day": True, "reason": ""} + body.update(over) + return w.client.post(f"/api/suspensions{w.q}", json=body) + + assert "早於" in post(end_date=(WED - timedelta(days=1)).isoformat()).json()["detail"] + assert "班級" in post(whole_school=False).json()["detail"] + assert "學期期間" in post(end_date=(WED + timedelta(days=170)).isoformat()).json()["detail"] + assert "第幾節" in post(all_day=False).json()["detail"] + assert "節次" in post(all_day=False, from_ordinal=5, to_ordinal=3).json()["detail"] + + # 老師看得到停課,不能設定 + make_user(w.db, "t", PW, roles=[Role.teacher]) + w.client.post("/api/auth/login", json={"username": "t", "password": PW}) + assert w.client.get(f"/api/suspensions{w.q}").status_code == 200 + assert post().status_code == 403 + + +def test_leave_on_suspended_periods_needs_no_substitute(env2): # noqa: F811 + w = env2 + w.teacher("王師", ["國文"]) + w.place("王師", "國文", "701", 0) # 第 1 節 + w.place("王師", "國文", "701", 4) # 第 5 節 + w.place("王師", "國文", "702", 5) # 第 6 節,702 照常上課 + w.publish() + _suspend(w, classes=["701"], lo=5, hi=7, reason="探索活動") + + r = w.client.post(f"/api/leaves{w.q}", json={ + "teacher_id": w.teachers["王師"], "leave_type": "sick", + "start_date": WED.isoformat(), "end_date": WED.isoformat()}) + assert r.status_code == 201, r.json() + body = r.json() + assert [(p["class_names"], p["period_name"]) for p in body["affected_periods"]] == [ + ("701", "第一節"), ("702", "第六節")] + assert [(s["period_name"], s["taken_by"]) for s in body["skipped"]] == [ + ("第五節", "停課(探索活動)")] + + +def test_whole_day_suspension_needs_no_homeroom_cover(env2): # noqa: F811 + w = env2 + w.teacher("王師", ["國文"]) + _homeroom(w, "701", "王師") + w.place("王師", "國文", "701", 0) + w.publish() + _suspend(w, classes=["701"]) # 701 週三整天停課 + _suspend(w, THU, classes=["701"], lo=1, hi=2) # 週四只停兩節:還是要代導 + r = w.client.post(f"/api/leaves{w.q}", json={ + "teacher_id": w.teachers["王師"], "leave_type": "personal", + "start_date": WED.isoformat(), "end_date": THU.isoformat()}) + assert r.status_code == 201, r.json() + assert [c["date"] for c in r.json()["homeroom_covers"]] == [THU.isoformat()] + + +def test_group_lesson_still_runs_when_only_one_class_is_off(env2): # noqa: F811 + """合班、跑班:還有一個班要上課,老師就要去——每一個班都停課才算停課。""" + w = env2 + w.klass("701") + w.klass("702") + _suspend(w, classes=["701"]) + cal = suspension_service.Calendar(w.db, w.sid, WED, WED) + assert cal.for_classes([w.classes["701"]], WED, 1) is not None + assert cal.for_classes([w.classes["701"], w.classes["702"]], WED, 1) is None + _suspend(w, classes=["702"]) + cal = suspension_service.Calendar(w.db, w.sid, WED, WED) + assert cal.for_classes([w.classes["701"], w.classes["702"]], WED, 1) is not None + assert cal.for_classes([], WED, 1) is None + + +def test_suspended_period_cannot_be_used_for_a_swap(env2): # noqa: F811 + w = env2 + w.teacher("王師", ["國文"]) + w.teacher("陳師", ["數學"]) + w.place("王師", "國文", "701", 0) + w.place("陳師", "數學", "701", 1, weekday=4) # 週四第 2 節 + w.publish() + affected = w.leave("王師") + _suspend(w, THU, classes=["701"], lo=2, reason="戶外教學") + + partner = _options(w, affected[0]["id"], "陳師")["partners"][0] + thu = [o for o in partner["options"] + partner["blocked"] if o["date"] == THU.isoformat()] + assert len(thu) == 1 and thu[0] in partner["blocked"] + assert "停課(戶外教學)" in thu[0]["blocked_reason"] + code, body = w.assign(affected[0]["id"], type="swap", handler_teacher_id=w.teachers["陳師"], + swap_entry_id=thu[0]["entry_id"], swap_date=thu[0]["date"], + swap_period_no=thu[0]["period_no"]) + assert code in (400, 409), body + assert "停課" in str(body) + + +def test_week_views_and_sheets_mark_suspended_lessons(env2): # noqa: F811 + w = env2 + w.teacher("王師", ["國文"]) + w.place("王師", "國文", "701", 0) + w.place("王師", "國文", "702", 1) + w.publish() + _suspend(w, classes=["701"], reason="探索活動") + + cls = _week(w, "class", w.classes["701"]) + assert _at(cls, WED, 1) == [("國文", "王師", "off", "停課(探索活動)")] + teacher = _week(w, "teacher", w.teachers["王師"]) + assert _at(teacher, WED, 1) == [("701 國文", "", "off", "停課(探索活動)")] + assert _at(teacher, WED, 2) == [("702 國文", "", "normal", "")] + + patrol = w.client.get(f"/api/patrol-sheets{w.q}&date_from={WED.isoformat()}").json() + morning = next(p for p in patrol["pages"] if "701" in p["classes"]) + first = morning["rows"][0]["cells"] + assert first[morning["classes"].index("701")]["note"] == "停課" + + +def test_whole_school_day_off_is_left_out_of_the_sheets(env2): # noqa: F811 + w = env2 + w.teacher("王師", ["國文"]) + w.place("王師", "國文", "701", 0) + w.place("王師", "國文", "701", 0, weekday=4) + w.publish() + _suspend(w) + + patrol = w.client.get( + f"/api/patrol-sheets{w.q}&date_from={WED.isoformat()}&date_to={THU.isoformat()}").json() + assert {p["date"] for p in patrol["pages"]} == {THU.isoformat()} + only_wed = w.client.get(f"/api/patrol-sheets{w.q}&date_from={WED.isoformat()}") + assert only_wed.status_code in (400, 404) and "停課" in only_wed.json()["detail"] + + sheets = w.client.get( + f"/api/teacher-week-sheets{w.q}&date_from={WED.isoformat()}&weeks=1").json() + assert WED.isoformat() not in {r["date"] for wk in sheets["weeks"] for r in wk["rows"]} + assert THU.isoformat() in {r["date"] for wk in sheets["weeks"] for r in wk["rows"]} + + +def test_existing_arrangements_are_listed_when_suspending(env2): # noqa: F811 + """停課是事後才設的:之前排好的不自動改(可能已經通知老師),列出來讓組長處理。""" + w = env2 + w.teacher("王師", ["國文"]) + w.teacher("陳師", ["國文"]) + w.place("王師", "國文", "701", 0) + w.publish() + affected = w.leave("王師") + w.assign(affected[0]["id"], type="substitute", handler_teacher_id=w.teachers["陳師"]) + + saved = _suspend(w, classes=["701"]) + md = f"{WED.month}/{WED.day}" + assert saved["conflicts"] == [f"{md} 第一節 701 國文:王師 病假"] + # 畫面上以停課為準 + assert _at(_week(w, "class", w.classes["701"]), WED, 1) == [ + ("國文", "王師", "off", "停課(校慶補假)")] + # 別班停課不相干 + w.klass("702") + assert _suspend(w, classes=["702"])["conflicts"] == [] diff --git a/docs/architecture.html b/docs/architecture.html index a0e7f742..10cd3544 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -771,6 +771,11 @@

2.2 核心實體定義

類型:substitute(代課)/swap(調課)/merge(併班)/self_study(自習)/cancel(不處理);代課教師、是否計鐘點、經費來源標記。調課另記補課那一節:swap_date、swap_period_no、swap_entry_id(已發布課表的格子)。格子屬於某一份課表,學期中重新發布時新課表每一格都是新的一列,所以發布時要把這學期的調課接到新課表「同一配課、同一星期、涵蓋該節」的格子(services/swap_relink.py,v1.4.18);接不上(那堂課被搬走)的維持原樣,發布回傳 swap_unlinked 提醒組長重排。週課表、巡堂表、調課清單都以 swap_entry_id 比對已發布課表,沒接上就畫不出補課那一節、也可能重複調課。遷移 0020 只改資料:把升級前已發生的接回目前已發布的課表 + class_suspension + 停課日(v1.4.19,遷移 0021) + 起訖日期、對象(whole_school,或經 class_suspension_classes 指定班級;畫面上勾年級 = 勾整個年級的班)、範圍(from_ordinal~to_ordinal:第幾節,只數一般課,依各班自己的節次表換算;兩個都空 = 整天)、說明。判斷集中在 services/suspensions.py:一門課的每一個班都停課才算停課(合班、跑班還有一班要上,老師就要去)。效果:請假展開時不列受影響節次(回傳 skipped「停課(…)」)、整天停課的班不產生代導、調課清單不能拿停課的那一節補課;patrol_sheets.Day 把停課的課標「停課」並優先於當天的調代課,全校整天停課的日子巡堂表與教師週總表略過。停課是事後設的,之前已安排的調代課不自動改(可能已通知老師),儲存時回傳 conflicts 讓組長自行撤回或改成「不處理」 + + notification 通知 站內+Email(v2 經 channel adapter 加 LINE/webhook);類型、收件人、已讀狀態 diff --git a/docs/architecture.md b/docs/architecture.md index 5aa611bf..458299d8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -197,6 +197,7 @@ erDiagram | `affected_period` | 受影響節次 | 請假展開後的每一節課;狀態機見 §5.3 | | `homeroom_cover` | **代導**(v1.4.0,遷移 0019) | 導師請假時,依「他帶的班 × 請假期間的上課日」各一列(`uq(leave_request_id, class_name, date)`),**與課表無關**——當天沒課也要有人帶班。快照:班名、年級;該日請假時段 `from_time`/`to_time`(兩端皆空 = 全天,否則為半天,顯示為上午/下午);狀態沿用 `affected_period` 的待處理/已確認/已取消(已完成為讀取時推導:那天過完);`no_cover`(不需代導)、代導教師 `handler_teacher_id`。人選不檢查課務(有課也能代導),只排除當天整天請假者。月結只記全天/半天天數,不計算代導費 | | `substitution` | 調代課處置 | 類型:`substitute`(代課)/`swap`(調課)/`merge`(併班)/`self_study`(自習)/`cancel`(不處理);代課教師、是否計鐘點、經費來源標記。調課另記補課那一節:`swap_date`、`swap_period_no`、`swap_entry_id`(**已發布課表的格子**)。格子屬於某一份課表,學期中重新發布時新課表每一格都是新的一列,所以**發布時要把這學期的調課接到新課表**「同一配課、同一星期、涵蓋該節」的格子(`services/swap_relink.py`,v1.4.18);接不上(那堂課被搬走)的維持原樣,發布回傳 `swap_unlinked` 提醒組長重排。週課表、巡堂表、調課清單都以 `swap_entry_id` 比對已發布課表,沒接上就畫不出補課那一節、也可能重複調課。遷移 0020 只改資料:把升級前已發生的接回目前已發布的課表 | +| `class_suspension` | **停課日**(v1.4.19,遷移 0021) | 起訖日期、對象(`whole_school`,或經 `class_suspension_classes` 指定班級;畫面上勾年級 = 勾整個年級的班)、範圍(`from_ordinal`~`to_ordinal`:第幾節,只數一般課,依各班自己的節次表換算;兩個都空 = 整天)、說明。判斷集中在 `services/suspensions.py`:**一門課的每一個班都停課才算停課**(合班、跑班還有一班要上,老師就要去)。效果:請假展開時不列受影響節次(回傳 `skipped`「停課(…)」)、整天停課的班不產生代導、調課清單不能拿停課的那一節補課;`patrol_sheets.Day` 把停課的課標「停課」並**優先於當天的調代課**,全校整天停課的日子巡堂表與教師週總表略過。停課是事後設的,之前已安排的調代課**不自動改**(可能已通知老師),儲存時回傳 `conflicts` 讓組長自行撤回或改成「不處理」 | | `notification` | 通知 | 站內+Email(v2 經 channel adapter 加 LINE/webhook);類型、收件人、已讀狀態 | | `user` / `user_role` | 帳號與角色 | 本地帳密(bcrypt);角色:admin / director(教務主任)/ scheduler(教學組長)/ teacher | | `audit_log` | 操作軌跡 | 誰在何時改了什麼(排課異動、調代課指派必記) | diff --git a/docs/deploy/upgrade.html b/docs/deploy/upgrade.html index 46e34b43..201673e2 100644 --- a/docs/deploy/upgrade.html +++ b/docs/deploy/upgrade.html @@ -172,7 +172,7 @@ 路線圖開發用 開發任務卡開發用 -
本頁目錄
+
本頁目錄
@@ -190,6 +190,10 @@

升級指南

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

+

升級到 v1.4.19:新增停課日用的資料表

+

v1.4.19 新增「停課日」用的兩張資料表,既有的資料表與資料都不動。和 v1.4.0 一樣,api 容器發現資料庫結構 + 需要升級時,會先自動備份一次再升級,照下方方式 A 或方式 B 一般升級即可。升級前已登記的請假不會因此改變; + 之後設定停課時,系統會列出那段時間已經安排的調代課,由組長自行處理。

升級到 v1.4.2 ~ v1.4.18:補登、修改假別與計費方式、未請假的調課、批次 PDF、登入鎖定資安修正

v1.4.2(補登)、v1.4.3(操作紀錄修正)、v1.4.4(修改假別與計費方式)、v1.4.5(未請假的調課)、v1.4.6(全校課表匯出 PDF)、v1.4.7(登入鎖定資安修正,建議升級)、v1.4.8(自動排課自動建立草稿)、v1.4.9(同一天幾節一起調課)、v1.4.10(補登調課)、v1.4.11(鐘點統計自訂區間)、v1.4.12(調課從較早的週開始找、換不了的原因)、v1.4.13(跑班群組在班級課表的顯示)、v1.4.14(全校教師週總表)、v1.4.15(某一週實際課表、新增假別)、v1.4.16(跑班顯示、先調課再請假)、v1.4.17(調課寫出補課日期)、v1.4.18(重新發布後調課接到新課表;升級時會自動修正既有調課的資料,不改資料表)都沒有資料表變更,照下方方式 A 或方式 B 一般升級即可。

升級到 v1.4.1:授權改為 AGPL-3.0

@@ -257,6 +261,16 @@

退回舊版(升級後發現問題)

⚠️ 注意資料庫遷移方向:若新版本引入了資料表結構變更,退回舊映像後其程式可能不認得新結構。最保險的退回方式是:退回舊映像 + 還原「升級前那份備份」(見備份指南的還原流程)。若該次升級的 CHANGELOG 未標註 schema 變更,則單純換映像即可。

+

從 v1.4.19 退回 v1.4.18

+

v1.4.19 新增了停課日的資料表,直接把版本號改回 v1.4.18,舊版會啟動失敗。兩種退回方式擇一:

+
    +
  • 方式一:用升級前自動備份還原——做法同下方「從 v1.3.0 退回 v1.2.x」的方式一。升級後才登記的請假、調代課、停課不會保留。
  • +
  • 方式二:退回指令(資料保留,只移除停課日)——在 docker-compose.yml 所在資料夾,先以 v1.4.19 執行:
  • +
+

bash + docker compose run --rm --entrypoint alembic api downgrade 0020_relink_swaps

+

這會移除停課日的資料表(設定的停課會一併刪除),課表、請假、代課等其他資料都不動。 + 接著把 .env 的 IMAGE_TAG 改回 v1.4.18,執行 docker compose pull 與 docker compose up -d。

從 v1.4.0 退回 v1.3.x

v1.4.0 改了資料表結構,直接把版本號改回 v1.3.x,舊版會啟動失敗。兩種退回方式擇一:

    diff --git a/docs/deploy/upgrade.md b/docs/deploy/upgrade.md index c4aaf59c..102b7697 100644 --- a/docs/deploy/upgrade.md +++ b/docs/deploy/upgrade.md @@ -8,6 +8,12 @@ > **開始前先備份。** 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見[備份指南](backup.md)。 +## 升級到 v1.4.19:新增停課日用的資料表 + +v1.4.19 新增「停課日」用的兩張資料表,**既有的資料表與資料都不動**。和 v1.4.0 一樣,`api` 容器發現資料庫結構 +需要升級時,**會先自動備份一次再升級**,照下方方式 A 或方式 B 一般升級即可。升級前已登記的請假不會因此改變; +之後設定停課時,系統會列出那段時間已經安排的調代課,由組長自行處理。 + ## 升級到 v1.4.2 ~ v1.4.18:補登、修改假別與計費方式、未請假的調課、批次 PDF、登入鎖定資安修正 v1.4.2(補登)、v1.4.3(操作紀錄修正)、v1.4.4(修改假別與計費方式)、v1.4.5(未請假的調課)、v1.4.6(全校課表匯出 PDF)、v1.4.7(登入鎖定資安修正,**建議升級**)、v1.4.8(自動排課自動建立草稿)、v1.4.9(同一天幾節一起調課)、v1.4.10(補登調課)、v1.4.11(鐘點統計自訂區間)、v1.4.12(調課從較早的週開始找、換不了的原因)、v1.4.13(跑班群組在班級課表的顯示)、v1.4.14(全校教師週總表)、v1.4.15(某一週實際課表、新增假別)、v1.4.16(跑班顯示、先調課再請假)、v1.4.17(調課寫出補課日期)、v1.4.18(重新發布後調課接到新課表;升級時會自動修正既有調課的資料,不改資料表)都沒有資料表變更,照下方方式 A 或方式 B 一般升級即可。 @@ -106,6 +112,20 @@ docker compose up -d > ⚠️ **注意資料庫遷移方向**:若新版本引入了資料表結構變更,退回舊映像後其程式可能不認得新結構。**最保險的退回方式是:退回舊映像 + 還原「升級前那份備份」**(見[備份指南](backup.md)的還原流程)。若該次升級的 CHANGELOG 未標註 schema 變更,則單純換映像即可。 +### 從 v1.4.19 退回 v1.4.18 + +v1.4.19 新增了停課日的資料表,**直接把版本號改回 v1.4.18,舊版會啟動失敗**。兩種退回方式擇一: + +- **方式一:用升級前自動備份還原**——做法同下方「從 v1.3.0 退回 v1.2.x」的方式一。升級後才登記的請假、調代課、停課不會保留。 +- **方式二:退回指令(資料保留,只移除停課日)**——在 `docker-compose.yml` 所在資料夾,**先以 v1.4.19 執行**: + + ```bash + docker compose run --rm --entrypoint alembic api downgrade 0020_relink_swaps + ``` + + 這會移除停課日的資料表(設定的停課會一併刪除),課表、請假、代課等其他資料都不動。 + 接著把 `.env` 的 `IMAGE_TAG` 改回 v1.4.18,執行 `docker compose pull` 與 `docker compose up -d`。 + ### 從 v1.4.0 退回 v1.3.x v1.4.0 改了資料表結構,**直接把版本號改回 v1.3.x,舊版會啟動失敗**。兩種退回方式擇一: diff --git a/docs/features.html b/docs/features.html index 7500d45d..e1115799 100644 --- a/docs/features.html +++ b/docs/features.html @@ -3,7 +3,7 @@ - + 功能總覽 · 排課與調代課系統 diff --git a/frontend/src/views/substitution/suspensionText.test.ts b/frontend/src/views/substitution/suspensionText.test.ts new file mode 100644 index 00000000..8e9725f4 --- /dev/null +++ b/frontend/src/views/substitution/suspensionText.test.ts @@ -0,0 +1,30 @@ +import { describe, expect, it } from 'vitest' +import type { ClassUnit } from '@/api/basedata' +import { dateRangeText, gradeGroups } from './suspensionText' + +function klass(id: number, name: string, grade: number, track: ClassUnit['track'] = 'junior_high'): ClassUnit { + return { + id, name, grade, track, semester_id: 1, department: null, student_count: null, + homeroom_teacher_id: null, homeroom_teacher: null, period_table_id: null, + } +} + +describe('停課對象的年級分組', () => { + it('依年級分組,年級小的在前', () => { + const groups = gradeGroups([klass(3, '801', 8), klass(1, '702', 7), klass(2, '701', 7)]) + expect(groups.map((g) => g.label)).toEqual(['七年級', '八年級']) + expect(groups[0].classes.map((c) => c.name)).toEqual(['701', '702']) + }) + + it('國中小並存時寫出學制', () => { + const groups = gradeGroups([klass(1, '101', 1, 'elementary'), klass(2, '701', 7)]) + expect(groups.map((g) => g.label)).toEqual(['國小一年級', '國中七年級']) + }) +}) + +describe('停課日期', () => { + it('一天、一段期間', () => { + expect(dateRangeText('2026-11-20', '2026-11-20')).toBe('11/20(五)') + expect(dateRangeText('2026-11-20', '2026-11-24')).toBe('11/20(五)~11/24(二)') + }) +}) diff --git a/frontend/src/views/substitution/suspensionText.ts b/frontend/src/views/substitution/suspensionText.ts new file mode 100644 index 00000000..d0f6247d --- /dev/null +++ b/frontend/src/views/substitution/suspensionText.ts @@ -0,0 +1,45 @@ +// 停課日頁的文字與年級分組(v1.4.19) + +import { TRACK_LABELS } from '@/api/basedata' +import type { ClassUnit } from '@/api/basedata' + +const DIGITS = '零一二三四五六七八九十' + +export interface GradeGroup { + key: string + label: string // 「七年級」;國中小並存時「國中七年級」 + classes: ClassUnit[] +} + +/** 班級依學制、年級分組(畫面上一次勾整個年級);年級小的在前。 */ +export function gradeGroups(classes: ClassUnit[]): GradeGroup[] { + const tracks = new Set(classes.map((c) => c.track)) + const map = new Map() + const sorted = [...classes].sort((a, b) => a.grade - b.grade || a.name.localeCompare(b.name)) + for (const c of sorted) { + const key = `${c.track}-${c.grade}` + if (!map.has(key)) { + const grade = c.grade >= 0 && c.grade <= 10 ? DIGITS[c.grade] : String(c.grade) + const prefix = tracks.size > 1 ? TRACK_LABELS[c.track] ?? '' : '' + map.set(key, { key, label: `${prefix}${grade}年級`, classes: [] }) + } + map.get(key)!.classes.push(c) + } + return [...map.values()] +} + +function md(iso: string): string { + const [, m, d] = iso.split('-').map(Number) + return `${m}/${d}` +} + +const WEEKDAYS = ['日', '一', '二', '三', '四', '五', '六'] + +/** 「11/20(五)」或「11/20(五)~11/24(二)」 */ +export function dateRangeText(start: string, end: string): string { + const one = (iso: string) => { + const [y, m, d] = iso.split('-').map(Number) + return `${md(iso)}(${WEEKDAYS[new Date(y, m - 1, d).getDay()]})` + } + return start === end ? one(start) : `${one(start)}~${one(end)}` +}