# Tài liệu Màn hình Thống kê (Dashboard)

Tài liệu này mô tả chi tiết về chức năng, dữ liệu và phân quyền của màn hình Thống kê (Statistics Dashboard) trong ứng dụng quản lý LVT App Daily.

## 1. Tổng quan

Màn hình Thống kê cung cấp cái nhìn tổng quan về hiệu quả hoạt động của các ứng dụng mobile (Android/iOS) theo thời gian thực (hourly) và theo ngày (daily). Dữ liệu được tổng hợp từ hai nguồn chính:

- **AdMob**: Doanh thu quảng cáo (Revenue).
- **Google Ads**: Chi phí quảng cáo (Cost).

Từ đó tính toán ra **Lợi nhuận (Profit)** và **Biên lợi nhuận (Margin)**.

## 2. Các thành phần chính

### 2.1. Bộ lọc thời gian (Date Filter)

- Cho phép người dùng chọn ngày cụ thể để xem báo cáo.
- Mặc định hiển thị dữ liệu của ngày hiện tại (`today`).
- Tự động tải lại trang khi thay đổi ngày.

### 2.2. Thẻ KPI (Key Performance Indicators)

Hiển thị 4 chỉ số quan trọng nhất cho ngày được chọn:

1.  **Doanh thu (Revenue)**: Tổng doanh thu từ AdMob.
    - So sánh với ngày hôm qua (tăng/giảm %)
2.  **Chi phí (Cost)**: Tổng chi phí từ Google Ads (đã bao gồm phí nạp tiền - loading fee).
    - So sánh với ngày hôm qua.
3.  **Lợi nhuận (Profit)**: `Doanh thu - Chi phí`.
    - So sánh với ngày hôm qua.
4.  **Biên lợi nhuận (Margin)**: `(Lợi nhuận / Chi phí) * 100`.
    - So sánh với ngày hôm qua.

### 2.3. Thông tin Trạng thái App (App Status Stats)

_Mặc định bị ẩn, nhấn nút "Xem thêm thông tin App" để mở rộng._
Gồm 4 thẻ thống kê về số lượng ứng dụng:

1.  **Tổng số App**: Tổng số ứng dụng trong hệ thống (hoặc được phân công).
2.  **App đang hoạt động**: Số lượng app có `status = 0` (Active).
3.  **App có dữ liệu hôm nay**: Số lượng app có phát sinh doanh thu hoặc chi phí trong ngày được chọn.
4.  **App đang lỗ**: Số lượng app có `Lợi nhuận < 0` trong ngày được chọn.

### 2.4. Biểu đồ xu hướng theo giờ (Hourly Trend Chart)

- Biểu đồ đường (Line Chart) hiển thị biến động của 3 chỉ số theo từng giờ trong ngày:
    - **Doanh thu** (Màu xanh dương).
    - **Chi phí** (Màu đỏ).
    - **Lợi nhuận** (Màu xanh lá - Mới thêm).
- Giúp theo dõi hiệu suất quảng cáo tức thời và phát hiện bất thường.

### 2.5. Top App hiệu quả nhất

- Danh sách 8 ứng dụng có **Lợi nhuận cao nhất** trong ngày.
- Hiển thị: Tên App (giới hạn 30 ký tự) và Lợi nhuận.

### 2.6. Quản lý Marketing (Chỉ dành cho Admin)

- Bảng danh sách các nhân viên Marketing (Role 3).
- Hiển thị: Tên, Email, và Số lượng App đang phụ trách.

## 3. Phân quyền (Role-based Access Control)

Hệ thống phân chia quyền hạn hiển thị dữ liệu dựa trên vai trò của người dùng (`role_id`):

### 3.1. Admin (Role ID = 1)

- **Quyền hạn**: Xem toàn bộ dữ liệu của hệ thống.
- **Dữ liệu hiển thị**:
    - Tất cả App có trong cơ sở dữ liệu.
    - KPI, Biểu đồ, Top App tính trên toàn bộ App.
    - Nhìn thấy nút "Xem thêm thông tin App" và chi tiết trạng thái App.
    - Nhìn thấy bảng "Danh sách marketing và số lượng App phụ trách".

### 3.2. User thường (Ví dụ: Marketing - Role ID = 3)

- **Quyền hạn**: Chỉ xem dữ liệu của các App được phân công quản lý.
- **Dữ liệu hiển thị**:
    - Chỉ tính KPI, Biểu đồ, Top App dựa trên danh sách App được gán cho user đó (quan hệ `users_apps`).
    - **Ẩn** nút "Xem thêm thông tin App".
    - **Ẩn** bảng danh sách User Marketing.

## 4. Dữ liệu và Thuật toán

### 4.1. Nguồn dữ liệu

- **Bảng `apps`**: Thông tin ứng dụng.
- **Bảng `admob_reports`**: Báo cáo doanh thu theo ngày (Daily).
- **Bảng `google_ads_reports`**: Báo cáo chi phí theo ngày (Daily).
- **Bảng `admob_reports_hourly`**: Dữ liệu doanh thu theo giờ (Hourly) dùng cho biểu đồ.
- **Bảng `google_ads_reports_hourly`**: Dữ liệu chi phí theo giờ (Hourly) dùng cho biểu đồ.

### 4.2. Cách tính toán

- **Tỷ giá (Exchange Rate)**: Doanh thu và Chi phí USD được quy đổi ra VND theo tỷ giá thiết lập trong hệ thống (`gs('exchange_rate')`).
- **Phí nạp tiền (Loading Fee)**: Chi phí Google Ads được nhân thêm hệ số phí nạp tiền (nếu có) từ bảng `google_ads`.
- **Lợi nhuận**: `Revenue (VND) - Cost (VND)`.

## 5. Cấu trúc Code

- **Controller**: `App\Http\Controllers\DashboardController.php`
    - `index()`: Hàm chính xử lý logic, phân quyền và gọi view.
    - `getStatsForDate()`: Tính KPI ngày.
    - `getHourlyChartData()`: Lấy dữ liệu biểu đồ giờ.
    - `getTopPerformingApps()`: Lấy Top 8 App.
    - `getAppStatusStats()`: Thống kê trạng thái App.
- **View**: `resources/views/dashboard/index.blade.php`
    - Sử dụng Bootstrap 5 cho layout.
    - Sử dụng Chart.js để vẽ biểu đồ line.
- **Helper**: `get_accessible_app_ids()` (trong `app/Http/Helpers/helpers.php`) để lấy danh sách App ID được phép truy cập.

---

_Tài liệu được cập nhật lần cuối: 09/02/2026_