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.15
# IMAGE_TAG=v1.4.16
# 若你是從原始碼 docker compose up -d 自行建置,此項可忽略。
IMAGE_TAG=latest

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

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

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

## [Unreleased]

## [1.4.16] — 2026-11-10

**修正:跑班顯示、先調課再請假**(LINE 社群組長回報)。

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

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

### 修正
- **跑班 4、5 組也列出每位老師**:v1.4.13 起班級課表的跑班格子 4 組以上只寫「共 N 組」,數學、英語分組常有 4 組,看不到老師。改成 5 組以內都列出老師,6 組以上(社團這類)才寫群組名稱與組數。課表查詢、匯出(Excel、PDF、PNG)、看某一週的課表都一樣;巡堂表仍是 4 組以上另出分組巡堂單。
- **先調課、再請假**:導師要外出一整天,組長先用「新增調課(未請假)」把當天的課調走,再登記請假讓系統排代導——那幾節原本又被列成「待處理」,怎麼處理都不對。現在已經在調課或別張有效假單裡的節次,登記請假時不再列入,完成訊息會寫出哪幾節已在哪一筆裡處理;代導照常產生。同一天重複登記兩張假,也不會再重複列出同樣的節次。
- **銷假後的代導**:假單上「代導:…」那一行在銷假後仍寫「請到調代課處理安排代導老師」,改成「已銷假,代導已取消」;都安排好的寫「都已處理」。

## [1.4.15] — 2026-11-10

