# Ghi chú phát hành — Nhập công OT (mode `workday`)

Những điều cần nói ra khi tính năng này lên production. Ba mục đầu là **thay đổi hành vi hoặc
giới hạn đã biết** — không nói trước thì sẽ bị báo ngược lại là bug. Mục cuối là điều kiện dữ
liệu cần chuẩn bị.

Dòng ngắn để dán vào `CHANGELOG.md` nằm ở cuối file.

---

## 1. Con số OT tháng trên màn hình yêu cầu tăng ca sẽ **tăng**

*(task 11.4 — Decision 8 của design.md)*

**Ảnh hưởng mọi công ty, kể cả công ty không dùng mode công.**

Trước đây thẻ "Tổng thời gian" cộng mỗi yêu cầu **một lần**, bất kể yêu cầu đó gắn bao nhiêu
nhân viên. Một yêu cầu 4 giờ gắn 5 người được tính là 4 giờ.

Từ bản này, con số được tính **theo từng nhân viên**: yêu cầu đó tính thành 20 giờ.

| | Trước | Sau |
|---|---|---|
| Admin, yêu cầu 4 giờ gắn 5 người | 4 giờ | 20 giờ |
| Quản lý, quản 2 trong 5 người đó | 4 giờ | 8 giờ |
| Yêu cầu chỉ gắn 1 người | 4 giờ | 4 giờ — không đổi |

**Đây là sửa chỗ đếm thiếu trước đây, không phải lỗi mới.** Công ty nào có thói quen tạo một
yêu cầu cho cả nhóm sẽ thấy con số nhảy lên rõ rệt ngay sau khi deploy; công ty nào luôn tạo
riêng từng người thì không thấy gì đổi.

Hai con số còn lại — "Tổng yêu cầu" và "Tổng nhân viên" — **không đổi**.

Có hai trường hợp biên con số sẽ **giảm**, cần kiểm tra trước khi deploy vì nó khó giải thích hơn:

- Yêu cầu chỉ gắn một nhân viên, mà tài khoản đó **đã bị xoá** → trước có tính, nay không
  (nhân viên **đã nghỉ việc** nhưng tài khoản còn thì vẫn tính như cũ)
- Yêu cầu **không gắn nhân viên nào** → trước có tính, nay không

Trên dev cả hai đều bằng 0 hàng. Nên chạy lại cùng truy vấn trên bản copy dữ liệu thật trước
khi lên (kèm trong task 11.1).

## 2. Yêu cầu OT chỉ vào lương khi ngày đó đã có dòng chấm công

*(task 11.3)*

Đúng với **cả hai mode**, không riêng mode công — nhưng mode công **dễ gặp hơn hẳn**, vì nó sinh
ra chính để dùng cho những ngày chấm công thiếu hoặc không có.

Yêu cầu OT được ghi nhận vào bảng công thông qua dòng timesheet của nhân viên trong ngày đó.
Ngày nào chưa có dòng timesheet thì số công OT đã duyệt vẫn nằm yên trong yêu cầu, chưa chảy
vào bảng lương.

Thẻ thống kê đầu trang thì **không** chịu giới hạn này — nó đọc thẳng từ yêu cầu, nên một yêu
cầu vừa duyệt là đếm ngay, kể cả cho ngày tương lai. Nghĩa là **thẻ thống kê và bảng lương có
thể lệch nhau** trong thời gian chấm công chưa chạy. Đây là chủ ý, không phải lỗi.

## 3. Đổi ca giữa tháng làm lệch giữa thẻ thống kê và bảng công

*(Decision 6 của design.md)*

Phần kiểm tra lúc tạo yêu cầu và phần quy đổi trên thẻ thống kê lấy **ca hiện tại** của nhân
viên. Bảng công thì lấy **ca đã lưu trên chính dòng timesheet** của ngày đó.

Bình thường hai cái là một. Nhưng nếu nhân viên đổi ca giữa tháng và hai ca có `work_ratio`
khác nhau, thì với những ngày **trước** lúc đổi:

- Thẻ thống kê quy đổi theo ca **mới**
- Bảng công đã tính theo ca **cũ**

→ hai con số không khớp. Ngưỡng tối thiểu báo ra lúc tạo yêu cầu cũng theo ca mới.

Mức độ ảnh hưởng phụ thuộc công ty có hay đổi ca giữa kỳ không. Nếu hiếm thì bỏ qua được; nếu
thường xuyên thì cần tính lại công sau mỗi lần đổi ca.

## 4. Điều kiện dữ liệu: nhân viên phải có ca, công ty phải có đủ setting

Mode công quy ngược số công đã nhập thành số giờ OT để so với ngưỡng tối thiểu. Phép quy ngược
cần `hệ số OT × work_ratio của ca` khác 0. Nếu bằng 0, yêu cầu bị từ chối với
`overtime_workday_cannot_be_evaluated`.

Trước khi mở tính năng cho một công ty, kiểm tra:

- [ ] Mọi nhân viên sẽ dùng mode công đều **đã được gán ca**, và ca đó có `work_ratio > 0`
- [ ] Công ty **có** dòng setting `overtime_ratio` và `overtime_day_off_ratio`, giá trị > 0
- [ ] Ngày lễ đã khai đều có `work_ratio`, không để trống

Lưu ý về setting: hệ thống trả cùng một lỗi cho hai tình huống khác nhau — **đã set bằng 0** và
**chưa có dòng setting nào**. Câu lỗi nói "is zero" trong cả hai trường hợp. Nếu gặp lỗi này mà
nhìn trên UI thấy setting vẫn bình thường, kiểm tra xem dòng setting có thực sự tồn tại trong DB
không.

---

## Dòng cho `CHANGELOG.md`

Dán vào mục version khi cắt bản phát hành:

```
- Overtime | Added workday input mode for overtime requests !747
- Overtime | Updated monthly overtime total to count each request once per employee !747
```
