[FEAT-REQUEST-LOGGER-POSTMAN] Implementasi Request Logger Middleware & Otomatisasi Postman Collection Generator

Modul: Single Billing | Tipe: Feature | Stage Saat Ini: PRODUCTION | Tanggal Dokumen: 2026-09-07

PRODUCTION RELEASED

Dokumen ini telah berada dalam tahap PRODUCTION. Perubahan logika backend, migrasi skema/konfigurasi, dan rilis v1.9.2 telah diterapkan secara penuh di lingkungan Production via MR !232.

LIFECYCLE GUIDE — UPDATE BERTAHAP:

Buat file ini saat selesai development. Isi semua section kecuali Staging & Production.
- Tanggal Dokumen (Header) & Riwayat Update Log: Gunakan tanggal hari ini (pembuatan dokumen).
- Baris Development (Lifecycle): Gunakan tanggal & jam commit terakhir terkait di branch development.
Update baris Staging saat naik ke UAT. Ubah "Stage Saat Ini" di header menjadi STAGING.
Update baris Production saat naik ke Prod. Ubah "Stage Saat Ini" di header menjadi PRODUCTION.
Update entry di README.md setiap kali status berubah. -->

1. Informasi Tugas & Referensi Bisnis

Task ID / Nomor Referensi: FEAT-REQUEST-LOGGER-POSTMAN
Sumber Instruksi: Peningkatan Observabilitas Developer & Otomatisasi Dokumentasi API via Postman Collection Generator
Dokumen Referensi / Lampiran: -
Task / Dependensi Terkait (Cross-Service): FEAT-SIMPONI-V3-ISOLATION
Modul Terkait: Single Billing
Service / Repository: single-billing-BE
PIC Pengembang: Hermansyah Efendi
Latar Belakang & Ringkasan Kebutuhan: Dalam siklus rilis dan integrasi Single Billing yang dinamis, dokumentasi Postman Collection kerap mengalami stale (ketinggalan zaman) karena perubahan payload di sisi caller tidak terdokumentasi secara konsisten. Di samping itu, developer dan QA membutuhkan sarana cepat untuk mereproduksi (reproduce) request HTTP riil tanpa harus menyusun ulang header dan body secara manual. Fitur ini memperkenalkan: (1) Middleware requestLogger yang secara otomatis menangkap incoming request, mendeteksi variasi struktur payload (berdasarkan root keys objek untuk menghindari duplikasi log yang identik), dan menyimpannya sebagai format perintah cURL siap pakai; (2) Generator Postman Collection (postman_collection_controller.js) yang mengonversi rekaman cURL log menjadi dokumen Postman Collection v2.1.0 resmi; dan (3) Pengamanan berbasis ADMIN_GROUPS pada middleware SSO auth (req.isAdmin) untuk membatasi akses endpoint generator hanya bagi pengguna berhak.
Ruang Lingkup & Rincian Sub-Pekerjaan (Technical Scope & Milestones):
- [x] Pembuatan middleware requestLogger pada app/middlewares/requestLogger.js yang mengonversi request masuk menjadi perintah cURL dan membandingkan variasi root keys payload
- [x] Registrasi middleware requestLogger pada pipeline global Express di server.js
- [x] Penambahan helper otorisasi isAdmin (ADMIN_GROUPS = ["00", "07", "20"]) dan injeksi atribut req.isAdmin pada app/middlewares/auth.js
- [x] Pembuatan controller app/controllers/postman_collection_controller.js untuk parsing rekaman cURL ke spesifikasi JSON Postman v2.1.0
- [x] Pendaftaran endpoint administrasi koleksi Postman (/postman/generate-collections, /postman/clean-collections, /postman/remove-all-collections) di app/routes/v2/index.js

2. Deployment Lifecycle

