KPI Lifecycle And Notification Deep Dive

Bộ tài liệu này đào sâu flow kpi-lifecycle-and-notification theo code thực tế hiện tại. Đây là package reverse-engineer trong docs/modules, không phải PRD/spec delivery. Mục tiêu là chốt một mental model rõ ràng cho 4 lớp rất dễ bị lẫn:

• KPI definition hiện đi chủ yếu qua direct Hasura CRUD, không có action lifecycle riêng,
• trạng thái KPI không phải cột state machine độc lập mà được suy ra từ from, to, canceled_at,
• progress runtime nằm ở kpi_metric_relation_log và AddKpiLog, không chỉ ở header kpi,
• notification bị tách thành event triggers cho kpi_branch/kpi_staff và các scheduler tổng hợp/remind riêng.

Đọc file nào?

Bạn là ai?	Nên đọc trước	Mục tiêu
PO / BA	shared-rules.md	Chốt thuật ngữ, lifecycle, result/status matrix, notification actors
FE Dev	type-kpi-lifecycle-and-status.md, type-progress-update-and-evaluation.md	Hiểu route shell, computed status, create/update/cancel/delete, manual metric updates
BE Dev	type-event-scheduler-and-notification-boundary.md, type-progress-update-and-evaluation.md	Hiểu event triggers, schedulers, AddKpiLog, kpi_permission audience
QA	shared-rules.md, type-kpi-lifecycle-and-status.md	Thiết kế test theo date-based status, notification triggers và progress logging
Người mới vào hệ thống	module-overview.md	Có bản đồ tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: entry surfaces, lifecycle, runtime data flow, notification map
shared-rules.md	Thuật ngữ chuẩn, status/result matrix, actor matrix, invariants
type-kpi-lifecycle-and-status.md	Deep dive cho create/update/delete/cancel/detail và computed status
type-progress-update-and-evaluation.md	Deep dive cho participant progress, manual metrics, auto metrics và KPI logs
type-event-scheduler-and-notification-boundary.md	Deep dive cho event triggers, schedulers, kpi_permission và runtime notifications

Kết luận ngắn

1. KPI core trong code hiện tại không có workflow status engine riêng; phần lớn lifecycle suy ra từ thời gian và soft actions.
2. ROUTE_KPI_LIST đang mở vào KPIRevenue, nên entry experience của module lệch đáng kể so với tên "KPIs".
3. Progress thật của KPI sống ở kpi_metric_relation_log và các read models/stats, không phải chỉ ở kpi header.
4. Notification boundary bị tách làm nhiều lớp: event kpi_branch_* / kpi_staff_*, scheduler kpi_notification, scheduler kpi_hotline, và các upstream domain events gọi AddKpiLog.

Liên kết tài liệu liên quan

• docs/modules/kpi/overview.md
• docs/modules/kpi/kpi.md
• docs/modules/kpi/kpi.technical.md
• docs/modules/report/operations-and-performance.md
• docs/modules/settings/incentive-policy.md
• docs/modules/user/employee-and-staff.md
• docs/modules/phase-2-backlog.md

Phạm vi của bộ docs này

• Bám theo code hiện tại của diva-admin, Hasura metadata, ecommerce-api, crm-api và các table domain ecommerce.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì workflow lý tưởng.
• Chủ động ghi các drift hoặc dấu hiệu bug ở FE filters, enum status, permission gating và notification runtime.