# Sales Returns/Void Sales with Audit Trail System

This system implements comprehensive audit trails for your POS system, allowing you to void sales or delete them while maintaining a complete record of all operations.

## Features Implemented

### 1. Audit Trail System
- **Complete tracking** of all sales operations (void, delete, edit, return)
- **User tracking** - records who performed each action
- **Reason tracking** - requires reason for void/delete operations
- **Data snapshots** - stores complete sale data before any changes
- **Timestamp tracking** - records when each action was performed

### 2. Sales Status Management
- **Active**: Normal sales
- **Voided**: Sales that are voided (reversible)
- **Returned**: Sales with returns processed
- **Deleted**: Sales permanently removed from system

### 3. Enhanced UI Features
- **Void Sale** button for soft deletion
- **Audit Trail** button to view complete history
- **Status indicators** in receipts list
- **Visual distinctions** for voided/deleted sales
- **Read-only sale details** - viewing only, no editing capabilities

## Installation

### Step 1: Run Database Migration
```bash
# Navigate to your POS directory
cd C:\xampp\htdocs\apps

# Run the migration script
php run_audit_migration.php
```

### Step 2: Verify Installation
- Check that new tables are created in your database
- Verify that the sales table has new status columns
- Test the new functionality in receipts.php

## Database Tables Created

### 1. `{branch_code}_sales_audit`
Stores audit trail for all sales operations:
- `audit_id`: Primary key
- `sale_id`: Reference to original sale
- `action_type`: Type of action (void, return, delete, edit)
- `original_total`: Sale amount before action
- `return_amount`: Amount returned (for returns)
- `reason`: Reason for the action
- `notes`: Additional notes
- `performed_by`: User who performed the action
- `sale_data_snapshot`: Complete sale data before action

### 2. `{branch_code}_sales_returns`
Manages sales return operations:
- `return_id`: Primary key
- `original_sale_id`: Reference to original sale
- `return_sale_id`: Reference to return transaction
- `return_type`: Full or partial return
- `return_amount`: Amount being returned
- `reason`: Reason for return
- `performed_by`: User who processed return

### 3. `{branch_code}_return_items`
Details of returned items:
- `return_item_id`: Primary key
- `return_id`: Reference to return record
- `item_id`: Product being returned
- `original_quantity`: Original quantity sold
- `return_quantity`: Quantity being returned
- `return_amount`: Amount for this item return

### 4. Updated `{branch_code}_sales` Table
Added columns:
- `status`: Sale status (active, voided, returned, deleted)
- `voided_at`: When sale was voided
- `voided_by`: User who voided the sale
- `void_reason`: Reason for voiding

## How to Use

### Void a Sale (Recommended)
1. Open receipts.php
2. Click on a sale to view details
3. Click "Void Sale" button
4. Enter reason for voiding
5. Enter optional notes
6. Confirm the action

**Effect**: 
- Sale status changes to "voided"
- Stock is restored
- Credit balances are adjusted (for credit sales)
- Cash flow is recorded (for cash sales)
- Original sale data is preserved
- Audit trail is created

### Delete a Sale (Backend Only)
Sales can only be deleted through the backend void/delete functions in the audit system. Direct deletion from the UI has been removed for security and control purposes.

### View Audit Trail
1. Open receipts.php
2. Click on any sale to view details
3. Click "Audit Trail" button
4. View complete history of actions on the sale

## Key Differences: Void vs Delete

| Action | Void Sale | Delete Sale |
|--------|-----------|-------------|
| **Data Retention** | Sale record remains | Sale record removed |
| **Reversibility** | Can potentially be reversed | Permanent action |
| **Stock Impact** | Stock restored | Stock restored |
| **Credit Impact** | Credits adjusted | Credits adjusted |
| **Cash Flow Impact** | Negative cash movement recorded | Negative cash movement recorded |
| **Audit Trail** | Full audit trail | Full audit trail |
| **Visibility** | Shows as "voided" | Not visible in normal views |
| **Use Case** | Mistakes, customer requests | Data cleanup, duplicates |

## Best Practices

### 1. When to Void vs Delete
- **Use Void** for:
  - Customer change of mind
  - Staff mistakes
  - Incorrect orders
  - Any situation where you might need to reference the original sale

- **Use Delete** for:
  - Duplicate entries
  - Test transactions
  - Data cleanup
  - Sales that should never have existed

### 2. Audit Trail Management
- Always provide clear reasons for actions
- Use the notes field for additional context
- Review audit trails regularly for compliance
- Train staff on proper void/delete procedures

### 3. Stock Management
- Both void and delete automatically restore stock
- Stock movements are logged with proper references
- Stock corrections are automatically applied

### 4. Credit Customer Handling
- Credit balances are automatically adjusted
- Credit transactions are properly handled
- Customer balance history is maintained

### 5. Cash Flow Integration
- Cash sales automatically record negative cash movements when voided/deleted
- Cash flow is tracked in the cash_flow.php system
- Shift balances are automatically updated
- Void/delete transactions appear as "VOID SALE" movement type
- Only cash sales affect cash flow (credit/GCash sales do not)

## Security Features

1. **User Tracking**: All actions are tied to the logged-in user
2. **Immutable Audit Trail**: Audit records cannot be modified
3. **Complete Data Snapshots**: Full sale data is preserved
4. **Reason Requirements**: All actions require documented reasons
5. **Confirmation Dialogs**: Multiple confirmations prevent accidental actions

## Troubleshooting

### Migration Issues
If migration fails:
1. Check database connection in `conf/config.php`
2. Ensure user has CREATE TABLE permissions
3. Verify branch code is set correctly
4. Check for existing table conflicts

### Missing Audit Helper
If you get "audit_helper.php not found":
1. Ensure the file exists in `includes/` directory
2. Check file permissions
3. Verify the include path is correct

### Button Not Working
If void/delete buttons don't work:
1. Check JavaScript console for errors
2. Verify Bootstrap modal is loaded
3. Ensure sales_handler.php is accessible
4. Check network requests in browser dev tools

## Future Enhancements

This system is designed to support future features like:
- **Partial Returns**: Return specific items from a sale
- **Return Reasons**: Categorized return reasons
- **Manager Overrides**: Special permissions for sensitive operations
- **Reporting**: Audit trail reports and analytics
- **Automated Alerts**: Notifications for unusual void/delete patterns

## Support

If you encounter issues:
1. Check the audit trail to understand what happened
2. Review the logs in `logs/` directory
3. Verify database structure matches expected schema
4. Test with a simple sale first

The audit trail system ensures complete transparency and accountability for all sales operations while maintaining data integrity and business compliance requirements.