accounting_dev_v2/docs/TAHAP-2.md

Tahap 2: Fondasi Arsitektur dan Transaksi

Arsitektur baru

Controller menangani request dan response, model menangani akses data, sedangkan aturan bisnis berada di service:

HTTP/CLI request
    -> Controller
        -> Domain Service
            -> Domain Model
                -> Database

Komponen yang tersedia:

• JournalService: validasi header, akun, baris, dan keseimbangan jurnal.
• PostingService: posting jurnal dari transaksi sumber dan pencegahan posting ganda.
• NumberingService: nomor dokumen atomic melalui document_sequences.
• AccountMappingService: mapping akun dari database dengan fallback konfigurasi.
• TransactionService: commit/rollback berbasis callback dan exception.
• JournalModel, AccountModel, InvoiceModel, dan InventoryModel.
• BusinessException dan helper response JSON konsisten.

Integrasi yang sudah dilakukan

• Jurnal manual menggunakan JournalService dan NumberingService.
• Draft invoice menggunakan InvoiceModel dan penomoran terpusat.
• Posting item invoice menggunakan PostingService.
• Sinkronisasi stok dari invoice menggunakan InventoryModel.
• Nomor jurnal invoice dan pembayaran menggunakan NumberingService.
• Mapping akun invoice tidak lagi ditulis langsung pada controller.
• Penyusutan aset menggunakan mapping akun dan PostingService.

Proses jurnal lama pada modul Items, Asset manual, dan pembayaran invoice yang kompleks masih tetap kompatibel. Migrasinya ke service dilakukan bertahap setelah characterization test tersedia agar perilaku transaksi lama tidak berubah tanpa terdeteksi.

Migration

Jalankan hanya melalui CLI:

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

Rollback ke version sebelumnya:

php index.php migrate version 20260831000100

Jangan rollback migration pertama jika sequence sudah dipakai production, karena tabel sequence dan mapping akan dihapus oleh migration down.

Pemeriksaan accounting

Pemeriksaan read-only:

php index.php accountingcheck

Pemeriksaan mendeteksi:

• Tabel fondasi yang hilang.
• Mapping menuju akun yang tidak ada.
• Nomor jurnal duplikat.
• Jurnal debit/kredit tidak balance.

Temuan data historis

Pada penerapan awal ditemukan lima nomor referensi jurnal yang sudah duplikat:

• ADJ-20260609-87
• INV-20260610-0006
• INV-20260611-0001
• INV-20260722-0002
• INV-20260723-0006

Data tersebut tidak diubah otomatis. Accounting perlu menentukan transaksi yang sah, kemudian referensi duplikat dikoreksi dengan audit trail. Setelah bersih, tambahkan unique index pada journals.no_ref melalui migration terpisah.

Aturan penggunaan service

1. Controller baru tidak boleh insert langsung ke journals atau journal_details.
2. Mapping akun baru dibuat pada system_account_mappings, bukan ID pada controller.
3. Nomor dokumen baru harus melalui NumberingService.
4. Operasi multi-tabel harus memakai TransactionService atau transaksi eksplisit dengan penanganan exception.
5. Saat dipanggil di dalam transaksi yang sudah aktif, gunakan parameter manageTransaction=false pada service posting.
6. Untuk sumber yang boleh menghasilkan beberapa jurnal, nonaktifkan duplicate-source guard dan gunakan referensi unik per periode/transaksi.

Langkah operasional berikutnya

1. Review delapan mapping akun bersama accounting.
2. Rekonsiliasi lima nomor jurnal historis yang duplikat.
3. Tambahkan characterization test untuk Items, Asset, dan pembayaran invoice.
4. Setelah test tersedia, pindahkan sisa direct journal insert ke PostingService.