# Reporting KPI Definitions — MedBASE V2

> Tài liệu này chuẩn hóa **định nghĩa KPI, logic tính, cadence và nguyên tắc sử dụng reporting** trong MedBASE V2.

## I. Nhật ký thay đổi

| Phiên bản | Ngày | Chi tiết | Người cập nhật |
|-----------|------|---------|----------------|
| 1.0 | 24/04/2026 | Chuẩn hóa theo official documentation baseline từ bộ docs/v2 và quá trình migration cấu trúc tài liệu | Huyen Tran |

---

> **Ghi chú chuẩn hóa Official:** Tài liệu này là bản chính thức trong bộ `docs/official/`. Nội dung được chuẩn hóa từ `docs/v2/` và các tài liệu migration bổ sung. Nếu có điểm diễn giải chưa rõ, ưu tiên theo [01-source-of-truth.md](./01-source-of-truth.md).

## II. Nguyên tắc chung

- Reporting là read-model / projection layer
- KPI phải bám vào định nghĩa business đã chốt, không được suy diễn tùy ý
- Một KPI phải có tối thiểu:
  - định nghĩa business
  - công thức tính
  - source logic
  - inclusion/exclusion rule
  - cadence
  - timezone rule

---

## III. Timezone và cadence baseline

### Timezone Rule
- Tất cả KPI V2 mặc định phải được tính theo **múi giờ vận hành chính thức của dự án**
- Nếu chưa có quyết định khác, mọi team phải dùng cùng một timezone rule để tránh lệch số

### Cadence Rule
- Mỗi KPI/dashboard phải ghi rõ thuộc một trong các loại:
  - near-real-time
  - scheduled refresh
  - daily batch

---

## IV. KPI nhóm Referral

### Referral Visit Count
**Business meaning**: số lượt referral visit được MedBASE ghi nhận trong kỳ.

**Formula**:
- đếm số referral visit records trong khoảng thời gian đã chọn

**Include**:
- visit hợp lệ được hệ thống ghi nhận

**Exclude**:
- event bị loại theo dedupe/system error policy

### Visits by Source / Campaign / Ref Code
**Business meaning**: phân bổ referral visits theo source/campaign/ref code.

**Rule**:
- chỉ dùng cho attribution/reporting
- không dùng làm buyer identity truth

---

## V. KPI nhóm Funnel

### Lead Count
**Business meaning**: số lead được tạo trong kỳ.

**Formula**:
- count(lead records có created_at nằm trong kỳ)

### Registration Count
**Business meaning**: số account/buyer registrations được tạo trong kỳ.

**Formula**:
- count(registrations có created_at nằm trong kỳ)

### KYC Submitted Count
**Business meaning**: số hồ sơ KYC/eligibility được submit trong kỳ.

**Formula**:
- count(cases có submitted_at nằm trong kỳ)

### KYC Approved Count
**Business meaning**: số hồ sơ được approve trong kỳ.

**Formula**:
- count(cases có approved_at nằm trong kỳ)

### Verified Buyer Count
**Business meaning**: số buyer có trạng thái VERIFIED tại thời điểm chốt kỳ hoặc theo logic được định nghĩa.

**Note**:
- cần chốt rõ là current-state metric hay event-in-period metric

### First Order Count
**Business meaning**: số buyer có order đầu tiên trong lịch sử MedBASE rơi vào kỳ báo cáo.

**Formula**:
- count(buyer có first committed order trong kỳ)

---

## VI. KPI nhóm Commerce

### Total Orders
**Business meaning**: tổng số order đã commit thành công trong kỳ.

**Include**:
- order đã được tạo thành business truth

**Exclude**:
- failed attempts chưa commit

### Completed Orders
**Business meaning**: số order chuyển sang COMPLETED trong kỳ.

### Rejected Orders
**Business meaning**: số order chuyển sang REJECTED trong kỳ.

### GMV
**Business meaning**: tổng giá trị order đã commit trong kỳ.

**Formula**:
- sum(order total của committed orders trong kỳ)

**Exclude**:
- failed attempts
- duplicate retries không tạo thêm order truth

### Average Order Value (AOV)
**Formula**:
- GMV / Total Orders

### Repeat Order Count
**Business meaning**: số order trong kỳ được tạo bởi buyer đã có ít nhất một committed order trước đó.

### Repeat Order Rate
**Formula**:
- Repeat Order Count / Total Orders

---

## VII. KPI nhóm Operations

### KYC Review Time
**Business meaning**: thời gian trung bình từ submitted_at đến quyết định cuối cùng.

### KYC Reject Rate
**Formula**:
- rejected cases / reviewed cases trong kỳ

### Manual Intervention Count
**Business meaning**: số manual operation requests đã được thực hiện hoặc ghi log trong kỳ theo policy.

### Checkout Failure Count
**Business meaning**: số lần create-order attempt trả thất bại trong kỳ.

**Exclude**:
- repeated retry cùng idempotency key nếu chỉ trả cùng kết quả cũ

### Inventory Incident Count
**Business meaning**: số incident inventory đã được xác nhận và ghi log trong kỳ.

---

## VIII. Dashboard tối thiểu của V2

Dashboard V2 tối thiểu nên hiển thị:
- referral visits
- lead count
- registration count
- KYC submitted
- KYC approved
- verified buyer count
- first order count
- total orders
- GMV
- basic ops/risk counters

---

## IX. Những điểm phải chốt thêm

- timezone chính thức của reporting
- exact cadence cho từng dashboard
- exact dedupe policy cho referral/lead nếu có
- current-state vs event-in-period cho verified buyer metric
- hierarchy của source attribution

---

## X. Tuyên bố cuối cùng

KPI definitions của MedBASE V2 phải đủ rõ để tất cả các bên:
- PM
- Ops
- QA
- Dev
- Stakeholder

cùng hiểu một điều:

> **dashboard của V2 là công cụ quan sát và ra quyết định, không phải nơi tái định nghĩa business truth.**