#	Environment	Tanggal & Waktu	PIC	Status	Catatan
1	Development	2026-07-08 08:52	Hermansyah Efendi	`DEPLOYED`	Branch: `development (Merged from feat/request-logger-postman)`
2	Staging (UAT)	2026-10-14 13:00	Hermansyah Efendi / QA	`DEPLOYED`	Release Candidate via MR Staging !229. Co-deployed: [FEAT-SIMPONI-V3-ISOLATION, TASK-SET-EXPIRED-BILLING-V3, FEAT-BILLING-REKAP-EXPIRED-DATE-PAYLOAD, REFACTOR-TAGIHAN-CONTROLLER-DEDUPLICATION, FIX-PAYMENT-WEBHOOK-RACE-CONDITION, FIX-TAGIHAN-PREVENT-PAID-INVOICE-REORDER, FEAT-REQUEST-LOGGER-POSTMAN, TEST-DRAGONFLY-VITEST-SUITE, FEAT-RUNTIME-ENV-VALIDATION, TASK-NON-BLOCKING-BILLING-DISPATCH-AND-RETRY-CONFIG]
3	Production	2026-10-14 20:06	achmad fauzi	`DEPLOYED`	Branch: `prod` via MR !232 (Release v1.9.2). Co-deployed: [FEAT-SIMPONI-V3-ISOLATION, TASK-SET-EXPIRED-BILLING-V3, FEAT-BILLING-REKAP-EXPIRED-DATE-PAYLOAD, REFACTOR-TAGIHAN-CONTROLLER-DEDUPLICATION, FIX-PAYMENT-WEBHOOK-RACE-CONDITION, FIX-TAGIHAN-PREVENT-PAID-INVOICE-REORDER, FEAT-REQUEST-LOGGER-POSTMAN, TEST-DRAGONFLY-VITEST-SUITE, FEAT-RUNTIME-ENV-VALIDATION, TASK-NON-BLOCKING-BILLING-DISPATCH-AND-RETRY-CONFIG]

Riwayat Update Log

Tanggal	Environment	Perubahan	PIC
2026-10-14	Production	Status diupdate ke PRODUCTION (DEPLOYED, CLOSED), rilis Release v1.9.2 via MR !232	Hermansyah Efendi
2026-09-07	Development	Inisialisasi draft audit log dari context block backend (commit `65c2ce3`)	Hermansyah Efendi

3. Analisis Teknis & Rincian Perubahan

Alur Logika & Bisnis:
- Pencegahan Flooding Log dengan Root-Key Structure Matching: Middleware mengecek getObjectRootKeys(req.body). Jika incoming payload memiliki kombinasi root keys yang identik dengan rekaman log sebelumnya pada endpoint tersebut, proses pencatatan dilewati (skip logging) untuk mencegah pembengkakan ruang penyimpanan disk. Ketika terdeteksi variasi struktur payload baru, request diformat ke perintah cURL (mencakup metode HTTP, Authorization header, Content-Type, query params, serta raw body JSON/form-data) dan disimpan ke berkas logs/request-logs/{METHOD_PATH}.json.
- Transformasi Log cURL ke Postman Collection v2.1.0: Controller membaca file log secara bertahap (batch processing), membedah struktur cURL ke komponen request Postman (URL template , headers, token variable , dan request body). Controller mengompilasi item-item tersebut ke format spesifikasi JSON resmi Postman Collection v2.1.0 sehingga siap diimpor langsung oleh developer dan QA.
- Guard Otorisasi Role Admin: Rute administrasi Postman collection dilindungi oleh evaluasi isAdmin(baseData.value.groupGa) pada middleware autentikasi SSO. Hanya pengguna yang tergolong dalam ADMIN_GROUPS ("00", "07", "20") yang memiliki req.isAdmin === true. Akses dari luar grup tersebut ditolak secara tegas dengan respon HTTP 403 Forbidden.
- Daftar File yang Berubah:
  - app/middlewares/requestLogger.js (Middleware NEW — ekstraksi struktur payload dan generator cURL log)
  - app/controllers/postman_collection_controller.js (Controller NEW — parser log cURL menjadi berkas Postman Collection)
  - app/middlewares/auth.js (Middleware — evaluasi role admin melalui grup GA SSO)
  - app/routes/v2/index.js (API Route — penambahan endpoint manajemen Postman collection)
  - server.js (Bootstrap — registrasi global middleware requestLogger)
Perubahan Database (DDL / DML):
Tidak ada migration file terdeteksi — fitur developer observability dan otomatisasi dokumentasi API berbasis filesystem lokal (logs/request-logs/).
Kontrak API & Response Payload:
GET /api/v2/postman/generate-collections
- Deskripsi: Mem-parsing rekaman cURL log di direktori lokal dan menghasilkan struktur Postman Collection v2.1.0.
- Autentikasi / Guard: Bearer Token (doIntrospection), Guard Admin (req.isAdmin === true).
- Request Header:
  - Authorization: Bearer <token>
- Response Payload (200 OK):
  json
```
{
  "status": 200,
  "message": "Berhasil generate postman collections",
  "data": {
    "info": {
      "name": "Single Billing API Collection",
      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": []
  }
}
```
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
- Response Error (403 Forbidden):
  json
