CKB/docs/WORK_PRODUCTS_STOCK_MANAGEMENT.md

Work Products & Stock Management System

Overview

Sistem ini memungkinkan setiap pekerjaan (work) memiliki relasi dengan banyak produk (products) dan otomatis mengurangi stock di dealer ketika transaksi pekerjaan dilakukan.

Fitur Utama

1. Work Products Management

• Setiap pekerjaan dapat dikonfigurasi untuk memerlukan produk tertentu
• Admin dapat mengatur jumlah (quantity) produk yang dibutuhkan per pekerjaan
• Mendukung catatan/notes untuk setiap produk

2. Automatic Stock Reduction

• Stock otomatis dikurangi ketika transaksi pekerjaan dibuat
• Validasi stock tersedia sebelum transaksi disimpan
• Stock dikembalikan ketika transaksi dihapus

3. Stock Validation & Warning

• Real-time checking stock availability saat memilih pekerjaan
• Warning ketika stock tidak mencukupi
• Konfirmasi user sebelum melanjutkan dengan stock negatif

4. Stock Prediction

• Melihat prediksi penggunaan stock untuk pekerjaan tertentu
• Kalkulasi berdasarkan quantity pekerjaan yang akan dilakukan

Database Schema

Tabel work_products

CREATE TABLE work_products (
    id BIGINT PRIMARY KEY,
    work_id BIGINT NOT NULL,
    product_id BIGINT NOT NULL,
    quantity_required DECIMAL(10,2) DEFAULT 1.00,
    notes TEXT NULL,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE KEY unique_work_product (work_id, product_id),
    FOREIGN KEY (work_id) REFERENCES works(id) ON DELETE CASCADE,
    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE
);

Model Relationships

Work Model

// Relasi many-to-many dengan Product
public function products()
{
    return $this->belongsToMany(Product::class, 'work_products')
                ->withPivot('quantity_required', 'notes')
                ->withTimestamps();
}

// Relasi one-to-many dengan WorkProduct
public function workProducts()
{
    return $this->hasMany(WorkProduct::class);
}

Product Model

// Relasi many-to-many dengan Work
public function works()
{
    return $this->belongsToMany(Work::class, 'work_products')
                ->withPivot('quantity_required', 'notes')
                ->withTimestamps();
}

API Endpoints

Work Products Management

GET    /admin/work/{work}/products          - List work products
POST   /admin/work/{work}/products          - Add product to work
GET    /admin/work/{work}/products/{id}     - Show work product
PUT    /admin/work/{work}/products/{id}     - Update work product
DELETE /admin/work/{work}/products/{id}     - Remove product from work

Stock Operations

POST   /transaction/check-stock             - Check stock availability
GET    /transaction/stock-prediction        - Get stock usage prediction
GET    /admin/work/{work}/stock-prediction  - Get work stock prediction

StockService Methods

checkStockAvailability($workId, $dealerId, $workQuantity)

Mengecek apakah dealer memiliki stock yang cukup untuk pekerjaan tertentu.

Parameters:

• $workId: ID pekerjaan
• $dealerId: ID dealer
• $workQuantity: Jumlah pekerjaan yang akan dilakukan

Returns:

[
    'available' => bool,
    'message' => string,
    'details' => [
        [
            'product_id' => int,
            'product_name' => string,
            'required_quantity' => float,
            'available_stock' => float,
            'is_available' => bool
        ]
    ]
]

reduceStockForTransaction($transaction)

Mengurangi stock otomatis berdasarkan transaksi pekerjaan.

restoreStockForTransaction($transaction)

Mengembalikan stock ketika transaksi dibatalkan/dihapus.

getStockUsagePrediction($workId, $quantity)

Mendapatkan prediksi penggunaan stock untuk pekerjaan.

User Interface

1. Work Products Management

• Akses melalui: Admin Panel > Master > Pekerjaan > [Pilih Pekerjaan] > Tombol "Produk"
• Fitur:
  • Tambah/edit/hapus produk yang diperlukan
  • Set quantity required per produk
  • Tambah catatan untuk produk
  • Preview prediksi penggunaan stock

2. Transaction Form dengan Stock Warning

