# Task 26 — Dashboard Analytics

## Goal
Build the Dashboard Analytics module to display high-level business KPIs across finance, sales, inventory, and HR.
This task focuses on read-only summary widgets for the main dashboard.

---

## Scope

This task covers:
- KPI service logic
- dashboard widgets/cards
- summary data from existing modules

This task does NOT cover:
- advanced BI dashboards
- charts library customization beyond basic implementation
- predictive analytics
- export

---

## Data Sources

Potential source tables:
- branches
- journal_entries
- account_period_balances
- invoices
- stock_movements
- payrolls
- employees

---

## Suggested KPIs

### Finance KPIs
- total posted journal entries
- total period debit
- total period credit

### Sales KPIs
- total invoices
- total sales amount

### Inventory KPIs
- total stock movements
- total distinct items
- total warehouses

### HR KPIs
- total employees
- total payroll amount

---

## Business Rules

1. Dashboard analytics should be read-only.
2. KPI queries should be lightweight and summarized.
3. Widgets should fail safely if a module is not yet fully implemented.
4. KPI values should respect branch scope where applicable.
5. Dashboard should remain fast.

---

## Files

### Service
- app/Services/System/DashboardAnalyticsService.php

### Controller
- app/Http/Controllers/Admin/System/DashboardController.php (extend existing if already present)

### Views
- resources/views/dashboard/dashboard.blade.php or existing dashboard view updates

### Lang files
- lang/ar/system.php
- lang/en/system.php

---

## Permissions

- system.dashboard.view

---

## UI

Main dashboard cards/widgets for:
- finance summary
- sales summary
- inventory summary
- HR summary

Optional:
- small trend charts later

---

## Lang Keys

Suggested keys:
- dashboard
- finance_summary
- sales_summary
- inventory_summary
- hr_summary
- total_invoices
- total_sales
- total_employees
- total_payroll
- total_posted_entries
- total_warehouses
- total_items

---

## Seeder

Update RolePermissionSeeder with:
- system.dashboard.view

---

## Steps

### Step 1
Create `DashboardAnalyticsService`.

### Step 2
Update or create dashboard controller method.

### Step 3
Update dashboard view with KPI cards.

### Step 4
Create lang files or append keys.

### Step 5
Update `RolePermissionSeeder`.

---

## Notes for AI

- Follow docs/ai/AI_MASTER_PROJECT.md
- Follow docs/ai/ARCHITECTURE_RULES.md
- Follow docs/ai/MODULE_STRUCTURE.md
- Execute one step at a time
- Do not modify unrelated files
- Do not generate tests in this task
- Wait for confirmation after each step