```
{
  "status": 403,
  "message": "Forbidden: Akses ditolak. Hanya grup administrator yang diizinkan.",
  "data": null
}
```
  1
  2
  3
  4
  5
GET /api/v2/postman/clean-collections
- Deskripsi: Membersihkan file log duplikat dan menormalkan data koleksi pada direktori logs/request-logs/.
- Autentikasi / Guard: Bearer Token (doIntrospection), Guard Admin (req.isAdmin === true).
- Request Header:
  - Authorization: Bearer <token>
- Response Payload (200 OK):
  json
```
{
  "status": 200,
  "message": "Berhasil membersihkan koleksi duplikat",
  "data": null
}
```
  1
  2
  3
  4
  5
GET /api/v2/postman/remove-all-collections
- Deskripsi: Menghapus seluruh file rekaman log cURL di direktori logs/request-logs/.
- Autentikasi / Guard: Bearer Token (doIntrospection), Guard Admin (req.isAdmin === true).
- Request Header:
  - Authorization: Bearer <token>
- Response Payload (200 OK):
  json
```
{
  "status": 200,
  "message": "Berhasil menghapus seluruh file request log",
  "data": null
}
```
  1
  2
  3
  4
  5

4. Bukti Teknis (Technical Proof & Audit Trail)

Repository: single-billing-BE
Branch Utama: development
Merge Request / PR: !232 (Release v1.9.2 — Merged to prod) | Staging: !229

Daftar Commit Terkait (Multi-Commit Trail)

Commit ID	Branch	Author	Tanggal & Jam	Ringkasan Perubahan
`65c2ce3`	`development`	Hermansyah Efendi	2026-07-08 08:52	feat: implement request logger middleware, postman collection generator, and add new routes

Cuplikan Kode / Implementasi Inti

javascript

// app/middlewares/requestLogger.js
const getObjectRootKeys = (obj) => {
  if (typeof obj !== 'object' || obj === null) {
    return new Set();
  }
  return new Set(Object.keys(obj));
};

const generateCurlCommand = (req) => {
  const originalUrl = req.originalUrl.replace('/api', '');
  let curlCommand = `curl -X ${req.method} '{{BASE_URL}}${originalUrl}'`;

  if (req.headers['authorization']) {
    curlCommand += ` \\\n  -H 'Authorization: Bearer {{TOKEN}}'`;
  }

  if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
    if (req.is('application/json') && req.body) {
      curlCommand += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${JSON.stringify(req.body)}'`;
    }
  }
  return curlCommand;
};

javascript

// app/middlewares/auth.js (Admin Group Guard)
const ADMIN_GROUPS = ["00", "07", "20"];

const isAdmin = (groupGa) => ADMIN_GROUPS.includes(groupGa);

// Di dalam doIntrospection:
req.isAdmin = isAdmin(baseData.value.groupGa);

5. Bukti Verifikasi Pengujian (QA / Unit Test / API Verification)

A. Verifikasi Unit Test (Development Stage)

Test Suite File: tests/middlewares/requestLogger.test.js
Status Eksekusi CLI: PASSED

text

 RUN  v4.1.11 D:/WORK/LNSW/single-billing-BE

 ✓ tests/middlewares/requestLogger.test.js (11 tests) 28ms

 Test Files  1 passed (1)
      Tests  11 passed (11)
   Start at  13:11:10
   Duration  350ms (transform 77ms, setup 89ms, import 38ms, tests 28ms, environment 0ms)

B. Panduan Pengujian QA & Verifikasi Staging (QA Playbook)

Diisi saat development sebagai panduan eksekusi pengujian QA, kemudian dilengkapi bukti response JSON saat verifikasi di Staging.

Cakupan / Surface Pengujian: API / Postman Only
Kebutuhan Akses / Role Akun: Token SSO Admin (groupGa 00/07/20) dan Token User Non-Admin.
Hasil Pengujian UAT: PASSED
Catatan QA: Verifikasi middleware request logger dan generator koleksi Postman admin berhasil lolos pengujian UAT.

Skenario Pengujian QA (Test Scenarios)

