# Stock Transfer Accounting - Quick Start Guide

## Overview

This implementation adds proper international accounting standards (IAS 2) compliant accounting for inter-branch stock transfers in your POS system.

## What Changed

### 1. Database
- Added `posting_status`, `dispatch_posted_at`, `receipt_posted_at`, and `notes` fields to `stock_transfers` table

### 2. Accounting Treatment
- **Inter-branch transfers are NOT sales** - they're internal movements
- Transfers are recorded at **COST** (purchase_price), not selling price
- **No revenue, no profit, no taxes** on transfers
- Proper audit trail via journal entries

### 3. Journal Entries

When a stock transfer is approved:
```
DR: Inventory (Receiving Branch)  [Cost]
CR: Inventory (Sending Branch)    [Cost]
```

## Installation Steps

### Step 1: Run Migration
```bash
php artisan migrate
```

This adds the new fields to the `stock_transfers` table.

### Step 2: Verify Files Updated
Ensure these files have been updated:
- ✅ `app/Models/StockTransfer.php` - Added new fillable fields
- ✅ `app/Services/AccountingPostingService.php` - Added 3 new methods
- ✅ `app/Http/Controllers/Tenant/StockTransferController.php` - Integrated accounting service

### Step 3: Test the System

#### Test 1: Create and Approve Transfer
1. Go to Stock Transfer page
2. Create a transfer from Branch A to Branch B
3. Select a product (e.g., 10 units @ GHS 5.00 cost = GHS 50.00)
4. Submit transfer (status = "processed")
5. Go to Approval page
6. Approve the transfer
7. **Expected Result:**
   - Inventory reduced in Branch A
   - Inventory increased in Branch B
   - Journal entry created with DR/CR of GHS 50.00

#### Test 2: Verify Accounting Entry
1. Go to Accounting → Journal Entries
2. Find entry with source_type = "stock_transfer"
3. **Verify:**
   - Debit = Credit (balanced)
   - Amount = total_cost (not selling_price)
   - Two lines: one for each branch
   - Memo describes the transfer clearly

#### Test 3: Delete Transfer (Reversal)
1. Create a transfer but don't approve it
2. Delete the transfer
3. **Expected Result:**
   - Stock restored to sending branch
   - If accounting was posted, reversal entry created

## Key Accounting Principles

### ✅ DO:
- Use **purchase_price** (cost) for all accounting entries
- Post entries when transfer is **approved**
- Track both dispatch and receipt
- Reverse entries when transfers are deleted
- Document transfer reasons in notes

### ❌ DON'T:
- Use selling_price for accounting
- Recognize revenue on transfers
- Charge VAT/taxes on transfers
- Delete transfers without reversing entries
- Skip approval workflow

## Accounting Flow

```
1. CREATE TRANSFER (Status: Processed)
   ├─ Reduce inventory in sending branch (physical)
   └─ No accounting entry yet

2. APPROVE TRANSFER (Status: Approved)
   ├─ Increase inventory in receiving branch (physical)
   └─ POST ACCOUNTING ENTRY:
      DR: Inventory (Receiving Branch)
      CR: Inventory (Sending Branch)

3. DELETE TRANSFER (if needed)
   ├─ Restore inventory in sending branch
   ├─ Reduce inventory in receiving branch (if approved)
   └─ REVERSE ACCOUNTING ENTRY (if posted)
```

## Reports Impact

### Trial Balance
- Inventory account remains balanced
- No impact on revenue/expenses
- Branch-specific inventory tracking

### Income Statement
- **No impact** - transfers don't affect P&L
- Only actual sales show as revenue

### Balance Sheet
- Inventory distributed across branches
- Total inventory value unchanged

## Common Scenarios

### Scenario 1: Simple Transfer
**Situation:** Transfer 100 units @ GHS 5.00 from Warehouse to Shop A

**Physical Movement:**
- Warehouse: -100 units, -GHS 500
- Shop A: +100 units, +GHS 500

**Accounting Entry:**
```
DR: Inventory (Shop A)      500.00
CR: Inventory (Warehouse)   500.00
```

### Scenario 2: Multiple Products Transfer
**Situation:** Transfer multiple products in one invoice

**Result:** One journal entry with multiple line pairs (one DR/CR pair per product)

### Scenario 3: Transfer Correction
**Situation:** Wrong quantity transferred, need to reverse

**Action:**
1. Delete the transfer
2. System automatically reverses accounting entry
3. Create new transfer with correct quantity

## Troubleshooting

### Issue: Accounting entry not created
**Check:**
- Is transfer status "approved"?
- Check logs for errors: `storage/logs/laravel.log`
- Verify inventory account exists in chart of accounts

### Issue: Trial balance not balanced
**Check:**
- All transfers have matching DR/CR amounts
- No manual edits to journal entries
- Run: `SELECT * FROM acc_journal_lines WHERE journal_id IN (SELECT id FROM acc_journals WHERE source_type = 'stock_transfer')`

### Issue: Wrong amount posted
**Verify:**
- Using `total_cost` field (qty × purchase_price)
- NOT using `selling_price` × qty
- Check product's purchase_price is correct

## Best Practices

1. **Always approve transfers promptly** - Don't leave in "processed" status
2. **Document reasons** - Use notes field for transfer justification
3. **Reconcile regularly** - Compare physical stock with accounting records
4. **Review aging transfers** - Investigate transfers pending approval > 24 hours
5. **Audit trail** - Never delete journal entries manually

## Stock Request vs Stock Transfer

### Stock Request
- **Initiated by:** Receiving branch (requesting stock)
- **Approval by:** Warehouse/source branch
- **Use when:** Branch needs to request stock from warehouse

### Stock Transfer
- **Initiated by:** Sending branch (pushing stock)
- **Approval by:** Receiving branch
- **Use when:** Warehouse distributing stock to branches

**Both use the same accounting treatment** - internal movement at cost.

## Integration with Existing Accounting

The stock transfer accounting integrates seamlessly with:
- ✅ Sales accounting (postSaleInvoice)
- ✅ Stock receipt accounting (postStockReceipt)
- ✅ Expense accounting (postExpense)
- ✅ Trial balance
- ✅ Income statement
- ✅ Balance sheet

## Compliance

This implementation complies with:
- **IAS 2 (Inventories)** - Proper inventory valuation and movement
- **IAS 1 (Presentation of Financial Statements)** - Proper classification
- **IFRS for SMEs** - Simplified reporting for small/medium entities

## Support

For issues or questions:
1. Check logs: `storage/logs/laravel.log`
2. Review journal entries: Accounting → Journal Entries
3. Verify trial balance: Accounting → Trial Balance
4. Check this documentation

## Summary

✅ **Implemented:** IAS 2 compliant stock transfer accounting
✅ **Benefit:** Accurate inventory tracking across branches
✅ **Impact:** Better financial reporting and audit trail
✅ **Compliance:** International accounting standards

The system now properly tracks all inter-branch movements with full accounting integration!