# DevQMS Developer Get Started Guide

## Table of Contents
1. [Project Overview](#project-overview)
2. [Architecture Overview](#architecture-overview)
3. [Core Components](#core-components)
4. [Module System](#module-system)
5. [DevExtreme Integration](#devextreme-integration)
6. [Admin-AJAX System](#admin-ajax-system)
7. [Save Trigger System](#save-trigger-system)
8. [Batch Excel Operations](#batch-excel-operations)
9. [Development Workflow](#development-workflow)
10. [Common Patterns](#common-patterns)
11. [Troubleshooting](#troubleshooting)

## Project Overview

DevQMS is a Quality Management System (QMS) built on Laravel framework with advanced features including:

- **Modular Architecture**: Each module (WeldLog, TestPackage, etc.) has its own Model, Controller, and View
- **DevExtreme Integration**: Advanced UI components for data grids, forms, and charts
- **Dynamic Form System**: Forms are generated dynamically based on database schema
- **Excel Import/Export**: Batch operations for data management
- **Role-based Access Control**: User permission system with different levels
- **Real-time Data Processing**: Save triggers for automatic data synchronization

## Architecture Overview

### Directory Structure

```
app/
├── Http/Controllers/
│   ├── AdminController.php          # Main CRUD controller
│   ├── AdminAjaxController.php     # AJAX request handler
│   └── SaveTrigger/                # Automatic data processing
├── DevExtreme/                     # DevExtreme integration classes
├── Models/                         # Eloquent models
└── Functions/                      # Helper functions

resources/views/
├── admin/                          # Admin panel views
│   └── type/                       # Module views
├── admin-ajax/                     # AJAX response views
├── components/                     # Reusable components
│   ├── blocks/                     # Module blocks
│   └── table/                      # DataGrid components
└── guide/                          # Documentation

routes/
└── web.php                         # Route definitions
```

### Core Technologies

- **Backend**: Laravel 8+ with PHP 8+
- **Frontend**: DevExtreme DataGrid, jQuery, Bootstrap
- **Database**: MySQL with InnoDB
- **File Storage**: Laravel Storage with local/cloud options
- **Excel Processing**: Maatwebsite Excel package

## Core Components

### 1. AdminController.php

The central controller handling all CRUD operations for modules. Key methods:

```php
// Read operations
public function tableToJson(Request $request, string $tableName)
public function getDetail(Request $request, string $tableName, string $columnName, string $value)

// Write operations  
public function insertJson(Request $request, string $tableName)
public function saveJson(Request $request, string $tableName)
public function removeJson(Request $request, string $tableName)

// Excel operations
public function importExcel(Request $request, string $tableName)
public function exportExcel(Request $request, string $tableName, string $fileName)
```

**Important**: All modules use this centralized controller - no need to create individual controllers for basic CRUD operations.

### 2. AdminAjaxController.php

Handles AJAX requests through view-based routing:

```php
public function index(Request $request, string $var) {
    $url = "admin-ajax.$var";
    return view($url, array("request" => $request));
}
```

AJAX views are located in `resources/views/admin-ajax/` and follow the naming pattern `{action}.blade.php`.

### 3. DevExtreme Integration

#### DbSet.php
Custom query builder for DevExtreme DataGrid:

```php
$dbSet = new DbSet($mySQL, 'table_name');
$result = $dbSet->Select(['id', 'name'])
                ->Filter(['status' => 'active'])
                ->OrderBy('name')
                ->SkipTake(0, 10)
                ->AsArray();
```

#### Utils.php
Helper functions for data processing and SQL escaping.

## Module System

### Creating a New Module

1. **Create Model and Migration**:
```php
// app/Models/NewModule.php
class NewModule extends Model {
    protected $table = 'new_modules';
    protected $primaryKey = 'id';
    public $timestamps = true;
}
```

2. **Create View Template**:
```php
// resources/views/admin/type/new-module.blade.php
<?php 
use App\Models\NewModule;

$title = "New Module";
$tableName = "new_modules";
$listDatas = NewModule::orderBy("id","DESC")->paginate(setting('row_count'));

$blockGroup = [    
    'General Info' => [
        'name',
        'description',
    ],
    'Details' => [
        'status',
        'created_at',
    ],
];

$relationDatas = [
    'status' => [
        'type' => 'select',
        'datas' => [
            'active' => 'Active',
            'inactive' => 'Inactive'
        ]
    ],
];

$firstUploadFolder = 'NewModule/';
$firstUploadTitle = 'Upload Files';
?>

<div class="content">
    <div class="row">   
        @include("admin.type.document.upload") 
        @include("components.blocks.module-block")     
    </div>
</div>
```

3. **Add to Types Table**:
Register the module in the admin panel's Types section with:
- Title: "New Module"
- Slug: "new-module" 
- Fields: "name,description,status,created_at"

### Module Template Structure

#### sablon4.blade.php
Base template for modules with these key variables:

```php
$title = "Module Title";                    // Page title
$tableName = "table_name";                  // Database table name
$listDatas = Model::paginate(50);          // Data source
$blockGroup = [];                          // Field grouping
$relationDatas = [];                       // Field type definitions
$firstUploadFolder = 'ModuleName/';        // File upload folder
$firstUploadTitle = 'Upload Title';        // Upload section title
```

#### module-block.blade.php
Handles the DataGrid integration and includes:
- Column selection
- Excel import/export
- DataGrid component
- Field type mapping

## DevExtreme Integration

### DataGrid Configuration

The DataGrid is configured in `resources/views/components/table/datagrid.blade.php` with:

```javascript
var dataGrid = $("#dataGrid").dxDataGrid({
    dataSource: dataSource,
    keyExpr: "{{$tableName}}",
    allowColumnResizing: true,
    allowColumnReordering: true,
    showBorders: true,
    filterRow: {
        visible: true
    },
    searchPanel: {
        visible: true
    },
    paging: {
        pageSize: 20
    },
    pager: {
        showPageSizeSelector: true,
        allowedPageSizes: [10, 20, 50, 100]
    },
    editing: {
        mode: "popup",
        allowUpdating: true,
        allowAdding: true,
        allowDeleting: true
    }
});
```

### Field Types

Supported field types in `relationDatas`:

```php
$relationDatas = [
    'text_field' => ['type' => 'text'],
    'date_field' => ['type' => 'date'],
    'number_field' => ['type' => 'number'],
    'select_field' => [
        'type' => 'select',
        'datas' => ['option1' => 'Label 1', 'option2' => 'Label 2']
    ],
    'link_field' => [
        'type' => 'link-search',
        'html' => '<i class="fa fa-link"></i>'
    ],
    'decimal_field' => ['type' => 'decimal'],
    'checkbox_field' => ['type' => 'checkbox']
];
```

### Custom Validation

Add custom validation in `components/table/datagrid/validation-callback/{module}/{field}.blade.php`:

```javascript
function validationCallback_fieldName(e) {
    // Custom validation logic
    if (e.value && e.value.length < 3) {
        return false;
    }
    return true;
}
```

## Admin-AJAX System

### Creating AJAX Endpoints

1. **Create AJAX View**:
```php
// resources/views/admin-ajax/custom-action.blade.php
@php
$data = db('table_name')->where('condition', $request->input('value'))->get();
echo json_encode([
    'status' => 'success',
    'data' => $data
]);
@endphp
```

2. **Call from JavaScript**:
```javascript
$.ajax({
    url: '/admin-ajax/custom-action',
    type: 'POST',
    data: {
        value: 'search_value',
        _token: csrf_token
    },
    success: function(response) {
        // Handle response
    }
});
```

### Common AJAX Patterns

#### Batch Operations
```php
// admin-ajax/batch-operation.blade.php
@php
$ids = $request->input('ids', []);
$operation = $request->input('operation');

foreach($ids as $id) {
    db('table_name')->where('id', $id)->update(['status' => $operation]);
}

echo json_encode(['status' => 'success', 'processed' => count($ids)]);
@endphp
```

#### Data Export
```php
// admin-ajax/export-data.blade.php
@php
$query = $request->input('query');
$data = DB::select($query);

$filename = 'export_' . date('Y-m-d_H-i-s') . '.xlsx';
Excel::store(new ExportExcel($data), $filename);

echo json_encode(['status' => 'success', 'file' => $filename]);
@endphp
```

## Save Trigger System

### Overview

Save triggers automatically process data changes and maintain data consistency across related tables.

### Trigger Structure

```php
// app/Http/Controllers/SaveTrigger/{table_name}.php
<?php
use App\Models\RelatedModel;

$id = $request['key'];
$data = db($tableName)->where("id", $id)->first();

// Detect changed fields
$changedFields = [];
foreach ($data as $key => $value) {
    if (isset($beforeData->$key) && $beforeData->$key != $value) {
        $changedFields[] = $key;
    }
}

// Execute related updates
if (in_array('status', $changedFields)) {
    // Update related records
    RelatedModel::where('parent_id', $id)
               ->update(['status' => $data->status]);
}
```

### Common Trigger Patterns

#### Status Synchronization
```php
// Update related records when status changes
if (in_array('status', $changedFields)) {
    $newStatus = $data->status;
    
    // Update child records
    db('child_table')->where('parent_id', $id)
                    ->update(['status' => $newStatus]);
    
    // Update summary tables
    $summary = db('summary_table')->where('parent_id', $id)->first();
    if ($summary) {
        $summary->update(['last_status' => $newStatus]);
    }
}
```

#### Calculated Fields
```php
// Recalculate totals when related fields change
if (array_intersect(['quantity', 'unit_price'], $changedFields)) {
    $total = $data->quantity * $data->unit_price;
    
    db($tableName)->where('id', $id)
                 ->update(['total' => $total]);
}
```

#### Cross-Table Updates
```php
// Update related tables when key fields change
if (in_array('project_id', $changedFields)) {
    $newProjectId = $data->project_id;
    
    // Update all related records
    db('related_table')->where('parent_id', $id)
                      ->update(['project_id' => $newProjectId]);
}
```

## Batch Excel Operations

### Import Process

1. **File Upload**: Users upload Excel files through the interface
2. **Validation**: System validates data format and required fields
3. **Processing**: Data is processed in batches to handle large files
4. **Save Triggers**: Each row triggers the appropriate save triggers
5. **Progress Tracking**: Real-time progress updates via AJAX

### Export Process

1. **Query Building**: Dynamic SQL query based on filters
2. **Data Retrieval**: Fetch data with pagination for large datasets
3. **Formatting**: Apply formatting and styling
4. **File Generation**: Create Excel file with multiple sheets if needed
5. **Download**: Provide download link to user

### Implementation Example

```php
// Batch Excel Import
public function importExcel(Request $request, string $tableName) {
    $file = $request->file('file');
    $import = new ImportExcel($tableName);
    
    Excel::import($import, $file);
    
    return response()->json([
        'status' => 'success',
        'imported' => $import->getRowCount()
    ]);
}

// Batch Excel Export
public function exportExcel(Request $request, string $tableName, string $fileName = "") {
    $query = $request->input('query');
    $data = DB::select($query);
    
    $fileName = $fileName ?: $tableName . '_' . date('Y-m-d_H-i-s');
    
    return Excel::download(new ExportExcel($data), $fileName . '.xlsx');
}
```

## Development Workflow

### 1. Environment Setup

```bash
# Clone repository
git clone [repository-url]
cd dev

# Install dependencies
composer install
npm install

# Configure environment
cp .env.example .env
php artisan key:generate

# Run migrations
php artisan migrate

# Start development server
php artisan serve
```

### 2. Creating New Features

1. **Database Changes**:
   ```bash
   php artisan make:migration create_new_table
   php artisan migrate
   ```

2. **Model Creation**:
   ```bash
   php artisan make:model NewModel
   ```

3. **View Template**:
   - Copy `sablon4.blade.php` as base
   - Customize variables and field groups
   - Add to Types table

4. **Save Triggers** (if needed):
   - Create trigger file in `SaveTrigger/`
   - Define change detection logic
   - Implement cross-table updates

### 3. Testing

```bash
# Run tests
php artisan test

# Test specific module
php artisan test --filter=NewModuleTest
```

### 4. Deployment

```bash
# Production deployment
composer install --optimize-autoloader --no-dev
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## Common Patterns

### 1. Dynamic Field Handling

```php
// Get field types from database
$fieldTypes = [];
foreach($columns as $column) {
    $fieldTypes[$column] = table_column_type($tableName, $column);
}

// Apply custom field types
$relationDatas = [
    'status' => ['type' => 'select', 'datas' => $statusOptions],
    'date_field' => ['type' => 'date'],
];
```

### 2. Permission Checking

```php
// Check user permissions
if (!isAuth($tableName, 'write')) {
    return response()->json(['error' => 'Permission denied'], 403);
}

// Role-based access
if (!isAdmin()) {
    // Limited access logic
}
```

### 3. Data Validation

```php
// Custom validation in save triggers
$requiredFields = ['name', 'email', 'status'];
foreach($requiredFields as $field) {
    if (empty($data->$field)) {
        throw new Exception("Field $field is required");
    }
}
```

### 4. Error Handling

```php
try {
    // Database operation
    DB::transaction(function() use ($data) {
        // Complex operations
    });
} catch (Exception $e) {
    Log::error('Operation failed', [
        'error' => $e->getMessage(),
        'data' => $data
    ]);
    
    return response()->json(['error' => 'Operation failed'], 500);
}
```

## Troubleshooting

### Common Issues

1. **DataGrid Not Loading**:
   - Check browser console for JavaScript errors
   - Verify AJAX endpoint returns valid JSON
   - Check network tab for failed requests

2. **Save Triggers Not Working**:
   - Verify trigger file exists in `SaveTrigger/`
   - Check database permissions
   - Review error logs

3. **Excel Import Failures**:
   - Validate Excel file format
   - Check column mappings
   - Verify required fields are present

4. **Permission Errors**:
   - Check user level in database
   - Verify module permissions
   - Review middleware configuration

### Debug Tools

1. **Laravel Telescope** (if enabled):
   ```
   /telescope
   ```

2. **Database Logging**:
   ```php
   DB::enableQueryLog();
   // ... operations
   dd(DB::getQueryLog());
   ```

3. **DevExtreme Debug**:
   ```javascript
   // Enable DevExtreme debug mode
   DevExpress.config({ debug: true });
   ```

### Performance Optimization

1. **Database Indexing**:
   ```sql
   CREATE INDEX idx_table_column ON table_name(column_name);
   ```

2. **Query Optimization**:
   ```php
   // Use eager loading for relationships
   $data = Model::with('relation')->get();
   ```

3. **Caching**:
   ```php
   // Cache frequently accessed data
   $data = Cache::remember('key', 3600, function() {
       return Model::all();
   });
   ```

---

This guide provides a comprehensive overview of the DevQMS system. For specific module documentation, refer to the individual guide files in the `guide/` directory. Always test changes in a development environment before deploying to production.