# 加班補休計算規則說明

> 適用對象：梁丹妮（員工 44）
> 資料範圍：2026 年 1〜3 月
> 更新日期：2026-03-23

---

## 一、資料來源

月份工作表（`2026.01`、`2026.02`、`2026.03`）各欄定義：

| 欄位 | 欄號 | 說明 |
|------|------|------|
| A | 員工姓名 | |
| B | 日期 | `YYYY-MM-DD` |
| C | 星期 | |
| D | 屬性 | `上班日`、`上班日加班`、`休息日`…等 |
| E | 上班打卡 | `HH:MM` |
| F | 下班打卡 | `HH:MM` |
| G | 應上下班時間 | 含「應上班 HH:MM」及「應下班 HH:MM」 |
| H | 工作時數 | |
| I | 午晚休時數（小時數，整數） | |
| J | 扣除午晚休後工時 | |
| K | 實際工時扣除應上班工時 | |
| L | 加班時數（小時，含小數） | |
| M | 備註 | |
| N | 選擇請領加班費 | |
| O | 選擇補休 | |

---

## 二、加班記錄篩選條件

**只要 L > 0 即納入計算**，不限 D 欄屬性。
（D 欄可能為「上班日加班」「上班日」「休息日」，只要有加班時數都須記錄）

以下日期之加班序號已手動預存於表中，不重複計算：
- `2026-01-02`（seq 1）

---

## 三、加班 OT 時段計算

依 D 欄屬性決定 OT 開始時間：

### 3.1 上班日加班（D 含「上班日加班」）

OT 時段 = **E 欄打卡時間** ～ **F 欄打卡時間**

### 3.2 上班日（D 含「上班日」但不含「加班」）

OT 時段 = **G 欄應下班時間** ～ **F 欄打卡時間**

解析方式：在 G 欄字串中用正規表達式找出「應下班 HH:MM」。

### 3.3 休息日（D 含「休息日」）

OT 時段 = **E 欄打卡時間** ～ **F 欄打卡時間**（適用不同 tier 規則）

---

## 四、中場休息處理

### 4.1 標準工作日（上班日 / 上班日加班）

- **條件**：I >= 1 且 OT 時段橫跨 20:00
- **動作**：在 20:00～21:00 插入晚餐休息空檔
- **結果**：OT 分為兩段：`[OT_start, 20:00]` 和 `[21:00, OT_end]`
- **若 I = 0**：OT 時段連續，不插入休息空檔（即便超過 20:00）

範例：
- `2026-01-09`：E=18:00, F=22:00, I=1 → 兩段：(18:00~20:00) + (21:00~22:00)
- `2026-03-17`：E=18:00, F=20:30, I=0 → 單段：(18:00~20:30)（連續，無中斷）

### 4.2 休息日（D 含「休息日」）

- **條件**：I >= 1
- **動作**：在 **E+2h ～ E+3h** 插入休息空檔（一小時）
- **結果**：OT 分為兩段：`[E, E+2h]` 和 `[E+3h, F]`

範例：
- `2026-02-08`：E=13:30, I=1 → 休息 15:30~16:30 → 兩段：(13:30~15:30) + (16:30~21:00)

---

## 五、加班 Tier（類型）分類

### 5.1 標準工作日 Tier

依**當日累積加班分鐘數**（跨多段 OT 時須連續累積）決定 tier：

| 累積加班 | Tier 標籤 |
|----------|-----------|
| 0 ～ 60 分鐘（第 1 小時） | 一般第8小時 |
| 60 ～ 180 分鐘（第 2〜3 小時） | 一般第9至第10小時 |
| 180 分鐘以上（第 4 小時起） | 一般第11至第12小時 |

### 5.2 休息日 Tier

| 累積加班 | Tier 標籤 |
|----------|-----------|
| 0 ～ 120 分鐘（前 2 小時） | 休息日第1至第2小時 |
| 120 分鐘以上（第 3 小時起） | 休息日第3至第8小時 |

### 5.3 同日多段 OT 的累積計算

