Timekeeping Request Working Schedule Deep Dive

Bộ tài liệu này đào sâu flow timekeeping-request-working-schedule theo code thực tế hiện tại. Đây là package reverse-engineer trong docs/modules, không phải PRD/spec delivery. Mục tiêu là chốt mental model rõ cho 4 lớp rất dễ bị gộp sai:

• request_working_schedule là request/approval engine dùng chung cho nhiều loại đơn, không chỉ timekeeping,
• time_slot_user là lịch làm việc write model trực tiếp đang được page WorkingSchedule mutate không qua approval,
• time_slot_time_keeping và WorkingTimeSheet là read/projection layer, không phải write model gốc,
• side effects lớn nhất của approval nằm ở events: notification, salary updates, timekeeping backfill, chứ không nằm ở page timekeeping.

Đọc file nào?

Bạn là ai?	Nên đọc trước	Mục tiêu
PO / BA	shared-rules.md	Chốt thuật ngữ, state model, boundary giữa request engine và direct schedule
FE Dev	type-direct-schedule-upsert-and-import.md	Hiểu schedule page đang ghi thẳng time_slot_user, import overwrite semantics
BE Dev	type-request-lifecycle-and-approval.md	Hiểu create/update/change-status actions, multi-step approval, event side effects
QA	type-timesheet-merge-and-side-effects.md, shared-rules.md	Tách test request approval khỏi test timesheet projection/export
Người mới vào hệ thống	module-overview.md	Có bản đồ tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: route families, lifecycle, backend boundaries, data layers
shared-rules.md	Thuật ngữ chuẩn, state matrix, invariants, permission/runtime drift
type-request-lifecycle-and-approval.md	Deep dive cho create/update/change-status, request logs, approver chain, notifications
type-direct-schedule-upsert-and-import.md	Deep dive cho WorkingSchedule, upsertTimeSlotUser, import/export, overwrite rules
type-timesheet-merge-and-side-effects.md	Deep dive cho WorkingTimeSheet, merged projection, approval side effects sang salary/timekeeping

Kết luận ngắn

1. request_working_schedule là approval engine generic của HRM, không đồng nghĩa với page "Lịch làm việc".
2. Module timekeeping hiện có một nhánh write bypass approval qua upsertTimeSlotUser và import Excel.
3. WorkingTimeSheet là projection trộn time_slot_time_keeping với request_working_schedule đã approved.
4. Approval status change mới là nơi side effects nặng xảy ra: notification, annual leave balance, salary, timekeeping backfill và các flow ngoại lệ khác.

Liên kết tài liệu liên quan

• docs/modules/timekeeping/overview.md
• docs/modules/salary/overview.md
• docs/modules/settings/overview.md
• docs/modules/user/overview.md
• docs/modules/ecommerce/overview.md
• docs/modules/phase-2-backlog.md

Phạm vi của bộ docs này

• Bám theo code hiện tại của diva-admin, ecommerce-api, Hasura metadata và source hrm + ecommerce.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì quy trình chấm công lý tưởng.
• Chủ động ghi ra drift giữa request engine, direct schedule CRUD, permission menu và timesheet projection.