# Task 12 — Income Statement

## Goal
Build the Income Statement report module to summarize revenues and expenses for a selected branch and accounting period.
This report should calculate net profit or loss using balances from the accounting foundation.

---

## Scope

This task covers:
- income statement query logic
- filters by branch / fiscal year / fiscal period
- grouping accounts by revenue and expense
- net result calculation
- report UI

This task does NOT cover:
- Balance Sheet
- Cash Flow
- advanced multi-column comparative reports
- export implementation

---

## Data Source

Primary source table:
- `account_period_balances`

Supporting tables:
- `accounts`
- `branches`
- `fiscal_years`
- `fiscal_periods`

---

## Required Output

Sections:
1. Revenues
2. Expenses
3. Net Profit / Loss

For each account row:
- account_code
- account_name
- amount

Summary:
- total revenues
- total expenses
- net result

---

## Business Rules

1. Income Statement must read from `account_period_balances`.
2. Revenue accounts are accounts with type = `income`.
3. Expense accounts are accounts with type = `expense`.
4. Filter support:
   - branch_id
   - fiscal_year_id
   - fiscal_period_id
5. Report amount should be based on period movement, not closing balance.
6. Income accounts normally increase on credit side.
7. Expense accounts normally increase on debit side.
8. Displayed amount should be normalized as positive business amounts.
9. Account name must use translated JSON field.

---

## Calculation Rules

### Revenue amount
Use:
- period_credit - period_debit

### Expense amount
Use:
- period_debit - period_credit

### Net result
Use:
- total_revenues - total_expenses

If net result > 0:
- Net Profit

If net result < 0:
- Net Loss

---

## Query Rules

Main joins:
- account_period_balances
- accounts

Required where filters:
- branch_id
- fiscal_year_id
- fiscal_period_id
- accounts.type in (income, expense)

Order by:
- accounts.type asc
- accounts.code asc

---

## Files

### Service
- app/Services/Finance/Reports/IncomeStatementService.php

### Controller
- app/Http/Controllers/Admin/Finance/IncomeStatementController.php

### Requests
- app/Http/Requests/Admin/Finance/IncomeStatementFilterRequest.php

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

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

---

## Permissions

- reports.income_statement.view

---

## Validation Rules

- branch_id: required, exists:branches,id
- fiscal_year_id: required, exists:fiscal_years,id
- fiscal_period_id: required, exists:fiscal_periods,id

---

## UI

Views path:
`resources/views/dashboard/finance/reports/income_statement/`

### Filter fields
- branch
- fiscal_year
- fiscal_period
- submit button

### Report sections
- Revenue accounts
- Expense accounts
- Net Profit / Loss summary

### Table columns
- account_code
- account_name
- amount

---

## Lang Keys

Suggested keys:
- income_statement
- revenues
- expenses
- net_profit
- net_loss
- total_revenues
- total_expenses
- amount
- account_code
- account_name
- branch
- fiscal_year
- fiscal_period
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- reports.income_statement.view

---

## Steps

### Step 1
Create `IncomeStatementFilterRequest`.

### Step 2
Create `IncomeStatementService`.

### Step 3
Create `IncomeStatementController`.

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

### Step 5
Create income statement view.

### Step 6
Update lang files.

### Step 7
Update `RolePermissionSeeder` with `reports.income_statement.view`.

---

## 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/DATABASE_RELATION_DIAGRAM.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