# 📋 Checklist & Framework Evaluasi Traceability (Python + Next.js)

Dokumen ini dirancang sebagai **Panduan Evaluasi & Audit Kesiapan Traceability** untuk proyek berbasis **Python** (FastAPI / Django / Flask) di sisi *Backend* dan **Next.js** (App Router / Pages Router) di sisi *Frontend*.

Gunakan dokumen ini untuk mengaudit apakah aplikasi Anda sudah memenuhi standar **Context Isolation**, **360-Degree Lineage**, **Deterministic Sequential Counter**, dan **Audit Trail Compliance**.

---

## 🎯 5 Pilar Utama Evaluasi

```
[1. Backend Python Context Isolation] ──> [2. Next.js Context & Session] ──> [3. Immutable Audit Ledger]
                                                  │
[5. Request Tracing & Security] <───────── [4. Data Lineage & Batch Link]
```

---

## 1. Backend Python: Context Isolation & Multi-Tenancy / Multi-Branch

Pada aplikasi Python (FastAPI/Django/SQLAlchemy/Django ORM), kebocoran data antar-tenant/cabang sering terjadi jika filter context lupa diselipkan di kueri database.

### 🔍 Checklist Evaluasi Backend Python:
- [ ] **Context Injection via Middleware / Dependency:**
  - *FastAPI:* Apakah `branch_id` / `tenant_id` diinjeksi via Dependency Injection (`Depends(get_current_context)`) secara otomatis ke setiap *repository / service layer*?
  - *Django:* Apakah terdapat *Custom Middleware* yang memasukkan `tenant_id` ke *Thread Local Context* / *ContextVars*?
- [ ] **Enforcement pada ORM Queries:**
  - Apakah semua kueri `SELECT`, `UPDATE`, `DELETE` secara otomatis menyertakan filter `where(Model.branch_id == context.branch_id)`?
  - Apakah digunakan library seperti `django-multitenant` atau *SQLAlchemy Global Filter / Event Listeners* untuk mencegah kueri telanjang tanpa `tenant_id`?
- [ ] **Atomic Concurrency Locking:**
  - Apakah transaksi kritis (seperti potong stok/checkout) menggunakan `SELECT FOR UPDATE` (pada PostgreSQL/MySQL) atau Redis `Redlock` untuk mencegah *race condition*?

---

## 2. Frontend Next.js: State & Context Propagation

Pada Next.js (terutama App Router dengan Server Components & Client Components), variabel konteks cabang/tenant riskan hilang saat terjadi transisi halaman atau pemanggilan API.

### 🔍 Checklist Evaluasi Frontend Next.js:
- [ ] **Header Propagation di API Client (Axios / Fetch Wrapper):**
  - Apakah API Client terpusat di Next.js secara otomatis menyisipkan *Header Konteks*:
    - `X-Tenant-ID`
    - `X-Branch-ID`
    - `Authorization: Bearer <token>`
- [ ] **Idempotency Key pada Submit Form Transaksi:**
  - Apakah setiap tombol submit transaksi di Next.js mengirimkan header `Idempotency-Key: uuidv4()` untuk mencegah pembuatan transaksi ganda saat koneksi lambat / user melakukan *double-click*?
- [ ] **Sanitasi Data di Server-Side Rendering (SSR):**
  - Apakah data sensitif cabang lain tersaring bersih di Server Component sebelum dikirimkan ke HTML *client*?

---

## 3. Immutable Audit Ledger & Sequential Counter

Untuk kebutuhan audit akuntansi dan *traceability*, catatan histori **TIDAK BOLEH** ditimpa (*overwrite*) dan harus memiliki urutan linier yang pasti.

### 🔍 Checklist Evaluasi Audit Ledger:
- [ ] **Append-Only Event Tables:**
  - Apakah perubahan status dokumen/stok dicatat pada tabel log terpisah (*Event Sourcing / Audit Log Table*) yang sifatnya *insert-only* (tanpa `UPDATE` / `DELETE`)?
