# Automated Sales & Purchase Journals - Implementation Summary

## Overview

This document describes the complete implementation of **automated journal entry posting** for Sales and Purchase transactions in the Accounting Reports module. The system automatically creates double-entry journal entries whenever a sale or purchase is finalized in UltimatePOS.

---

## ✅ What Has Been Implemented

### 1. **Event Listeners** (Automatic Posting)

#### **PostSaleJournalListener**
- **Location:** `Modules/AccountingReports/Listeners/PostSaleJournalListener.php`
- **Functionality:**
  - Listens to `SellCreatedOrModified` events
  - Automatically posts sales transactions to journal entries
  - Only processes final sales (not drafts or quotations)
  - Checks if module is enabled before posting
  - Prevents duplicate posting (checks for existing journal entries)
  - Logs errors without breaking the sale process

#### **PostPurchaseJournalListener**
- **Location:** `Modules/AccountingReports/Listeners/PostPurchaseJournalListener.php`
- **Functionality:**
  - Listens to `PurchaseCreatedOrModified` events
  - Automatically posts purchase transactions to journal entries
  - Only processes received purchases (not drafts)
  - Checks if module is enabled before posting
  - Prevents duplicate posting
  - Logs errors without breaking the purchase process

### 2. **Event Registration**

- **Location:** `Modules/AccountingReports/Providers/AccountingReportsServiceProvider.php`
- **Method:** `registerEventListeners()`
- **Functionality:**
  - Registers both listeners in the service provider's `boot()` method
  - Uses Laravel's Event facade for event listening
  - Automatically active when module is loaded

### 3. **Sales Journal Controller**

- **Location:** `Modules/AccountingReports/Http/Controllers/SalesJournalController.php`
- **Routes:**
  - `GET /accounting-reports/sales-journal` - Index page
  - `GET /accounting-reports/sales-journal/get-data` - AJAX data
  - `GET /accounting-reports/sales-journal/export` - Export (placeholder)

- **Features:**
  - Date range filtering
  - Location filtering
  - Permission-based access control
  - DataTables integration
  - Shows: Voucher No, Date, Invoice No, Customer, Debit, Credit, Location, Narration
  - Action buttons: View Voucher, View Source Document

### 4. **Purchase Journal Controller**

- **Location:** `Modules/AccountingReports/Http/Controllers/PurchaseJournalController.php`
- **Routes:**
  - `GET /accounting-reports/purchase-journal` - Index page
  - `GET /accounting-reports/purchase-journal/get-data` - AJAX data
  - `GET /accounting-reports/purchase-journal/export` - Export (placeholder)

- **Features:**
  - Date range filtering
  - Location filtering
  - Permission-based access control
  - DataTables integration
  - Shows: Voucher No, Date, Bill No, Supplier, Debit, Credit, Location, Narration
  - Action buttons: View Voucher, View Source Document

### 5. **Views**

#### **Sales Journal View**
- **Location:** `Modules/AccountingReports/Resources/views/sales-journal/index.blade.php`
- **Features:**
  - Date range picker (defaults to current month)
  - Location dropdown filter
  - DataTables with server-side processing
  - Export button (for users with export permission)
  - Responsive design matching UltimatePOS style

#### **Purchase Journal View**
- **Location:** `Modules/AccountingReports/Resources/views/purchase-journal/index.blade.php`
- **Features:**
  - Same features as Sales Journal
  - Tailored for purchase transactions

### 6. **Menu Integration**

- **Location:** `Modules/AccountingReports/Http/Controllers/DataController.php`
- **Menu Items Added:**
  - **Sales Journal** - Under Accounting Reports dropdown
  - **Purchase Journal** - Under Accounting Reports dropdown
- **Position:** After Cash Flow, before Direct Expenses
- **Permission:** Requires `accounting.view_all` permission

### 7. **Language Translations**

- **Location:** `Modules/AccountingReports/Resources/lang/en/lang.php`
- **New Translations:**
  - `sales_journal` - "Sales Journal"
  - `purchase_journal` - "Purchase Journal"
  - `automated_journal_entries` - "Automated Journal Entries"
  - `view_voucher` - "View Voucher"
  - `view_source_document` - "View Source Document"
  - `bill_no` - "Bill No"

### 8. **Routes**

- **Location:** `Modules/AccountingReports/Routes/web.php`
- **Routes Added:**
  ```php
  // Sales Journal
  Route::get('/sales-journal', 'SalesJournalController@index')
  Route::get('/sales-journal/get-data', 'SalesJournalController@getData')
  Route::get('/sales-journal/export', 'SalesJournalController@export')
  
  // Purchase Journal
  Route::get('/purchase-journal', 'PurchaseJournalController@index')
  Route::get('/purchase-journal/get-data', 'PurchaseJournalController@getData')
  Route::get('/purchase-journal/export', 'PurchaseJournalController@export')
  ```

---

## 🔄 How It Works

### Automatic Journal Posting Flow

1. **Sale Transaction Created:**
   ```
   User creates sale → Transaction saved → SellCreatedOrModified event fired
   → PostSaleJournalListener triggered → postSale() called
   → Journal entry created with double-entry postings
   ```

2. **Purchase Transaction Created:**
   ```
   User creates purchase → Transaction saved → PurchaseCreatedOrModified event fired
   → PostPurchaseJournalListener triggered → postPurchase() called
   → Journal entry created with double-entry postings
   ```

### Journal Entry Structure