Skenario 1 — Automatic Request Logging saat Endpoint API Dipanggil (Happy Path):
- Pre-kondisi: Direktori logs/request-logs/ bersih/kosong.
- Trigger / Request: Kirim request POST /api/v3/terima-rekap-tagihan dengan body payload JSON.
- Ekspektasi Response: API merespons normal, dan sistem secara otomatis menulis rekaman file cURL pada logs/request-logs/POST_v3_terima-rekap-tagihan.json.
- Verifikasi Database / Log: Pastikan berkas file cURL terbuat di direktori lokal dengan placeholder dan .
Skenario 2 — Generate Postman Collection oleh Role Admin:
- Pre-kondisi: Terdapat file log cURL di logs/request-logs/, Token SSO memiliki atribut groupGa = "00" (atau "07" / "20").
- Trigger / Request: GET /api/v2/postman/generate-collections dengan header Authorization: Bearer <admin_token>.
- Ekspektasi Response: HTTP 200 OK, mengembalikan struktur JSON Postman Collection v2.1.0 yang valid dan dapat diimpor langsung ke Postman Desktop.
- Verifikasi Database / Log: Periksa schema JSON pada atribut info.schema bernilai https://schema.getpostman.com/json/collection/v2.1.0/collection.json.
Skenario 3 — Negative Test: Akses Generator oleh Non-Admin:
- Pre-kondisi: Token SSO memiliki groupGa di luar ["00", "07", "20"] (contoh: user operasional dengan group "99").
- Trigger / Request: GET /api/v2/postman/generate-collections dengan header Authorization: Bearer <non_admin_token>.
- Ekspektasi Response: HTTP 403 Forbidden / penolakan akses oleh guard admin.
- Verifikasi Database / Log: Server mencatat rejection unauthorized/forbidden access pada log aplikasi.

Bukti Response Verifikasi Staging (Diisi saat UAT)

json

{
  "status": "PASSED",
  "note": "Pengujian verifikasi UAT dan validasi integrasi berhasil lolos, rilis production v1.9.2 telah live."
}

[FEAT-REQUEST-LOGGER-POSTMAN] Implementasi Request Logger Middleware & Otomatisasi Postman Collection Generator

1. Informasi Tugas & Referensi Bisnis

2. Deployment Lifecycle

Riwayat Update Log

3. Analisis Teknis & Rincian Perubahan

`GET` `/api/v2/postman/generate-collections`

`GET` `/api/v2/postman/clean-collections`

`GET` `/api/v2/postman/remove-all-collections`

4. Bukti Teknis (Technical Proof & Audit Trail)

Daftar Commit Terkait (Multi-Commit Trail)

Cuplikan Kode / Implementasi Inti

5. Bukti Verifikasi Pengujian (QA / Unit Test / API Verification)

A. Verifikasi Unit Test (Development Stage)

B. Panduan Pengujian QA & Verifikasi Staging (QA Playbook)

Skenario Pengujian QA (Test Scenarios)

Bukti Response Verifikasi Staging (Diisi saat UAT)

[FEAT-REQUEST-LOGGER-POSTMAN] Implementasi Request Logger Middleware & Otomatisasi Postman Collection Generator ​

1. Informasi Tugas & Referensi Bisnis ​

2. Deployment Lifecycle ​

Riwayat Update Log ​

3. Analisis Teknis & Rincian Perubahan ​

GET /api/v2/postman/generate-collections ​

GET /api/v2/postman/clean-collections ​

GET /api/v2/postman/remove-all-collections ​

4. Bukti Teknis (Technical Proof & Audit Trail) ​

Daftar Commit Terkait (Multi-Commit Trail) ​

Cuplikan Kode / Implementasi Inti ​

5. Bukti Verifikasi Pengujian (QA / Unit Test / API Verification) ​

A. Verifikasi Unit Test (Development Stage) ​

B. Panduan Pengujian QA & Verifikasi Staging (QA Playbook) ​

Skenario Pengujian QA (Test Scenarios) ​

Bukti Response Verifikasi Staging (Diisi saat UAT) ​

[FEAT-REQUEST-LOGGER-POSTMAN] Implementasi Request Logger Middleware & Otomatisasi Postman Collection Generator

1. Informasi Tugas & Referensi Bisnis

2. Deployment Lifecycle

Riwayat Update Log

3. Analisis Teknis & Rincian Perubahan

`GET` `/api/v2/postman/generate-collections`

`GET` `/api/v2/postman/clean-collections`

`GET` `/api/v2/postman/remove-all-collections`

4. Bukti Teknis (Technical Proof & Audit Trail)

Daftar Commit Terkait (Multi-Commit Trail)

Cuplikan Kode / Implementasi Inti

5. Bukti Verifikasi Pengujian (QA / Unit Test / API Verification)

A. Verifikasi Unit Test (Development Stage)

B. Panduan Pengujian QA & Verifikasi Staging (QA Playbook)

Skenario Pengujian QA (Test Scenarios)

Bukti Response Verifikasi Staging (Diisi saat UAT)