KPI - Technical Map

Auto-generated bởi codebase-doc-generator ngày 2026-03-23 (verified từ code thực). Không chỉnh sửa thủ công.

Routes

Route	Path	Mục đích
ROUTE_KPI_LIST	/k/KPIs	Entry chính của module KPI
ROUTE_KPI_CREATE	/k/KPIs/create	Tạo KPI
ROUTE_KPI_DETAIL	/k/KPIs/:id	Detail KPI
ROUTE_KPI_UPDATE	/k/KPIs/:id/edit	Cập nhật KPI
ROUTE_KPI_DETAIL_METRIC	/k/KPIs/:id/metric	Tab metric
ROUTE_KPI_DETAIL_TARGET	/k/KPIs/:id/target	Tab target
ROUTE_KPI_DETAIL_MY_KPI	/k/KPIs/:id/my-kpi	Tab KPI cá nhân
ROUTE_KPI_DETAIL_BRANCH_KPI	/k/KPIs/:id/branch-kpi	Tab KPI chi nhánh
ROUTE_BRANCH_KPI_DETAIL	/k/KPIs/:id/branch-kpi/:assigneeId	Detail participant branch
ROUTE_PERSONAL_KPI_DETAIL	/k/KPIs/:id/personal-kpi/:assigneeId	Detail participant personal
ROUTE_KPI_REVENUE_CREATE	/k/KPIs/revenue/create	Tạo branch revenue KPI
ROUTE_KPI_REVENUE_EDIT	/k/KPIs/revenue/edit	Sửa branch revenue KPI
ROUTE_KPI_REVENUE_BRANCH	/k/KPIs/branch-revenue/:id	Wrapper detail branch revenue
ROUTE_KPI_REVENUE_BRANCH_DETAIL	/k/KPIs/branch-revenue/:id/detail	Detail branch revenue
ROUTE_KPI_REVENUE_BRANCH_USER_CREATE	/k/KPIs/branch-revenue/user-create/:id	Tạo KPI user trong branch revenue
ROUTE_KPI_REVENUE_BRANCH_USER_EDIT	/k/KPIs/branch-revenue/user-edit/:id	Sửa KPI user trong branch revenue

Navigation & Permission

Item	Giá trị
MODULE_KPI	k
Route moduleId	kpi
Route permissions	ITLeader, BOD, BranchManager, DepartmentManager, nhóm CallCenter
Dashboard runtime permissions	ITLeader, ITStaff, AccountantLeader, AccountantStaffGeneral, HRLeader, HRStaff, cộng thêm BranchManager ở POS gating
Navigation title	Quản lý KPI

FE Pages (4)

Page	File	Vai trò
KPIs	pages/KPIs.tsx	Entry route, hiện render KPIRevenue
KPICreate	pages/KPICreate.tsx	Tạo KPI definition
KPIDetail	pages/KPIDetail.tsx	Detail KPI + tab routing
KPIUpdate	pages/KPIUpdate.tsx	Cập nhật KPI definition

FE Components / Areas