#### **Sales Journal Entry:**
```
Dr. Accounts Receivable / Cash/Bank    (final_total)
Cr. Sales Revenue                      (revenue)
Cr. Output Tax                         (tax)
Dr. Discount Expense                   (if discount)
Dr. COGS                               (calculated via FIFO)
Cr. Inventory                          (calculated via FIFO)
```

#### **Purchase Journal Entry:**
```
Dr. Inventory                          (purchase cost)
Dr. Input Tax                          (tax)
Cr. Accounts Payable / Cash/Bank       (total)
```

### Viewing Journals

1. Navigate to **Accounting → Reports → Sales Journal** or **Purchase Journal**
2. Select date range and location (optional)
3. Click "Filter" to load journal entries
4. View all automated journal entries with:
   - Voucher details
   - Customer/Supplier information
   - Debit and Credit totals
   - Links to source documents
   - Links to view full voucher details

---

## 🔒 Security & Permissions

- **Access Control:** All routes protected by `accounting.view_all` permission
- **Location Scoping:** Respects user's permitted locations
- **Business Scoping:** All queries scoped to user's business_id
- **Export Permission:** Export requires `accounting.export_reports` permission

---

## 📊 Features

### ✅ Automatic Posting
- No manual intervention required
- Posts immediately when transaction is finalized
- Prevents duplicate posting

### ✅ Error Handling
- Errors logged but don't break transaction flow
- Graceful degradation if module disabled
- Period lock checking

### ✅ Integration
- Full integration with UltimatePOS transaction flow
- Respects location permissions
- Links to source documents
- Drill-down to voucher details

### ✅ Reporting
- Date range filtering
- Location filtering
- Export capability (placeholder)
- DataTables for fast loading

---

## 🚀 Usage

### For End Users

1. **Create a Sale:**
   - Go to POS or Sales module
   - Create and finalize a sale
   - Journal entry is automatically created
   - View it in Sales Journal

2. **Create a Purchase:**
   - Go to Purchase module
   - Create and receive a purchase
   - Journal entry is automatically created
   - View it in Purchase Journal

3. **View Journals:**
   - Navigate to Accounting → Reports
   - Click "Sales Journal" or "Purchase Journal"
   - Filter by date range and location
   - View all automated entries

### For Administrators

- **Monitor Posting:** Check logs for any posting errors
- **Period Locking:** Enable period locks to prevent edits
- **Rebuild:** Use Integrity Tools to rebuild journals if needed

---

## 🔧 Configuration

### Enable/Disable Module

The automatic posting only works if:
1. Accounting Reports module is installed
2. Module is enabled in `modules_statuses.json`
3. Module version is set in system table

### Period Locking

If period locking is enabled:
- Transactions in locked periods cannot be posted
- Errors will be logged but won't break the transaction

---

## 📝 Technical Details

### Event Listener Registration

Event listeners are registered in `AccountingReportsServiceProvider::boot()`:

```php
protected function registerEventListeners()
{
    \Event::listen(
        \App\Events\SellCreatedOrModified::class,
        \Modules\AccountingReports\Listeners\PostSaleJournalListener::class
    );

    \Event::listen(
        \App\Events\PurchaseCreatedOrModified::class,
        \Modules\AccountingReports\Listeners\PostPurchaseJournalListener::class
    );
}
```

### Duplicate Prevention

Both listeners check for existing journal entries:

```php
$existingJournal = JournalEntryHeader::where('source_transaction_id', $transaction->id)
    ->where('source_module', 'sale')
    ->first();

if ($existingJournal) {
    return; // Skip if already posted
}
```

---

## 🐛 Troubleshooting

### Journals Not Posting

1. **Check Module Status:**
   - Verify module is enabled in `modules_statuses.json`
   - Check system table for `accountingreports_version`

2. **Check Logs:**
   - Review Laravel logs for posting errors
   - Look for "AccountingReports:" prefixed messages

3. **Check Permissions:**
   - Ensure Chart of Accounts is set up
   - Verify control accounts exist

4. **Check Period Locks:**
   - If period locking enabled, verify date is not locked

### Missing Journal Entries

1. **Rebuild Journals:**
   - Go to Accounting → Integrity Tools
   - Run "Rebuild Ledgers" to backfill missing entries

2. **Check Transaction Status:**
   - Only final sales and received purchases are posted
   - Drafts and quotations are not posted

---

## 📈 Future Enhancements

Potential improvements:
- [ ] Payment journal entries (receipts/payments)
- [ ] Expense journal entries
- [ ] Stock adjustment journal entries
- [ ] Export to Excel/PDF
- [ ] Email notifications for posting errors
- [ ] Dashboard widget showing recent journals
- [ ] Batch rebuild tool

---

## ✅ Testing Checklist

- [x] Event listeners created and registered
- [x] Sales journal automatically posts on sale creation
- [x] Purchase journal automatically posts on purchase creation
- [x] Duplicate posting prevented
- [x] Sales Journal view displays correctly
- [x] Purchase Journal view displays correctly
- [x] Menu items appear in sidebar
- [x] Permissions enforced
- [x] Location filtering works
- [x] Date filtering works
- [x] Links to source documents work
- [x] Links to voucher details work

---

## 📞 Support

For issues or questions:
1. Check Laravel logs for errors
2. Review journal entries in database
3. Use Integrity Tools to validate data
4. Check module installation status

---

**Implementation Date:** 2025-01-XX  
**Version:** 1.0.4  
**Status:** ✅ Production Ready