Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ HTTP_PORT=80
# ── 預建映像版本(僅「拉取映像」部署方式需要)──────────
# 用 docker compose pull 拉官方映像時,決定要拉哪一版。
# 預設 latest(最新);正式部署建議釘選版本號以利可控升級,例如:
# IMAGE_TAG=v1.4.21
# IMAGE_TAG=v1.4.22
# 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。
IMAGE_TAG=latest

Expand Down
29 changes: 28 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,37 @@

破壞性變更(需人工介入才能升級)以 ⚠️ 標註。

> **新使用者請直接安裝 v1.4.21**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.20 是先前版本;以下條目保留作為變更紀錄。
> **新使用者請直接安裝 v1.4.22**(見 [README](README.md) 快速開始)。v1.0.0 ~ v1.4.21 是先前版本;以下條目保留作為變更紀錄。

## [Unreleased]

## [1.4.22] — 2026-11-19

**寒暑假輔導**(組長許願):學期多了「寒假輔導」「暑期輔導」兩種,另外排一份輔導課表,
請假、代課、調課照常使用。

沒有資料表變更,照一般方式升級即可(`.env` 改 `IMAGE_TAG=v1.4.22` → `docker compose pull && docker compose up -d`)。

官方映像(amd64 + arm64 雙架構)已發布於 GHCR:
`ghcr.io/begin0808/course_scheduling_system-{api,worker,web}:v1.4.22`

### 新增
- **寒暑假輔導學期**:「學期與節次表」建立學期或「複製到新學期」時,學期別可選「寒假輔導」「暑期輔導」,
名稱寫成「115 學年度暑期輔導」。
- 起訖日期必填,而且**不能和其他學期重疊**(請假、代課是依日期判斷屬於哪個學期);重疊時寫出撞到哪一個學期。
- 各校差異都用現有設定:哪幾個年級(複製時帶班級、刪掉沒有輔導的班)、幾週(起訖日期)、
每天幾節(輔導學期自己的節次表)。併班上課就另外新增班級,或用跑班群組。
- 複製成輔導學期時預設同一學年度、班級年級不進位,日期清空讓組長照校曆填。
- **不管基本鐘點與超鐘點**:配課畫面改列「教師輔導節數」(每週幾節),不受「超鐘點上限」限制,
排課前檢查也不提示「超出應授鐘點」。
- 排課、發布、課表查詢與匯出、請假、代課、調課、併班、停課日、調代課單都和一般學期一樣;
調課單抬頭寫「115學年暑期輔導」。

### 改善
- **各頁預設選「今天所在的學期」**:學期清單改照日期由新到舊排列,請假、調代課、配課、儀表板等頁面
預設選今天落在起訖日期內的學期(沒有才選最新的)。先建好下學期或暑期輔導,
每天處理的請假與代課也不會跳到還沒開始的學期。

## [1.4.21] — 2026-11-18

**三角調課可以指定老師,湊不成時寫出原因**(組長回報:三角調課的清單裡找不到某位老師)。
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,11 +132,11 @@ docker compose up -d # 首次會建置映像,需數分鐘

## 專案狀態

