Shared Rules — Timekeeping Request Working Schedule

1. Thuật ngữ chuẩn

Thuật ngữ	Nghĩa trong hệ thống
Request working schedule	Record ở request_working_schedule; generic request object cho nhiều loại đơn
Direct schedule	Bản ghi time_slot_user được tạo/sửa trực tiếp từ page lịch làm việc hoặc import
Timesheet	Projection time_slot_time_keeping cộng với overlay của approved requests
Request log	Audit trail ở request_log cho approve/reject/cancel/step transitions
Original slot	time_slot_user gốc mà request như change_shift đang tham chiếu qua original_slot_id

2. State Matrix

2.1 request_working_schedule

State	Dấu hiệu DB	Ý nghĩa
Pending	status_id = pending	Chờ duyệt bước hiện tại
Approved step one	status_id = approved_step_one	Đã qua một bước duyệt nhưng chưa final
Approved	status_id = approved	Final approved, được đưa vào side effects/projection
Rejected	status_id = rejected	Bị từ chối
Canceled / recalled	status_id = canceled hoặc recalled	Bị hủy/thu hồi theo semantics riêng

2.2 time_slot_user

State	Dấu hiệu DB	Ý nghĩa
Active slot	disabled = false	Ca làm việc tuần đang có hiệu lực
Deleted/overwritten	Bị delete trong mutation import/upsert range	Không còn trong lịch tuần hiện hành

3. Invariants

1. Chỉ request ở trạng thái pending mới được updateDataRequestWorkingSchedule.
2. Không phải ai cũng được approve/reject; changeStatusRequestWorkingSchedule kiểm tra reviewer chain và owner rules.
3. WorkingTimeSheet chỉ overlay approved requests.
4. Import lịch làm việc là destructive update theo tuần/user, không giữ lại slot cũ trong range.
5. time_slot_user.requests chỉ nối sang các request qua original_slot_id, tức request overlay là sidecar của slot gốc chứ không thay trực tiếp slot record.

4. Boundary Rules

Boundary	Rule
timekeeping -> settings	Shift template/group là source để build slot từ form/import
timekeeping -> user	Department/branch/account filters quyết định tập user được nhìn/sửa
timekeeping -> salary	Approve/cancel một số request sẽ recalc salary và ngày công
timekeeping -> ecommerce/projects	Cùng request engine còn chạm negative payment, device handover, doctor commission, task status

5. Những điều dễ hiểu nhầm

5.1 "Lịch làm việc" không đồng nghĩa "đơn lịch làm việc"

Page WorkingSchedule hiện đang thao tác time_slot_user trực tiếp. Nó không phải UI của createRequestWorkingSchedule.

5.2 Approved request không đồng nghĩa slot gốc đã bị rewrite

Timesheet UI overlay approved request từ store và request metadata. Một phần semantics được render ở component, không phải luôn phản ánh bằng mutation trực tiếp vào slot record.

5.3 Request engine là generic, không phải domain-pure

Cùng request_working_schedule engine đang xử lý leave, remote, clock in/out, device, negative payment, doctor commission. Vì vậy mọi rule change ở engine này có blast radius vượt timekeeping.

6. Checklist QA ngắn

1. Tách test direct schedule create/import khỏi test request approval.
2. Test import overwrite theo tuần với nhiều user, không chỉ test insert thành công.
3. Test multi-step approval và trạng thái approved_step_one.
4. Test timesheet popup hiển thị approved requests đúng ngày và đúng behavior.
5. Test side effects approval/reject lên annual leave balance, timekeeping flags và salary where applicable.