# Accounting Reports Module - Implementation Guide

## Overview

This module provides a complete Tally-style accounting system for UltimatePOS with double-entry bookkeeping, comprehensive financial reports, and integrity tools.

## What's Been Implemented

### ✅ Complete Foundation

1. **Module Structure**
   - Service providers (main + route)
   - Routes (web + API)
   - Configuration file
   - Language files

2. **Database Schema** (10 migrations)
   - Chart of Accounts
   - Journal Entry Headers & Lines
   - FIFO Layers for inventory costing
   - Ledger Rollups (materialized views)
   - Receivables/Payables subledger
   - Bank Reconciliation
   - Period Locks
   - Audit Log
   - Ratio Snapshots

3. **Models** (10 entities)
   - All with relationships and scopes
   - Helper methods for balance calculations
   - Validation methods

4. **Core Services**
   - ✅ `PostingRulesService` - Complete double-entry posting for:
     - Sales (with COGS)
     - Purchases
     - Receipts
     - Payments
     - Expenses
   - ✅ `FifoCostingService` - FIFO costing and COGS calculation
   - ✅ `TrialBalanceService` - Complete trial balance generation

5. **Controllers**
   - ✅ InstallController
   - ✅ AccountingReportsController (main index)
   - ✅ TrialBalanceController (fully functional)
   - All other report controllers (stubbed for routing)

6. **Views**
   - ✅ Main index page with report cards
   - ✅ Trial Balance page with filters and AJAX

7. **Exports**
   - ✅ TrialBalanceExport class (Excel example)

8. **Seeders**
   - ✅ Default Chart of Accounts seeder

9. **Documentation**
   - ✅ Comprehensive README.md
   - ✅ Configuration examples

## What Needs Implementation

### Report Services (Following TrialBalanceService Pattern)

Create services similar to `TrialBalanceService.php`:

1. **BalanceSheetService**
   - Aggregate assets, liabilities, equity as of date
   - Include inventory valuation from FIFO
   - Calculate retained earnings from cumulative P&L

2. **ProfitLossService**
   - Revenue - Returns - Discounts = Net Sales
   - Net Sales - COGS = Gross Profit
   - Gross Profit - Operating Expenses = Operating Profit
   - ± Other Income/Expenses = PBT
   - PBT - Tax = PAT
   - Support monthly columns and variance %

3. **CashFlowService** (Indirect Method)
   - Start from PAT
   - Add back non-cash items (depreciation)
   - Adjust for working capital changes (AR, Inventory, AP)
   - Calculate CFO, CFI, CFF
   - Reconcile opening + flows = closing cash

4. **FundsFlowService**
   - Calculate working capital (CA - CL) for two dates
   - Show sources and uses of funds

5. **ReceivablesService**
   - Calculate aging buckets
   - Show opening, invoices, receipts, closing per customer
   - Generate customer statements

6. **PayablesService**
   - Similar to receivables but for suppliers

7. **DayBookService**
   - Chronological listing of all JE lines
   - Support filters (date, voucher type, account, amount range)

8. **RatioAnalysisService**
   - Calculate all ratios from config
   - Store snapshots in `ar_ratio_snapshots`

9. **CashBookService**
   - Ledger for cash-in-hand account
   - Running balance

10. **BankBookService**
    - Per-bank-account ledger
    - Reconciliation helpers

11. **StatisticsService**
    - KPIs and charts
    - Use existing chart libraries

### Views

Create view files following `trial-balance/index.blade.php` pattern:

- `balance-sheet/index.blade.php`
- `profit-loss/index.blade.php`
- `cash-flow/index.blade.php`
- `funds-flow/index.blade.php`
- `receivables/index.blade.php` + `aging.blade.php`
- `payables/index.blade.php` + `aging.blade.php`
- `day-book/index.blade.php`
- `ratio-analysis/index.blade.php`
- `cash-book/index.blade.php`
- `bank-book/index.blade.php` + `reconciliation.blade.php`
- `statistics/index.blade.php`
- `batch-print/index.blade.php`
- `integrity/index.blade.php`
- `voucher/view.blade.php`

