ShippingFiles Documentation

Shipping Files Controller Documentation

File: /controllers/shippingFilesController.php

Purpose: Manages shipping documentation, file uploads, and delivery tracking for import contracts

Last Updated: December 19, 2024

Total Functions: 3 main actions + 12 file type handlers

Lines of Code: 161

---

📋 Overview

The Shipping Files Controller manages the complete documentation workflow for shipping and import operations. It handles:

Primary Functions

Document Types Managed

Related Controllers

---

🗄️ Database Tables

Primary Tables (Direct Operations)

Table NamePurposeKey Columns
**shippingfile**Main shipping documentsid, chasis, buybillfile, cocfile, finalbillfile, warehousefile, etc.
**shippingfile (user columns)**User trackingbuybilluserid, cocuserid, finalbilluserid, warehouseuserid, etc.
**shippingfile (date columns)**Date trackingbuybilldate, cocdate, finalbilldate, warehousedate, etc.
### Integration Tables

Table NamePurposeRelationship
**importcontract**Import chassis dataSource of chassis numbers
**user**User informationUser who uploaded files
### File Storage Structure

DirectoryPurposeFile Types
**../upload/shippingFiles**Document storagePDF, DOC, JPG, PNG, etc.
### Document Tracking Schema

Each document type has 3 associated columns:

Example for Buy Bill documents:

---

🔧 Key Functions

1. Main Interface (empty $do)

Purpose: Display chassis selection and main shipping files interface

Called By: Direct navigation to controller

Line: 8

Process Flow: 

Load Chassis Numbers
         ↓
Filter Active Contracts (del < 2)
         ↓
Display Chassis Selection
         ↓
Await User Selection

Business Logic:

1. Queries distinct chassis numbers from importcontract table

2. Filters only active contracts (not deleted: del < 2)

3. Displays chassis selection dropdown

4. Provides interface for file management

Database Query: 

SELECT DISTINCT chasisno FROM importcontract 
WHERE chasisno != '' AND del < 2

2. getFiles

Purpose: Load or create shipping file record for specific chassis

Called By: AJAX request with chassis selection

Line: 18

Parameters (via $_POST):

Process Flow:

┌─────────────────────────┐
If Not Exists:
- Create new record
- Set chassis number
- Set creation date
- Set creating user
└─────────────────────────┘
┌─────────────────────────┐
Enhance with Usernames
- Load all user names
- Map to file types
- Prepare display data
└─────────────────────────┘

Business Logic:

1. Auto-Creation: Creates shipping file record if doesn't exist

2. User Resolution: Loads employee names for all document types

3. Complete Data: Provides full file status for interface

4. Real-time Updates: Supports dynamic file management

Username Resolution Example: 

$files['buybillusername'] = R::getCell(
    "SELECT employeename FROM user WHERE userid = ?", 
    [$files['buybilluserid']]
);

3. updateFilesData

Purpose: Handle file uploads and note updates with comprehensive type mapping

Called By: AJAX file upload or note update

Line: 68

Parameters (via $_POST):

Process Flow:

┌─────────────────────┐
Determine Type
- Note Update
- File Upload
└─────────────────────┘
┌─────────────────────┐
For File Uploads:
- Process file
- Map column names
- Update database
- Return file info
└─────────────────────┘
┌─────────────────────┐
For Note Updates:
- Update text field
- No user tracking
└─────────────────────┘

Business Logic:

1. Type Detection: Handles both file uploads and note updates

2. Column Mapping: Maps file types to database columns and user tracking fields

3. User Audit: Tracks who uploaded what and when

4. Error Handling: Provides proper response codes for AJAX

5. File Management: Uses custom upload library for file processing

Column Mapping Logic: 

switch ($col) {
    case 'buybillfile':
        $userCol = 'buybilluserid';
        $dateCol = 'buybilldate';
        break;
    case 'cocfile':
        $userCol = 'cocuserid';
        $dateCol = 'cocdate';
        break;
    // ... continues for all 12+ document types
}

