10. ĐẶC TẢ GIAO DIỆN (UI SPECIFICATION)
Tài liệu này định nghĩa danh mục mã màn hình (Screen Catalog) và đặc tả chi tiết các trường dữ liệu (Fields), cấu trúc Payload, và điều kiện hiển thị cho từng màn hình UI trong hệ thống HRM.
10.1 Danh mục màn hình UI (Screen Catalog)
| Screen ID |
Tên Màn Hình / Giao Diện |
Phân Hệ |
Tác Nhân Chính |
Use Case Ánh Xạ |
| SCR-HR-01 |
Danh sách nhân sự & Bộ lọc |
Hồ sơ nhân sự |
HR, Manager, Admin |
UC-HR-01 |
| SCR-HR-02 |
Chi tiết hồ sơ nhân sự |
Hồ sơ nhân sự |
Employee, HR, Manager |
UC-HR-02 |
| SCR-HR-03 |
Form Thêm mới nhân sự |
Hồ sơ nhân sự |
HR, Admin |
UC-HR-03 |
| SCR-HR-04 |
Form Cập nhật hồ sơ cá nhân |
Hồ sơ nhân sự |
Employee, HR |
UC-HR-04 |
| SCR-HR-05 |
Popup Liên kết tài khoản User |
Hồ sơ nhân sự |
HR, Admin |
UC-HR-05 |
| SCR-HR-06 |
Popup Xuất hồ sơ ra Word |
Hồ sơ nhân sự |
HR |
UC-HR-06 |
| SCR-HR-07 |
Popup Import nhân sự từ Excel |
Hồ sơ nhân sự |
HR, Admin |
UC-HR-07 |
| SCR-HR-08 |
Màn hình Phê duyệt thay đổi hồ sơ |
Hồ sơ nhân sự |
HR, Manager |
UC-HR-08 |
| SCR-LV-01 |
Màn hình Xem quỹ phép cá nhân |
Quản lý phép |
Employee, Manager |
UC-LV-01 |
| SCR-LV-02 |
Form Khởi tạo đơn xin nghỉ phép |
Quản lý phép |
Employee |
UC-LV-02 |
| SCR-LV-03 |
Danh sách đơn xin nghỉ phép |
Quản lý phép |
Employee, Manager, HR |
UC-LV-03 |
| SCR-LV-04 |
Màn hình Duyệt đơn nghỉ phép (2 cấp) |
Quản lý phép |
Manager, HR |
UC-LV-04 |
| SCR-LV-05 |
Popup Yêu cầu Hủy đơn nghỉ phép |
Quản lý phép |
Employee, HR |
UC-LV-05 |
| SCR-LV-06 |
Lịch nghỉ phép phòng ban (Calendar) |
Quản lý phép |
Employee, Manager, HR |
UC-LV-06 |
| SCR-ATT-01 |
Giao diện Tự chấm công (Web/App Check-in) |
Chấm công |
Employee |
UC-ATT-01 |
| SCR-ATT-02 |
Form Chấm công bổ sung (Manual Punch) |
Chấm công |
HR, Admin |
UC-ATT-02 |
| SCR-ATT-03 |
Nhật ký chấm công cá nhân |
Chấm công |
Employee, Manager |
UC-ATT-03 |
| SCR-ATT-04 |
Form Nộp đơn giải trình chấm công |
Chấm công |
Employee |
UC-ATT-04 |
| SCR-TS-01 |
Màn hình Chốt / Mở chốt bảng công |
Bảng công |
HR, Admin |
UC-TS-01 |
| SCR-TS-02 |
Giao diện Kích hoạt máy tính công |
Bảng công |
HR, Admin |
UC-TS-02 |
| SCR-TS-03 |
Bảng công cá nhân chi tiết |
Bảng công |
Employee, Manager |
UC-TS-03 |
| SCR-TS-04 |
Ma trận bảng công tổng hợp công ty |
Bảng công |
HR, Manager, Admin |
UC-TS-04 |
| SCR-LOG-01 |
Báo cáo tổng hợp tháng (Monthly Summary) |
Log & Báo cáo |
Employee, Manager, HR |
UC-LOG-01 |
| SCR-LOG-02 |
Giao diện Kích hoạt Recompute báo cáo |
Log & Báo cáo |
HR, Admin |
UC-LOG-02 |
| SCR-LOG-03 |
Giao diện Chốt báo cáo push sang Payroll |
Log & Báo cáo |
HR, Admin |
UC-LOG-03 |
10.2 Đặc tả chi tiết các trường dữ liệu (Field Specification)
Các bảng dưới đây đặc tả chi tiết danh mục trường dữ liệu (Payload & Form Controls) cho từng màn hình tương tác chính theo chuẩn Canonical Professional v5.
Màn hình / Payload: Quản lý Hồ sơ nhân sự (SCR-HR-01 đến SCR-HR-08)
| Field (Trường) |
Data/UI Type |
Required |
Default |
Validation / Source |
Display Condition |
Notes / Impact |
employeeCode |
Text / String |
Yes |
Tự sinh |
Phải duy nhất. Format: EMP-YYYY-XXXX |
Luôn hiển thị (Read-only) |
Dùng làm định danh in thẻ nhân viên. |
firstName |
Text / String |
Yes |
None |
Max 50 chars. Không chứa ký tự đặc biệt. |
Luôn hiển thị |
Hiển thị trên mọi danh sách. |
lastName |
Text / String |
Yes |
None |
Max 50 chars. Không chứa ký tự đặc biệt. |
Luôn hiển thị |
|
email |
Email |
Yes |
None |
Phải đúng chuẩn Email. Phải duy nhất. |
Luôn hiển thị |
Dùng làm tài khoản đăng nhập (SSO). |
phoneNumber |
Text / String |
Yes |
None |
10-11 số, bắt đầu bằng 0 hoặc +84. |
Luôn hiển thị |
Dùng gửi SMS OTP nếu cần. |
dob |
Datepicker |
Yes |
None |
Tuổi >= 18 tính từ ngày hiện tại. |
Luôn hiển thị |
Dùng tính tuổi, sinh nhật. |
joinDate |
Datepicker |
Yes |
Ngày hiện tại |
Không được sau ngày hiện tại > 30 ngày. |
Luôn hiển thị |
Mốc tính thâm niên và phép năm. |
departmentId |
Dropdown |
Yes |
None |
Load từ API /departments. |
Luôn hiển thị |
Phân quyền Data Scope dựa vào trường này. |
status |
Dropdown |
Yes |
ACTIVE |
Enum: ACTIVE, PROBATION, INACTIVE |
Luôn hiển thị |
Trạng thái hoạt động hồ sơ. |
importFile |
File Upload |
Yes |
None |
File .xlsx đúng template chuẩn |
Khi dùng SCR-HR-07 |
File chứa danh sách nhân sự import. |
templateId |
Dropdown |
Yes |
Mặc định |
Selected từ danh sách Word Templates |
Khi dùng SCR-HR-06 |
Mẫu xuất file hợp đồng/sơ yếu lý lịch. |
Màn hình / Payload: Quản lý Nghỉ phép (SCR-LV-01 đến SCR-LV-06)
| Field (Trường) |
Data/UI Type |
Required |
Default |
Validation / Source |
Display Condition |
Notes / Impact |
leaveTypeId |
Dropdown |
Yes |
None |
Load từ API /leave-types. Phải Active. |
Luôn hiển thị |
Query số dư quỹ phép tương ứng. |
startDate |
Datepicker |
Yes |
Hôm nay |
Phải là ngày làm việc hợp lệ. |
Luôn hiển thị |
Mốc bắt đầu nghỉ. |
endDate |
Datepicker |
Yes |
Bằng startDate |
>= startDate. |
Luôn hiển thị |
Mốc kết thúc nghỉ. |
duration |
Decimal |
Yes |
Auto calc |
Tự động tính dựa trên startDate & endDate. |
Read-only |
Trừ LeaveBalance nếu đơn duyệt. |
reason |
Text Area |
Yes |
None |
Max 500 chars. |
Luôn hiển thị |
Lý do nghỉ hiển thị cho Manager duyệt. |
attachment |
File Upload |
No |
None |
JPG, PNG, PDF (Max 5MB). |
Nếu Nghỉ ốm > 3 ngày |
Chứng từ y tế gửi nhân sự. |
approvalNote |
Text Area |
No |
None |
Max 255 chars khi bấm Phê duyệt/Từ chối |
Khi dùng SCR-LV-04 |
Ghi chú phản hồi của Manager/HR. |
Màn hình / Payload: Chấm công, Bảng công & Báo cáo (SCR-ATT-01..04, SCR-TS-01..04, SCR-LOG-01..03)
| Field (Trường) |
Data/UI Type |
Required |
Default |
Validation / Source |
Display Condition |
Notes / Impact |
attendanceDate |
Datepicker |
Yes |
Hôm nay |
Định dạng YYYY-MM-DD. |
Luôn hiển thị |
Ngày phát sinh sự kiện chấm công. |
checkInTime |
Timepicker |
No |
None |
HH ss. |
Theo sự kiện IN |
Giờ vào ca. |
checkOutTime |
Timepicker |
No |
None |
HHss. |
Theo sự kiện OUT |
Giờ ra ca. |
reasonText |
Text Area |
Yes |
None |
Max 255 chars khi giải trình. |
Khi dùng SCR-ATT-04 |
Giải trình thiếu chấm công. |
yearMonth |
MonthPicker |
Yes |
Tháng hiện tại |
Format YYYY-MM. |
Khi dùng SCR-TS-01, SCR-LOG-01 |
Kỳ công / Tháng báo cáo tổng hợp. |
isLocked |
Checkbox |
Yes |
false |
Boolean state đại diện trạng thái khóa kỳ công |
Khi dùng SCR-TS-01 |
Ngăn chặn sửa đổi chấm công khi true. |
10.3 Quy tắc Validation & Xử lý lỗi Giao diện
- Frontend Validation: Giao diện Client bắt buộc phải kiểm tra các ràng buộc dữ liệu cơ bản (Trường bắt buộc, Độ dài tối đa, Định dạng Email/SĐT) trước khi gọi API Backend.
- Phản hồi lỗi Backend (HTTP Status):
400 Bad Request: Trả về mảng chi tiết các field vi phạm Validation. Giao diện phải highlight đỏ trường vi phạm kèm thông điệp lỗi.403 Forbidden: Trả về khi người dùng thao tác vượt quá phân quyền Data Scope hoặc Role Permission.409 Conflict: Trả về khi vi phạm ràng buộc duy nhất (Email, Mã nhân viên bị trùng).- Hiệu năng & Tải dữ liệu (Lazy Loading): Đối với các dropdown danh sách lớn (Phòng ban, Loại phép, Nhân sự > 50 bản ghi), giao diện phải triển khai cơ chế Tìm kiếm từ xa (Remote Search) hoặc Phân trang (Pagination).