[ND-256/LNSW.34/2026] Sanitasi Karakter dan Truncate 50 Karakter Nama Wajib Bayar & Organization Name Single Billing

Modul: Pengangkut | Tipe: Change Request | Stage Saat Ini: DEVELOPMENT | Tanggal Dokumen: 2026-08-24

---

1. Informasi Tugas & Referensi Bisnis

• Task ID / Nomor Referensi: ND-256/LNSW.34/2026
• Sumber Instruksi: Nota Dinas Resmi ND-256/LNSW.34/2026
• Dokumen Referensi / Lampiran: ND-256-LNSW.34-2026.pdf
• Modul Terkait: Pengangkut
• Service / Repository: pengangkut-backend
• PIC Pengembang: Hermansyah Efendi
• Latar Belakang & Ringkasan Kebutuhan: Berdasarkan arahan integrasi SIMPONI Single Billing pada Nota Dinas ND-256/LNSW.34/2026, field nama wajib bayar dan nama organisasi wajib memenuhi batasan alfanumerik serta panjang maksimal 50 karakter (C(50)). Perubahan dilakukan pada layer helper utilitas, validasi Zod, dan builder payload Single Billing agar request tagihan valid dan tidak mengalami penolakan (rejection) oleh gateway SIMPONI akibat karakter spesial atau string overflow.

---

2. Deployment Lifecycle

#	Environment	Tanggal & Waktu	PIC	Status	Catatan
1	Development	2026-08-20 14:30	Hermansyah Efendi	DEPLOYED	Branch: development
2	Staging (UAT)	—	—	PENDING	—
3	Production	—	—	PENDING	—

Riwayat Update Log

Tanggal	Environment	Perubahan	PIC
2026-08-24	Development	Inisialisasi draft audit log dari context block backend (commit 401a4dcb)	Hermansyah Efendi

---

3. Analisis Teknis & Rincian Perubahan

• Alur Logika & Bisnis:

  • Penambahan helper normalizeNpwp untuk standardisasi format NPWP dengan membersihkan karakter selain angka (spasi, titik, tanda minus).
  • Penambahan helper sanitizeAlphanumeric dengan regex untuk membersihkan karakter non-alfanumerik, menormalkan spasi ganda menjadi spasi tunggal, serta melakukan pemotongan string otomatis maksimal 50 karakter.
  • Refactor skema validasi NPWP di app/helpers/zod.js menggunakan helper normalizeNpwp.
  • Integrasi sanitasi & truncate 50 karakter di app/models/billing_models.js pada method generateBillingPayloadV3, setRekapTagihanV2, dan payloadSingleBillingV2 untuk field organization_name (header) dan nama_wajib_bayar (detail).
  • Penambahan test suite komprehensif di tests/helpers/utils.test.js dan tests/models/billing_models.test.js.

• Perubahan Database (DDL / DML):

  -- Tidak ada perubahan skema database (DDL/DML) untuk task ini.
  -- Perubahan murni pada layer data formatting dan outbound API payload builder.

• Kontrak API & Response Payload: Penyesuaian outbound payload menuju Single Billing SIMPONI: field organization_name dan nama_wajib_bayar dijamin alfanumerik dengan panjang $\le 50$ karakter.

  {
    "organization_name": "PT PELAYARAN NASIONAL INDONESIA",
    "details": [
      {
        "nama_wajib_bayar": "PT PELAYARAN NASIONAL INDONESIA",
        "npwp": "012345678901234"
      }
    ]
  }

---

4. Bukti Teknis (Technical Proof & Audit Trail)

• Repository: pengangkut-backend
• Branch: development
• Commit ID / Hash: 401a4dcb68b77cacbf3e6eda741bca565ca1c8fd
• Merge Request / PR: -

Cuplikan Kode / Implementasi Inti

// app/helpers/utils.js
const sanitizeAlphanumeric = (str, maxLength = 50) => {
  if (!str || typeof str !== 'string') return '';
  return str
    .replace(/[^a-zA-Z0-9\s]/g, '')
    .replace(/\s+/g, ' ')
    .trim()
    .slice(0, maxLength);
};

const normalizeNpwp = (npwp) => {
  if (!npwp || typeof npwp !== 'string') return '';
  return npwp.replace(/[^0-9]/g, '');
};

---

5. Bukti Verifikasi Pengujian (QA / API Verification)

Diisi saat naik ke Staging atau Production.

{
  "test_suites": [
    "tests/helpers/utils.test.js (PASS)",
    "tests/models/billing_models.test.js (PASS)"
  ],
  "verification_status": "DEV_PASSED"
}

• Hasil Pengujian: PENDING (Menunggu verifikasi integrasi UAT Staging)
• Catatan QA: Unit test lokal lulus. Menunggu jadwal deployment dan verifikasi staging.