**新功能:課表查詢可以看某一週實際的課表;新增常用假別**(老師建議)。
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.15 已發行(2026-11-10)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 772 項單元/整合測試、61 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。
**v1.4.16 已發行(2026-11-10)。** 六大里程碑 M0–M5 全部完成,功能齊備並經完整驗收(後端 778 項單元/整合測試、61 項 Playwright 端對端測試涵蓋全部 20 個頁面,每次提交皆對真實 Docker 全棧跑過)。官方映像(amd64 + arm64)已發布於 GHCR。

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.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.15` 是目前建議使用的版本。各版變更見 [CHANGELOG](CHANGELOG.md),開發歷程見 [docs/tasks.md](docs/tasks.md)。
**請直接從最新版開始安裝**(見上方快速開始);`v1.4.16` 是目前建議使用的版本。各版變更見 [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
8 changes: 6 additions & 2 deletions backend/app/api/leaves.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
LeaveRequestIn,
LeaveRequestOut,
LeaveUpdateIn,
SkippedPeriodOut,
SwapRequestIn,
)
from app.services import leaves as leave_service
Expand Down Expand Up @@ -146,7 +147,7 @@ def create_leave(
on_behalf = teacher.user_id != user.id

try:
leave = leave_service.create(
leave, skipped = leave_service.create(
db, sem, teacher,
leave_type=body.leave_type,
start_date=body.start_date, start_time=body.start_time,
Expand All @@ -170,7 +171,10 @@ def create_leave(
))
db.commit()
db.refresh(leave)
return _serialize(leave)
out = _serialize(leave)
out.skipped = [SkippedPeriodOut(date=s.day, period_name=s.period_name, taken_by=s.taken_by)
for s in skipped]
return out


@router.get("/leaves", response_model=list[LeaveRequestOut])
Expand Down
10 changes: 10 additions & 0 deletions backend/app/schemas/leave.py
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,14 @@ class LeaveUpdateIn(BaseModel):
reason: str | None = Field(default=None, max_length=200)


class SkippedPeriodOut(BaseModel):
"""登記請假時沒列入的一節:它已經在別張假單或「調課(未請假)」裡(v1.4.16)。"""

date: date
period_name: str
taken_by: str


class DayPeriodOut(BaseModel):
"""這位老師這一天的一節課(新增調課時勾選,v1.4.5)。"""

Expand Down Expand Up @@ -115,6 +123,8 @@ class LeaveRequestOut(BaseModel):
affected_periods: list[AffectedPeriodOut] = []
homeroom_covers: list[HomeroomCoverOut] = []
cover_pending_count: int = 0 # 還沒安排的代導(天次)
# 只有登記時回傳:已經在別張假單或調課裡、這次沒列入的節次(v1.4.16)
skipped: list[SkippedPeriodOut] = []


class LeaveCancelled(BaseModel):
Expand Down
45 changes: 37 additions & 8 deletions backend/app/services/leaves.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
"""

from collections.abc import Iterator
from dataclasses import dataclass
from datetime import date, datetime, time, timedelta

from sqlalchemy import select
Expand Down Expand Up @@ -244,6 +245,15 @@ def expand_covers(db: Session, leave: LeaveRequest) -> list[HomeroomCover]:
return out


@dataclass(frozen=True, slots=True)
class Skipped:
"""登記請假時沒列入的一節:它已經在別張假單或調課裡(v1.4.16)。"""

day: date
period_name: str
taken_by: str # 那張的假別名稱,例如「調課(未請假)」


def cover_is_past(day: date) -> bool:
"""代導以天為單位:那一天過完了才算代過(當天仍可改派、銷假仍會取消)。"""
return day < clock.school_today()
Expand Down Expand Up @@ -279,8 +289,13 @@ def create(
created_by_user_id: int | None,
created_by_name: str,
notify_teacher: bool,
) -> LeaveRequest:
"""登記請假並展開受影響節次。呼叫端負責 commit。"""
) -> tuple[LeaveRequest, list[Skipped]]:
"""登記請假並展開受影響節次。呼叫端負責 commit。

已經在別張有效假單或「調課(未請假)」裡的節次不再列入,回傳在第二個值(v1.4.16,
組長回報:導師先把當天的課調走,再請假讓系統排代導,那兩節又變成待處理,怎麼處理都不對)。
同一節不能處理兩次——和「新增調課」的檢查同一條規則,只是反過來。
"""
validate(semester, start_date, end_date)
if start_date == end_date and start_time and end_time and end_time <= start_time:
raise LeaveError("結束時間不可早於開始時間")
Expand All @@ -294,7 +309,13 @@ def create(
db.add(leave)
db.flush()

taken = taken_slots(db, teacher.id, start_date, end_date)
skipped: list[Skipped] = []
for period in expand(db, leave):
label = taken.get((period.date, period.period_no))
if label:
skipped.append(Skipped(period.date, period.period_name, label))
continue
db.add(period)
for cover in expand_covers(db, leave):
db.add(cover)
Expand All @@ -311,7 +332,7 @@ def create(
title=f"{created_by_name} 已為您登記{LEAVE_TYPE_CN[leave.leave_type]}",
body=body,
)
return leave
return leave, skipped


def day_periods(
Expand All @@ -329,19 +350,27 @@ def day_periods(
return sorted(expand(db, probe), key=lambda p: p.period_no)


def taken_periods(db: Session, teacher_id: int, day: date) -> dict[int, str]:
"""這一天已經在別張有效假單(或調課)裡的節次 → 那張的假別名稱。同一節不能處理兩次。"""
def taken_slots(
db: Session, teacher_id: int, start: date, end: date
) -> dict[tuple[date, int], str]:
"""這段期間已經在有效假單(或調課)裡的節次 → 那張的假別名稱。同一節不能處理兩次。"""
rows = db.execute(
select(AffectedPeriod.period_no, LeaveRequest.leave_type)
select(AffectedPeriod.date, AffectedPeriod.period_no, LeaveRequest.leave_type)
.join(LeaveRequest, AffectedPeriod.leave_request_id == LeaveRequest.id)
.where(
LeaveRequest.teacher_id == teacher_id,
LeaveRequest.status == LeaveStatus.registered.value,
AffectedPeriod.date == day,
AffectedPeriod.date >= start,
AffectedPeriod.date <= end,
AffectedPeriod.status != AffectedStatus.cancelled.value,
)
).all()
return {no: LEAVE_TYPE_CN.get(lt, lt) for no, lt in rows}
return {(d, no): LEAVE_TYPE_CN.get(lt, lt) for d, no, lt in rows}


def taken_periods(db: Session, teacher_id: int, day: date) -> dict[int, str]:
"""這一天已經在別張有效假單(或調課)裡的節次 → 那張的假別名稱。"""
return {no: label for (_, no), label in taken_slots(db, teacher_id, day, day).items()}


def create_swap_request(
Expand Down
3 changes: 3 additions & 0 deletions backend/app/services/patrol_sheets.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@

CLASSES_PER_PAGE = 12 # A4 橫式一頁放得下的班級欄數(照使用學校的紙本)
GROUP_LIST_MIN = 4 # 群組在同一節有幾門課以上,就改列成分組巡堂單
# 班級、場地課表的一格:群組有幾組以上才只寫「共 N 組」(v1.4.16,組長回報:數學、英語分組
# 有 4 組,原本門檻 4 看不到老師)。分組教學多半 5 組以內,社團才會更多。巡堂表另有分組巡堂單,維持 4。
GRID_GROUP_LIST_MIN = 6
MAX_DAYS = 14 # 一次最多印幾天
_NOON = time(12, 0)

Expand Down
Loading
Loading