feat(webstatement): tambah ProcessProvinceDataJob untuk import data provinsi

Perubahan yang dilakukan:
- Membuat job baru ProcessProvinceDataJob dengan referensi dari ProcessSectorDataJob.
- Menggunakan model ProvinceCore untuk menyimpan data provinsi.
- Mendukung format file ST.PROVINCE.csv dengan delimiter khusus tilde (~).
- Menambahkan validasi untuk kolom: id, date_time, province, dan province_name.
- Mengabaikan baris header pada file saat proses import.
- Menggunakan database transaction untuk menjaga konsistensi data.
- Menambahkan counter untuk memantau jumlah record yang dilewati (skipped).
- Mengimplementasikan error handling dan logging yang detail.
- Menggunakan updateOrCreate untuk mencegah duplikasi data.
- Menambahkan method failed() untuk menangani kasus job failure.
- Melakukan mapping field province ke code dan province_name ke name.
- Melakukan validasi data wajib sebelum menyimpan ke database.

Tujuan perubahan:
- Memfasilitasi proses import data provinsi dari file eksternal secara otomatis dan aman.
- Menjamin data yang masuk telah tervalidasi dan bebas duplikasi.
- Menyediakan log dan feedback yang cukup saat terjadi kegagalan.

app/Http/Controllers/MigrasiController.php

@@ -1,4 +1,5 @@
 <?php
+
     namespace Modules\Webstatement\Http\Controllers;
 
     use App\Http\Controllers\Controller;
@@ -6,7 +7,7 @@
     use Exception;
     use Illuminate\Http\JsonResponse;
     use Illuminate\Support\Facades\Storage;
