# UploadBackoffice Controller Documentation

## Overview
The `UploadBackoffice` controller is a Laravel PHP controller responsible for handling file uploads of financial and trading data in the Fintra back-office system. It processes three main types of financial data uploads:

1. **Balance Position Files** - Client account balance data
2. **Share Holding Files** - Client security holdings data  
3. **Trade Log Files** - Trading transaction logs

## Class Structure

### Namespace and Dependencies
```php
namespace App\Http\Controllers;

// Key dependencies:
- Illuminate\Http\Request - HTTP request handling
- Illuminate\Support\Facades\Validator - Data validation
- Illuminate\Support\Facades\DB - Database operations
- PHPOpenSourceSaver\JWTAuth\Facades\JWTAuth - JWT authentication
- App\Models\Holiday - Holiday data model
- App\Models\FintraBackUser - User authentication model
```

## Authentication & Authorization

### `checkUser($userdata)` Method
**Purpose**: Validates user authentication and authorization for file upload operations.

**Process Flow**:
1. **JWT Token Validation**: Verifies the JWT token and extracts user information
2. **User Data Validation**: Validates required user fields (users_id, name, email, role, post)
3. **User Existence Check**: Confirms both authenticated user and target user exist in database
4. **ID Matching**: Ensures user ID consistency across token and request data
5. **Token Matching**: Validates remember_token consistency
6. **Role Authorization**: Verifies user role and post permissions

**Return Values**:
- Success: `['status' => true]`
- Failure: Array with status, message, errors, and HTTP code

## Utility Methods

### `exestingRecordheck($tableName, $columnName, $logic, $matchValue)`
**Purpose**: Check if records exist in a table based on date criteria.
**Parameters**:
- `$tableName`: Database table name
- `$columnName`: Column to check (typically date column)
- `$logic`: Comparison operator (>=, =, etc.)
- `$matchValue`: Value to compare against

### `json_response_data($status, $message, $data, $meta, $errors, $ResponseCode)`
**Purpose**: Standardized JSON response formatter.
**Returns**: Formatted JSON response with consistent structure.

### `getSettlementDate($transactionDate, $Tn)`
**Purpose**: Calculate settlement date for financial transactions.
**Logic**:
- Adds `$Tn` business days to transaction date
- Excludes weekends (Friday & Saturday)
- Excludes public holidays from Holiday model
- Returns settlement date in Y-m-d format

## Main Upload Methods

## 1. Balance Position File Upload

### `balancePositionFile(Request $request)`

**Purpose**: Process client account balance position files.

**Input Validation**:
```php
- Date: required|date_format:d-m-Y
- iAgree: required|in:Yes,No  
- data: required|array
- data.*.ClientCode: required|string|max:16
- data.*.Cash: required|numeric
```

**Process Flow**:
1. **Request Validation**: Validates input structure and data types
2. **User Authentication**: Calls `checkUser()` to verify permissions
3. **Duplicate Check**: Checks for existing records on or after the specified date
4. **Agreement Check**: If duplicates exist and user hasn't agreed, returns warning
5. **Database Transaction**: Begins transaction for data integrity
6. **Flag Update**: Sets all existing records to flag='U' (Updated)
7. **Data Processing**:
   - Loops through each position record
   - Looks up BO (Beneficiary Owner) information using ClientCode
   - Inserts new records with flag='A' (Active)
8. **Error Handling**: Rolls back transaction if any record fails
9. **Response**: Returns success/failure with processing statistics

**Database Table**: `adm_position_temp`

**Key Fields**:
- `bo_id`: Foreign key to bo_initial_info
- `fintr_customer_id`: Client identifier
- `balance`: Account balance amount
- `flag`: Record status (A=Active, U=Updated)
- `date`: Position date

## 2. Share Holding File Upload

### `shareHoldingFile(Request $request)`

**Purpose**: Process client security holding position files.

**Input Validation**:
```php
- Date: required|string
- iAgree: required|in:Yes,No
- data: required|array
- data.*.ClientCode: required|string
- data.*.SecurityCode: required|string
- data.*.Quantity: required|numeric
- data.*.TotalCost: required|numeric
- data.*.PositionType: required|string
```

**Process Flow**: Similar to balance position file with additional security-specific fields.

**Database Table**: `client_share_holding`

**Key Fields**:
- `bo_id`: Foreign key to bo_initial_info
- `fintr_customer_id`: Client identifier
- `security_code`: Security/stock identifier
- `quantity`: Number of shares held
- `total_cost`: Total cost of holdings
- `position_type`: Type of position (Long/Short, etc.)

## 3. Trade Log File Upload

### `finTradeLogFile(Request $request)`

**Purpose**: Process trading transaction log files.

**Input Validation**: Extensive validation for 20+ trading-related fields including:
```php
- Action, Status, AssetClass, OrderID, RefOrderID
- Side, SecurityCode, Board, Time
- Quantity, Price, Value
- Trading and settlement details
```

**Process Flow**:
1. **Status Filtering**: Only processes records with Status = 'PF' or 'FILL'
2. **Settlement Calculation**: 
   - Z Category: 3 business days settlement
   - Other Categories: 2 business days settlement
3. **Bridge Loan Processing**: Calculates bridge loan capacity and availability
4. **Comprehensive Logging**: Stores complete trading transaction details

**Database Table**: `client_share_holding_log`

**Key Fields**: Complete trading transaction data including execution details, settlement information, and bridge loan calculations.

## Error Handling & Response Patterns

### Transaction Management
- All operations use database transactions
- Complete rollback on any failure
- Maintains data integrity across all records

### Response Structure
```json
{
    "status": "success|error",
    "message": "Description",
    "data": {}, 
    "meta": {
        "successful": count,
        "failed": count
    },
    "errors": []
}
```

### Common Error Scenarios
1. **Authentication Failures**: Invalid JWT, user mismatch, role issues
2. **Validation Errors**: Missing fields, invalid data types
3. **Duplicate Data**: Records already exist for date range
4. **Database Errors**: Insert failures, connection issues
5. **Business Logic Errors**: Missing BO accounts, invalid client codes

## Security Features

1. **JWT Authentication**: Token-based user authentication
2. **Role-Based Authorization**: User role and post validation
3. **Data Integrity**: Database transactions ensure consistency
4. **Input Validation**: Comprehensive validation for all inputs
5. **SQL Injection Prevention**: Uses parameterized queries

## Usage Notes

### File Upload Flow
1. Client sends POST request with file data
2. System validates user permissions
3. Data is validated against business rules
4. Existing records are flagged as updated
5. New records are inserted with active flag
6. Transaction commits only if all records succeed

### Date Handling
- Input dates in d-m-Y format (e.g., "25-12-2024")
- Stored in database as Y-m-d format
- Settlement dates calculated using business day logic

### Flag System
- `A` = Active (newly inserted records)
- `U` = Updated (previous records marked as superseded)

This controller is critical for maintaining accurate financial position data and trade logs in the Fintra system, with robust error handling and data integrity measures.