Module Overview — KPI Lifecycle And Notification

1. KPI module thực tế đang bị chia thành 4 lớp

Lớp	Thành phần	Vai trò
KPI core definition	kpi, kpi_participant, kpi_metric_relation, kpi_template	Định nghĩa KPI, đối tượng, metric, target
KPI revenue surface	kpi_branch, kpi_staff, KPIRevenue*	Dashboard và target doanh thu branch/staff
Progress runtime	kpi_metric_relation_log, kpi_stats, kpi_metric_stats, AddKpiLog	Ghi nhận tiến độ thực tế và projection thống kê
Notification runtime	kpi_branch_*, kpi_staff_*, kpi_notification, kpi_hotline	Gửi assign/change/delete/remind/tổng hợp notifications

Điểm quan trọng là 4 lớp này dùng chung tên "KPI" nhưng không chạy trên cùng một engine duy nhất.

2. Surface map

FE routes

Route family	Vai trò
/k/KPIs	Entry module, hiện render KPIRevenue thay vì list KPI generic
/k/KPIs/create	Tạo KPI definition
/k/KPIs/:id/edit	Cập nhật KPI definition
/k/KPIs/:id/*	Detail KPI, tabs metric/target/my-kpi/branch-kpi
/k/KPIs/revenue/*	Tạo/sửa KPI target doanh thu branch/staff

Backend runtime

Runtime	Vai trò
Hasura CRUD trên kpi* tables	Create/update/cancel/delete KPI core và branch/staff targets
Event kpi_branch_*, kpi_staff_*	Gửi notification khi target được assign/change/delete
Scheduler kpi_notification	Gửi staff remind, branch day/month aggregate, branch remind
Scheduler kpi_hotline	Ghi KPI logs từ call center completed calls
AddKpiLog	API nội bộ để các domain events ghi log KPI vào runtime layer

3. Lifecycle của KPI core là computed lifecycle

Create KPI
  -> insert kpi + participants + metric relations
  -> status FE = new | inprogress | closed (computed)

Update KPI
  -> update header
  -> sync participant delta
  -> sync metric relation delta
  -> vẫn không có status transition action riêng

Cancel KPI
  -> update_kpi_by_pk(_set: { canceled_at: now })
  -> status FE = canceled

Delete KPI
  -> update_kpi_by_pk(_set: { disabled: true })
  -> biến mất khỏi list nếu builder dùng disabled=false

Computed status ở FE

Status	Cách suy ra
new	from còn ở tương lai
inprogress	from <= now <= to và canceled_at IS NULL
closed	to < now và canceled_at IS NULL
canceled	canceled_at IS NOT NULL
done	Chỉ là display status phụ khi progress >= 100% trong vài component

Không có cột status canonical trong bảng kpi.

4. Progress runtime không nằm ở header

Nguồn dữ liệu chính

Surface	Vai trò
kpi_metric_relation_log	Event log của từng metric relation/participant
kpi_stats	Projection tổng cho KPI
kpi_metric_stats	Projection tổng cho từng metric relation
search_kpi_branch_*, search_kpi_staff_*	Read models cho doanh thu KPI

Hai nhánh update

Nhánh	Cách hoạt động
Manual metric	FE gọi upsertManualMetrics để insert/update kpi_metric_relation_log
Auto metric	Event/scheduler backend gọi AddKpiLog(metricType, refIDs, extra)

Điều này có nghĩa "cập nhật KPI" và "cập nhật tiến độ KPI" là hai chuyện khác nhau về mặt runtime.

5. Notification model tổng quát

Event-trigger notifications

Trigger	Ý nghĩa
kpi_branch_insert	Branch target được assign lần đầu
kpi_branch_update	Branch target assign lần đầu hoặc thay đổi target
kpi_branch_delete	Branch target bị xóa
kpi_staff_insert	Staff target được assign lần đầu
kpi_staff_update	Staff target assign lần đầu hoặc thay đổi target
kpi_staff_delete	Staff target bị xóa

Scheduler notifications

Scheduler	Lịch chạy metadata	Vai trò
kpi_notification	0 14 * * *	staff remind + branch day + branch month + branch remind
kpi_hotline	0 16 * * *	ghi KPI logs hotline từ CRM runtime

6. Findings nổi bật

ID	Finding
MO-F01	Entry route /k/KPIs render KPIRevenue, nên "module KPI" ở UI thực tế nghiêng về revenue dashboard trước khi vào KPI core.
MO-F02	KPI lifecycle là computed lifecycle, nên mọi bug ở from/to/canceled_at sẽ đổi luôn status mà không có audit transition riêng.
MO-F03	KPI_STATUS_DONE tồn tại nhưng không nằm trong KPI_STATUSES; enum status hiện không hoàn toàn đồng bộ.
MO-F04	Notification boundary bị phân mảnh: event triggers, schedulers, kpi_permission, và upstream domain events đều tham gia.