-    use Log;
+    use Illuminate\Support\Facades\Log;
     use Modules\Webstatement\Jobs\{ProcessAccountDataJob,
         ProcessArrangementDataJob,
         ProcessAtmTransactionJob,
@@ -22,7 +23,8 @@
         ProcessStmtNarrParamDataJob,
         ProcessTellerDataJob,
         ProcessTransactionDataJob,
-        ProcessSectorDataJob};
+        ProcessSectorDataJob,
+        ProcessProvinceDataJob};
 
     class MigrasiController extends Controller
     {
@@ -42,7 +44,8 @@
             'atmTransaction'     => ProcessAtmTransactionJob::class,
             'arrangement'        => ProcessArrangementDataJob::class,
             'billDetail'         => ProcessBillDetailDataJob::class,
-            'sector'             => ProcessSectorDataJob::class
+            'sector'             => ProcessSectorDataJob::class,
+            'province'           => ProcessProvinceDataJob::class
         ];
 
         private const PARAMETER_PROCESSES = [
@@ -50,7 +53,8 @@
             'stmtNarrParam',
             'stmtNarrFormat',
             'ftTxnTypeCondition',
-            'sector'
+            'sector',
+            'province'
         ];
 
         private const DATA_PROCESSES = [

app/Jobs/ProcessProvinceDataJob.php

@@ -0,0 +1,300 @@
+<?php
+
+namespace Modules\Webstatement\Jobs;
+
+use Exception;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Facades\DB;
+use Modules\Webstatement\Models\ProvinceCore;
+
+class ProcessProvinceDataJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    private const CSV_DELIMITER      = '~';
+    private const MAX_EXECUTION_TIME = 86400; // 24 hours in seconds
+    private const FILENAME           = 'ST.PROVINCE.csv';
+    private const DISK_NAME          = 'sftpStatement';
+
+    private string $period = '';
+    private int    $processedCount = 0;
+    private int    $errorCount     = 0;
+    private int    $skippedCount   = 0;
+
+    /**
+     * Membuat instance job baru untuk memproses data provinsi
+     * 
+     * @param string $period Periode data yang akan diproses
+     */
+    public function __construct(string $period = '')
+    {
+        $this->period = $period;
+        Log::info('ProcessProvinceDataJob: Job dibuat untuk periode: ' . $period);
+    }
+
+    /**
+     * Menjalankan job untuk memproses file ST.PROVINCE.csv
+     * Menggunakan transaction untuk memastikan konsistensi data
+     * 
+     * @return void
+     * @throws Exception
+     */
+    public function handle(): void
+    {
+        DB::beginTransaction();
+        
+        try {
+            Log::info('ProcessProvinceDataJob: Memulai pemrosesan data provinsi');
+            
+            $this->initializeJob();
+
+            if ($this->period === '') {
+                Log::warning('ProcessProvinceDataJob: Tidak ada periode yang diberikan untuk pemrosesan data provinsi');
+                DB::rollback();
+                return;
+            }
+
+            $this->processPeriod();
+            $this->logJobCompletion();
+            
+            DB::commit();
+            Log::info('ProcessProvinceDataJob: Transaction berhasil di-commit');
+            
+        } catch (Exception $e) {
+            DB::rollback();
+            Log::error('ProcessProvinceDataJob: Error dalam pemrosesan, transaction di-rollback: ' . $e->getMessage());
+            throw $e;
+        }
+    }
+
+    /**
+     * Inisialisasi pengaturan job
+     * Mengatur timeout dan reset counter
+     * 
+     * @return void
+     */
+    private function initializeJob(): void
+    {
+        set_time_limit(self::MAX_EXECUTION_TIME);
+        $this->processedCount = 0;
+        $this->errorCount     = 0;
+        $this->skippedCount   = 0;
+        
+        Log::info('ProcessProvinceDataJob: Job diinisialisasi dengan timeout ' . self::MAX_EXECUTION_TIME . ' detik');
+    }
+
+    /**
+     * Memproses file untuk periode tertentu
+     * Mengambil file dari SFTP dan memproses data
+     * 
+     * @return void
+     */
+    private function processPeriod(): void
+    {
+        $disk     = Storage::disk(self::DISK_NAME);
+        $filePath = "$this->period/" . self::FILENAME;
+
+        Log::info('ProcessProvinceDataJob: Memproses periode ' . $this->period);
+        
+        if (!$this->validateFile($disk, $filePath)) {
+            return;
+        }
+
+        $tempFilePath = $this->createTemporaryFile($disk, $filePath);
+        $this->processFile($tempFilePath, $filePath);
+        $this->cleanup($tempFilePath);
+    }
+
+    /**
+     * Validasi keberadaan file di storage
+     * 
+     * @param mixed $disk Storage disk instance
+     * @param string $filePath Path file yang akan divalidasi
+     * @return bool
+     */
+    private function validateFile($disk, string $filePath): bool
+    {
+        Log::info("ProcessProvinceDataJob: Memvalidasi file provinsi: $filePath");
+
+        if (!$disk->exists($filePath)) {
+            Log::warning("ProcessProvinceDataJob: File tidak ditemukan: $filePath");
+            return false;
+        }
+
+        Log::info("ProcessProvinceDataJob: File ditemukan dan valid: $filePath");
+        return true;
+    }
+
+    /**
+     * Membuat file temporary untuk pemrosesan
+     * 
+     * @param mixed $disk Storage disk instance
+     * @param string $filePath Path file sumber
+     * @return string Path file temporary
+     */
+    private function createTemporaryFile($disk, string $filePath): string
+    {
+        $tempFilePath = storage_path("app/temp_" . self::FILENAME);
+        file_put_contents($tempFilePath, $disk->get($filePath));
+        
+        Log::info("ProcessProvinceDataJob: File temporary dibuat: $tempFilePath");
+        return $tempFilePath;
+    }
+
+    /**
+     * Memproses file CSV dan mengimpor data ke database
+     * Format CSV: id~date_time~province~province_name
+     * 
+     * @param string $tempFilePath Path file temporary
+     * @param string $filePath Path file asli untuk logging
+     * @return void
+     */
+    private function processFile(string $tempFilePath, string $filePath): void
+    {
+        $handle = fopen($tempFilePath, "r");
+        if ($handle === false) {
+            Log::error("ProcessProvinceDataJob: Tidak dapat membuka file: $filePath");
+            return;
+        }
+
+        Log::info("ProcessProvinceDataJob: Memulai pemrosesan file: $filePath");
+        
+        $rowCount = 0;
+        $isFirstRow = true;
+
+        while (($row = fgetcsv($handle, 0, self::CSV_DELIMITER)) !== false) {
+            $rowCount++;
+            
+            // Skip header row
+            if ($isFirstRow) {
+                $isFirstRow = false;
+                Log::info("ProcessProvinceDataJob: Melewati header row: " . implode(self::CSV_DELIMITER, $row));
+                continue;
+            }
+            
+            $this->processRow($row, $rowCount, $filePath);
+        }
+
+        fclose($handle);
+        Log::info("ProcessProvinceDataJob: Selesai memproses $filePath. Total baris: $rowCount, Diproses: {$this->processedCount}, Error: {$this->errorCount}, Dilewati: {$this->skippedCount}");
+    }
+
+    /**
+     * Memproses satu baris data CSV
+     * 
+     * @param array $row Data baris CSV
+     * @param int $rowCount Nomor baris untuk logging
+     * @param string $filePath Path file untuk logging
+     * @return void
+     */
+    private function processRow(array $row, int $rowCount, string $filePath): void
+    {
+        // Validasi jumlah kolom (id~date_time~province~province_name = 4 kolom)
+        if (count($row) !== 4) {
+            Log::warning("ProcessProvinceDataJob: Baris $rowCount di $filePath memiliki jumlah kolom yang salah. Diharapkan: 4, Ditemukan: " . count($row));
+            $this->skippedCount++;
+            return;
+        }
+
+        // Map data sesuai format CSV
+        $data = [
+            'code' => trim($row[2]), // province code
+            'name' => trim($row[3])  // province_name
+        ];
+        
+        Log::debug("ProcessProvinceDataJob: Memproses baris $rowCount dengan data: " . json_encode($data));
+        
+        $this->saveRecord($data, $rowCount, $filePath);
+    }
+
+    /**
+     * Menyimpan record provinsi ke database
+     * Menggunakan updateOrCreate untuk menghindari duplikasi
+     * 
+     * @param array $data Data provinsi yang akan disimpan
+     * @param int $rowCount Nomor baris untuk logging
+     * @param string $filePath Path file untuk logging
+     * @return void
+     */
+    private function saveRecord(array $data, int $rowCount, string $filePath): void
+    {
+        try {
+            // Validasi data wajib
+            if (empty($data['code']) || empty($data['name'])) {
+                Log::warning("ProcessProvinceDataJob: Baris $rowCount di $filePath memiliki data kosong. Code: '{$data['code']}', Name: '{$data['name']}'");
+                $this->skippedCount++;
+                return;
+            }
+
+            // Simpan atau update data provinsi
+            $province = ProvinceCore::updateOrCreate(
+                ['code' => $data['code']], // Kondisi pencarian
+                ['name' => $data['name']]   // Data yang akan diupdate/insert
+            );
+            
+            $this->processedCount++;
+            Log::debug("ProcessProvinceDataJob: Berhasil menyimpan provinsi ID: {$province->id}, Code: {$data['code']}, Name: {$data['name']}");
+            
+        } catch (Exception $e) {
+            $this->errorCount++;
+            Log::error("ProcessProvinceDataJob: Error menyimpan data provinsi pada baris $rowCount di $filePath: " . $e->getMessage());
+            Log::error("ProcessProvinceDataJob: Data yang error: " . json_encode($data));
+        }
+    }
+
+    /**
+     * Membersihkan file temporary
+     * 
+     * @param string $tempFilePath Path file temporary yang akan dihapus
+     * @return void
+     */
+    private function cleanup(string $tempFilePath): void
+    {
+        if (file_exists($tempFilePath)) {
+            unlink($tempFilePath);
+            Log::info("ProcessProvinceDataJob: File temporary dihapus: $tempFilePath");
+        }
+    }
+
+    /**
+     * Logging hasil akhir pemrosesan job
+     * 
+     * @return void
+     */
+    private function logJobCompletion(): void
+    {
+        $message = "ProcessProvinceDataJob: Pemrosesan data provinsi selesai. " .
+            "Total diproses: {$this->processedCount}, " .
+            "Total error: {$this->errorCount}, " .
+            "Total dilewati: {$this->skippedCount}";
+            
+        Log::info($message);
+        
+        // Log summary untuk monitoring
+        if ($this->errorCount > 0) {
+            Log::warning("ProcessProvinceDataJob: Terdapat {$this->errorCount} error dalam pemrosesan");
+        }
+        
+        if ($this->skippedCount > 0) {
+            Log::info("ProcessProvinceDataJob: Terdapat {$this->skippedCount} baris yang dilewati");
+        }
+    }
+
+    /**
+     * Handle job failure
+     * 
+     * @param Exception $exception
+     * @return void
+     */
+    public function failed(Exception $exception): void
+    {
+        Log::error('ProcessProvinceDataJob: Job gagal dijalankan: ' . $exception->getMessage());
+        Log::error('ProcessProvinceDataJob: Stack trace: ' . $exception->getTraceAsString());
+    }
+}

