# Task 20 — Sales Reports

## Goal
Build the Sales Reports module to provide operational visibility on sales performance.
This task focuses on a basic sales summary report using invoices as the primary source.

---

## Scope

This task covers:
- sales summary query logic
- filters by branch / customer / date range
- report UI
- totals for invoice amounts

This task does NOT cover:
- advanced BI dashboards
- product profitability analysis
- export implementation
- customer aging (handled separately)

---

## Data Source

Primary source table:
- `invoices`

Supporting tables:
- `customers`
- `branches`

---

## Required Output

For each row:
- invoice_number
- invoice_date
- customer_name
- branch_name
- subtotal
- tax_amount
- total_amount
- status

Summary section:
- total invoices count
- total subtotal
- total tax
- total sales amount

---

## Business Rules

1. Sales report must read from `invoices`.
2. Filters must support:
   - branch_id (optional)
   - customer_id (optional)
   - date_from (optional)
   - date_to (optional)
3. Only confirmed invoices may be shown by default, if status flow is active.
4. Customer name must use translated JSON field.
5. If no data exists, return empty result safely.

---

## Query Rules

Main joins:
- invoices
- customers
- branches

Suggested filters:
- branch_id
- customer_id
- date range
- status = confirmed (if business decides to exclude draft/cancelled)

Order by:
- invoice_date desc
- invoices.id desc

---

## Files

### Service
- app/Services/Sales/Reports/SalesReportService.php

### Controller
- app/Http/Controllers/Admin/Sales/SalesReportController.php

### Requests
- app/Http/Requests/Admin/Sales/SalesReportFilterRequest.php

### Views
- resources/views/dashboard/sales/reports/index.blade.php

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

---

## Permissions

- sales.reports.view

---

## Validation Rules

- branch_id: nullable, exists:branches,id
- customer_id: nullable, exists:customers,id
- date_from: nullable, date
- date_to: nullable, date, after_or_equal:date_from

---

## UI

Views path:
`resources/views/dashboard/sales/reports/`

### Filter fields
- branch
- customer
- date_from
- date_to
- submit button

### Table columns
- invoice_number
- invoice_date
- customer
- branch
- subtotal
- tax_amount
- total_amount
- status

### Summary cards/section
- total invoices
- total subtotal
- total tax
- total sales amount

---

## Lang Keys

Suggested keys:
- sales_reports
- sales_report
- invoice_number
- invoice_date
- customer
- branch
- subtotal
- tax_amount
- total_amount
- status
- total_invoices
- total_sales
- filter
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- sales.reports.view

---

## Steps

### Step 1
Create `SalesReportFilterRequest`.

### Step 2
Create `SalesReportService`.

### Step 3
Create `SalesReportController`.

### Step 4
Add routes in `routes/admin.php`.

### Step 5
Create sales report view.

### Step 6
Create lang files.

### Step 7
Update `RolePermissionSeeder`.

---

## Notes for AI

- Follow docs/ai/AI_MASTER_PROJECT.md
- Follow docs/ai/ARCHITECTURE_RULES.md
- Follow docs/ai/DATABASE_SCHEMA.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