Achievement - Business Rules

Mục đích

Module achievement quản lý 2 lớp nghiệp vụ riêng nhưng dùng chung khái niệm “huy hiệu”:

• achievement_management: xem danh sách huy hiệu đã gắn cho nhân viên hoặc phòng ban, sau đó drill-down vào detail theo từng cá nhân/phòng ban.
• program_management: tạo, sửa, xem, import và áp dụng chương trình huy hiệu cho nhân viên hoặc phòng ban.

Module chạy trên frontend Admin, route gốc là /a và chỉ hiển thị trên PLATFORM_ADMIN theo cấu hình navigation của module.

Phạm vi nghiệp vụ

Nhánh	Mục tiêu	Đối tượng dữ liệu
Quản lý huy hiệu cá nhân	Theo dõi huy hiệu đã nhận của từng nhân viên	achievement, employee_achievement_link, program
Quản lý huy hiệu phòng ban	Theo dõi huy hiệu đã nhận của từng phòng ban	department_achievement, department_achievement_link, department_program
Quản lý chương trình cá nhân	Tạo và áp dụng chương trình huy hiệu cho nhân viên	program, program_achievement_link, program_manager_link, employee_achievement_link
Quản lý chương trình phòng ban	Tạo và áp dụng chương trình huy hiệu cho phòng ban	department_program, department_program_achievement_link, department_program_manager_link, department_achievement_link

Màn hình chính

Màn hình	Route	Chức năng
Quản lý huy hiệu	/a/achievement-management	Tab cá nhân / phòng ban, danh sách huy hiệu, mở detail theo record
Chi tiết nhân viên	/a/achievement-management/account/:accountCode	Xem tất cả huy hiệu của 1 nhân viên, lọc theo chương trình/ngày/từ khóa
Chi tiết phòng ban	/a/achievement-management/department/:departmentCode	Xem tất cả huy hiệu của 1 phòng ban, lọc theo chương trình/ngày/từ khóa
Quản lý chương trình	/a/achievement-program	Tab cá nhân / phòng ban, tạo/sửa/xem chương trình, import Excel, áp dụng huy hiệu

Vai trò và quyền

4.1 Quyền hiển thị module

Module được gắn cho các role trong role_module và có gate ở frontend:

• it_leader
• it_staff
• hr_leader
• hr_staff
• bod
• content_leader

4.2 Quyền thao tác

Khu vực	Điều kiện
Menu Huy hiệu	Cần có module achievement và đang ở PLATFORM_ADMIN
Tab Quản lý huy hiệu	Cần thuộc FULL_ACHIEVEMENT_MANAGEMENT_ROLES
Tab Quản lý chương trình	Luôn thấy trong module, nhưng dữ liệu trả về vẫn bị lọc theo manager nếu không có full-scope
Nút Tạo chương trình	Chỉ hiện cho full-scope roles
Xem danh sách chương trình	Người không full-scope chỉ thấy chương trình mà mình là manager

FULL_ACHIEVEMENT_MANAGEMENT_ROLES hiện gồm ITLeader, ITStaff, HRLeader, BOD, ContentLeader (diva-admin/src/modules/achievement/types.ts).

Luồng nghiệp vụ chính

5.1 Quản lý huy hiệu cá nhân / phòng ban

1. Người dùng vào /a/achievement-management.
2. UI mặc định mở tab cá nhân nếu query tab không được truyền.
3. Danh sách bên trái load toàn bộ huy hiệu bằng infinite scroll + search.
4. Chọn 1 huy hiệu để load bảng record bên phải.
5. Click vào dòng record để mở detail theo nhân viên hoặc phòng ban.
6. Detail screen cho phép lọc theo từ khóa, chương trình và ngày nhận huy hiệu.

5.2 Tạo / cập nhật chương trình

1. Người dùng vào /a/achievement-program.
2. Chọn tab cá nhân hoặc phòng ban.
3. Nút Tạo chương trình mở form ProgramForm.
4. Form yêu cầu: tên, thời gian bắt đầu/kết thúc, danh sách huy hiệu áp dụng, người phụ trách, mô tả.
5. Khi lưu:
   • create: insert_program / insert_department_program kèm nested insert vào bảng link.
   • update: update_program_by_pk / update_department_program_by_pk rồi xóa và chèn lại toàn bộ link.

5.3 Áp dụng huy hiệu hàng loạt

1. Người dùng mở dialog Áp dụng huy hiệu.
2. Chọn chương trình.
3. Chọn ngày áp dụng, danh sách huy hiệu trong chương trình.
4. Chọn một số nhân viên/phòng ban hoặc chọn toàn bộ.
5. Hệ thống tạo danh sách link và gọi mutation bulk insert.

5.4 Import Excel

1. Người dùng mở dialog Nhập dữ liệu.
2. Tải file .xlsx theo template.
3. Hệ thống đọc file, kiểm tra:
   • số cột,
   • chương trình có được phép thao tác,
   • huy hiệu có thuộc chương trình,
   • nhân viên/phòng ban có tồn tại,
   • ngày hợp lệ.
4. Nếu file hợp lệ mới cho phép import vào employee_achievement_link hoặc department_achievement_link.

Quy tắc nghiệp vụ nổi bật

Mã	Quy tắc
BR-ACH-001	Chương trình phải có duration_from và duration_to, và duration_from <= duration_to.
BR-ACH-002	Chương trình chỉ được áp dụng các huy hiệu nằm trong danh sách achievements của chính chương trình đó.
BR-ACH-003	Import Excel chỉ chấp nhận file .xlsx có đúng 4 cột theo template.
BR-ACH-004	Người không có full-scope chỉ thao tác được trên chương trình mà mình là manager.
BR-ACH-005	Detail screen luôn lọc dữ liệu theo chương trình đang xem, rồi mới lọc tiếp theo keyword / phòng ban / ngày.
BR-ACH-006	Phần áp dụng bulk sinh 1 record cho mỗi cặp achievement_code x account_code hoặc department_code.

Tích hợp với module khác

Module	Vai trò tích hợp
settings	Cung cấp UI chọn huy hiệu (AchievementSelect, AchievementDepartmentSelect) và UI render huy hiệu (AchievementDisplay)
user	Cung cấp chọn nhân viên, phòng ban, avatar và các query account/department
crm-api backend	Có action applyEmployeeProgram để nhân bản huy hiệu của program sang link nhân viên
controller backend	Lưu toàn bộ bảng chương trình, link huy hiệu, link manager và link phát hành

Rủi ro / Findings

Mức	Mô tả
P1	Bulk import đang đọc Excel bằng sheet.eachRow(async ...) nhưng không await từng row, nên progress/result có thể kết thúc trước khi các kiểm tra async xong.
P2	Cơ chế lưu userBehavior đang dùng key đọc và key ghi khác nhau giữa table và detail, nên page size có thể không được persist đúng.
P2	Luồng “áp dụng cho tất cả” phụ thuộc vào data đã load đủ qua infinite scroll; nếu chưa nạp hết danh sách thì tập dữ liệu submit có thể chưa đầy đủ.