# 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:

```bash
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:

```bash
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.