diff --git a/.env.example b/.env.example
index a492df3..68a74ed 100644
--- a/.env.example
+++ b/.env.example
@@ -32,7 +32,7 @@ HTTP_PORT=80
# ── 預建映像版本(僅「拉取映像」部署方式需要)──────────
# 用 docker compose pull 拉官方映像時,決定要拉哪一版。
# 預設 latest(最新);正式部署建議釘選版本號以利可控升級,例如:
-# IMAGE_TAG=v1.4.20
+# IMAGE_TAG=v1.4.21
# 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。
IMAGE_TAG=latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 447b93e..be1b7cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,10 +4,32 @@
破壞性變更(需人工介入才能升級)以 ⚠️ 標註。
-> **新使用者請直接安裝 v1.4.20**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.19 是先前版本;以下條目保留作為變更紀錄。
+> **新使用者請直接安裝 v1.4.21**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.20 是先前版本;以下條目保留作為變更紀錄。
## [Unreleased]
+## [1.4.21] — 2026-11-18
+
+**三角調課可以指定老師,湊不成時寫出原因**(組長回報:三角調課的清單裡找不到某位老師)。
+
+組長心裡已經有一組換法,清單裡卻一組都沒有那位老師。系統其實是對的——請假的老師另一班的課已經先調好,
+補課剛好排在那個時段,不能再回來上那位老師的課;但清單只列換得成的組合,組長看不出卡在哪裡。
+
+沒有資料表變更,照一般方式升級即可(`.env` 改 `IMAGE_TAG=v1.4.21` → `docker compose pull && docker compose up -d`)。
+
+官方映像(amd64 + arm64 雙架構)已發布於 GHCR:
+`ghcr.io/begin0808/course_scheduling_system-{api,worker,web}:v1.4.21`
+
+### 新增
+- **三角調課「指定老師」**:選這個班的一位老師,清單**只列有他的組合**(不受 200 組的上限截斷),
+ 並逐節寫出他**其他節次為什麼湊不成**,分兩種位置:
+ - 當 ①(來上請假那一節、讓出自己的一節):例如「不能來上請假那一節 11/25(週三) 第一節:陳師這節自己有課(703 英語)」。
+ - 當 ②(來上別人讓出的一節、請假的老師回來上他的課):例如「王師回來上陳師的 11/26(週四) 第二節 數學:王師已被安排回 702 國文 調課補課」。
+- 三角調課清單下方提示:找不到想要的老師,可以在「指定老師」選他。
+
+### 改善
+- 「已被安排代其他課」改寫出是哪一班:「已被安排代 702 國文」「已被安排回 702 國文 調課補課」「已被安排去 701 數學 三角調課」。調課清單、三角調課、代課指派的原因都適用。
+
## [1.4.20] — 2026-11-18
**新功能:三角調課**(組長拿別家系統的畫面來問:「會出三角調課嗎?」)。
diff --git a/README.md b/README.md
index 5fad7e8..2eb63f9 100644
--- a/README.md
+++ b/README.md
@@ -132,11 +132,11 @@ docker compose up -d # 首次會建置映像,需數分鐘
## 專案狀態
-**v1.4.20 已發行(2026-11-18)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 804 項單元/整合測試、63 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
+**v1.4.21 已發行(2026-11-18)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 808 項單元/整合測試、63 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
-v1.4.20 新增**三角調課**(同一班三位老師輪流換課,列出可行的三人組合;三位老師與班級各有調課單,撤回一起撤);v1.4.19 新增**停課日**(全校、年級或班級,整天或第幾節到第幾節;請假不必代課、不能拿來調課補課,巡堂表與週課表標停課);v1.4.18 修正調課後**重新發布課表**時補課那一節消失的問題;v1.4.17 調代課紀錄與某一週的班級課表,調課**寫出對調的另一節在哪一天**;v1.4.16 跑班 5 組以內在班級課表**列出每位老師**,先調課再請假時已調走的節次**不再重複列出**;v1.4.15 課表查詢可以**看某一週實際的課表**(含調代課,異動標色),並新增身心調適假等常用假別;v1.4.14 新增**全校教師週總表**(老師為欄、標出這週的調代課,可列印或匯出 Excel);v1.4.13 修正跑班群組在班級課表只顯示一位老師(同一格改列出每一組);v1.4.12 調課可以**從較早的週開始找**(老師提早請假、想先補課),換不了的節次會**寫出原因**,代導半天改以「次」計;v1.4.11「代課鐘點統計」可以**自訂統計區間**(每月 15 日結算的學校可選 10/16~11/15);v1.4.10 已經上過的調課可以**事後補登**(「新增調課(未請假)」勾已經上過的節次;不通知老師),調代課紀錄也能篩出「調課(未請假)」,查老師多常換課;v1.4.9 同一天好幾節要一起換(例如學校活動讓兩班的第七、八節同時對調)也**調得成**了;v1.4.8 新學期第一次進「自動排課」會**自動建立草稿**,配完課就能直接排;v1.4.7 **資安修正**:登入失敗鎖定不會再被「同時送出」繞過(建議升級);v1.4.6 全校總表與批次 zip 都可以**匯出 PDF**;v1.4.5 老師**沒請假也能調課**(調代課處理的「新增調課」);v1.4.4 登記後可以**修改假別與計費方式**(已經上過的代課也可以改計費方式),請假的假別改成一定要選;v1.4.3 修正安排代導時操作紀錄沒寫出老師名字;v1.4.2 可以**補登**事後才登記的請假(已經過去的節次補登代課,不通知老師、列入鐘點統計);v1.4.1 起改採 **AGPL-3.0 授權**(見下方「授權」;功能與資料都沒有變動);v1.4.0 新增**代導**(導師請假當天由誰代他帶班,當天沒課也算、半天也算;可印代導通知單,月結分開記全天與半天天數;⚠️ 資料表結構變更,升級前會自動備份);v1.3.5 修正**併班**選不到老師(改列出這一節正在上課的老師),調課單加上記號說明;v1.3.4 讓跑班群組、導師、任教科目等下拉選單都能**打字搜尋**;v1.3.3 的儀表板新增**即時概況**(現在這一節各班在上什麼課、誰在上,已套用當天的調代課);v1.3.2 新增**重設管理員密碼**的指令(忘了密碼或第一次就登不進去時,不必刪資料或還原備份);v1.3.1 新增**帳號管理**(系統管理員可設定教學組長、教務主任的帳號);v1.3.0 支援**單雙週課程**(同一節單週、雙週輪流上不同的課,排課、請假代課、調課、巡堂表、鐘點都分單雙週;⚠️ 首次改動資料表結構,升級前請先備份);v1.2.19 支援**日薪代課**(國小常見:月結統計把鐘點與日薪分開列)並可**整批指派代課**(整張假單或整天一次派給同一位老師);v1.2.18 可**檢查課表**(發布前列出衝堂、教師不可排時段等衝突;事後修改不可排時段時當場提示已排的課);v1.2.17 修正登入按一次送出兩筆請求(輸錯密碼約第 3 次就被鎖定);v1.2.15、v1.2.16 修正跑班群組的兩個問題(同一位老師在群組裡重複配課時自動排課會排出撞課的課表;同一格有多筆同科目配課時,手動排課把每日節數重複計算);v1.2.12~v1.2.14 可列印**巡堂表**並匯出 Excel(依當天的調代課結果產生,社團另出分組巡堂單);v1.2.10、v1.2.11 讓**國中小、完全中學**跨部上課的老師,課表與通知單都標出實際上課時間,兩部節數不同(國中七節、高中八節)也不會漏課;v1.2.9 可一次匯出**全校教師課表**(總表與批次打包);v1.2.8 可用 Excel **批次更新既有教師**(新學年職務異動),並能**停用/啟用教師登入帳號**(離職教師保留歷史紀錄又進不來);v1.2.7 補上**學期起訖日期**的填寫與修改(先前畫面上無處可填,導致請假被擋);v1.2.6 修掉第一批外部使用者回報的三個問題(教師帳號首次登入卡死、無法事後補開教師帳號、未排課務清單過長時拖不動),並可在畫面上自行修改與重設密碼;v1.2.5 可列印**教師代課通知單與班級代課通知單**(照學校紙本格式,代課時可選計費方式);v1.2.4 的調代課處理會寫出處置方式(代課或調課、哪天補課);v1.2.3 起系統會顯示目前版本,並在有新版時提醒系統管理員(只提醒、不自動升級);v1.2.2 可列印**教師調課通知單與班級調課通知單**(照學校紙本格式);v1.2.1 補上**調課**的操作畫面——請假(含研習)的節次可直接列出雙方都有空的對調節次,支援跨週(最多四週)與連堂,補課日也會出現在今日看板。v1.2.0 起另有**一鍵示範資料**,裝好後兩分鐘內就能看到一張排好的全校課表。
+v1.4.21 三角調課可以**指定老師**,湊不成時寫出卡在哪一節、為什麼;v1.4.20 新增**三角調課**(同一班三位老師輪流換課,列出可行的三人組合;三位老師與班級各有調課單,撤回一起撤);v1.4.19 新增**停課日**(全校、年級或班級,整天或第幾節到第幾節;請假不必代課、不能拿來調課補課,巡堂表與週課表標停課);v1.4.18 修正調課後**重新發布課表**時補課那一節消失的問題;v1.4.17 調代課紀錄與某一週的班級課表,調課**寫出對調的另一節在哪一天**;v1.4.16 跑班 5 組以內在班級課表**列出每位老師**,先調課再請假時已調走的節次**不再重複列出**;v1.4.15 課表查詢可以**看某一週實際的課表**(含調代課,異動標色),並新增身心調適假等常用假別;v1.4.14 新增**全校教師週總表**(老師為欄、標出這週的調代課,可列印或匯出 Excel);v1.4.13 修正跑班群組在班級課表只顯示一位老師(同一格改列出每一組);v1.4.12 調課可以**從較早的週開始找**(老師提早請假、想先補課),換不了的節次會**寫出原因**,代導半天改以「次」計;v1.4.11「代課鐘點統計」可以**自訂統計區間**(每月 15 日結算的學校可選 10/16~11/15);v1.4.10 已經上過的調課可以**事後補登**(「新增調課(未請假)」勾已經上過的節次;不通知老師),調代課紀錄也能篩出「調課(未請假)」,查老師多常換課;v1.4.9 同一天好幾節要一起換(例如學校活動讓兩班的第七、八節同時對調)也**調得成**了;v1.4.8 新學期第一次進「自動排課」會**自動建立草稿**,配完課就能直接排;v1.4.7 **資安修正**:登入失敗鎖定不會再被「同時送出」繞過(建議升級);v1.4.6 全校總表與批次 zip 都可以**匯出 PDF**;v1.4.5 老師**沒請假也能調課**(調代課處理的「新增調課」);v1.4.4 登記後可以**修改假別與計費方式**(已經上過的代課也可以改計費方式),請假的假別改成一定要選;v1.4.3 修正安排代導時操作紀錄沒寫出老師名字;v1.4.2 可以**補登**事後才登記的請假(已經過去的節次補登代課,不通知老師、列入鐘點統計);v1.4.1 起改採 **AGPL-3.0 授權**(見下方「授權」;功能與資料都沒有變動);v1.4.0 新增**代導**(導師請假當天由誰代他帶班,當天沒課也算、半天也算;可印代導通知單,月結分開記全天與半天天數;⚠️ 資料表結構變更,升級前會自動備份);v1.3.5 修正**併班**選不到老師(改列出這一節正在上課的老師),調課單加上記號說明;v1.3.4 讓跑班群組、導師、任教科目等下拉選單都能**打字搜尋**;v1.3.3 的儀表板新增**即時概況**(現在這一節各班在上什麼課、誰在上,已套用當天的調代課);v1.3.2 新增**重設管理員密碼**的指令(忘了密碼或第一次就登不進去時,不必刪資料或還原備份);v1.3.1 新增**帳號管理**(系統管理員可設定教學組長、教務主任的帳號);v1.3.0 支援**單雙週課程**(同一節單週、雙週輪流上不同的課,排課、請假代課、調課、巡堂表、鐘點都分單雙週;⚠️ 首次改動資料表結構,升級前請先備份);v1.2.19 支援**日薪代課**(國小常見:月結統計把鐘點與日薪分開列)並可**整批指派代課**(整張假單或整天一次派給同一位老師);v1.2.18 可**檢查課表**(發布前列出衝堂、教師不可排時段等衝突;事後修改不可排時段時當場提示已排的課);v1.2.17 修正登入按一次送出兩筆請求(輸錯密碼約第 3 次就被鎖定);v1.2.15、v1.2.16 修正跑班群組的兩個問題(同一位老師在群組裡重複配課時自動排課會排出撞課的課表;同一格有多筆同科目配課時,手動排課把每日節數重複計算);v1.2.12~v1.2.14 可列印**巡堂表**並匯出 Excel(依當天的調代課結果產生,社團另出分組巡堂單);v1.2.10、v1.2.11 讓**國中小、完全中學**跨部上課的老師,課表與通知單都標出實際上課時間,兩部節數不同(國中七節、高中八節)也不會漏課;v1.2.9 可一次匯出**全校教師課表**(總表與批次打包);v1.2.8 可用 Excel **批次更新既有教師**(新學年職務異動),並能**停用/啟用教師登入帳號**(離職教師保留歷史紀錄又進不來);v1.2.7 補上**學期起訖日期**的填寫與修改(先前畫面上無處可填,導致請假被擋);v1.2.6 修掉第一批外部使用者回報的三個問題(教師帳號首次登入卡死、無法事後補開教師帳號、未排課務清單過長時拖不動),並可在畫面上自行修改與重設密碼;v1.2.5 可列印**教師代課通知單與班級代課通知單**(照學校紙本格式,代課時可選計費方式);v1.2.4 的調代課處理會寫出處置方式(代課或調課、哪天補課);v1.2.3 起系統會顯示目前版本,並在有新版時提醒系統管理員(只提醒、不自動升級);v1.2.2 可列印**教師調課通知單與班級調課通知單**(照學校紙本格式);v1.2.1 補上**調課**的操作畫面——請假(含研習)的節次可直接列出雙方都有空的對調節次,支援跨週(最多四週)與連堂,補課日也會出現在今日看板。v1.2.0 起另有**一鍵示範資料**,裝好後兩分鐘內就能看到一張排好的全校課表。
-**請直接從最新版開始安裝**(見上方快速開始);`v1.4.20` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。
+**請直接從最新版開始安裝**(見上方快速開始);`v1.4.21` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。
系統仍在實際校園環境試用中,若你是第一批使用者,歡迎加入 [LINE 社群](https://line.me/ti/g2/hP0Lg7mqvE5rvWg0sE9MHI-QsLkd94Cfp3wKcg) 或透過 [Issues](https://github.com/begin0808/Course_Scheduling_System/issues) 回報任何問題。
diff --git a/backend/app/api/substitutions.py b/backend/app/api/substitutions.py
index 871079d..0698e21 100644
--- a/backend/app/api/substitutions.py
+++ b/backend/app/api/substitutions.py
@@ -125,13 +125,17 @@ def get_triangle_options(
affected_id: int,
weeks: int = Query(default=swap_options.DEFAULT_WEEKS, ge=1, le=swap_options.MAX_WEEKS),
start: date | None = Query(default=None),
+ teacher_id: int | None = Query(default=None),
db: Session = Depends(get_db),
_: User = Depends(editor),
):
- """三角調課(v1.4.20):同一班三位老師輪流換課的可行組合,範圍與互調相同。"""
+ """三角調課(v1.4.20):同一班三位老師輪流換課的可行組合,範圍與互調相同。
+
+ `teacher_id`(v1.4.21):只列有這位老師的組合,並寫出他其餘節次為什麼湊不成。
+ """
affected = _get_affected(db, affected_id)
return TriangleOptionsOut.model_validate(asdict(swap_options.triangle_search(
- db, affected, weeks=weeks, start=start)))
+ db, affected, weeks=weeks, start=start, teacher_id=teacher_id)))
@router.get("/swap-slips", response_model=SlipsOut)
diff --git a/backend/app/schemas/substitution.py b/backend/app/schemas/substitution.py
index a196644..587b3c7 100644
--- a/backend/app/schemas/substitution.py
+++ b/backend/app/schemas/substitution.py
@@ -169,6 +169,22 @@ class TriangleOptionOut(BaseModel):
makeup: TriangleLessonOut # 丙原本的那一節,甲回來上
+class ClassTeacherOut(BaseModel):
+ teacher_id: int
+ teacher_name: str
+
+
+class TeacherCheckOut(BaseModel):
+ """指定老師(v1.4.21):能湊成幾組,其餘節次為什麼不行。"""
+
+ teacher_id: int
+ teacher_name: str
+ found: int = 0
+ note: str = ""
+ as_partner: list[str] = [] # 當 ①:來上請假那一節
+ as_third: list[str] = [] # 當 ②:來上別人讓出的一節,請假老師回來上他的課
+
+
class TriangleOptionsOut(BaseModel):
"""三角調課(v1.4.20):可行的三人組合。`unavailable` 非空 = 這一節不能三角調課。"""
@@ -178,6 +194,8 @@ class TriangleOptionsOut(BaseModel):
unavailable: str = ""
total: int = 0
options: list[TriangleOptionOut] = []
+ teachers: list[ClassTeacherOut] = []
+ check: TeacherCheckOut | None = None
class SlipRowOut(BaseModel):
diff --git a/backend/app/services/availability.py b/backend/app/services/availability.py
index 381707b..7218c65 100644
--- a/backend/app/services/availability.py
+++ b/backend/app/services/availability.py
@@ -199,11 +199,17 @@ def _on_leave(self, teacher_id: int, when: date, slot: Interval) -> bool:
return False
# ── 當日已接手:已被指派代別班/調課到那個時段 ──
- def _already_covering(self, teacher_id: int, when: date, slot: Interval) -> Interval | None:
+ def _already_covering(self, teacher_id: int, when: date, slot: Interval) -> str | None:
+ """已經被安排在這個時段去上別班的課 → 去上哪一班(「代 702 國文」);沒有回 None。
+
+ 寫出是哪一班(v1.4.21,組長回報「三角調課抓不到某位老師」):只寫「已被安排代其他課」,
+ 組長不知道要去哪裡找那一筆。
+ """
# (a) 身為其他受影響節次的代課/接手者
rows = self.db.execute(
select(AffectedPeriod.weekday, AffectedPeriod.period_no,
- AffectedPeriod.start_time, AffectedPeriod.end_time)
+ AffectedPeriod.start_time, AffectedPeriod.end_time,
+ AffectedPeriod.class_names, AffectedPeriod.subject_name)
.join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id)
.where(
AffectedPeriod.handler_teacher_id == teacher_id,
@@ -212,15 +218,15 @@ def _already_covering(self, teacher_id: int, when: date, slot: Interval) -> Inte
AffectedPeriod.date == when,
)
).all()
- for weekday, period_no, start, end in rows:
- other = Interval(weekday, period_no, start, end)
- if slot.overlaps(other):
- return other
+ for weekday, period_no, start, end, classes, subject in rows:
+ if slot.overlaps(Interval(weekday, period_no, start, end)):
+ return f"代 {classes} {subject}".strip()
# (b) 身為調課的補課者(swap 的甲方,補在 swap_date)。
# **補課方是該筆調課「請假的當事人」**,不是 handler(乙);必須以
# AffectedPeriod→LeaveRequest.teacher_id 比對,否則會把全校在該時段都誤判為已佔用。
swaps = self.db.execute(
- select(Substitution.swap_period_no)
+ select(Substitution.swap_period_no, Substitution.swap_class_names,
+ Substitution.swap_subject_name)
.join(AffectedPeriod, Substitution.affected_period_id == AffectedPeriod.id)
.join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id)
.where(
@@ -230,12 +236,13 @@ def _already_covering(self, teacher_id: int, when: date, slot: Interval) -> Inte
AffectedPeriod.status != AffectedStatus.cancelled.value,
)
).all()
- for (swap_period_no,) in swaps:
+ for swap_period_no, classes, subject in swaps:
if swap_period_no == slot.period_no: # 調課補課以節次號記錄
- return Interval(slot.weekday, swap_period_no, None, None)
+ return f"回 {classes} {subject} 調課補課".replace(" ", " ")
# (c) 三角調課的丙:來上乙原本那一節(tri_date,v1.4.20)
tris = self.db.execute(
- select(Substitution.tri_period_no)
+ select(Substitution.tri_period_no, Substitution.tri_class_names,
+ Substitution.tri_subject_name)
.join(AffectedPeriod, Substitution.affected_period_id == AffectedPeriod.id)
.join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id)
.where(
@@ -245,9 +252,9 @@ def _already_covering(self, teacher_id: int, when: date, slot: Interval) -> Inte
AffectedPeriod.status != AffectedStatus.cancelled.value,
)
).all()
- for (tri_period_no,) in tris:
+ for tri_period_no, classes, subject in tris:
if tri_period_no == slot.period_no:
- return Interval(slot.weekday, tri_period_no, None, None)
+ return f"去 {classes} {subject} 三角調課".replace(" ", " ")
return None
# ── 對外:某教師某時段能不能用 ──
@@ -311,8 +318,9 @@ def conflict_for(
return Conflict("teaching", "該時段有自己的課")
if self._on_leave(teacher_id, when, slot):
return Conflict("on_leave", "當天也請假")
- if self._already_covering(teacher_id, when, slot) is not None:
- return Conflict("already_covering", "已被安排代其他課")
+ covering = self._already_covering(teacher_id, when, slot)
+ if covering is not None:
+ return Conflict("already_covering", f"已被安排{covering}")
return None
def is_free(self, teacher_id: int, when: date, slot: Interval) -> bool:
diff --git a/backend/app/services/swap_options.py b/backend/app/services/swap_options.py
index ea2dd5c..b7cd35c 100644
--- a/backend/app/services/swap_options.py
+++ b/backend/app/services/swap_options.py
@@ -11,6 +11,10 @@
**三角調課**(v1.4.20,`triangle_search`):兩人互調湊不出來時,同一班三位老師輪流換課——
乙來上甲請假那節、丙來上乙原本的一節、甲回來上丙原本的一節。只限同一個班的一般課
(一位老師上的課;跑班、單雙週組、協同教學不列),找的範圍與互調相同。
+
+**指定老師**(v1.4.21,組長回報「三角調課的清單裡找不到某位老師」):清單只列換得成的組合,
+湊不出來時組長看不出卡在哪裡;指定一位老師就逐節寫出他在每個位置為什麼不行
+(`TeacherCheck`),他的組合也不受 `MAX_TRIANGLES` 截斷。
"""
from dataclasses import dataclass, field
@@ -220,13 +224,16 @@ def third_reason(
self, third: Teacher, entry: ScheduleEntry, when: date, period_no: int
) -> str | None:
"""丙這一節能不能來上課(自己有課、請假、已被安排代課都不行)。"""
- slot = self.av.entry_slot(entry, period_no)
- hit = self.av.lesson_at(third.id, slot, when)
+ return self.busy(third, when, self.av.entry_slot(entry, period_no))
+
+ def busy(self, teacher: Teacher, when: date, slot: Interval) -> str | None:
+ """這位老師這個時段能不能來上課;不能時寫原因(「林師這節自己有課(401 體育)」)。"""
+ hit = self.av.lesson_at(teacher.id, slot, when)
if hit is not None:
- return f"{third.name}這節自己有課({self._lesson_label(hit[1])})"
- conflict = self.av.conflict_for(third.id, when, slot)
+ return f"{teacher.name}這節自己有課({self._lesson_label(hit[1])})"
+ conflict = self.av.conflict_for(teacher.id, when, slot)
if conflict is not None:
- return f"{third.name}{conflict.detail}"
+ return f"{teacher.name}{conflict.detail}"
return None
def _lesson_label(self, assignment_id: int) -> str:
@@ -466,6 +473,28 @@ class TriangleOption:
makeup: Lesson
+@dataclass(frozen=True, slots=True)
+class ClassTeacher:
+ """這一班(請假老師以外)有一般課的老師:「指定老師」的選單。"""
+
+ teacher_id: int
+ teacher_name: str
+
+
+@dataclass
+class TeacherCheck:
+ """指定一位老師(v1.4.21):他能湊成幾組,其餘的節次為什麼不行。"""
+
+ teacher_id: int
+ teacher_name: str
+ found: int = 0
+ note: str = "" # 非空 = 根本沒有這一班的課
+ # 當 ①:來上請假那一節(要讓出自己的一節給別人上)
+ as_partner: list[str] = field(default_factory=list)
+ # 當 ②:來上別人讓出的一節,請假老師回來上他的課
+ as_third: list[str] = field(default_factory=list)
+
+
@dataclass
class TriangleSearch:
affected_period_id: int
@@ -474,9 +503,21 @@ class TriangleSearch:
unavailable: str = "" # 非空 = 這一節不能三角調課的原因(跑班、協同教學…)
total: int = 0 # 一共幾組(清單只回前 MAX_TRIANGLES 組)
options: list[TriangleOption] = field(default_factory=list)
+ teachers: list[ClassTeacher] = field(default_factory=list)
+ check: TeacherCheck | None = None
MAX_TRIANGLES = 200
+_WEEKDAY_TEXT = "一二三四五六日"
+
+
+def _when(day: date, period_name: str) -> str:
+ """「12/16(週三) 第四節」。"""
+ return f"{day.month}/{day.day}(週{_WEEKDAY_TEXT[day.isoweekday() - 1]}) {period_name}".strip()
+
+
+def _lesson_text(x: Lesson) -> str:
+ return f"{_when(x.date, x.period_name)} {x.subject_name}".strip()
def triangle_unit(db: Session, affected: AffectedPeriod) -> tuple[int | None, str]:
@@ -541,11 +582,13 @@ def triangle_search(
weeks: int = DEFAULT_WEEKS,
start: date | None = None,
availability: Availability | None = None,
+ teacher_id: int | None = None,
) -> TriangleSearch:
"""列出可行的三人組合:乙在甲那節有空、丙在乙那節有空、甲在丙那節有空。
每一格的檢查與互調同一套(`SwapChecker`):停課、請假、已經拿去調課、自己有課、
已被安排代課都不行。依兩節裡較晚的那天排序(越早換完越好)。
+ `teacher_id`:只列有這位老師(當 ① 或 ②)的組合,並寫出他其餘節次為什麼不行。
"""
av = availability or Availability(db, affected.semester_id)
date_from, date_to = search_window(affected.date, weeks, start)
@@ -566,6 +609,9 @@ def triangle_search(
entries = {e.id: e for e in db.scalars(
select(ScheduleEntry).where(ScheduleEntry.id.in_({x.entry_id for x in lessons} or [0])))}
+ result.teachers = sorted(
+ (ClassTeacher(teacher_id=t.id, teacher_name=t.name) for t in teachers.values()),
+ key=lambda t: t.teacher_name)
partner_ok = {tid: checker.partner_blocker(t) is None for tid, t in teachers.items()}
# 甲能不能回來上這一節(丙的課)
makeups: dict[int, list[Lesson]] = {}
@@ -592,8 +638,76 @@ def triangle_search(
partner_id=owner.id, partner_name=owner.name, mid=mid,
third_id=third.id, third_name=third.name, makeup=z))
+ if teacher_id is not None:
+ found = [o for o in found if teacher_id in (o.partner_id, o.third_id)]
+ result.check = _teacher_check(
+ db, checker, teacher_id, lessons, teachers, entries, partner_ok, makeups, len(found))
found.sort(key=lambda o: (max(o.mid.date, o.makeup.date), o.mid.date, o.mid.period_no,
o.makeup.date, o.makeup.period_no, o.partner_name, o.third_name))
result.total = len(found)
result.options = found[:MAX_TRIANGLES]
return result
+
+
+def _teacher_check(
+ db: Session,
+ checker: SwapChecker,
+ teacher_id: int,
+ lessons: list[Lesson],
+ teachers: dict[int, Teacher],
+ entries: dict[int, ScheduleEntry],
+ partner_ok: dict[int, bool],
+ makeups: dict[int, list[Lesson]],
+ found: int,
+) -> TeacherCheck:
+ """這位老師在三角調課的兩個位置,每一節為什麼湊不成(v1.4.21)。
+
+ ①:他來上請假那一節,讓出自己的一節給第三位老師上;
+ ②:他來上別人讓出的一節,請假老師回來上他的一節。
+ """
+ absent = checker.absent.name
+ t = teachers.get(teacher_id) or db.get(Teacher, teacher_id)
+ chk = TeacherCheck(teacher_id=teacher_id, teacher_name=t.name if t else "", found=found)
+ mine = [x for x in lessons if x.teacher_id == teacher_id]
+ if t is None or not mine:
+ chk.note = (f"{chk.teacher_name}在這段期間沒有這一班的課(或都已經上過);"
+ "三角調課只找同一班的老師,可以改用互調或代課")
+ return chk
+
+ a = checker.affected
+ blocker = checker.busy(t, a.date, checker.av.slot_of(a))
+ if blocker:
+ chk.as_partner.append(f"不能來上請假那一節 {_when(a.date, a.period_name)}:{blocker}")
+ else:
+ others = [teachers[tid] for tid in makeups if tid != teacher_id]
+ for x in mine:
+ entry = entries[x.entry_id]
+ why = checker.mid_base_reason(t, entry, x.date, x.period_no)
+ if why is None:
+ if any(checker.third_reason(o, entry, x.date, x.period_no) is None
+ for o in others):
+ continue
+ why = (f"{absent}能回來上課的老師({'、'.join(o.name for o in others)})這節都沒空"
+ if others else f"{absent}沒辦法回來上這一班其他老師的任何一節")
+ chk.as_partner.append(f"讓出 {_lesson_text(x)}:{why}")
+
+ usable = []
+ for x in mine:
+ why = checker.reason(t, entries[x.entry_id], x.date, x.period_no)
+ if why:
+ chk.as_third.append(f"{absent}回來上{t.name}的 {_lesson_text(x)}:{why}")
+ else:
+ usable.append(x)
+ if usable:
+ mids = [m for m in lessons
+ if m.teacher_id != teacher_id and partner_ok[m.teacher_id]
+ and checker.mid_base_reason(teachers[m.teacher_id], entries[m.entry_id],
+ m.date, m.period_no) is None]
+ if not mids:
+ chk.as_third.append(f"{absent}可以回來上{t.name}的課,但其他老師都沒辦法來上請假那一節"
+ "(或讓不出自己的課)")
+ for m in mids:
+ why = checker.third_reason(t, entries[m.entry_id], m.date, m.period_no)
+ if why:
+ chk.as_third.append(f"來上{m.teacher_name}的 {_lesson_text(m)}:{why}")
+ return chk
diff --git a/backend/tests/test_triangle_teacher_check_v1421.py b/backend/tests/test_triangle_teacher_check_v1421.py
new file mode 100644
index 0000000..f4a3234
--- /dev/null
+++ b/backend/tests/test_triangle_teacher_check_v1421.py
@@ -0,0 +1,120 @@
+"""三角調課指定老師(v1.4.21,組長回報「三角調課的清單裡找不到某位老師」)。
+
+組長的情況:律動老師(這裡是丙師)只有週四有課,週四整天「調課(未請假)」;201 的換法是
+「甲師(導師)來上丙師週四的律動 → 乙師(體育)上甲師週三第二節 → 丙師回來上乙師週三第四節體育」。
+清單裡乙師一次都沒出現:丙師週四另一班的課已經先調好,補課就排在週三第四節,
+同一個時段不能再回 201 上體育。系統是對的,但組長看不出卡在哪裡。
+
+指定老師後:只列有這位老師的組合(不受 200 組截斷),並逐節寫出他在每個位置為什麼不行。
+"""
+
+from datetime import timedelta
+
+from app.services.availability import Availability, Interval
+from tests.dates import WED
+from tests.test_timetable_week import w # noqa: F401 - w 為 fixture
+
+THU = WED + timedelta(days=1)
+NEXT_WED = WED + timedelta(days=7)
+
+
+def _md(d):
+ return f"{d.month}/{d.day}"
+
+
+def _school(world):
+ world.teacher("甲師", ["國語"])
+ world.teacher("乙師", ["體育"])
+ world.teacher("丙師", ["律動"])
+ world.teacher("戊師", ["數學"])
+ world.place("甲師", "國語", "201", 0, weekday=3)
+ world.place("甲師", "國語", "201", 1, weekday=3)
+ world.place("乙師", "體育", "201", 3, weekday=3) # 週三第四節 201 體育
+ world.place("乙師", "體育", "401", 4, weekday=4) # 週四第五節有別班:不能當 ①
+ world.place("丙師", "律動", "102", 3, weekday=4) # 丙師只有週四有課
+ world.place("丙師", "律動", "201", 4, weekday=4)
+ world.place("戊師", "數學", "102", 3, weekday=3) # 102 週三第四節
+ world.publish()
+ day = world.client.get(
+ f"/api/teachers/{world.teachers['丙師']}/day-periods{world.q}&date={THU}").json()
+ r = world.client.post(f"/api/swap-requests{world.q}", json={
+ "teacher_id": world.teachers["丙師"], "date": THU.isoformat(),
+ "period_nos": [p["period_no"] for p in day]})
+ assert r.status_code == 201, r.json()
+ aps = {a["class_names"]: a["id"] for a in r.json()["affected_periods"]}
+ return aps["201"], aps["102"]
+
+
+def _swap_102_to_wednesday(world, ap102):
+ """丙師週四 102 的課先和戊師對調:丙師週三第四節回 102 補課。"""
+ opts = world.client.get(f"/api/affected-periods/{ap102}/swap-options").json()
+ wu = next(p for p in opts["partners"] if p["teacher_name"] == "戊師")
+ opt = next(o for o in wu["options"] if o["date"] == WED.isoformat())
+ code, body = world.assign(ap102, type="swap", handler_teacher_id=world.teachers["戊師"],
+ swap_entry_id=opt["entry_id"], swap_date=opt["date"],
+ swap_period_no=opt["period_no"])
+ assert code == 200, body
+
+
+def _triangles(world, aid, teacher=None):
+ q = f"?teacher_id={world.teachers[teacher]}" if teacher else ""
+ r = world.client.get(f"/api/affected-periods/{aid}/triangle-options{q}")
+ assert r.status_code == 200, r.json()
+ return r.json()
+
+
+def _combo(o):
+ return (o["partner_name"], o["mid"]["date"], o["mid"]["period_name"], o["third_name"],
+ o["makeup"]["date"], o["makeup"]["subject_name"])
+
+
+def test_rotation_through_pe_is_listed_when_nothing_is_in_the_way(w): # noqa: F811
+ ap201, _ = _school(w)
+ body = _triangles(w, ap201)
+ assert [t["teacher_name"] for t in body["teachers"]] == ["乙師", "甲師"]
+ assert body["check"] is None
+ assert _combo(body["options"][0]) == (
+ "甲師", WED.isoformat(), w.wed[0]["name"], "乙師", WED.isoformat(), "體育")
+
+
+def test_picking_the_teacher_explains_the_blocked_makeup(w): # noqa: F811
+ ap201, ap102 = _school(w)
+ _swap_102_to_wednesday(w, ap102)
+ body = _triangles(w, ap201)
+ # 這一週的乙師不見了(只剩下週的體育)
+ assert all(o["makeup"]["date"] != WED.isoformat() for o in body["options"]
+ if o["third_name"] == "乙師")
+
+ picked = _triangles(w, ap201, "乙師")
+ check = picked["check"]
+ assert check["teacher_name"] == "乙師" and check["note"] == ""
+ assert check["found"] == picked["total"] == len(picked["options"]) > 0
+ assert all("乙師" in (o["partner_name"], o["third_name"]) for o in picked["options"])
+ assert {o["makeup"]["date"] for o in picked["options"]} == {NEXT_WED.isoformat()}
+ # ①:乙師週四第五節自己有課,來不了
+ assert check["as_partner"] == [
+ f"不能來上請假那一節 {_md(THU)}(週四) {w.wed[4]['name']}:乙師這節自己有課(401 體育)"]
+ # ②:這一週的體育,丙師已經要回 102 補課
+ assert check["as_third"] == [
+ f"丙師回來上乙師的 {_md(WED)}(週三) {w.wed[3]['name']} 體育:"
+ "丙師已被安排回 102 數學 調課補課"]
+
+
+def test_a_teacher_without_lessons_in_the_class_gets_a_note(w): # noqa: F811
+ ap201, _ = _school(w)
+ body = _triangles(w, ap201, "戊師")
+ assert body["options"] == [] and body["total"] == 0
+ assert "沒有這一班的課" in body["check"]["note"]
+
+
+def test_substitute_conflicts_name_the_class(w): # noqa: F811
+ """已被安排代課時寫出是哪一班(原本只寫「已被安排代其他課」,組長不知道去哪裡找)。"""
+ _school(w)
+ ap = w.leave("戊師", WED)[0]["id"] # 戊師週三請假,甲師代 102 第四節
+ code, body = w.assign(ap, type="substitute", handler_teacher_id=w.teachers["甲師"])
+ assert code == 200, body
+ w.db.expire_all()
+ av = Availability(w.db, w.sid)
+ slot = Interval(3, w.wed[3]["period_no"], None, None)
+ conflict = av.conflict_for(w.teachers["甲師"], WED, slot)
+ assert conflict is not None and conflict.detail == "已被安排代 102 數學"
diff --git a/docs/deploy/upgrade.html b/docs/deploy/upgrade.html
index 86b98f4..1cf1bbe 100644
--- a/docs/deploy/upgrade.html
+++ b/docs/deploy/upgrade.html
@@ -172,7 +172,7 @@
路線圖開發用
開發任務卡開發用
-
本頁目錄
+本頁目錄
@@ -190,6 +190,9 @@ 升級指南
開始前先備份。 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見備份指南。
+ 升級到 v1.4.21:三角調課指定老師
+ v1.4.21 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可;從 v1.4.19 或更早的版本升上來,一樣會經過
+ v1.4.20 的資料表變更(會先自動備份)。要退回 v1.4.20,把 IMAGE_TAG 改回 v1.4.20 再 pull、up -d 即可。
升級到 v1.4.20:調代課處置的資料表新增三角調課欄位
v1.4.20 在「調代課處置」的資料表新增幾個欄位(三角調課的第三位老師與中間那一節,都可以是空的),
既有的資料都不動——升級前的調課都是兩人互調,這些欄位留空。和 v1.4.19 一樣,api 容器發現資料庫結構
diff --git a/docs/deploy/upgrade.md b/docs/deploy/upgrade.md
index 4a0b5e9..f558811 100644
--- a/docs/deploy/upgrade.md
+++ b/docs/deploy/upgrade.md
@@ -8,6 +8,11 @@
> **開始前先備份。** 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見[備份指南](backup.md)。
+## 升級到 v1.4.21:三角調課指定老師
+
+v1.4.21 沒有資料表變更,照下方方式 A 或方式 B 一般升級即可;從 v1.4.19 或更早的版本升上來,一樣會經過
+v1.4.20 的資料表變更(會先自動備份)。要退回 v1.4.20,把 `IMAGE_TAG` 改回 v1.4.20 再 `pull`、`up -d` 即可。
+
## 升級到 v1.4.20:調代課處置的資料表新增三角調課欄位
v1.4.20 在「調代課處置」的資料表新增幾個欄位(三角調課的第三位老師與中間那一節,都可以是空的),
diff --git a/docs/features.html b/docs/features.html
index 8b29ebe..e7fc2f9 100644
--- a/docs/features.html
+++ b/docs/features.html
@@ -3,7 +3,7 @@
-
+
功能總覽 · 排課與調代課系統