# Patent Transactions Module

## Overview

The Patent Transactions module provides a comprehensive system for recording, managing, and tracking financial transactions related to patent applications. This production-ready feature allows agents to record each transaction paid per patent application with full audit trails and status management.

## Features

### Core Functionality
- **Transaction Recording**: Record various types of transactions (filing fees, maintenance fees, legal fees, etc.)
- **Multi-Currency Support**: Handle transactions in different currencies with automatic USD conversion
- **Status Management**: Track transaction status (pending, approved, rejected, paid, cancelled)
- **Bill Management**: Track billing status (not billed, billed, paid)
- **Target Management**: Associate transactions with clients or associates
- **Country Tracking**: Record country-specific transaction details
- **Deadline Management**: Set transaction and billing deadlines
- **Audit Trail**: Complete history of transaction changes and approvals

### Advanced Features
- **Automatic Reference Generation**: Unique transaction reference numbers
- **Exchange Rate Management**: Real-time currency conversion
- **Payment Method Tracking**: Bank transfer, credit card, cash, check, other
- **Invoice Integration**: Link transactions to invoice numbers
- **Comments System**: Add notes and comments to transactions
- **Quick Stats Dashboard**: Real-time transaction statistics
- **Filtering & Search**: Advanced filtering by status, country, date range, etc.

## Database Structure

### Main Table: `pt_transactions`

```sql
CREATE TABLE pt_transactions (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    reference_no VARCHAR(255) UNIQUE NOT NULL,
    patent_id BIGINT NOT NULL,
    transaction_type_id BIGINT NOT NULL,
    target_type ENUM('clients', 'associates') DEFAULT 'clients',
    target_id BIGINT NULL,
    country VARCHAR(255) NULL,
    amount DECIMAL(15,2) DEFAULT 0,
    amount_usd DECIMAL(15,2) DEFAULT 0,
    currency VARCHAR(3) DEFAULT 'USD',
    exchange_rate DECIMAL(10,4) DEFAULT 1.0000,
    transaction_date DATE NULL,
    deadline DATE NULL,
    bill_deadline DATE NULL,
    description TEXT NULL,
    payment_method VARCHAR(255) NULL,
    transaction_reference VARCHAR(255) NULL,
    invoice_no VARCHAR(255) NULL,
    status ENUM('pending', 'approved', 'rejected', 'paid', 'cancelled') DEFAULT 'pending',
    bill_status ENUM('not_billed', 'billed', 'paid') DEFAULT 'not_billed',
    has_bills BOOLEAN DEFAULT FALSE,
    stages JSON NULL,
    role_ranks JSON NULL,
    created_by BIGINT NOT NULL,
    approved_by BIGINT NULL,
    approved_at TIMESTAMP NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (patent_id) REFERENCES pt_patent_tkts(id) ON DELETE CASCADE,
    FOREIGN KEY (transaction_type_id) REFERENCES actions_type_transactions(id) ON DELETE RESTRICT,
    FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE RESTRICT,
    FOREIGN KEY (approved_by) REFERENCES users(id) ON DELETE SET NULL,
    
    INDEX idx_patent_status (patent_id, status),
    INDEX idx_transaction_date (transaction_date),
    INDEX idx_deadline (deadline),
    INDEX idx_country (country),
    INDEX idx_target (target_type, target_id)
);
```

## API Endpoints

### Transaction Management
- `GET /patents/transactions/patent/{patentId}` - List transactions for a patent
- `GET /patents/transactions/patent/{patentId}/create` - Create new transaction form
- `POST /patents/transactions/patent/{patentId}` - Store new transaction
- `GET /patents/transactions/patent/{patentId}/{transactionId}` - View transaction details
- `GET /patents/transactions/patent/{patentId}/{transactionId}/edit` - Edit transaction form
- `PUT /patents/transactions/patent/{patentId}/{transactionId}` - Update transaction
- `DELETE /patents/transactions/patent/{patentId}/{transactionId}` - Delete transaction

### Transaction Actions
- `POST /patents/transactions/patent/{patentId}/{transactionId}/approve` - Approve transaction
- `POST /patents/transactions/patent/{patentId}/{transactionId}/reject` - Reject transaction
- `POST /patents/transactions/patent/{patentId}/{transactionId}/mark-paid` - Mark as paid

