Dokumentasi Project — Sankyu Transport Management System

Dokumentasi lengkap untuk developer: tech stack, arsitektur, development, deployment, troubleshooting, dan coding conventions.

Daftar Isi

• 1. Tech Stack
• 2. Architecture
• 3. Development Setup
• 4. Database & Migrations
• 5. API Reference
• 6. Deployment
• 7. Troubleshooting
• 8. Coding Conventions

1. Tech Stack

Backend — node_backend/

Dependency Utama Backend

1
{
2
  "cors": "^2.8.5",
3
  "dotenv": "^16.4.5",
4
  "exceljs": "^4.4.0",
5
  "express": "^4.18.2",
6
  "jsonwebtoken": "^9.0.2",
7
  "mongoose": "^9.1.4",
8
  "multer": "^2.0.2",
9
  "mysql2": "^3.9.7",
10
  "xlsx": "^0.18.5"
11
}

Frontend — tailadmin-vuejs-1.0.0/

Dependency Utama Frontend

1
{
2
  "vue": "^3.5.13",
3
  "vue-router": "^4.5.0",
4
  "leaflet": "^1.9.4",
5
  "leaflet.markercluster": "^1.5.3",
6
  "tailwindcss": "^4.0.0",
7
  "apexcharts": "^4.4.0",
8
  "lucide-vue-next": "^0.474.0"
9
}

Documentation — docs/

External Services

Ports Default

2. Architecture

Gambaran Umum

Sistem ini menggunakan arsitektur monorepo dengan dua aplikasi utama:

1
┌─────────────────────┐     HTTP/JSON      ┌──────────────────────┐
2
│   Vue 3 Frontend    │ ◄────────────────► │   Express Backend    │
3
│  (SPA + Vite)       │     /api/*          │   (Node.js)          │
4
└─────────────────────┘                     └──────────┬───────────┘
5
                                                       │
6
                                            ┌──────────┼───────────┐
7
                                            │          │           │
8
                                       ┌────▼───┐ ┌───▼────┐ ┌───▼────────┐
9
                                       │ MySQL  │ │MongoDB │ │ Wialon API │
10
                                       │(utama) │ │(legacy)│ │ (GPS)      │
11
                                       └────────┘ └────────┘ └────────────┘

Backend Architecture

Layer Pattern

Backend mengikuti pola Route → Service → Database:

1
Request
2
  │
3
  ▼
4
middleware/auth.js        ← JWT verification
5
middleware/rbac.js        ← Role-based access control
6
  │
7
  ▼
8
routes/<domain>.js        ← HTTP handling, validation, response
9
  │
10
  ▼
11
services/<domain>.js      ← Business logic, external API calls
12
  │
13
  ▼
14
db.js (MySQL pool)        ← Direct SQL queries via mysql2/promise
15
models/<model>.js         ← Mongoose models (MongoDB, legacy)

Route Registration

Semua route didaftarkan di server.js dengan prefix /api/:

1
app.use("/api/trucks", truckRouter);
2
app.use("/api/sales-costs", salesCostRouter);
3
app.use("/api/wialon", wialonRouter);
4
// ...

Authentication Flow

1. User login via POST /api/auth/login
2. Backend memverifikasi kredensial dan mengembalikan JWT token
3. Frontend menyimpan token dan mengirimnya di header Authorization: Bearer <token>
4. Middleware authenticateToken memverifikasi token di setiap request
5. Middleware restrictCsAccess membatasi akses role CS ke route tertentu

Role-Based Access Control

Database Connection

MySQL menggunakan connection pool (mysql2/promise):

1
const pool = mysql.createPool({
2
  host: process.env.DB_HOST,
3
  user: process.env.DB_USER,
4
  password: process.env.DB_PASS,
5
  database: process.env.DB_NAME || "trucking",
6
  connectionLimit: 10
7
});

Query dilakukan langsung tanpa ORM:

1
const [rows] = await pool.query("SELECT * FROM truck WHERE is_active = 1");

External Integration: Wialon

1
Backend                          Wialon API
2
  │                                  │
3
  ├── Login (token) ────────────────►│
4
  │◄──── Session ID ────────────────┤
5
  │                                  │
6
  ├── search_items (units) ─────────►│
7
  │◄──── Unit positions ────────────┤
8
  │                                  │
9
  ├── get_zones_by_unit ────────────►│
10
  │◄──── Geofence membership ──────┤
11
  │                                  │
12
  ├── unit/get_trips ───────────────►│
13
  │◄──── Trip history ─────────────┤

• Session di-reuse selama TTL belum habis
• Semua komunikasi Wialon hanya dari backend (token tidak pernah ke frontend)
• Response Wialon bisa nested — selalu gunakan normalizer

Geofence Tracking (Background Service)

1
geofenceTrackingService.js
2
  │
3
  ├── Load active Sales Cost candidates
4
  ├── Load route-step → geofence mappings
5
  ├── Poll Wialon zone membership (interval)
6
  │
7
  └── If truck in mapped zone & not yet recorded:
8
      └── INSERT into sales_cost_route_history

• Berjalan otomatis saat server start
• Interval dikonfigurasi via GEOFENCE_TRACKING_INTERVAL_MS
• Hanya mencatat first-entry per step (no duplicates)

Frontend Architecture

Component Hierarchy

1
App.vue
2
  └── Router View
3
       ├── views/Master/*        ← CRUD pages
4
       ├── views/Transaksi/*     ← Transaction pages
5
       ├── views/Monitoring/*    ← GPS & mileage
6
       ├── views/DataTransport/* ← Reports
7
       └── views/Auth/*          ← Login

API Communication

Frontend berkomunikasi dengan backend melalui:

1. Development: Vite proxy (/api → http://127.0.0.1:3000)
2. Production: Direct ke VITE_API_URL (e.g., https://sankyu-transport.fun)

1
export const API_ORIGIN = import.meta.env.VITE_API_URL || window.location.origin
2
export const API_BASE = `${API_ORIGIN}/api`

State Management

• Tidak menggunakan Vuex/Pinia global store
• State dikelola per-component atau via composables
• Data dari API di-fetch langsung di views menggunakan service wrappers

Map Architecture (Monitoring)

1
TruckLocationMap.vue
2
  ├── Left Panel: Leaflet Map (markers, clusters)
3
  ├── Middle Panel: Vehicle Detail (shown on selection)
4
  └── Right Panel: Fleet List (scrollable, searchable)

• Auto-refresh setiap 30 detik
• Reverse geocode hanya untuk truck yang dipilih (bukan semua)
• Cache di localStorage dengan TTL 24 jam

Data Flow Patterns

Soft Delete Pattern

Trucks dan drivers menggunakan is_active flag:

1
Active (is_active = 1):
2
  ✓ Muncul di dropdown operasional
3
  ✓ Muncul di GPS/map views
4
  ✓ Bisa digunakan untuk transaksi baru
5

6
Inactive (is_active = 0):
7
  ✓ Tetap muncul di Master Data (admin)
8
  ✓ Tetap muncul di historical records
9
  ✗ Tidak muncul di dropdown operasional
10
  ✗ Tidak muncul di GPS/map views
11
  ✗ Tidak bisa digunakan untuk transaksi baru

Date Handling

⚠️ Penting: MySQL DATE values harus diperlakukan sebagai local date.

Jangan gunakan:

• new Date('YYYY-MM-DD') (akan di-parse sebagai UTC)
• toISOString().slice(0, 10) (bisa bergeser 1 hari)

Gunakan:

1
// Backend: preserve local calendar parts
2
const [year, month, day] = dateString.split('-');
3

4
// Frontend: parse to local Date
5
new Date(year, month - 1, day);

File Upload Pattern

1
Frontend (multipart/form-data)
2
  │
3
  ▼
4
multer middleware (disk storage)
5
  │
6
  ▼
7
node_backend/upload/<category>/

Kategori upload: doc-data-truck, doc-data-chasis, doc-supir

3. Development Setup

Prerequisites

Langkah 1: Clone Repository

1
git clone <repo-url> transport_v1.04
2
cd transport_v1.04

Langkah 2: Setup Backend

Install Dependencies

1
cd node_backend
2
npm install

Konfigurasi Environment

1
Copy-Item .env.example .env

Edit node_backend/.env dan isi nilai yang sesuai:

1
# Database MySQL
2
DB_HOST=localhost
3
DB_PORT=3306
4
DB_USER=root
5
DB_PASS=your_password
6
DB_NAME=trucking
7

8
# Authentication
9
JWT_SECRET=your_random_secret_string
10

11
# Server
12
PORT=3000
13

14
# Wialon GPS (minta ke admin)
15
WIALON_BASE_URL=https://hst-api.wialon.com/wialon/ajax.html
16
WIALON_TOKEN=your_wialon_token
17
WIALON_LOGIN_FLAGS=13
18
WIALON_SESSION_TTL_MS=2700000
19
WIALON_TIMEOUT_MS=20000
20

21
# Geoapify Reverse Geocoding
22
GEOAPIFY_API_KEY=your_geoapify_api_key
23
GEOAPIFY_BASE_URL=https://api.geoapify.com/v1/geocode/reverse
24
GEOAPIFY_TIMEOUT_MS=6000
25

26
# Cache TTL
27
REVERSE_GEOCODE_CACHE_TTL_MS=86400000
28
WIALON_MONTHLY_DISTANCE_CACHE_TTL_MS=600000
29

30
# Geofence Tracking
31
GEOFENCE_TRACKING_INTERVAL_MS=60000
32
DEFAULT_FINISH_GEOFENCE_NAME=Sankyu

💡 Tip: Untuk development lokal tanpa GPS, cukup isi DB_*, JWT_SECRET, dan PORT. Fitur Wialon dan Geoapify akan gagal gracefully tanpa crash.

Setup Database

Perangkat Baru (Database Kosong):

1
npm run migrate

Perintah ini akan:

• Membuat database trucking jika belum ada
• Menjalankan semua migration files di db/migrations/

Database Existing (Sudah Ada Data):

1
npm run migrate:adopt-existing

Perintah ini akan:

• Melengkapi schema yang kurang (tabel tracking baru)
• Menandai semua migration sebagai sudah diterapkan
• Tidak menghapus data yang sudah ada

Jalankan Backend

1
npm start

Backend akan berjalan di http://localhost:3000.

Langkah 3: Setup Frontend

Install Dependencies

1
cd tailadmin-vuejs-1.0.0
2
npm install

Jalankan Frontend

1
npm run dev

Frontend akan berjalan di http://localhost:5173.

ℹ️ Info: Vite dev server otomatis mem-proxy request /api/* ke backend di port 3000. Pastikan backend sudah berjalan sebelum mengakses frontend.

Langkah 4: Setup Documentation (Opsional)

1
cd docs
2
npm install
3
npm run dev

Docs akan berjalan di http://localhost:5174.

Verifikasi Setup

Checklist untuk memastikan setup berhasil:

• Backend berjalan tanpa error di terminal
• http://localhost:3000/api/auth/login merespons (POST)
• Frontend bisa diakses di http://localhost:5173
• Login berhasil dengan kredensial yang valid
• Dashboard menampilkan data

Development Workflow

Buka 2 terminal terpisah:

Terminal 1 — Backend:

1
cd node_backend
2
npm start

Terminal 2 — Frontend:

1
cd tailadmin-vuejs-1.0.0
2
npm run dev

Hot Reload

• Frontend: Vite HMR otomatis reload saat file berubah
• Backend: Tidak ada hot reload bawaan. Restart manual dengan Ctrl+C lalu npm start

💡 Tip: Untuk auto-restart backend, install nodemon:

1
npm install -g nodemon
2
nodemon server.js

Akses dari Device Lain di LAN

Frontend Vite sudah dikonfigurasi listen di 0.0.0.0:5173. Akses dari device lain:

1
http://<IP-HOST>:5173

Build Check (Frontend)

Sebelum commit, pastikan build tidak error:

1
cd tailadmin-vuejs-1.0.0
2
npm run build-only

Linting & Formatting

1
cd tailadmin-vuejs-1.0.0
2
npm run lint       # ESLint auto-fix
3
npm run format     # Prettier format

4. Database & Migrations

Overview

Sistem menggunakan MySQL sebagai database utama dan MongoDB untuk fitur legacy. Schema MySQL dikelola menggunakan dbmate yang dibungkus dalam custom Node.js scripts.

Struktur File

1
node_backend/
2
├── db.js                  # MySQL connection pool
3
├── db/
4
│   ├── migrations/        # SQL migration files (timestamp-ordered)
5
│   │   ├── 20260401010000_baseline_from_trucking_dump.sql
6
│   │   ├── 20260401011000_add_tracking_foreign_keys.sql
7
│   │   ├── 20260401012000_add_area_finish_geofence.sql
8
│   │   ├── 20260424010000_add_truck_is_active.sql
9
│   │   └── 20260424011000_add_driver_is_active.sql
10
│   ├── schema.sql         # Generated schema snapshot
11
│   └── README.md          # Migration CLI documentation
12
├── scripts/
13
│   ├── run-dbmate.js      # dbmate wrapper
14
│   ├── build-baseline-migration.js
15
│   ├── adopt-existing-migrations.js
16
│   └── dump-schema.js
17
└── models/                # Mongoose models (MongoDB legacy)

Migration Commands

Workflow: Membuat Perubahan Schema Baru

1. Buat file migration:

   1
   cd node_backend
   2
   npm run migrate:new -- add_column_xyz

2. Edit file yang dihasilkan di db/migrations/:

   1
   -- migrate:up
   2
   ALTER TABLE truck ADD COLUMN xyz VARCHAR(100) NULL;
   3
   
   4
   -- migrate:down
   5
   ALTER TABLE truck DROP COLUMN xyz;

3. Jalankan migration:

   1
   npm run migrate

4. (Opsional) Update schema snapshot:

   1
   npm run migrate:dump

5. Commit file migration ke git

Naming Convention Migration

Format: YYYYMMDDHHMMSS_deskripsi_singkat.sql

Contoh:

• 20260401010000_baseline_from_trucking_dump.sql
• 20260424010000_add_truck_is_active.sql

Tabel Utama

truck

driver

sales_cost

Tabel transaksi utama yang menghubungkan truck, driver, customer, area, dan data biaya.

area

area_route_step

Menyimpan urutan langkah route per area dengan mapping ke Wialon geofence.

sales_cost_route_history

Menyimpan riwayat kunjungan geofence aktual per Sales Cost delivery.

schema_migrations

Tabel internal dbmate untuk tracking migration yang sudah diterapkan.

Connection Pool

1
const pool = mysql.createPool({
2
  host: process.env.DB_HOST,
3
  user: process.env.DB_USER,
4
  password: process.env.DB_PASS,
5
  database: process.env.DB_NAME || "trucking",
6
  waitForConnections: true,
7
  connectionLimit: 10,
8
  queueLimit: 0
9
});

Penggunaan di Route/Service

1
const pool = require("../db");
2

3
// Query biasa
4
const [rows] = await pool.query("SELECT * FROM truck WHERE is_active = 1");
5

6
// Query dengan parameter (prepared statement)
7
const [rows] = await pool.query("SELECT * FROM truck WHERE id = ?", [truckId]);
8

9
// Insert
10
const [result] = await pool.query(
11
  "INSERT INTO truck (no_polisi, jenis_kendaraan) VALUES (?, ?)",
12
  [noPolisi, jenisKendaraan]
13
);

⚠️ Keamanan: Selalu gunakan parameterized queries (? placeholder). Jangan pernah string concatenation untuk values.

MongoDB (Legacy)

MongoDB digunakan untuk beberapa fitur lama. Model didefinisikan di node_backend/models/.

Koneksi MongoDB opsional — jika MONGO_URI tidak diset di .env, server tetap berjalan tanpa MongoDB.

Backup & Restore

1
# Export schema
2
npm run migrate:dump
3

4
# Full backup
5
mysqldump -u root -p trucking > backup_trucking.sql
6

7
# Restore
8
mysql -u root -p trucking < backup_trucking.sql
9
npm run migrate:adopt-existing

Tips Database

1. Selalu buat migration untuk perubahan schema — jangan edit database langsung
2. Commit migration files ke git agar semua developer sinkron
3. Jangan edit migration yang sudah di-apply — buat migration baru untuk koreksi
4. Test migration down sebelum push untuk memastikan rollback berfungsi
5. Gunakan is_active flag untuk soft delete, bukan DELETE FROM
6. Date handling: Simpan sebagai DATE type, parse sebagai local date (bukan UTC)

5. API Reference

Semua endpoint menggunakan prefix /api/ dan berkomunikasi via JSON. Autentikasi menggunakan JWT Bearer token di header Authorization.

Authentication

Login

1
POST /api/auth/login
2
Content-Type: application/json
3

4
{
5
  "username": "admin",
6
  "password": "password123"
7
}

Response:

1
{
2
  "token": "eyJhbGciOiJIUzI1NiIs...",
3
  "user": { "id": 1, "username": "admin", "level": "admin" }
4
}

Get Current User

1
GET /api/auth/me
2
Authorization: Bearer <token>

Update Profile

1
PUT /api/auth/me
2
Authorization: Bearer <token>

Master Data

Trucks

Drivers

Customers

Areas

Warehouses

Subcontractors

Admins

Transactions

Sales Cost

ℹ️ Info: Sales Cost reject inactive trucks/drivers untuk create dan import. Edit existing record memperbolehkan keep current inactive truck/driver, tapi reject ganti ke inactive lain.

Repairs

Subcontractor Transactions

GPS & Monitoring (Wialon)

Truck Locations

1
GET /api/wialon/trucks/location
2
Authorization: Bearer <token>

Response per truck:

1
{
2
  "id": 1,
3
  "no_polisi": "B 1234 XYZ",
4
  "lat": -6.123456,
5
  "lon": 106.789012,
6
  "speed": 45,
7
  "gps_status": "moving",
8
  "driver_name": "Budi",
9
  "operational_status": "transaksi",
10
  "transaksi": {},
11
  "repair": null,
12
  "last_transaction": {}
13
}

⚠️ Catatan: Hanya mengembalikan trucks dengan is_active = 1.

Reverse Geocoding

1
GET /api/wialon/reverse-geocode?lat=-6.123&lon=106.789
2
Authorization: Bearer <token>

• Hanya request untuk 1 truck yang dipilih (bukan semua)
• Cached 24 jam di backend dan frontend localStorage

Monthly Mileage

1
GET /api/wialon/trucks/monthly-distance?month=2026-01
2
Authorization: Bearer <token>

Monthly Mileage Export

1
GET /api/wialon/trucks/monthly-distance/export?month=2026-01
2
Authorization: Bearer <token>

Returns: .xlsx file

Auto-Map Trucks to Wialon

1
POST /api/wialon/trucks/auto-map
2
Authorization: Bearer <token>

Geofence List

1
GET /api/wialon/geofences
2
Authorization: Bearer <token>

Other Endpoints

Error Responses

Semua error mengikuti format:

1
{
2
  "message": "Deskripsi error dalam Bahasa Indonesia"
3
}

Authentication Header

Semua endpoint (kecuali /api/auth/login) memerlukan:

1
Authorization: Bearer <jwt_token>

6. Deployment

Arsitektur Production

1
Internet
2
  │
3
  ▼
4
[Reverse Proxy / Domain]
5
  │
6
  ├── https://sankyu-transport.fun (Frontend)
7
  │     └── Static files (Vite build output)
8
  │
9
  └── https://sankyu-transport.fun/api/* (Backend)
10
        └── Node.js Express (port 3000)

Prerequisites Production

Opsional:

• MongoDB 6.0+ (jika fitur legacy digunakan)
• PM2 atau systemd (process manager)
• Nginx atau Caddy (reverse proxy)

Deploy Backend

1. Clone & Install

1
git clone <repo-url> /opt/transport
2
cd /opt/transport/node_backend
3
npm install --production

2. Konfigurasi Environment

Buat file .env dengan nilai production:

1
DB_HOST=localhost
2
DB_PORT=3306
3
DB_USER=transport_user
4
DB_PASS=<strong_password>
5
DB_NAME=trucking
6

7
JWT_SECRET=<random_64_char_string>
8
PORT=3000
9

10
WIALON_BASE_URL=https://hst-api.wialon.com/wialon/ajax.html
11
WIALON_TOKEN=<production_wialon_token>
12
WIALON_LOGIN_FLAGS=13
13
WIALON_SESSION_TTL_MS=2700000
14
WIALON_TIMEOUT_MS=20000
15

16
GEOAPIFY_API_KEY=<production_api_key>
17
GEOAPIFY_BASE_URL=https://api.geoapify.com/v1/geocode/reverse
18
GEOAPIFY_TIMEOUT_MS=6000
19

20
REVERSE_GEOCODE_CACHE_TTL_MS=86400000
21
WIALON_MONTHLY_DISTANCE_CACHE_TTL_MS=600000
22
GEOFENCE_TRACKING_INTERVAL_MS=60000
23
DEFAULT_FINISH_GEOFENCE_NAME=Sankyu

🔒 Keamanan:

• Gunakan password MySQL yang kuat dan user dedicated (bukan root)
• Generate JWT_SECRET yang random dan panjang
• Jangan commit .env ke git
• Batasi akses file .env hanya untuk user yang menjalankan service

3. Setup Database

1
npm run migrate

4. Jalankan dengan Process Manager

Menggunakan PM2:

1
npm install -g pm2
2

3
# Start
4
pm2 start server.js --name transport-backend
5

6
# Auto-start on reboot
7
pm2 startup
8
pm2 save
9

10
# Monitor
11
pm2 status
12
pm2 logs transport-backend

Menggunakan systemd:

1
[Unit]
2
Description=Transport Backend API
3
After=network.target mysql.service
4

5
[Service]
6
Type=simple
7
User=transport
8
WorkingDirectory=/opt/transport/node_backend
9
ExecStart=/usr/bin/node server.js
10
Restart=on-failure
11
RestartSec=10
12
Environment=NODE_ENV=production
13

14
[Install]
15
WantedBy=multi-user.target

1
sudo systemctl enable transport-backend
2
sudo systemctl start transport-backend

Deploy Frontend

1. Build

1
cd /opt/transport/tailadmin-vuejs-1.0.0
2
npm install
3
npm run build-only

Output build ada di folder dist/.

ℹ️ Info: npm run build-only skip type-check untuk build lebih cepat. Gunakan npm run build jika ingin type-check sekaligus.

2. Konfigurasi API URL

Pastikan .env.production mengarah ke URL backend yang benar:

1
VITE_API_URL=https://sankyu-transport.fun

3. Nginx Configuration

1
server {
2
    listen 80;
3
    server_name sankyu-transport.fun;
4

5
    # Frontend static files
6
    root /opt/transport/tailadmin-vuejs-1.0.0/dist;
7
    index index.html;
8

9
    # SPA fallback
10
    location / {
11
        try_files $uri $uri/ /index.html;
12
    }
13

14
    # Proxy API ke backend
15
    location /api/ {
16
        proxy_pass http://127.0.0.1:3000;
17
        proxy_http_version 1.1;
18
        proxy_set_header Upgrade $http_upgrade;
19
        proxy_set_header Connection 'upgrade';
20
        proxy_set_header Host $host;
21
        proxy_set_header X-Real-IP $remote_addr;
22
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
23
        proxy_set_header X-Forwarded-Proto $scheme;
24
        proxy_cache_bypass $http_upgrade;
25
    }
26

27
    # Proxy static uploads
28
    location /img/ {
29
        proxy_pass http://127.0.0.1:3000;
30
    }
31
    location /doc-data-truck/ {
32
        proxy_pass http://127.0.0.1:3000;
33
    }
34
    location /doc-data-chasis/ {
35
        proxy_pass http://127.0.0.1:3000;
36
    }
37
    location /doc-supir/ {
38
        proxy_pass http://127.0.0.1:3000;
39
    }
40
}

Alternatif: Development Server sebagai Production

Untuk deployment sederhana (internal network):

1
# Backend
2
cd node_backend && npm start
3

4
# Frontend
5
cd tailadmin-vuejs-1.0.0 && npm run dev -- --host 0.0.0.0

⚠️ Peringatan: Cara ini tidak direkomendasikan untuk production publik.

Update / Redeploy

1
# Pull changes
2
cd /opt/transport
3
git pull origin main
4

5
# Update backend
6
cd node_backend
7
npm install
8
npm run migrate
9
pm2 restart transport-backend
10

11
# Update frontend
12
cd ../tailadmin-vuejs-1.0.0
13
npm install
14
npm run build-only

SSL/HTTPS

1
sudo apt install certbot python3-certbot-nginx
2
sudo certbot --nginx -d sankyu-transport.fun

Monitoring Production

1
# Logs (PM2)
2
pm2 logs transport-backend
3

4
# Logs (systemd)
5
journalctl -u transport-backend -f
6

7
# Health check
8
curl http://localhost:3000/api/auth/me
9
# Expect: 401 = server berjalan

Database Backup (Cron)

1
0 2 * * * transport mysqldump -u transport_user -p'password' trucking > /backup/trucking_$(date +\%Y\%m\%d).sql

Checklist Deployment

• .env production sudah dikonfigurasi dengan benar
• Database migration sudah dijalankan
• Frontend build berhasil tanpa error
• Backend berjalan dan merespons di port 3000
• Reverse proxy (Nginx) dikonfigurasi
• SSL certificate aktif
• Process manager (PM2/systemd) dikonfigurasi untuk auto-restart
• Backup database terjadwal
• Firewall hanya expose port 80/443

7. Troubleshooting

Backend Issues

Server Tidak Bisa Start

Cek port yang dipakai:

1
netstat -ano | findstr :3000
2
taskkill /PID <pid> /F

API Return 401 Unauthorized

Penyebab umum:

1. Token expired — login ulang
2. Token tidak dikirim — cek header Authorization: Bearer <token>
3. JWT_SECRET berbeda antara saat generate dan verify

API Return 403 Forbidden

User dengan role cs mencoba akses endpoint yang tidak diizinkan. Hanya endpoint berikut yang bisa diakses CS:

• GET /api/schedule-pengiriman
• GET /api/auth/me
• PUT /api/auth/me

MySQL Connection Pool Exhausted

Gejala: Request timeout atau Too many connections

Solusi:

1. Pastikan tidak ada query yang hang
2. Cek connectionLimit di db.js (default: 10)
3. Pastikan setiap query menggunakan pool (bukan manual connection)

Migration Gagal

Frontend Issues

Halaman Blank / White Screen

1. Buka browser DevTools (F12) → Console
2. Cek apakah ada JavaScript error
3. Cek Network tab — apakah API calls gagal

Penyebab umum:

• Backend belum berjalan → start backend dulu
• CORS error → seharusnya tidak terjadi dengan Vite proxy
• Build error → jalankan npm run build-only untuk cek

API Calls Gagal (Network Error)

Development:

• Pastikan backend berjalan di port 3000
• Vite proxy otomatis forward /api/* ke http://127.0.0.1:3000

Production:

• Pastikan VITE_API_URL di .env.production benar
• Cek Nginx proxy configuration

CSS / UI Tidak Update

• Hard refresh: Ctrl + Shift + R
• Clear browser cache
• Leaflet cluster icons bisa ter-cache

TypeScript Build Error

Jika ada TS error di file yang tidak terkait:

• Gunakan npm run build-only (skip type-check)
• File legacy .js di src/services/ mungkin punya implicit any — known issue

Leaflet Map Tidak Muncul

1. Container div tidak punya height → pastikan parent punya fixed height
2. Leaflet CSS tidak ter-import → cek import di component
3. Tile server unreachable → cek koneksi internet

GPS / Wialon Issues

Semua Truck Muncul Offline

1. Restart backend
2. Cek log backend untuk error login Wialon
3. Verifikasi WIALON_TOKEN di .env belum expired
4. Cek apakah Wialon API accessible dari server

Reverse Geocode Tidak Menampilkan Alamat

Penyebab:

1. GEOAPIFY_API_KEY tidak valid atau quota habis
2. Koordinat tidak valid (0,0 atau null)

Solusi:

• UI fallback ke koordinat mentah
• Cek Geoapify dashboard untuk usage/quota
• Clear localStorage jika ingin force re-fetch:

  1
  Object.keys(localStorage)
  2
    .filter(k => k.startsWith('geocode_'))
  3
    .forEach(k => localStorage.removeItem(k));

Geofence History Tetap “Pending”

Penyebab: Wialon resource/get_zones_by_unit mengembalikan nested payload.

Langkah debug:

1. Cek raw Wialon membership result untuk truck/unit bermasalah
2. Verifikasi parsed membership map dari fetchUnitsInZonesByResource
3. Pastikan normalizeZoneMembershipPayload handle nested format: {resourceId: {zoneId: [unitIds]}}
4. Cek apakah truck benar-benar di dalam polygon geofence di Wialon

Monthly Mileage “Invalid GPS Mapping”

Penyebab: wialon_unit_id di database tidak cocok dengan unit di Wialon.

Solusi:

1. Cek mapping di Master Truck
2. Jalankan auto-map ulang: POST /api/wialon/trucks/auto-map
3. Atau update wialon_unit_id manual

Database Issues

Tanggal Bergeser 1 Hari

Penyebab: MySQL DATE di-parse melalui UTC conversion.

Solusi:

• Backend: Jangan gunakan new Date(dateString).toISOString().slice(0,10)
• Frontend: Parse dengan new Date(year, month - 1, day) bukan new Date('YYYY-MM-DD')

Data Tidak Konsisten Setelah Import

1. Cek log import di backend console
2. Verifikasi format Excel sesuai template
3. Pastikan referensi (truck_id, driver_id) valid dan active
4. Import akan reject inactive trucks/drivers

Network & Infrastructure

CORS Error

• Development: Pastikan request ke /api/* (bukan full URL ke port 3000)
• Production: Pastikan Nginx proxy_pass dikonfigurasi untuk semua path

WebSocket / HMR Error (Development)

• Pastikan port 5173 tidak diblokir firewall
• Untuk development lokal, comment out hmr config di vite.config.ts

PowerShell Execution Policy

1
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Performance Issues

Backend Response Lambat

1. Cek slow queries: SHOW PROCESSLIST;
2. Tambahkan index untuk kolom yang sering di-query/filter
3. Cek Wialon API timeout (increase WIALON_TIMEOUT_MS)
4. Cek connection pool usage

Frontend Load Lambat

1. Jalankan production build (bukan dev mode)
2. Cek bundle size via npm run build-only
3. Pastikan gambar/assets sudah optimized
4. Gunakan browser DevTools → Performance tab

8. Coding Conventions

Backend (Node.js / Express)

Bahasa & Module System

• JavaScript (bukan TypeScript)
• CommonJS: require() / module.exports
• Tidak menggunakan ES Modules di backend

Struktur File Route

1
const express = require("express");
2
const router = express.Router();
3
const pool = require("../db");
4
const { authenticateToken } = require("../middleware/auth");
5

6
router.use(authenticateToken);
7

8
router.get("/", async (req, res) => {
9
  try {
10
    const [rows] = await pool.query("SELECT * FROM table_name");
11
    res.json(rows);
12
  } catch (error) {
13
    console.error("Error:", error);
14
    res.status(500).json({ message: "Gagal mengambil data" });
15
  }
16
});
17

18
module.exports = router;

Naming Conventions (Backend)

Database Query Pattern

1
// ✅ Parameterized query (aman dari SQL injection)
2
const [rows] = await pool.query(
3
  "SELECT * FROM truck WHERE id = ? AND is_active = ?",
4
  [id, 1]
5
);
6

7
// ❌ String concatenation (JANGAN)
8
const [rows] = await pool.query(
9
  `SELECT * FROM truck WHERE id = ${id}`
10
);

Error Handling Pattern

1
router.post("/", async (req, res) => {
2
  try {
3
    // ... logic
4
    res.status(201).json({ message: "Berhasil", data: result });
5
  } catch (error) {
6
    console.error("Deskripsi context:", error);
7
    res.status(500).json({ message: "Pesan error user-friendly" });
8
  }
9
});

Soft Delete Pattern

1
// Deactivate
2
router.patch("/:id/status", async (req, res) => {
3
  const { is_active } = req.body;
4
  await pool.query("UPDATE truck SET is_active = ? WHERE id = ?", [is_active, id]);
5
});
6

7
// Default query: hanya active
8
const [rows] = await pool.query("SELECT * FROM truck WHERE is_active = 1");
9

10
// Admin view: semua
11
const [rows] = await pool.query("SELECT * FROM truck");

Date Handling (Backend)

1
// ✅ Preserve local date parts
2
const formatDate = (dateValue) => {
3
  if (!dateValue) return null;
4
  const d = new Date(dateValue);
5
  const year = d.getFullYear();
6
  const month = String(d.getMonth() + 1).padStart(2, '0');
7
  const day = String(d.getDate()).padStart(2, '0');
8
  return `${year}-${month}-${day}`;
9
};
10

11
// ❌ Jangan gunakan (bisa geser 1 hari karena UTC)
12
const bad = new Date(dateValue).toISOString().slice(0, 10);

Frontend (Vue 3 / TypeScript)

Bahasa & Style

• TypeScript untuk file baru (.ts, .vue dengan <script setup lang="ts">)
• File legacy boleh tetap .js sampai ada kebutuhan refactor
• Vue 3 Composition API dengan <script setup>
• Tailwind CSS utility classes

Struktur Component (Vue SFC)

1
<script setup lang="ts">
2
import { ref, onMounted } from 'vue'
3
import { API_BASE } from '@/config/api'
4

5
const props = defineProps<{
6
  truckId: number
7
}>()
8

9
const loading = ref(false)
10
const data = ref<TruckData | null>(null)
11

12
const fetchData = async () => {
13
  loading.value = true
14
  try {
15
    const res = await fetch(`${API_BASE}/trucks/${props.truckId}`)
16
    data.value = await res.json()
17
  } finally {
18
    loading.value = false
19
  }
20
}
21

22
onMounted(() => {
23
  fetchData()
24
})
25
</script>
26

27
<template>
28
  <div class="p-4">
29
    <!-- template -->
30
  </div>
31
</template>

Naming Conventions (Frontend)

Service Pattern

1
import { API_BASE } from '@/config/api'
2

3
export const getTruckLocations = async () => {
4
  const token = localStorage.getItem('token')
5
  const res = await fetch(`${API_BASE}/wialon/trucks/location`, {
6
    headers: { Authorization: `Bearer ${token}` }
7
  })
8
  if (!res.ok) throw new Error('Failed to fetch')
9
  return res.json()
10
}

Path Alias

Gunakan @/ untuk import dari src/:

1
import { API_BASE } from '@/config/api'
2
import TruckCard from '@/components/TruckCard.vue'

Tailwind CSS Guidelines

1
<!-- ✅ Tailwind utilities -->
2
<div class="flex items-center gap-4 p-4 rounded-lg bg-white shadow-sm">
3

4
<!-- ❌ Hindari custom class tanpa alasan kuat -->
5
<div class="truck-card-wrapper">

Git Conventions

Commit Messages

Format: <type>: <description>

Contoh:

1
feat: add monthly mileage export to Excel
2
fix: date shift issue on Sales Cost edit
3
refactor: extract geofence tracking to service

Branch Naming

1
feature/add-truck-mileage
2
fix/date-shift-sales-cost
3
refactor/wialon-service-cleanup

File Organization Rules

1. Satu route file per domain — jangan gabung multiple domains
2. Business logic di services — route hanya handle HTTP
3. Satu service file per external integration — e.g., wialonService.js
4. Views by domain — views/Master/, views/Transaksi/
5. Shared components di components/ — bukan di dalam views/
6. Migration files tidak boleh diedit setelah di-apply — buat migration baru

Bahasa

Dokumen ini di-generate dari: docs/developer/ folder
Terakhir diperbarui: Mei 2026

Thanks for reading!

Transport Project Doc

Tue May 26 2026

3377 words · 27 minutes

Documentation No tags assigned

---

© Rifky Awalul Huda | CC BY-NC-SA 4.0

Share

Share this article

X (Twitter) Telegram WhatsApp LinkedIn Reddit Facebook Email Copy Link

Close

Close