• Real-time stock checking saat memilih pekerjaan
• Warning visual ketika stock tidak mencukupi
• Konfirmasi sebelum submit dengan stock negatif

3. Stock Prediction Modal

• Kalkulasi total produk yang dibutuhkan
• Informasi per produk dengan quantity dan satuan

Usage Examples

1. Mengatur Produk untuk Pekerjaan "Service Rutin"

1. Masuk ke Admin Panel > Master > Pekerjaan
2. Klik tombol "Produk" pada pekerjaan "Service Rutin"
3. Klik "Tambah Produk"
4. Pilih produk "Oli Mesin", set quantity 4, notes "4 liter untuk ganti oli"
5. Tambah produk "Filter Oli", set quantity 1, notes "Filter standar"
6. Simpan

2. Membuat Transaksi dengan Stock Warning

1. Pada form transaksi, pilih pekerjaan "Service Rutin"
2. Set quantity 2 (untuk 2 kendaraan)
3. Sistem akan menampilkan warning jika stock tidak cukup:
   • Oli Mesin: Butuh 8 liter, Tersedia 5 liter
   • Filter Oli: Butuh 2 unit, Tersedia 3 unit
4. User dapat memilih untuk melanjutkan atau membatalkan

3. Melihat Prediksi Stock

1. Di halaman Work Products, klik "Prediksi Stock"
2. Set jumlah pekerjaan (misal: 5)
3. Sistem menampilkan:
   • Oli Mesin: 4 liter/pekerjaan × 5 = 20 liter total
   • Filter Oli: 1 unit/pekerjaan × 5 = 5 unit total

Stock Flow Process

Saat Transaksi Dibuat:

1. User memilih pekerjaan dan quantity
2. Sistem check stock availability
3. Jika stock tidak cukup, tampilkan warning
4. User konfirmasi untuk melanjutkan
5. Transaksi disimpan dengan status 'completed'
6. Stock otomatis dikurangi sesuai konfigurasi work products

Saat Transaksi Dihapus:

1. Sistem ambil data transaksi
2. Kembalikan stock sesuai dengan produk yang digunakan
3. Catat dalam stock log
4. Hapus transaksi

Error Handling

Stock Tidak Mencukupi:

• Tampilkan warning dengan detail produk
• Izinkan user untuk melanjutkan dengan konfirmasi
• Stock boleh menjadi negatif (business rule)

Product Tidak Dikonfigurasi:

• Jika pekerjaan belum dikonfigurasi produknya, tidak ada pengurangan stock
• Transaksi tetap bisa dibuat normal

Database Transaction:

• Semua operasi stock menggunakan database transaction
• Rollback otomatis jika ada error

Best Practices

1. Konfigurasi Work Products

• Set quantity required yang akurat
• Gunakan notes untuk informasi tambahan
• Review berkala konfigurasi produk

2. Stock Management

• Monitor stock levels secara berkala
• Set minimum stock alerts
• Koordinasi dengan procurement team

3. Training User

• Berikan training tentang stock warnings
• Edukasi tentang impact stock negatif
• Prosedur escalation jika stock habis

Troubleshooting

Stock Tidak Berkurang Otomatis:

1. Cek konfigurasi work products
2. Pastikan produk memiliki stock record di dealer
3. Check error logs

Error Saat Submit Transaksi:

1. Refresh halaman dan coba lagi
2. Check koneksi internet
3. Contact admin jika masih error

Stock Calculation Salah:

1. Review konfigurasi quantity di work products
2. Check apakah ada duplikasi produk
3. Verify stock log untuk audit trail

Monitoring & Reporting

Stock Logs

Semua perubahan stock tercatat dalam stock_logs table dengan informasi:

• Source transaction
• Previous quantity
• New quantity
• Change amount
• Timestamp
• User who made the change

Reports Available

• Stock usage by work type
• Stock movement history
• Negative stock alerts
• Product consumption analysis

Future Enhancements

1. Automated Stock Alerts: Email notifications ketika stock di bawah minimum
2. Batch Operations: Update multiple work products sekaligus
3. Stock Forecasting: Prediksi kebutuhan stock berdasarkan historical data
4. Mobile Interface: Mobile-friendly interface untuk stock checking
5. Integration: Integration dengan sistem procurement/inventory external