app/Models/ProvinceCore.php

@@ -0,0 +1,161 @@
+<?php
+
+namespace Modules\Webstatement\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Log;
+
+class ProvinceCore extends Model
+{
+    use HasFactory;
+
+    /**
+     * Nama tabel yang digunakan oleh model
+     *
+     * @var string
+     */
+    protected $table = 'province_core';
+
+    /**
+     * Field yang dapat diisi secara mass assignment
+     *
+     * @var array
+     */
+    protected $fillable = [
+        'code',
+        'name',
+    ];
+
+    /**
+     * Field yang di-cast ke tipe data tertentu
+     *
+     * @var array
+     */
+    protected $casts = [
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+
+    /**
+     * Scope untuk mencari berdasarkan kode provinsi
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     * @param string $code
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeByCode($query, $code)
+    {
+        Log::info('ProvinceCore: Mencari provinsi dengan kode: ' . $code);
+        return $query->where('code', $code);
+    }
+
+    /**
+     * Scope untuk mencari berdasarkan nama provinsi
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     * @param string $name
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeByName($query, $name)
+    {
+        Log::info('ProvinceCore: Mencari provinsi dengan nama: ' . $name);
+        return $query->where('name', 'ILIKE', '%' . $name . '%');
+    }
+
+    /**
+     * Scope untuk mendapatkan semua provinsi yang aktif
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeActive($query)
+    {
+        Log::info('ProvinceCore: Mengambil semua provinsi aktif');
+        return $query->orderBy('name', 'asc');
+    }
+
+    /**
+     * Mendapatkan provinsi berdasarkan kode
+     *
+     * @param string $code
+     * @return ProvinceCore|null
+     */
+    public static function getByCode($code)
+    {
+        try {
+            Log::info('ProvinceCore: Mengambil provinsi dengan kode: ' . $code);
+            return self::byCode($code)->first();
+        } catch (\Exception $e) {
+            Log::error('ProvinceCore: Error mengambil provinsi dengan kode ' . $code . ': ' . $e->getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * Mendapatkan semua provinsi untuk dropdown/select
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public static function getForDropdown()
+    {
+        try {
+            Log::info('ProvinceCore: Mengambil data provinsi untuk dropdown');
+            return self::active()->pluck('name', 'code');
+        } catch (\Exception $e) {
+            Log::error('ProvinceCore: Error mengambil data dropdown provinsi: ' . $e->getMessage());
+            return collect();
+        }
+    }
+
+    /**
+     * Validasi kode provinsi
+     *
+     * @param string $code
+     * @return bool
+     */
+    public static function isValidCode($code)
+    {
+        try {
+            Log::info('ProvinceCore: Validasi kode provinsi: ' . $code);
+            return self::byCode($code)->exists();
+        } catch (\Exception $e) {
+            Log::error('ProvinceCore: Error validasi kode provinsi ' . $code . ': ' . $e->getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * Boot method untuk model events
+     *
+     * @return void
+     */
+    protected static function boot()
+    {
+        parent::boot();
+
+        static::creating(function ($model) {
+            Log::info('ProvinceCore: Membuat data provinsi baru dengan kode: ' . $model->code);
+        });
+
+        static::created(function ($model) {
+            Log::info('ProvinceCore: Data provinsi berhasil dibuat dengan ID: ' . $model->id);
+        });
+
+        static::updating(function ($model) {
+            Log::info('ProvinceCore: Mengupdate data provinsi dengan ID: ' . $model->id);
+        });
+
+        static::updated(function ($model) {
+            Log::info('ProvinceCore: Data provinsi berhasil diupdate dengan ID: ' . $model->id);
+        });
+
+        static::deleting(function ($model) {
+            Log::info('ProvinceCore: Menghapus data provinsi dengan ID: ' . $model->id);
+        });
+
+        static::deleted(function ($model) {
+            Log::info('ProvinceCore: Data provinsi berhasil dihapus dengan ID: ' . $model->id);
+        });
+    }
+}

database/migrations/2025_07_10_025454_create_province_core_table.php

@@ -0,0 +1,64 @@
+<?php
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Database\Migrations\Migration;
+
+return new class extends Migration
+{
+    /**
+     * Menjalankan migrasi untuk membuat tabel province_core
+     * Tabel ini menyimpan data master provinsi dengan kode dan nama
+     *
+     * @return void
+     */
+    public function up(): void
+    {
+        DB::beginTransaction();
+        
+        try {
+            Schema::create('province_core', function (Blueprint $table) {
+                $table->id();
+                $table->string('code', 10)->unique()->comment('Kode provinsi unik');
+                $table->string('name', 255)->comment('Nama provinsi');
+                $table->timestamps();
+                
+                // Index untuk performa pencarian
+                $table->index(['code']);
+                $table->index(['name']);
+            });
+            
+            DB::commit();
+            Log::info('Migration province_core table berhasil dibuat');
+            
+        } catch (\Exception $e) {
+            DB::rollback();
+            Log::error('Migration province_core table gagal: ' . $e->getMessage());
+            throw $e;
+        }
+    }
+
+    /**
+     * Membalikkan migrasi dengan menghapus tabel province_core
+     *
+     * @return void
+     */
+    public function down(): void
+    {
+        DB::beginTransaction();
+        
+        try {
+            Schema::dropIfExists('province_core');
+            
+            DB::commit();
+            Log::info('Migration rollback province_core table berhasil');
+            
+        } catch (\Exception $e) {
+            DB::rollback();
+            Log::error('Migration rollback province_core table gagal: ' . $e->getMessage());
+            throw $e;
+        }
+    }
+};