**v1.4.21 已發行(2026-11-18)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 808 項單元/整合測試、63 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
**v1.4.22 已發行(2026-11-19)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 815 項單元/整合測試、64 項 Playwright 端對端測試涵蓋全部 21 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。

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.22 新增**寒暑假輔導**學期(另排輔導課表,請假代課照常,不算超鐘點);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.21` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。
**請直接從最新版開始安裝**(見上方快速開始);`v1.4.22` 是目前建議使用的版本。各版變更見 [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) 回報任何問題。

Expand Down
46 changes: 38 additions & 8 deletions backend/app/api/semesters.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
權限:讀取 = 教學組長/教務主任;寫入 = 教學組長(admin 一律通過)。
"""

from datetime import date

from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy import func, select
from sqlalchemy.orm import Session
Expand All @@ -11,7 +13,7 @@
from app.core.db import get_db
from app.models.basedata import ClassUnit, Room, Subject, Teacher
from app.models.period import Period, PeriodTable
from app.models.semester import Semester
from app.models.semester import TUTORING_TERMS, Semester, sorted_semesters
from app.models.user import Role
from app.schemas.semester import (
AvailableSlot,
Expand Down Expand Up @@ -52,6 +54,32 @@ def _get_period_table(db: Session, table_id: int) -> PeriodTable:
return table


def _check_dates(
db: Session, term: int, start: date | None, end: date | None, exclude_id: int | None = None
) -> None:
"""寒暑假輔導(v1.4.22)要填起訖日期,且不能和其他學期重疊。

請假、代課是依日期落在哪個學期來判斷;輔導學期通常在學期進行中就先建好,
日期一重疊就分不清楚。只檢查「有一邊是輔導」的組合,一般學期之間照舊不擋。
"""
tutoring = term in TUTORING_TERMS
if tutoring and (start is None or end is None):
raise HTTPException(status.HTTP_400_BAD_REQUEST, "寒暑假輔導要填開始日與結束日")
if start is None or end is None:
return
for other in db.scalars(select(Semester).where(Semester.id != (exclude_id or 0))):
if other.start_date is None or other.end_date is None:
continue
if not tutoring and not other.is_tutoring:
continue
if start <= other.end_date and other.start_date <= end:
raise HTTPException(
status.HTTP_409_CONFLICT,
f"日期和「{other.label}」({other.start_date:%Y/%m/%d}~{other.end_date:%Y/%m/%d})"
"重疊;寒暑假輔導的日期不能和其他學期重疊",
)


def _unset_other_defaults(db: Session, semester_id: int, keep_id: int | None) -> None:
others = db.scalars(
select(PeriodTable).where(
Expand Down Expand Up @@ -80,9 +108,7 @@ def list_templates(_: object = Depends(viewer)) -> list[TemplateOut]:
# ── 學期 ──────────────────────────────
@router.get("/semesters", response_model=list[SemesterListItem])
def list_semesters(db: Session = Depends(get_db), _: object = Depends(viewer)):
return db.scalars(
select(Semester).order_by(Semester.academic_year.desc(), Semester.term.desc())
).all()
return sorted_semesters(db.scalars(select(Semester)).all())


@router.post("/semesters", response_model=SemesterOut, status_code=status.HTTP_201_CREATED)
Expand All @@ -96,6 +122,7 @@ def create_semester(
)
if exists:
raise HTTPException(status.HTTP_409_CONFLICT, "該學年度學期已存在")
_check_dates(db, body.term, body.start_date, body.end_date)

if body.template_key:
if tpl.get_template(body.template_key) is None:
Expand Down Expand Up @@ -138,6 +165,7 @@ def copy_to_new_semester(
)
if exists:
raise HTTPException(status.HTTP_409_CONFLICT, "目標學年度學期已存在")
_check_dates(db, body.term, body.start_date, body.end_date)
opts = CopyOptions(
period_tables=body.period_tables,
subjects=body.subjects,
Expand Down Expand Up @@ -191,10 +219,12 @@ def update_semester(
data = body.model_dump(exclude_unset=True)
if "status" in data and data["status"] is not None:
semester.status = data["status"].value
if "start_date" in data:
semester.start_date = data["start_date"]
if "end_date" in data:
semester.end_date = data["end_date"]
start = data["start_date"] if "start_date" in data else semester.start_date
end = data["end_date"] if "end_date" in data else semester.end_date
if "start_date" in data or "end_date" in data:
_check_dates(db, semester.term, start, end, exclude_id=semester.id)
semester.start_date = start
semester.end_date = end
db.commit()
db.refresh(semester)
return semester
Expand Down
10 changes: 6 additions & 4 deletions backend/app/api/timetables.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
from app.models.assignment import CourseAssignment
from app.models.basedata import ClassUnit, Room, Teacher
from app.models.period import PeriodTable
from app.models.semester import Semester
from app.models.semester import Semester, sorted_semesters
from app.models.timetable import ScheduleEntry, Timetable, TimetableStatus
from app.models.user import Role, User
from app.schemas.timetable import (
Expand Down Expand Up @@ -306,9 +306,11 @@ def published_semesters(db: Session = Depends(get_db), _: User = Depends(get_act
select(Semester)
.join(Timetable, Timetable.semester_id == Semester.id)
.where(Timetable.status == TimetableStatus.published.value)
.order_by(Semester.academic_year.desc(), Semester.term.desc())
).all()
return [PublicSemester(id=s.id, label=s.label) for s in rows]
).unique().all()
return [
PublicSemester(id=s.id, label=s.label, start_date=s.start_date, end_date=s.end_date)
for s in sorted_semesters(rows)
]


@router.get("/published/my-teacher", response_model=NamedBrief | None)
Expand Down
Loading
Loading