Component/Area	Vai trò
KPIRevenue*	Dashboard doanh thu theo tháng/ngày/branch/user
KpiForm	Form tạo KPI
KPIUpdateForm	Form cập nhật KPI
KPIInfo	Thông tin summary bên trái detail
Metrics	Tab metric definition
Targets	Tab target/participant
Assignee	Tab/detail participant branch hoặc personal
AutoMetricForm/*	Form cấu hình các auto metric theo loại nghiệp vụ
KPIAction	Bộ action view/edit/cancel/delete/download

GraphQL Operations

File: diva-admin/src/modules/kpi/graphql/kpi.graphql

KPI core

Operation	Mục đích
getKPIs	Lấy danh sách KPI
getKPIStats	Lấy stats KPI
GetKPIByPk	Lấy chi tiết KPI
createKpi	Tạo KPI
updateKpi	Update KPI header
getKPITemplates	Lấy KPI templates
deleteKPITemplate	Xóa template KPI

Metric / participant

Operation	Mục đích
GetKPIMetrics	Lấy danh mục metric
insertKpiParticipant	Thêm participant
deleteKpiParticipants	Xóa participant
insertKpiMetricRelations	Thêm metric relations
deleteKpiMetricRelationss	Xóa metric relations
upsertManualMetrics	Upsert manual metric logs/values
getKPIMetricParticipants	Lấy participant + metric detail
getKPIMetricRelations	Lấy metric relations
getKPIMetricRelationLogs	Lấy KPI log history
getKPIMetricStats	Lấy metric stats

Branch / revenue KPI

Operation	Mục đích
GetBranchCreateTarget	Data tạo target branch
InsertKPIBranch	Insert kpi_branch
GetKPIMonthTargetChart	Chart/ranking KPI tháng
GetKPIDayTargetChart	Chart/ranking KPI ngày
GetKPITargetTable	Bảng target KPI
GetKPITargetEdit	Lấy dữ liệu edit target
UpdateKPITarget	Gọi bulk update target branch
GetKPIBranchTableEmployee	Bảng KPI nhân viên theo branch
GetKPIBranchCalender	Calendar KPI branch
GetKPIUserCreateTarget	Data tạo KPI user
GetKPIUserEditTarget	Data sửa KPI user
InsertKPIStaff	Insert kpi_staff
SumcardKPIBranch	Sumcard KPI branch
DeleteKPIBranch	Xóa branch target
DeleteKPIStaff	Xóa staff target

FE Runtime logic

KPIs.tsx

Logic	Ghi chú
Entry rendering	Nếu route là ROUTE_KPI_LIST thì render KPIRevenue
POS gate	Kiểm tra thêm PERMISSIONS_KPI + BranchManager
Local tab state	Lưu tab key trong localStorage với key customer

KPIDetail.tsx

Logic	Ghi chú
Detail source	GetKPIByPk(id)
Dynamic tabs	Tab hiển thị theo role và type KPI
Branch manager scope	Tính managedBranches từ account.branches và participant branch users
Assignee detail mode	Route sâu branch-kpi/:assigneeId và personal-kpi/:assigneeId ẩn tab header

KPICreate.tsx

Logic	Ghi chú
Header insert	Insert kpi với general info + totals
Participant insert	participants.data đi cùng insert KPI
Template capture	Lưu capture khi isSaved = true
Metric insert	Gọi insertKpiMetricRelations sau khi đã có participant map
Date normalization	from đầu ngày, to cuối ngày

KPIUpdate.tsx

Logic	Ghi chú
Delta update	Tính participant/metric bị thêm, xóa, thay đổi
Participant cleanup	Xóa metrics trước khi xóa participant
Metric sync	Insert lại metric relations mới hoặc changed
Child metric sync	Tách riêng nhánh update additional metric ranges

KPIUpdateForm.tsx

Logic	Ghi chú
Empty guards	Chặn nếu chưa có metric hoặc target
Cross validation	Mỗi target phải có metric tương ứng
Init from existing KPI	Dựng lại form từ metric_relations, participants, totals
Additional metrics	Map child ranges theo metric ID

KPIAction.tsx

Logic	Ghi chú
Edit mode	Chỉ hiện cho new/inprogress và non-dynamic group
Cancel mode	Chỉ hiện cho inprogress
Delete mode	Chỉ hiện cho new
Download	Cho tải metric hoặc target

KPIBuildWhere

Logic	Ghi chú
Disabled filter	Luôn có thể ép disabled = false
Keyword search	Search theo keywords của KPI hoặc participant user
Status filter	Suy luận trạng thái từ from, to, canceled_at thay vì chỉ đọc status field
My KPI scope	Hạn chế theo participant / creator / branch tùy role
Participant filters	Lọc theo branch, department users, user ids, loại KPI
Date bug	setStartEndDate() dùng createDate(from, ...) cho cả nhánh to, có dấu hiệu sai logic

Core constants / enums

Constant	Giá trị / Ý nghĩa
KPI_BRANCH	kpi_branch
KPI_PERSONAL	kpi_personal
KPI_STATUS_NEW	new
KPI_STATUS_INPROGRESS	inprogress
KPI_STATUS_CLOSED	closed
KPI_STATUS_DONE	done
KPI_STATUS_CANCELED	canceled
KPI_STATUSES	new, inprogress, closed, canceled
KPI_RESULTS	not_achieved, need_to_improve, qualified, exceed_requirements
KPI_METRIC_GROUP_MANUAL	kpi_metric_group_manual

Metric catalog highlights

Nhóm	Ví dụ metric type
Revenue / sales	actual_revenue, sales, order_quantity
Customer	new_customers, returning_customers, customers_purchased
Contact center	minutes_on_calls, call_productivity_calls_hour, call_productivity_minutes_hour, outgoing_calls_to_customers, created_tickets, created_appointments
Campaign	orders_from_campaign, sales_from_campaign, actual_revenue_from_campaign, actual_revenue_from_campaign_prepaid_card
Workload / task	total_workload, total_completed_workload, total_time_completed_task, completed_tasks, overdue_tasks

Store / data model

Object	Vai trò
kpi	Header KPI definition
kpi_template	KPI template capture
kpi_participant	Đối tượng KPI: user hoặc branch
kpi_metric	Danh mục metric
kpi_metric_relation	Metric target gắn với participant
kpi_metric_relation_log	Log tiến độ thực tế theo metric
kpi_stats	Stats tổng hợp của KPI
kpi_metric_stats	Stats tổng hợp của metric
kpi_branch	Target doanh thu theo chi nhánh
kpi_staff	Target doanh thu theo nhân viên
kpi_permission	Mapping role nhận KPI notification / scope đặc biệt
kpi_branch_result / kpi_staff_result	Read models cho report/ranking KPI

Backend Services

Service	Vai trò
controller	CRUD tables/functions/metadata KPI
ecommerce-api	Event triggers cho kpi_branch, kpi_staff; scheduler kpi_notification
crm-api	Scheduler kpi_hotline ghi KPI log từ hotline calls

Backend Events / Schedulers

kpi_branch_insert

Step	Vai trò
Guard	Bỏ qua nếu TotalTarget <= 0
Lookup	Lấy KpiBranchDetail + branch managers
Notify	Gửi NotificationTriggerBranchKpiAssign cho branch managers

kpi_branch_update

Step	Vai trò
Assign case	0 -> >0 thì gửi assign notification
Change case	>0 -> >0 và thay đổi target thì gửi change notification
Rank lookup	Có query search_kpi_branch_by_month_rank để lấy % hiện tại trước khi gửi change

kpi_staff_insert

Step	Vai trò
Guard	Bỏ qua nếu TotalTarget <= 0
Notify	Gửi NotificationTriggerStaffKpiAssign cho chính user staff

kpi_staff_update

Step	Vai trò
Assign case	0 -> >0 thì gửi assign notification
Change case	>0 -> >0 và thay đổi target thì gửi change notification
History lookup	Query search_kpi_staff_history để lấy progress % hiện tại

kpi_notification

Step	Vai trò
kpiStaffNotification	Nhắc staff chưa đạt KPI tháng hiện tại
kpiDayBranchNotification	Gửi tổng hợp KPI branch theo ngày
kpiMonthBranchNotification	Gửi tổng hợp KPI branch theo tháng
kpiRemindBranchNotification	Nhắc branch managers theo điều kiện scheduler

kpi_hotline

Step	Vai trò
Source	Quét incall_call có ticket completed trong ngày
Per-user metric	Ghi call_productivity_calls_hour và call_productivity_minutes_hour dựa trên working hours
Per-branch metric	Ghi aggregate call count và total minutes cho branch
Persistence	Ghi qua AddKpiLog(...)

AddKpiLog mechanism

Step	Vai trò
Participant lookup	Tìm kpi_participant theo reference_id
Active KPI gate	Chỉ nhận KPI active, không disabled, không canceled, nằm trong thời gian hiệu lực
Metric match	Chỉ log vào kpi_metric_relation có metric.type_id khớp
Insert log	Insert kpi_metric_relation_log với point và entity references

Domain coupling

Module/Domain	Kiểu liên kết
report	Đọc kpi_branch_result, kpi_staff_result, metric stats
dashboard	Dùng dữ liệu KPI revenue/ranking
user	Participant, role, branch ownership, department
notification	Các event/scheduler KPI gửi notification templates
crm	Hotline scheduler sinh KPI logs
projects	Một số metric workload/task dùng dữ liệu task domain

Rủi ro / Findings kỹ thuật

#	Note
1	ROUTE_KPI_LIST thực tế render KPIRevenue; tên route và entry UX không phản ánh hết việc module đang thiên về KPI doanh thu.
2	KPI_PERMISSIONS và PERMISSIONS_KPI không trùng nhau hoàn toàn; route-level access và screen-level access có thể lệch.
3	KPI_STATUS_DONE tồn tại nhưng không nằm trong KPI_STATUSES, cho thấy enum trạng thái chưa đồng bộ hoàn chỉnh.
4	useKPIBuilder.setStartEndDate() có dấu hiệu bug vì dùng from cho cả điều kiện _lte của to.
5	kpi_metric_relation_log là read/write backbone cho auto metrics; KPI progress không chỉ đến từ form manual mà còn từ nhiều scheduler/event backend.