# Task 10 — Trial Balance

## Goal
Build the Trial Balance report module using `account_period_balances` as the primary source.
This report must provide balances by account for a selected branch, fiscal year, and fiscal period.

---

## Scope

This task covers:
- trial balance query logic
- filters by branch / fiscal year / fiscal period
- report UI
- export-ready structure later

This task does NOT cover:
- General Ledger
- Income Statement
- PDF/Excel export implementation
- advanced analytics widgets

---

## Data Source

Primary source table:
- `account_period_balances`

Supporting tables:
- `accounts`
- `branches`
- `fiscal_years`
- `fiscal_periods`
- `cost_centers` (optional filter later, not required now)

---

## Required Fields in Report

For each account row:
- account_code
- account_name
- opening_debit
- opening_credit
- period_debit
- period_credit
- closing_debit
- closing_credit

Optional later:
- cost_center view
- grouped totals by account type

---

## Business Rules

1. Trial Balance must read from `account_period_balances`, not journal_entry_lines directly.
2. Accounts with zero balances may be hidden by default or shown later as optional.
3. Report must support filter by:
   - branch
   - fiscal year
   - fiscal period
4. Output should be ordered by account code.
5. Account name must use HasTranslations value.
6. Only active accounts should be included unless explicitly requested later.
7. If no balances exist for the filter, return empty result safely.

---

## Query Rules

Main query should join:
- account_period_balances
- accounts

Required select output:
- accounts.code
- accounts.name
- account_period_balances.opening_debit
- account_period_balances.opening_credit
- account_period_balances.period_debit
- account_period_balances.period_credit
- account_period_balances.closing_debit
- account_period_balances.closing_credit

Required where filters:
- branch_id
- fiscal_year_id
- fiscal_period_id

Order by:
- accounts.code asc

---

## Files

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

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

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

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

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

---

## Permissions

- reports.trial_balance.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

Optional later:
- show_zero: boolean

---

## UI

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

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

### Table columns
- account_code
- account_name
- opening_debit
- opening_credit
- period_debit
- period_credit
- closing_debit
- closing_credit

### Summary section (optional now)
- total opening debit / credit
- total period debit / credit
- total closing debit / credit

---

## Lang Keys

Suggested keys:
- trial_balance
- account_code
- account_name
- opening_debit
- opening_credit
- period_debit
- period_credit
- closing_debit
- closing_credit
- fiscal_year
- fiscal_period
- branch
- filter
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- reports.trial_balance.view

---

## Steps

### Step 1
Create `TrialBalanceFilterRequest`.

### Step 2
Create `TrialBalanceService`.

### Step 3
Create `TrialBalanceController`.

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

### Step 5
Create trial balance view.

### Step 6
Update lang files.

### Step 7
Update `RolePermissionSeeder` with `reports.trial_balance.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