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 @@ 路線圖開發用 開發任務卡開發用 -
本頁目錄
升級到 v1.4.20:調代課處置的資料表新增三角調課欄位升級到 v1.4.19:新增停課日用的資料表升級到 v1.4.2 ~ v1.4.18:補登、修改假別與計費方式、未請假的調課、批次 PDF、登入鎖定資安修正升級到 v1.4.1:授權改為 AGPL-3.0升級到 v1.4.0:新增代導用的資料表升級到 v1.3.0:系統會自動先備份一條規則:docker-compose.yml 要跟著版本走方式 A:拉取映像部署(最常見)方式 B:從原始碼建置部署關於版本釘選退回舊版(升級後發現問題)從 v1.4.20 退回 v1.4.19從 v1.4.19 退回 v1.4.18從 v1.4.0 退回 v1.3.x從 v1.3.0 退回 v1.2.x升級檢查清單
+
本頁目錄
升級到 v1.4.21:三角調課指定老師升級到 v1.4.20:調代課處置的資料表新增三角調課欄位升級到 v1.4.19:新增停課日用的資料表升級到 v1.4.2 ~ v1.4.18:補登、修改假別與計費方式、未請假的調課、批次 PDF、登入鎖定資安修正升級到 v1.4.1:授權改為 AGPL-3.0升級到 v1.4.0:新增代導用的資料表升級到 v1.3.0:系統會自動先備份一條規則:docker-compose.yml 要跟著版本走方式 A:拉取映像部署(最常見)方式 B:從原始碼建置部署關於版本釘選退回舊版(升級後發現問題)從 v1.4.20 退回 v1.4.19從 v1.4.19 退回 v1.4.18從 v1.4.0 退回 v1.3.x從 v1.3.0 退回 v1.2.x升級檢查清單
@@ -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 @@ - + 功能總覽 · 排課與調代課系統