Type — Progress Update And Evaluation

1. Progress không nằm ở KPI header

KPI header chỉ giữ definition và ngưỡng tổng. Tiến độ thực được materialize ở:

Surface	Vai trò
kpi_metric_relation_log	log raw của từng metric relation / participant
kpi_stats	stats tổng của KPI
kpi_metric_stats	stats tổng của metric relation
search_kpi_branch_*, search_kpi_staff_*	projections doanh thu theo branch/staff

Vì vậy câu hỏi "KPI này đạt bao nhiêu rồi?" không thể trả lời đúng chỉ bằng cách đọc bảng kpi.

2. Manual metric update ở FE

Branch/manager view

Targets.tsx mở ManualMetricForm, rồi submit qua upsertManualMetrics.

Input	Vai trò
kpi_metric_relation_id	relation đang được cập nhật
kpi_participant_id	participant được cập nhật
point	giá trị nhập tay
created_at	ngày được chọn trong form

Assignee detail view

ManualMetricTab.tsx cho phép sửa theo lịch dạng calendar:

• chọn metric thủ công,
• chọn tháng,
• sửa point theo ngày,
• upsert log cho đúng ô ngày đó.

Điều này cho thấy manual metric có ít nhất hai bề mặt nhập liệu: bulk-ish manager form và daily-assignee form.

3. Auto metric update ở backend

AddKpiLog là API nội bộ trung tâm cho auto metrics.

Contract

AddKpiLog(metricType, refIDs, extra)
  -> lọc participant theo reference_id
  -> chỉ giữ participant có KPI active
  -> chỉ giữ metric relations có metric.type_id khớp
  -> insert kpi_metric_relation_log

Guard của AddKpiLog

Participant chỉ được ghi log nếu KPI thỏa:

• disabled = false
• canceled_at IS NULL
• from <= now
• to >= now
• có metric relation với metric.type_id tương ứng

Đây là runtime invariant rất quan trọng: event đến đúng nhưng KPI không active thì sẽ không có log.

4. Upstream sources của auto metric logs

Từ code đã đọc/search, AddKpiLog được gọi từ nhiều domain:

Domain	Ví dụ source
CRM	ticket_insert, incall_call_log_insert, kpi_hotline
Ecommerce	invoice_insert_update, order_insert, appointment_insert
Projects/tasks	project_task_assignee_insert/delete, task_log
Time-based scheduler	notification_task_expired

KPI progress vì vậy là coupling runtime đa domain chứ không phải module nội bộ đóng kín.

5. Evaluation/result computation

Ở target/participant screens, result buckets được tính bằng cách so sánh tổng điểm hiện tại với các ngưỡng:

Bucket	Điều kiện
not_achieved	< total_need_to_improve
need_to_improve	>= total_need_to_improve và < total_qualified
qualified	>= total_qualified và < total_exceed_requirements
exceed_requirements	>= total_exceed_requirements

Các bucket này không phải state transition độc lập; chúng là evaluation view của progress.

6. KPI hotline là bridge từ CRM sang KPI runtime

Scheduler kpi_hotline của crm-api:

• lấy các incall_call có answered logs trong ngày,
• chỉ giữ ticket completed,
• tính call/hour và minute/hour theo user và branch,
• gọi AddKpiLog cho các metric hotline tương ứng.

Điều này cho thấy một phần progress KPI của call center không đi qua event insert từng log đơn lẻ mà còn có cron aggregate.

7. Findings

ID	Finding
PUE-F01	KPI progress là multi-source runtime; thiếu bất kỳ upstream event/scheduler nào cũng làm stats sai mà không đụng vào KPI header.
PUE-F02	Manual metrics có 2 UX nhập liệu khác nhau nhưng đổ về cùng kpi_metric_relation_log, nên QA cần test cả hai surfaces.
PUE-F03	AddKpiLog chỉ ghi cho KPI active; backfill ngoài khung from/to sẽ bị drop im lặng theo guard hiện tại.