accounting_dev_v2/docs/TECHNICIAN-EQUIPMENT-FINALIZATION.md

Finalisasi Peralatan Teknisi

Ruang lingkup

Peralatan Teknisi adalah subledger operasional penguasaan fisik. Modul tidak membuat jurnal, tidak menulis stock_logs/inventory_ledger, serta tidak mengubah qty_sisa, harga, costing, atau nilai persediaan. Barang perusahaan tetap mengacu ke items, kode_barang, dan item_barcodes. reserved_qty dipakai untuk menahan kuantitas yang sedang berada di luar gudang agar tidak dapat dijual dua kali.

Barang customer disimpan terpisah dalam customer_equipment_registry dan tidak pernah diberi item_id atau barcode_id persediaan.

Migration production

Jalankan setelah backup dan maintenance window:

php index.php migrate latest
php index.php migrate status
php index.php migrate equipment_audit

Migration yang harus terpasang berurutan:

1. 20260911000100_finalize_technician_equipment_operations.php
2. 20260911000200_link_application_users_to_employees.php
3. 20260911000300_add_customer_equipment_source_fields.php
4. 20260911000400_add_technician_document_location.php
5. 20260911000500_add_technician_condition_permission.php
6. 20260911000600_document_technician_opening_balances.php
7. 20260911000700_add_technician_attachment_permission.php

Migration pertama membuat register barang customer, dokumen/header-detail, saldo custody, antrean pemeriksaan, indeks, permission awal, dan saldo awal dari item_technician. Migration tidak membuat ulang item_movements lama. Migration kedua menambah relasi opsional users.employee_id agar akun ber-role Teknisi dapat dibatasi pada barangnya sendiri. Migration ketiga menambah tanggal, nomor dokumen, dan alasan sumber barang customer/non-persediaan. Migration keempat menambah lokasi pemasangan pada dokumen operasional. Migration kelima memisahkan izin kondisi rusak/hilang. Migration keenam membuat dokumen immutable “Saldo Awal Migrasi” tanpa menggandakan movement lama. Migration ketujuh memisahkan izin melihat lampiran.

Setelah migration, buka Pengaturan → Pengguna dan tautkan setiap akun Teknisi ke Data Karyawan yang benar. Login ulang diperlukan agar permission baru masuk ke session.

Alur final

1. Gudang → teknisi: pilih teknisi sekali, scan/cari banyak barang, lalu posting satu dokumen batch. Sistem menahan reserved_qty, mencatat item_movements, dan saldo custody per baris.
2. Teknisi → customer: pemasangan penuh/sebagian dan dokumen pemasangan.
3. Customer → teknisi: pelepasan dengan kondisi, customer asal, dan histori.
4. Teknisi → teknisi: pilih teknisi asal/tujuan sekali dan transfer banyak barang penuh/sebagian.
5. Teknisi → gudang: pengembalian banyak barang dalam satu dokumen dan satu bukti batch; seluruhnya masuk karantina dan belum available.
6. Pemeriksaan: hanya hasil layak yang melepaskan reservation dan membuat barang perusahaan available kembali.
7. Penggantian: pemasangan barang baru dan pelepasan barang lama berada dalam satu transaksi/dokumen.
8. Koreksi: membuat dokumen reversal baru; dokumen lama menjadi reversed dan tidak dihapus.

Pencarian menerima input scanner barcode USB/Bluetooth, barcode, serial number, kode barang, dan nama barang. Barang customer yang sudah terdaftar dipilih dari hasil scan/pencarian sehingga identitasnya tidak perlu dimasukkan ulang. PDF daftar posisi barang tersedia pada setiap teknisi.

UNIT dan QTY

• UNIT: kuantitas selalu 1 dan hanya boleh mempunyai satu posisi aktif.
• QTY: mendukung perpindahan sebagian dan saldo per teknisi/customer/status. Setiap perubahan menggunakan transaksi, row lock, version check, validasi saldo, dan idempotency key.

Permission

• technician_equipment: akses/register/export.
• technician_equipment_all: melihat seluruh teknisi.
• technician_attachment: melihat foto/dokumen lampiran.
• technician_handover: serah terima gudang.
• technician_installation: pemasangan, pelepasan, penggantian.
• technician_transfer: transfer antar teknisi.
• technician_return: pengembalian.
• technician_inspection: pemeriksaan gudang.
• technician_condition: menandai rusak, hilang, atau dihapuskan operasional.
• technician_correction: reversal.

Master Admin/Admin selalu mendapat seluruh kemampuan. Role Teknisi tanpa izin technician_equipment_all dibatasi memakai users.employee_id.

Pemeriksaan development

Perintah smoke test menggunakan transaksi rollback dan tidak meninggalkan data:

php index.php migrate equipment_smoke
php index.php migrate equipment_qty_smoke
php index.php migrate equipment_replacement_smoke
php index.php migrate equipment_query_smoke
php index.php migrate equipment_batch_smoke

Jangan menjalankan metode smoke melalui HTTP; controller migration hanya menerima CLI.

Tidak diubah

Alur pembelian, penerimaan, penjualan, invoice, aset tetap, payroll, laporan accounting, master barang, harga, costing, dan general ledger tidak diubah oleh finalisasi ini.