### AJAX Endpoints
- `GET /patents/transactions/target-options` - Get target options based on type

## Usage Examples

### Creating a New Transaction

```php
use Modules\Patent\Entities\PatentTransaction;

$transaction = PatentTransaction::create([
    'patent_id' => 123,
    'transaction_type_id' => 5,
    'target_type' => 'clients',
    'target_id' => 456,
    'country' => 'Egypt',
    'amount' => 1000.00,
    'currency' => 'USD',
    'exchange_rate' => 1.0000,
    'amount_usd' => 1000.00,
    'transaction_date' => now(),
    'deadline' => now()->addDays(30),
    'description' => 'Patent filing fee',
    'payment_method' => 'bank_transfer',
    'status' => 'pending'
]);
```

### Querying Transactions

```php
// Get all transactions for a patent
$transactions = PatentTransaction::where('patent_id', 123)->get();

// Get pending transactions
$pending = PatentTransaction::withStatus('pending')->get();

// Get transactions by country
$egyptTransactions = PatentTransaction::fromCountry('Egypt')->get();

// Get transactions within date range
$recentTransactions = PatentTransaction::withinDateRange('2024-01-01', '2024-12-31')->get();

// Search transactions
$searchResults = PatentTransaction::search('filing fee')->get();
```

### Approving a Transaction

```php
$transaction = PatentTransaction::find(1);
$transaction->update([
    'status' => 'approved',
    'approved_by' => auth()->id(),
    'approved_at' => now()
]);
```

## Integration with Existing System

### Patent Application Edit View
The transaction management section has been integrated into the patent application edit view with:
- Quick access buttons to view and create transactions
- Real-time statistics dashboard
- Links to both new patent transactions and legacy accounting transactions

### Legacy System Compatibility
The system maintains compatibility with the existing `AccTransactionController` while providing a dedicated patent transaction system with enhanced features.

## Security & Permissions

### Authentication
- All routes require authentication (`auth` middleware)
- User tracking for created and approved transactions

### Data Validation
- Comprehensive validation rules for all transaction fields
- Currency and amount validation
- Date validation for deadlines and transaction dates

### Audit Trail
- Complete tracking of who created, modified, and approved transactions
- Timestamp tracking for all changes
- Status change history

## Performance Optimizations

### Database Indexes
- Optimized indexes for common query patterns
- Foreign key constraints for data integrity
- Efficient pagination support

### Query Optimization
- Eager loading of related models
- Scoped queries for common operations
- Efficient filtering and search capabilities

## Deployment Instructions

### 1. Run Migration
```bash
php artisan migrate
```

### 2. Clear Cache
```bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
```

### 3. Verify Routes
```bash
php artisan route:list --name=patent.transactions
```

### 4. Test Functionality
- Create a test patent application
- Add transactions through the UI
- Test approval workflow
- Verify statistics display

## Monitoring & Maintenance

### Regular Tasks
- Monitor transaction statuses for overdue items
- Review pending approvals
- Check currency exchange rates
- Audit transaction data integrity

### Reporting
- Transaction summaries by patent
- Financial reports by country
- Status distribution reports
- Payment method analytics

## Troubleshooting

### Common Issues

1. **Transaction not appearing**: Check if the patent ID exists and user has permissions
2. **Currency conversion errors**: Verify exchange rate is set correctly
3. **Status not updating**: Ensure user has approval permissions
4. **Missing target options**: Check if clients/associates exist in the system

### Debug Mode
Enable debug mode in `.env` to see detailed error messages:
```
APP_DEBUG=true
```

## Future Enhancements

### Planned Features
- Bulk transaction import/export
- Advanced reporting dashboard
- Email notifications for deadlines
- Integration with external payment systems
- Mobile-responsive interface improvements
- API for external system integration

### Scalability Considerations
- Consider partitioning for large transaction volumes
- Implement caching for frequently accessed data
- Add background job processing for heavy operations
- Consider microservices architecture for high-volume deployments

## Support

For technical support or feature requests, please contact the development team or create an issue in the project repository.

---

**Version**: 1.0.0  
**Last Updated**: January 2024  
**Compatibility**: Laravel 8+, PHP 8.0+