同一天若有多個 OT 時段（例如早上和晚上各一段），需**按 OT 開始時間排序**，並將前一段的累積分鐘數帶入下一段的 tier 計算。

範例：`2026-02-02`
- 早上：08:30〜10:30（2 小時）→ 一般第8小時(08:30~09:30) + 一般第9至第10小時(09:30~10:30)
- 晚上：18:30〜20:00（1.5 小時）；當日累積已達 120 分鐘 →
  一般第9至第10小時(18:30~19:30) + 一般第11至第12小時(19:30~20:00)

---

## 六、加班登記表（`2026年加班登記表`）

每筆 OT 記錄依 tier 拆分後寫入一行，欄位為：

| 欄位 | 說明 |
|------|------|
| B | 加班序號（流水號，從 1 開始） |
| C | 選擇補休之加班日期（`YYYY/M/D`） |
| D | 加班開始時間 |
| E | 加班結束時間 |
| F | 加班時數（`H:MM` 格式） |
| G | 加班類型（tier 標籤） |

- H2 記錄所有加班序號的**累積時數合計**
- Seq 1 為 2026/1/2 手動預存，Seq 2 起由程式自動填入
- 若同一段 OT 跨越多個 tier，則拆成多行（各行共用同一日期）

---

## 七、補休登記表（`2026年加班選擇補休登記表`）

### 7.1 補休時數計算

補休時數 = 補休結束時間 − 補休開始時間（直接相減，無需調整）

### 7.2 加班序號 FIFO 消耗

- 加班序號按**由小到大（最早序號優先）**的順序消耗
- 每個序號的可用分鐘數 = 其對應的 OT tier 時長
- 一次補休可跨多個序號（餘額不足時繼續取下一個序號）
- 補休登記表 G 欄記錄本次補休消耗的序號（以「、」分隔）

### 7.3 月份剩餘時數

補休登記表各月「加班合計」行的 H 欄記錄**截至當月結束的加班餘額**：

```
1月剩餘 = 1月累積加班時數 − 截至1月底的累積補休時數
2月剩餘 = 1月剩餘 + 2月累積加班時數 − 2月補休時數
```

---

## 八、2026 年 1〜3 月統計摘要

| 月份 | 加班時數 | 補休使用 | 月末剩餘 |
|------|----------|----------|----------|
| 1 月 | 34:45 | 10:15 | 24:30 |
| 2 月 | 21:30 | 38:00 | 8:00 |
| 3 月 | 9:30 | 尚餘於帳 | — |
| **合計** | **65:45** | — | — |

> 3 月補休均已在 3/5〜3/23 期間補休完畢（消耗 3 月以前累積餘額），詳見補休登記表。

---

## 九、特殊情形備注

1. **2026-02-08（休息日）**：I=1，起始時間 13:30，休息在 15:30〜16:30（E+2h），OT 分兩段：13:30〜15:30（2h，休息日第1至第2小時）、16:30〜21:00（4:30，休息日第3至第8小時）。

2. **2026-02-07（上班日）**：G 欄應下班時間為 19:00，OT 從 19:00 開始；I=2（當日有 2 段休息），晚餐休息 20:00〜21:00 插入，OT 分兩段：19:00〜20:00 及 21:00〜23:30。

3. **同日多段 OT**：2/2、2/4、2/6 等日期有早晚各一段 OT，tier 依全日累積計算。

---

## 十、自動化程式說明

主程式：`fill_overtime.py`

執行指令：
```bash
su debian -c "python3 fill_overtime.py"
```

執行後會自動：
1. 讀取 `2026.01`、`2026.02`、`2026.03` 三個月份工作表（L>0 之所有行）
2. 計算各 OT 時段、tier、中場休息
3. 清除並重新填入「2026年加班登記表」seq 2 起的所有行
4. FIFO 消耗補休登記表各行的加班時數
5. 填入「2026年加班選擇補休登記表」F、G 欄（補休時數、使用加班序號）
6. 填入 1、2 月補休合計行的剩餘時數（H 欄）