Lanjut ke konten
Samkarsa Logbook

Ketik untuk mencari…

↑↓untuk navigasi
Esc

v1.0.0-001 : Baseline Architecture (Jualan)

Snapshot awal seluruh komponen, UI, dan arsitektur terpadu Jualan (Frontend Blonjo, MCP, dan Backend Sajen).

Jualan2mnt baca

Timestamp: [2026-07-23 00:00:00]

Snapshot awal seluruh komponen, infrastruktur AI, UI, dan arsitektur ekosistem Jualan yang menggabungkan Frontend (Blonjo), Server Konteks (MCP), dan Backend (Sajen). File ini merupakan penggabungan dari catatan arsitektur masing-masing layanan agar lebih terpusat dan rapi.

Diagram di bawah ini mengilustrasikan bagaimana ketiga entitas utama berinteraksi secara berkesinambungan:

flowchart TD %% Frontend Node subgraph Frontend["Blonjo UI (React/Vite)"] UI_Input["User Input (Struk / Teks)"] UI_SmartNote["SmartNoteTab & Local OCR"] UI_Purchase["Purchase Plan & Dashboard"] end %% Backend Node subgraph Backend["Sajen API (FastAPI)"] API_Gateway["API Gateway / Routers"] Worker_OCR["Background Worker (OCR)"] Vision_Match["Vision Matcher (OpenCV)"] NLP_Engine["Accounting & NLP Normalization"] DB[(PostgreSQL & Vector)] end %% MCP Node subgraph MCP["MCP Server (Context Provider)"] COA_Tool["COA Lookup"] Pricing_Tool["Pricing Rule Resolver"] Visual_Map["Visual Template Mapping"] end %% Flow UI_Input -->|Upload / Teks| UI_SmartNote UI_SmartNote -->|Local OCR Fallback| API_Gateway API_Gateway -->|Submit Image| Worker_OCR Worker_OCR <-->|Check Template| Vision_Match Worker_OCR <-->|Fallback Normalization| NLP_Engine %% Backend to MCP NLP_Engine <-->|Vector Search & Context| MCP Vision_Match <-->|Coordinate Maps| Visual_Map NLP_Engine <-->|Injects Rules| Pricing_Tool %% Save to DB API_Gateway <--> DB Worker_OCR <--> DB %% Return to UI API_Gateway -->|JSON Result| UI_Purchase

  • Stack Teknologi: React 18, TypeScript, Vite, TailwindCSS, shadcn/ui.
  • Modul Pencatatan Cerdas (Smart Note & OCR): Melakukan pindaian pra-pemrosesan di browser (Local OCR menggunakan Xenova/trocr-small-printed). Jika gagal atau skor di bawah batas keyakinan (confidence), akan di-fallback ke API Backend (/ocr/upload).
  • Smart Parser Local: Menggunakan Regex (v2) untuk menerjemahkan teks Indonesia singkat menjadi struktur ber-tipe (meski belum menangani properti matematika rumit seperti discount dengan otomatis).
  • Modul Material Control & Master Data: Pusat penyusunan rencana belanja (PurchasePlanForm) dan manajemen data produk serta kontak, yang dihubungkan dengan Pricing Rules.
  • Business Compass: Dashboard yang menyajikan metrik visual untuk pendukung keputusan bisnis (contoh: Cash Balance, Net Profit).

  • Infrastruktur Dasar: FastAPI (Python), PostgreSQL, async engine.
  • Pemrosesan Gambar (OCR & Vision): Menampung fallback OCR di ocr_worker.py (via Background Task) dengan menggunakan Gemini Vision API. Dibantu oleh vision_matcher.py (OpenCV pHash 8x8) untuk pendeteksian letak nota (dengan catatan masih rentan terhadap False Positive pada latar datar).
  • Engine Akuntansi & Normalisasi: Menangani teks mentah menjadi struktur data valid JSON via accounting.py. Menggunakan 3 tahap: Regex rule-based, Cache Matching, dan LLM Fallback via Gemini.

  • Fungsi Utama: Bertindak sebagai Context Provider berbasis RAG yang menyuntikkan informasi kaya langsung ke Backend Sajen.
  • Kapabilitas Tools:
    • COA Lookup: Mencegah halusinasi AI saat pendaftaran Chart of Account.
    • Pricing Rule Resolver: Menyediakan data aturan harga kustom per-tenant.
    • Visual Template Mapping: Menyimpan daftar koordinat crop spesifik dari setiap vendor/supplier untuk mempersempit pindaian OCR.

  • Masalah: Terjadi error TypeError: 'discount_value' is an invalid keyword argument for InventoryLog saat melakukan penyimpanan transaksi.
  • Penyebab: Script di accounting.py mencoba memasukkan data diskon (discount_value, is_percent, is_manual_correction) secara eksplisit ke dalam model InventoryLog. Namun secara arsitektur, tabel inventory_logs tidak memiliki kolom tersebut karena difokuskan hanya untuk stock movement dan perhitungan HPP (quantity dan price_per_unit bersih).
  • Perbaikan: Menghapus argumen tersebut dari inisialisasi InventoryLog. Diskon tetap diproses dan diakumulasikan ke dalam variabel adjusted_unit_price sehingga nilai HPP dan stok tetap akurat tanpa mengubah skema tabel database live yang ada.

  • Masalah: Muncul error 502 Bad Gateway saat ParsePreview dan 405 Method Not Allowed saat proses simpan transaksi.
  • Penjelasan: Error ini bukan berasal dari bug kode, melainkan terjadi karena timing pengujian yang dilakukan tepat bersamaan dengan proses deployment (restart container backend) di VPS.
    • Saat container backend mati sejenak untuk di-update, Traefik (API Gateway) kehilangan koneksi ke backend sehingga mengembalikan status 502.
    • Bersamaan dengan itu, Traefik mencabut rute /api. Ketika ada request baru (POST /transactions), Traefik melemparnya ke rute default (Frontend Nginx). Nginx tidak mengizinkan request POST untuk static file, sehingga membalas dengan 405 Method Not Allowed.

Berikut adalah ilustrasi alurnya:

sequenceDiagram participant UI as Frontend (Blonjo) participant TR as Traefik (Gateway) participant API as Backend (Sajen API) Note over UI,API: 🔴 FASE DEPLOY (API DOWN / RESTARTING) API--xTR: Connection Refused / Container Down UI->>TR: POST /api/v1/finance/transactions/parse TR-->>UI: 502 Bad Gateway (ParsePreview gagal) Note over TR: Traefik mencabut rute /api sementara UI->>TR: POST /api/v1/finance/transactions (Save) TR-->>UI: 405 Method Not Allowed (Jatuh ke Nginx) Note over UI,API: 🟢 DEPLOY SELESAI (API UP & HEALTHY) API->>TR: Container Ready (Port 8005) Note over TR: Traefik mendaftarkan ulang rute /api UI->>TR: POST /api/v1/finance/transactions (Save Ulang) TR->>API: Forward Request API-->>TR: 201 Created (Berhasil disimpan) TR-->>UI: Success Response