- [ ] **Deterministic Sequential Counter:**
  - Apakah setiap transaksi utama memiliki kolom `counter_number` (integer incremental per cabang/tahun) sebagai penentu pasti urutan linier selain kolom `created_at`?
  - *Di Python:* Apakah pembuat nomor urut counter menggunakan mekanisme *atomic transaction* (misal: `Redis INCR` / `PostgreSQL Sequence` / `Custom Counter Table with Row Lock`)?
- [ ] **Audit Metadata (Who, When, Where):**
  - Apakah setiap tabel transaksi wajib menyimpan:
    - `created_by_user_id` & `created_by_user_name`
    - `created_at` (UTC / ISO 8601 dengan timezone)
    - `ip_address` & `user_agent`

---

## 4. Data Lineage & Batch/Lot Traceability Matrix

Kemampuan untuk menelusuri silsilah data dari satu titik ke titik awal (Hulu ke Hilir).

### 🔍 Checklist Evaluasi Data Lineage:
- [ ] **Parent Reference Pointer Chain:**
  - Apakah setiap baris data turunan menyimpan pointer referensi ke induknya?
    $$\text{Invoice Detail} \xrightarrow{\texttt{delivery\_item\_id}} \text{Delivery Item} \xrightarrow{\texttt{so\_item\_id}} \text{Sales Order Item}$$
- [ ] **Batch / Lot / Serial Number Genealogy:**
  - Apakah barang memiliki identitas `batch_number` / `lot_number` yang mengikat transaksi asal (Penerimaan Supplier / Goods Receipt)?
  - Apakah terdapat API Endpoint (misal `/api/v1/traceability/lineage/{invoice_id}`) yang mampu mengembalikan struktur pohon (*Tree Graph JSON*) silsilah barang & dokumen secara rekursif?

---

## 5. Distributed Tracing & Observability Log

Memastikan jika terjadi kesalahan atau manipulasi data, tim enginer dapat melacak jejak eksekusi dari Next.js hingga ke Python secara pasti.

### 🔍 Checklist Evaluasi Observability:
- [ ] **Correlation ID / Trace ID:**
  - Apakah Next.js membangkitkan `X-Request-ID` / `X-Trace-ID` pada setiap permintaan, dan Python mempropagasi ID ini ke seluruh *log entries* & *database queries*?
- [ ] **Structured JSON Logging:**
  - Apakah Python menggunakan *Structured Logging* (`structlog` / `loguru` / `python-json-logger`) yang memuat `trace_id`, `tenant_id`, `user_id`, dan `endpoint`?

---

## 📊 Matriks Skor Evaluasi Mandiri (Self-Assessment Matrix)

Isi matriks ini saat menguji proyek Python + Next.js Anda:

| No | Domain Evaluasi | Status (`PASS` / `NEED FIX` / `MISSING`) | Catatan / Action Item |
| :--- | :--- | :---: | :--- |
| **1** | **Backend Python Context Scoping** (Filter Tenant/Cabang di ORM) | `[ ] PASS` | |
| **2** | **Next.js Context & Idempotency Header** (Auto Header Propagation) | `[ ] PASS` | |
| **3** | **Sequential Counter Column** (`counter_number` per cabang) | `[ ] PASS` | |
| **4** | **Immutable Audit Log Table** (Append-only histori perubahan) | `[ ] PASS` | |
| **5** | **Parent-Child Reference Linkage** (`parent_tr_id` & `batch_id`) | `[ ] PASS` | |
| **6** | **Traceability Tree API** (Endpoint penelusuran silsilah 360°) | `[ ] PASS` | |
| **7** | **Distributed Trace ID** (`X-Trace-ID` dari Next.js ke Python) | `[ ] PASS` | |

---

> 💡 **Rekomendasi Tindak Lanjut:**
> Jika skor **`PASS` < 5**, proyek berisiko mengalami kecolongan urutan data, kebocoran data antar-tenant (*data leakage*), atau kesulitan saat diaudit oleh pihak luar. Rekomendasikan perbaikan prioritas pada **Domain 1 (Context Scoping)** dan **Domain 3 (Sequential Counter)** terlebih dahulu.