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)}`
+}