diff --git a/.env.example b/.env.example
index 2a32b528..a8d5f9d9 100644
--- a/.env.example
+++ b/.env.example
@@ -32,7 +32,7 @@ HTTP_PORT=80
# ── 預建映像版本(僅「拉取映像」部署方式需要)──────────
# 用 docker compose pull 拉官方映像時,決定要拉哪一版。
# 預設 latest(最新);正式部署建議釘選版本號以利可控升級,例如:
-# IMAGE_TAG=v1.4.17
+# IMAGE_TAG=v1.4.18
# 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。
IMAGE_TAG=latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e218cae1..02632cbd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,10 +4,27 @@
破壞性變更(需人工介入才能升級)以 ⚠️ 標註。
-> **新使用者請直接安裝 v1.4.17**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.16 是先前版本;以下條目保留作為變更紀錄。
+> **新使用者請直接安裝 v1.4.18**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.17 是先前版本;以下條目保留作為變更紀錄。
## [Unreleased]
+## [1.4.18] — 2026-11-11
+
+**修正:調課之後重新發布課表,補課那一節不見了**(LINE 社群組長回報,**建議升級**)。
+
+**資料表沒有變動**,照一般方式升級即可(`.env` 改 `IMAGE_TAG=v1.4.18` → `docker compose pull && docker compose up -d`)。升級時系統會自動修正既有調課的資料(見下),修正前會先自動備份。
+
+官方映像(amd64 + arm64 雙架構)已發布於 GHCR:
+`ghcr.io/begin0808/course_scheduling_system-{api,worker,web}:v1.4.18`
+
+### 修正
+- **重新發布課表後,調課的補課那一節不見了**:調課記下補課那一節時,記的是「課表的哪一格」;學期中改課表再發布,新課表每一格都是新的,補課那一節還指著已封存的舊課表。結果:
+ - 班級、教師的週課表、全校教師週總表、巡堂表、即時概況都畫不出補課那一節(只有請假那一格變色,看起來像「只有一個人被調」);
+ - 調課清單以為那一節還沒被拿去調,**同一節可能再換給別的老師**。
+
+ 現在發布新課表時,調課會自動接到新課表「同一門課、同一天、同一節」的格子。新課表把那堂課搬走、接不上的,發布後會提醒「有 N 筆調課的補課節次…」,請到「調代課處理」按該節的「撤回」後重新安排。
+- **升級時修正已經發生的**:升級到 v1.4.18 時,既有調課會用同一套規則接回目前已發布的課表(只改調課的資料,不改資料表)。
+
## [1.4.17] — 2026-11-11
**修正:調課寫出補課在哪一天**(LINE 社群組長回報)。
diff --git a/README.md b/README.md
index 60c5c972..992bc840 100644
--- a/README.md
+++ b/README.md
@@ -132,11 +132,11 @@ docker compose up -d # 首次會建置映像,需數分鐘
## 專案狀態
-**v1.4.17 已發行(2026-11-11)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 779 項單元/整合測試、61 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
+**v1.4.18 已發行(2026-11-11)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 783 項單元/整合測試、61 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
-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 修正調課後**重新發布課表**時補課那一節消失的問題;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.17` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。
+**請直接從最新版開始安裝**(見上方快速開始);`v1.4.18` 是目前建議使用的版本。各版變更見 [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/0020_relink_swaps.py b/backend/alembic/versions/0020_relink_swaps.py
new file mode 100644
index 00000000..31badbb5
--- /dev/null
+++ b/backend/alembic/versions/0020_relink_swaps.py
@@ -0,0 +1,69 @@
+"""v1.4.18:調課的補課節次接回目前已發布的課表(只修資料,不改資料表)。
+
+調課記下補課那一節時記的是「課表的哪一格」。v1.4.17 以前,學期中重新發布課表後,
+補課那一節還指著舊課表(已封存)的格子:週課表、巡堂表畫不出補課那一節,調課清單
+也以為那一節還能再拿去調。v1.4.18 起發布時會自動接過去(`app.services.swap_relink`);
+這裡把升級前已經發生的接回來,規則相同:目前已發布課表裡「同一門課(配課)、同一天、
+涵蓋那一節」的格子。找不到的(新課表把那堂課移走了)維持原樣。
+
+Revision ID: 0020_relink_swaps
+Revises: 0019_homeroom_covers
+"""
+
+from datetime import date
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "0020_relink_swaps"
+down_revision = "0019_homeroom_covers"
+branch_labels = None
+depends_on = None
+
+
+def _weekday(value) -> int:
+ d = value if isinstance(value, date) else date.fromisoformat(str(value)[:10])
+ return d.isoweekday()
+
+
+def relink(conn) -> int:
+ """回傳接上的筆數(測試也直接呼叫)。"""
+ rows = conn.execute(sa.text(
+ """
+ SELECT s.id, s.swap_date, s.swap_period_no, oe.course_assignment_id, oe.period_no,
+ tp.id AS published_id
+ FROM substitutions s
+ JOIN schedule_entries oe ON oe.id = s.swap_entry_id
+ JOIN timetables tp ON tp.semester_id = s.semester_id AND tp.status = 'published'
+ WHERE s.type = 'swap' AND s.swap_date IS NOT NULL AND oe.timetable_id <> tp.id
+ """
+ )).all()
+ moved = 0
+ for sub_id, swap_date, swap_period_no, assignment_id, old_period_no, published_id in rows:
+ period_no = swap_period_no if swap_period_no is not None else old_period_no
+ new_id = conn.execute(sa.text(
+ """
+ SELECT id FROM schedule_entries
+ WHERE timetable_id = :tt AND course_assignment_id = :a AND weekday = :wd
+ AND period_no <= :p AND :p < period_no + span
+ ORDER BY id LIMIT 1
+ """
+ ), {"tt": published_id, "a": assignment_id, "wd": _weekday(swap_date),
+ "p": period_no}).scalar()
+ if new_id is None:
+ continue
+ conn.execute(sa.text(
+ "UPDATE substitutions SET swap_entry_id = :e, swap_period_no = :p WHERE id = :i"
+ ), {"e": new_id, "p": period_no, "i": sub_id})
+ moved += 1
+ return moved
+
+
+def upgrade() -> None:
+ relink(op.get_bind())
+
+
+def downgrade() -> None:
+ # 接到新課表的格子是正確的資料,不還原
+ pass
diff --git a/backend/app/api/timetables.py b/backend/app/api/timetables.py
index 82910303..9521a269 100644
--- a/backend/app/api/timetables.py
+++ b/backend/app/api/timetables.py
@@ -40,7 +40,7 @@
TimetableWeekOut,
)
from app.services import conflict_checker as cc
-from app.services import timetable_check, timetable_week
+from app.services import swap_relink, timetable_check, timetable_week
from app.services import timetable_publish as pub
from app.services.teachers import current_teacher
@@ -285,6 +285,7 @@ def publish_timetable(
# 條件 D:重新發布後,提醒仍有多少「今日之後」的調代課是依舊課表展開的
out = get_timetable(timetable_id, db, None)
out.stale_affected = pub.stale_future_affected_count(db, tt.semester_id)
+ out.swap_unlinked = swap_relink.unlinked_count(db, tt)
return out
diff --git a/backend/app/schemas/timetable.py b/backend/app/schemas/timetable.py
index aed83f20..872d135a 100644
--- a/backend/app/schemas/timetable.py
+++ b/backend/app/schemas/timetable.py
@@ -48,6 +48,8 @@ class TimetableOut(BaseModel):
entries: list[ScheduleEntryOut] = []
# 發布後回填:今日之後、依舊課表展開的受影響節次數(>0 提醒組長重新檢視調代課)
stale_affected: int = 0
+ # 發布後回填:今日之後的調課裡,補課那一節在新課表找不到同一堂課的筆數(v1.4.18)
+ swap_unlinked: int = 0
class ConflictOut(BaseModel):
diff --git a/backend/app/services/swap_relink.py b/backend/app/services/swap_relink.py
new file mode 100644
index 00000000..fdeb90fe
--- /dev/null
+++ b/backend/app/services/swap_relink.py
@@ -0,0 +1,93 @@
+"""發布新課表時,把調課的補課節次接到新課表(v1.4.18)。
+
+調課記下補課那一節時,記的是「課表的哪一格」(`Substitution.swap_entry_id`)。
+學期中重新發布課表,新課表的每一格都是新的一列,舊課表封存——補課那一節還指著
+舊課表的格子,於是:
+
+- 班級、教師的週課表、教師週總表、巡堂表、即時概況都畫不出補課那一節
+ (它們只看已發布課表的格子);
+- 調課清單以為那一節「還沒被拿去調」,同一節可能再換給別人。
+
+組長回報(v1.4.18):先調課再改課表發布,週課表只有請假那一格變紅。
+
+做法:發布時找出這學期所有調課,在新課表裡找「同一門課(配課)、同一天、
+涵蓋那一節」的格子接過去。找不到代表新課表把那堂課移走了,補課那一節已經
+沒有這門課——不猜,留著原樣,由 `unlinked_count` 數出來提醒組長重新處理。
+
+升級時的一次性修正見 alembic `0020_relink_swaps`(同一套規則,以 SQL 寫成)。
+"""
+
+from datetime import date
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.core import clock
+from app.models.leave import AffectedPeriod, AffectedStatus, LeaveRequest, LeaveStatus
+from app.models.substitution import Substitution, SubstitutionType
+from app.models.timetable import ScheduleEntry, Timetable
+
+
+def _swaps(db: Session, semester_id: int) -> list[Substitution]:
+ return list(db.scalars(
+ select(Substitution).where(
+ Substitution.semester_id == semester_id,
+ Substitution.type == SubstitutionType.swap.value,
+ Substitution.swap_date.is_not(None),
+ )
+ ))
+
+
+def _find(entries: list[ScheduleEntry], period_no: int) -> ScheduleEntry | None:
+ return next((e for e in entries if e.period_no <= period_no < e.period_no + e.span), None)
+
+
+def relink(db: Session, timetable: Timetable) -> int:
+ """把這學期調課的補課節次接到 `timetable` 的格子;回傳接上的筆數。呼叫端負責 commit。
+
+ 已經在這份課表上的不動;舊格子已被刪除(課表刪掉了)的找不到配課,也不動。
+ """
+ index: dict[tuple[int, int], list[ScheduleEntry]] = {}
+ for e in db.scalars(select(ScheduleEntry).where(ScheduleEntry.timetable_id == timetable.id)):
+ index.setdefault((e.course_assignment_id, e.weekday), []).append(e)
+
+ moved = 0
+ for sub in _swaps(db, timetable.semester_id):
+ old = db.get(ScheduleEntry, sub.swap_entry_id) if sub.swap_entry_id else None
+ if old is None or old.timetable_id == timetable.id or sub.swap_date is None:
+ continue
+ period_no = sub.swap_period_no if sub.swap_period_no is not None else old.period_no
+ new = _find(index.get((old.course_assignment_id, sub.swap_date.isoweekday()), []),
+ period_no)
+ if new is not None:
+ sub.swap_entry_id = new.id
+ sub.swap_period_no = period_no
+ moved += 1
+ db.flush()
+ return moved
+
+
+def unlinked_count(db: Session, timetable: Timetable, today: date | None = None) -> int:
+ """今天以後、仍有效的調課裡,補課那一節不在這份課表上的筆數(發布後提醒組長)。"""
+ today = today or clock.school_today()
+ rows = db.execute(
+ select(Substitution.swap_entry_id)
+ .join(AffectedPeriod, Substitution.affected_period_id == AffectedPeriod.id)
+ .join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id)
+ .where(
+ Substitution.semester_id == timetable.semester_id,
+ Substitution.type == SubstitutionType.swap.value,
+ Substitution.swap_date >= today,
+ LeaveRequest.status == LeaveStatus.registered.value,
+ AffectedPeriod.status != AffectedStatus.cancelled.value,
+ )
+ ).all()
+ ids = [r for (r,) in rows]
+ if not ids:
+ return 0
+ on_this = set(db.scalars(
+ select(ScheduleEntry.id).where(
+ ScheduleEntry.timetable_id == timetable.id,
+ ScheduleEntry.id.in_([i for i in ids if i is not None] or [0]))
+ ))
+ return sum(1 for i in ids if i not in on_this)
diff --git a/backend/app/services/timetable_publish.py b/backend/app/services/timetable_publish.py
index 2bf4d4ac..61b3c55f 100644
--- a/backend/app/services/timetable_publish.py
+++ b/backend/app/services/timetable_publish.py
@@ -13,6 +13,7 @@
from app.models.leave import AffectedPeriod, AffectedStatus, LeaveRequest, LeaveStatus
from app.models.timetable import ScheduleEntry, Timetable, TimetableStatus
from app.models.user import User
+from app.services import swap_relink
def _reasons_by_assignment(timetable: Timetable) -> dict[int, str]:
@@ -127,6 +128,9 @@ def publish(db: Session, timetable: Timetable, user: User, forced: bool) -> Time
for p in previous:
p.status = TimetableStatus.archived.value
timetable.status = TimetableStatus.published.value
+ db.flush()
+ # 調課的補課節次接到新課表的格子(v1.4.18);接不上的由 API 回報筆數
+ swap_relink.relink(db, timetable)
db.add(AuditLog(
user_id=user.id, username=user.username,
diff --git a/backend/tests/test_swap_relink_v1418.py b/backend/tests/test_swap_relink_v1418.py
new file mode 100644
index 00000000..2f1429f5
--- /dev/null
+++ b/backend/tests/test_swap_relink_v1418.py
@@ -0,0 +1,124 @@
+"""調課後重新發布課表,補課那一節要接到新課表(v1.4.18,LINE 社群組長回報)。
+
+組長把週四第五節和週三第六節對調,之後又改課表重新發布:週課表只有週四那格變紅,
+週三補課那格變回原本的課。原因是調課記的是「舊課表的哪一格」,新課表每一格都是新的。
+連帶:老師本人的週課表少了補課那一節,調課清單也以為那一節還能再拿去調。
+"""
+
+import importlib.util
+from datetime import timedelta
+from pathlib import Path
+
+from app.models.substitution import Substitution
+from app.models.timetable import ScheduleEntry
+from tests.dates import WED
+from tests.test_substitutions import _options
+from tests.test_timetable_week import _at, _week, w # noqa: F401 - w 為 fixture
+
+THU = WED + timedelta(days=1)
+FRI = WED + timedelta(days=2)
+
+
+def _world(world):
+ """王師週四第五節 701 國文請假;林師週三第六節在 701 上輔導。"""
+ world.teacher("王師", ["國文"])
+ world.teacher("林師", ["輔導"])
+ world.place("王師", "國文", "701", 4, weekday=4)
+ world.place("林師", "輔導", "701", 5, weekday=3)
+ world.publish()
+ aid = world.leave("王師", THU)[0]["id"]
+ opt = next(o for o in _options(world, aid, "林師")["partners"][0]["options"]
+ if o["date"] == WED.isoformat())
+ code, body = world.assign(aid, 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
+ return aid
+
+
+def _republish(world, move: tuple[int, int] | None = None) -> dict:
+ """複製目前的課表成新草稿再發布;move=(weekday, period_no) 時先把林師的輔導搬走。"""
+ new = world.client.post(f"/api/timetables/{world.tt}/duplicate", json={"name": "草稿B"}).json()
+ if move is not None:
+ e = next(x for x in new["entries"] if x["weekday"] == 3)
+ r = world.client.patch(f"/api/timetables/{new['id']}/entries/{e['id']}",
+ json={"weekday": move[0], "period_no": move[1]})
+ assert r.status_code == 200, r.json()
+ r = world.client.post(f"/api/timetables/{new['id']}/publish?force=true")
+ assert r.status_code == 200, r.json()
+ world.tt = new["id"]
+ return r.json()
+
+
+def _swap_entry(world) -> ScheduleEntry:
+ world.db.expire_all()
+ sub = world.db.query(Substitution).filter(Substitution.type == "swap").one()
+ return world.db.get(ScheduleEntry, sub.swap_entry_id)
+
+
+def test_republish_keeps_the_makeup_period(w): # noqa: F811
+ _world(w)
+ out = _republish(w)
+ assert out["swap_unlinked"] == 0
+ assert _swap_entry(w).timetable_id == w.tt, "補課那一節接到新課表的格子"
+
+ cls = _week(w, "class", w.classes["701"]).json()
+ assert _at(cls, THU, 5)[0][2] == "swap"
+ assert _at(cls, WED, 6)[0][:3] == ("國文", "王師", "swap"), "補課那格照樣變紅"
+ wang = _week(w, "teacher", w.teachers["王師"]).json()
+ assert _at(wang, WED, 6)[0][2] == "swap", "老師本人的週課表看得到補課那一節"
+
+
+def test_republish_does_not_offer_the_same_period_again(w): # noqa: F811
+ """重新發布後,林師週三第六節已經換給王師補課,不能再換給別人。"""
+ _world(w)
+ _republish(w)
+ w.teacher("張師", ["英文"])
+ # 張師週五 701 英文請假:林師週三那一節不能再拿來對調
+ new = w.client.post(f"/api/timetables/{w.tt}/duplicate", json={"name": "草稿C"}).json()
+ w.tt = new["id"]
+ w.place("張師", "英文", "701", 0, weekday=5)
+ r = w.client.post(f"/api/timetables/{w.tt}/publish?force=true")
+ assert r.status_code == 200, r.json()
+ aid = w.leave("張師", FRI)[0]["id"]
+ partners = _options(w, aid, "林師")["partners"]
+ offered = [o["date"] for p in partners for o in p["options"]]
+ assert WED.isoformat() not in offered
+
+
+def test_moved_lesson_is_reported(w): # noqa: F811
+ """新課表把林師的輔導搬走了:補課那一節已經沒有這堂課,接不上,發布後回報筆數。"""
+ _world(w)
+ slots = [p for p in w.client.get(
+ f"/api/class-units/{w.classes['701']}/period-table").json()["periods"]
+ if p["weekday"] == 2 and p["type"] == "regular"]
+ out = _republish(w, move=(2, slots[0]["period_no"]))
+ assert out["swap_unlinked"] == 1
+ assert _swap_entry(w).timetable_id != w.tt, "不猜,維持原樣"
+
+
+def _migration():
+ path = Path(__file__).resolve().parents[1] / "alembic" / "versions" / "0020_relink_swaps.py"
+ spec = importlib.util.spec_from_file_location("m0020", path)
+ assert spec and spec.loader
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def test_upgrade_relinks_swaps_made_before_v1418(w): # noqa: F811
+ """升級前就已經發生的:調課還指著舊課表的格子,升級後接回目前的課表。"""
+ _world(w)
+ old_entry = _swap_entry(w)
+ _republish(w)
+ # 模擬 v1.4.17 以前:發布時沒有接過去
+ sub = w.db.query(Substitution).filter(Substitution.type == "swap").one()
+ sub.swap_entry_id = old_entry.id
+ w.db.commit()
+ assert _at(_week(w, "class", w.classes["701"]).json(), WED, 6)[0][2] == "normal"
+
+ assert _migration().relink(w.db.connection()) == 1
+ w.db.commit()
+ assert _swap_entry(w).timetable_id == w.tt
+ assert _at(_week(w, "class", w.classes["701"]).json(), WED, 6)[0][2] == "swap"
+ assert _migration().relink(w.db.connection()) == 0, "再跑一次不會重複改"
diff --git a/docs/architecture.html b/docs/architecture.html
index bd485276..a0e7f742 100644
--- a/docs/architecture.html
+++ b/docs/architecture.html
@@ -768,7 +768,7 @@
2.2 核心實體定義
substitution
調代課處置
- 類型:substitute(代課)/swap(調課)/merge(併班)/self_study(自習)/cancel(不處理);代課教師、是否計鐘點、經費來源標記
+ 類型: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 只改資料:把升級前已發生的接回目前已發布的課表
notification
diff --git a/docs/architecture.md b/docs/architecture.md
index 491509aa..5aa611bf 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -196,7 +196,7 @@ erDiagram
| `leave_request` | 請假 | 教師、假別(公/事/病/婚/喪/產/進修)、起訖日期時間、事由、登記人 |
| `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`(不處理);代課教師、是否計鐘點、經費來源標記 |
+| `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 只改資料:把升級前已發生的接回目前已發布的課表 |
| `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 5122bcc8..46e34b43 100644
--- a/docs/deploy/upgrade.html
+++ b/docs/deploy/upgrade.html
@@ -172,7 +172,7 @@
路線圖開發用
開發任務卡開發用
-本頁目錄
+本頁目錄
◐ 切換深色 / 淺色
@@ -190,8 +190,8 @@ 升級指南
開始前先備份。 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見備份指南 。
- 升級到 v1.4.2 ~ v1.4.17:補登、修改假別與計費方式、未請假的調課、批次 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(調課寫出補課日期)都沒有資料表變更,照下方方式 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
v1.4.1 只改了授權(由 MIT 改為 AGPL-3.0),並在登入頁與側邊欄加上「原始碼」連結。功能與資料表都沒有變動 ,
照下方方式 A 或方式 B 一般升級即可;從 v1.3.x 或更早的版本升上來,一樣會經過 v1.4.0 的資料表變更(會先自動備份)。
diff --git a/docs/deploy/upgrade.md b/docs/deploy/upgrade.md
index ba00c521..c4aaf59c 100644
--- a/docs/deploy/upgrade.md
+++ b/docs/deploy/upgrade.md
@@ -8,9 +8,9 @@
> **開始前先備份。** 升級本身不會刪資料,但任何重大操作前留一份備份是好習慣。到「系統管理 → 資料備份與還原 → 立即備份」,或見[備份指南](backup.md)。
-## 升級到 v1.4.2 ~ v1.4.17:補登、修改假別與計費方式、未請假的調課、批次 PDF、登入鎖定資安修正
+## 升級到 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(調課寫出補課日期)都沒有資料表變更,照下方方式 A 或方式 B 一般升級即可。
+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
diff --git a/docs/features.html b/docs/features.html
index e5da4a77..7500d45d 100644
--- a/docs/features.html
+++ b/docs/features.html
@@ -3,7 +3,7 @@
-
+
功能總覽 · 排課與調代課系統