### Export Classes

Create export classes following `TrialBalanceExport.php` pattern:

- Use `Maatwebsite\Excel` for Excel/CSV
- Use `barryvdh/laravel-dompdf` or `mpdf/mpdf` for PDF

### Permissions Setup

Add permissions to database (create seeder or add to existing):

```php
use Spatie\Permission\Models\Permission;

$permissions = [
    'accounting.view_all',
    'accounting.view_trial_balance',
    'accounting.view_balance_sheet',
    'accounting.view_pl',
    'accounting.view_cashflow',
    'accounting.view_ar',
    'accounting.view_ap',
    'accounting.view_daybook',
    'accounting.view_cashbook',
    'accounting.view_bankbook',
    'accounting.export_reports',
    'accounting.print_multi_account',
];

foreach ($permissions as $permission) {
    Permission::firstOrCreate(['name' => $permission, 'guard_name' => 'web']);
}
```

### Event Listeners (Optional but Recommended)

Create listeners to auto-post transactions:

1. **Listen to transaction events**:
   - When sale is finalized → post journal entry
   - When purchase is finalized → post journal entry
   - When payment is added → post receipt entry
   - When expense is created → post expense entry

2. **Create Event Listeners**:
   - `Listeners/PostSaleListener.php`
   - `Listeners/PostPurchaseListener.php`
   - `Listeners/PostPaymentListener.php`
   - `Listeners/PostExpenseListener.php`

### Integrity Tools Implementation

Complete `IntegrityController` methods:

1. **validate()** - Check all vouchers balance, orphan OBs, etc.
2. **rebuild()** - Rebuild ledgers from transactions
3. **reconcileCogs()** - Reconcile COGS from FIFO vs posted

### Batch Print Implementation

Implement `BatchPrintController@process`:
- Merge multiple PDFs
- Generate table of contents
- Use libraries like `setasign/fpdf` or `mpdf/mpdf`

## Integration with UltimatePOS

### Auto-Posting Transactions

To automatically create journal entries when transactions occur, add to transaction controllers:

```php
// In SellController after sale is finalized
$postingService = new \Modules\AccountingReports\Services\PostingRulesService();
$postingService->postSale($transaction);
```

Or use event listeners (recommended).

### Mapping Existing Accounts

The module creates a default Chart of Accounts, but you may want to map existing `accounts` table to `ar_chart_of_accounts`:

- `ChartOfAccount::where('account_id', $accountId)` - links to existing account
- Create mapping during installation or migration

## Testing

Create tests following Laravel testing patterns:

1. **Unit Tests**:
   - `Tests/Unit/PostingRulesServiceTest.php`
   - `Tests/Unit/FifoCostingServiceTest.php`
   - `Tests/Unit/TrialBalanceServiceTest.php`

2. **Feature Tests**:
   - `Tests/Feature/TrialBalanceTest.php`
   - `Tests/Feature/JournalEntryTest.php`

## Performance Optimization

1. **Materialized Ledgers**: Already included in schema
   - Create scheduled job to update `ar_ledger_rollups` nightly
   - Use for fast report generation

2. **Indexes**: Already added to migrations
   - Monitor slow queries and add indexes as needed

3. **Caching**: Add caching for:
   - Chart of Accounts structure
   - Account balances
   - Ratio calculations

## Next Steps

1. **Complete Trial Balance** (already done) ✅
2. **Implement Balance Sheet Service & View**
3. **Implement P&L Service & View**
4. **Add event listeners for auto-posting**
5. **Complete remaining report services one by one**
6. **Add permissions seeder**
7. **Create unit tests**
8. **Set up scheduled jobs for rollups**
9. **Create migration tool for existing data**

## Support

For questions or issues:
1. Review the README.md
2. Check audit logs (`ar_audit_log`)
3. Use integrity tools to identify problems
4. Review journal entries for transaction flow

---

**Module Status**: Foundation Complete ✅ | Reports: 1/13 Implemented | Ready for Extension