Type — Event, Scheduler And Notification Boundary

1. Event triggers cho branch/staff KPI

kpi_branch

Trigger	Điều kiện kích hoạt	Ý nghĩa
kpi_branch_insert	insert row mới	Gửi assign notification nếu total_target > 0
kpi_branch_update	update cột total_target	Tách assign lần đầu và change target
kpi_branch_delete	delete row	Gửi delete notification nếu target cũ > 0

kpi_staff

Trigger	Điều kiện kích hoạt	Ý nghĩa
kpi_staff_insert	insert row mới	Gửi assign notification nếu total_target > 0
kpi_staff_update	update cột total_target	Tách assign lần đầu và change target
kpi_staff_delete	delete row	Gửi delete notification nếu target cũ > 0

Observation

Notification ở các flows này không phụ thuộc KPI core header kpi; nó gắn trực tiếp vào kpi_branch và kpi_staff.

2. Scheduler kpi_notification

Metadata hiện chạy kpi_notification theo lịch:

• 0 14 * * * vào {\{ECOMMERCE_BASE_URL}\}/schedulers

Scheduler này gọi 4 nhánh:

Nhánh	Vai trò
kpiStaffNotification	Nhắc staff chưa đạt target tháng
kpiDayBranchNotification	Tổng hợp ngày cho nhóm all-branch/BOD-like audience
kpiMonthBranchNotification	Tổng hợp tháng giữa kỳ/cuối kỳ
kpiRemindBranchNotification	Nhắc branch managers khi branch chưa đạt target tháng

Rule nổi bật

ID	Rule
ESN-001	kpiMonthBranchNotification chỉ chạy vào ngày 15 hoặc ngày cuối tháng.
ESN-002	Staff remind chỉ gửi khi total_revenue_target > 0 và total_revenue < total_revenue_target.
ESN-003	Branch remind chỉ gửi cho branch có target > 0 nhưng actual chưa đạt target.

3. Scheduler kpi_hotline

Metadata hiện chạy kpi_hotline theo lịch:

• 0 16 * * * vào {\{CRM_BASE_URL}\}/schedulers

Khác với kpi_notification, scheduler này không gửi notification trực tiếp; nó ghi KPI logs hotline vào runtime layer.

4. kpi_permission là audience/config table

kpi_permission có fields:

• role_id
• type
• web_view
• web_update
• web_delete

Trong các file đã đọc, runtime đang dùng type nhiều nhất để nhóm audience:

type example	Cách dùng
all_branch	Chọn role nhận tổng hợp branch day/month
branch_manager	Chọn role nhận branch remind

Điểm đáng chú ý là FE route access và participant detail permission không đọc trực tiếp từ kpi_permission trong phần code đã đọc.

5. Template triggers sử dụng

Trigger code family	Use case
noti_staff_kpi_assign	assign KPI staff
noti_staff_kpi_change	đổi target KPI staff
noti_staff_kpi_delete	xóa KPI staff
noti_staff_kpi_remind	staff reminder
noti_branch_kpi_assign	assign KPI branch
noti_branch_kpi_change	đổi target KPI branch
noti_branch_kpi_delete	xóa KPI branch
noti_branch_kpi_remind	nhắc branch chưa đạt
noti_kpi_branch_day_bod	tổng hợp ngày cho audience all-branch
noti_kpi_branch_month_bod	tổng hợp tháng cho audience all-branch

6. Rủi ro kỹ thuật đáng chú ý

Inconsistency giữa FE permission và notification audience

• FE route/detail có permission logic riêng.
• Scheduler notification lại đi qua kpi_permission.
• Một role có thể xem KPI nhưng không nhận noti, hoặc ngược lại, nếu config drift.

Dấu hiệu bug ở kpi_staff_update

Trong nhánh change notification, code xây biến template bằng query.KpiStaffResults[0] sau nhánh lỗi/trường hợp rỗng.

Điều này tạo risk:

1. query lỗi hoặc trả rỗng,
2. code vẫn dereference phần tử đầu,
3. runtime có thể panic hoặc gửi biến thiếu dữ liệu.

Trigger coverage hạn chế

• kpi_branch_update và kpi_staff_update chỉ bắn khi cột total_target đổi.
• Nếu business muốn notify khi sửa các field khác như month, year, total_sales_target, thì metadata hiện chưa cover.

7. Findings

ID	Finding
ESN-F01	Notification runtime của KPI bị tách thành nhiều lớp và không có một source-of-truth permission duy nhất.
ESN-F02	kpi_staff_update có risk truy cập query.KpiStaffResults[0] dù query có thể lỗi/rỗng.
ESN-F03	Event triggers branch/staff chỉ quan tâm mạnh đến total_target; các thay đổi nghiệp vụ khác có thể không phát noti.