Database Update with Audit Trail: 

R::exec("UPDATE shippingfile SET $col = '$fileName', 
         $userCol = " . $_SESSION['userid'] . ", 
         $dateCol = '$date' WHERE id = $fileid");

---

🔄 Business Logic Flow

Complete Shipping Documentation Workflow

┌─────────────────────────────┐
Initialize Shipping Files
- Create file record
- Link to chassis number
- Set initial status
└─────────────────────────────┘
┌─────────────────────────────┐
Document Collection Phase
- Purchase orders
- Certificates
- Compliance docs
└─────────────────────────────┘
┌─────────────────────────────┐
Upload Documents
- Multiple file types
- User tracking
- Date stamping
└─────────────────────────────┘
┌─────────────────────────────┐
Document Review
- Completeness check
- Compliance verification
- Approval process
└─────────────────────────────┘
┌─────────────────────────────┐
Shipping Clearance
- All documents uploaded
- Ready for shipment
- Track progress
└─────────────────────────────┘

File Upload Process

┌──────────────────────────┐
Validate File
- Check file type
- Verify file size
- Ensure permissions
└──────────────────────────┘
┌──────────────────────────┐
Process Upload
- Move to server
- Generate filename
- Update database
└──────────────────────────┘
┌──────────────────────────┐
Update Audit Trail
- Record uploader
- Timestamp upload
- Log activity
└──────────────────────────┘
┌──────────────────────────┐
Return Status
- File URL
- Upload date
- Uploader name
└──────────────────────────┘

---

⚠️ Common Issues

1. File Upload Failures

Symptoms: Files not uploading, error responses

Causes:

Solutions:

2. Chassis Number Not Found

Symptoms: No chassis numbers appear in dropdown

Causes:

Solutions:

3. User Name Resolution Failures

Symptoms: Blank user names in file upload tracking

Causes:

Solutions:

4. AJAX Response Errors

Symptoms: File upload interface not updating

Causes:

Solutions:

---

🔗 Dependencies

Required Files

Database Dependencies

File System Dependencies

Frontend Dependencies

Template Files

---

🎯 Integration Points

Import Contract Integration

User Management Integration

File Management Integration

Workflow Integration

---

💡 Best Practices

File Management

1. Organize files systematically by chassis number and document type

2. Implement file versioning for updated documents

3. Regular backup of critical shipping documents

4. Monitor storage space usage

5. Validate file integrity after uploads

Security Considerations

1. Validate file types to prevent malicious uploads

2. Scan uploaded files for viruses if possible

3. Implement access controls based on user roles

4. Log all file access for security auditing

5. Regular security reviews of upload directory

Performance Optimization

1. Compress large files before storage when possible

2. Use efficient file formats (PDF over images when applicable)

3. Implement lazy loading for file listings

4. Cache user information to reduce database queries

5. Monitor upload times and optimize as needed

Data Management

1. Maintain complete audit trails for all document changes

2. Regular cleanup of obsolete or duplicate files

3. Document retention policies based on legal requirements

4. Backup strategies for critical shipping documents

5. Disaster recovery plans for document loss scenarios

---

🔧 Technical Implementation Details

File Upload Process 

// File upload with custom library
$handle = new upload($_FILES['uploadedFile']);
$fileName = uploadfile($handle, '../upload/shippingFiles');

// Database update with audit trail
R::exec("UPDATE shippingfile SET $col = '$fileName', 
         $userCol = " . $_SESSION['userid'] . ", 
         $dateCol = '$date' WHERE id = $fileid");

AJAX Response Format 

{
    "success": true,
    "data": [
        "file_url",
        "upload_date", 
        "uploader_name"
    ]
}

Database Schema Pattern

For each document type, the system maintains:

This provides complete audit trail for all shipping documents.