API Retribusi - Slim Framework 4

Sistem API Retribusi berbasis Slim Framework 4 dengan arsitektur modular untuk infrastruktur pemerintah.

🚀 Fitur

• Modular Architecture - Struktur code yang terorganisir dan mudah di-scale
• JWT Authentication - Secure authentication dengan role-based access
• CORS Support - Cross-Origin Resource Sharing untuk akses dari browser
• CRUD Master Data - Locations, Gates, Tariffs dengan audit logging
• Realtime Dashboard - SSE (Server-Sent Events) untuk update real-time
• Data Aggregation - Daily & Hourly summary untuk reporting
• API Key Protection - X-API-KEY untuk ingest endpoint (mesin YOLO)

📋 Requirements

• PHP >= 8.2
• MySQL/MariaDB
• Composer
• aaPanel (recommended) atau web server dengan PHP-FPM

🔧 Installation

Development

1. Clone repository:

git clone https://git.btekno.cloud/kangmin/api-btekno.git
cd api-btekno

2. Install dependencies:

composer install --no-dev --optimize-autoloader

3. Setup environment:

cp .env.example .env
# Edit .env dengan konfigurasi database dan JWT

4. Apply migrations:

# Pastikan berada di folder project root
cd /path/to/api-btekno

# Apply migrations
mysql -u your_user -p your_database < ./migrations/001_create_audit_logs.sql
mysql -u your_user -p your_database < ./migrations/002_create_hourly_summary.sql
mysql -u your_user -p your_database < ./migrations/003_create_realtime_events.sql

Production Deployment (aaPanel)

PENTING: Vendor folder TIDAK di-commit ke git. Harus di-install di server!

1. Clone atau pull repository:

cd /www/wwwroot/api.btekno.cloud/api
git pull origin main

2. WAJIB: Install dependencies (ini yang menyebabkan error jika di-skip):

composer install --no-dev --optimize-autoloader

3. Setup environment:

cp .env.example .env
nano .env  # Edit dengan konfigurasi production

4. Apply migrations (jika belum):

# Pastikan berada di folder project root
cd /www/wwwroot/api.btekno.cloud/api

# Apply migrations dengan path relatif
mysql -u sql_retribusi -p sql_retribusi < ./migrations/001_create_audit_logs.sql
mysql -u sql_retribusi -p sql_retribusi < ./migrations/002_create_hourly_summary.sql
mysql -u sql_retribusi -p sql_retribusi < ./migrations/003_create_realtime_events.sql

5. Setup web server (aaPanel):

   • DocumentRoot: /www/wwwroot/api.btekno.cloud/api/public
   • PHP Version: 8.2 atau 8.3
   • Enable rewrite rules

6. Set permissions:

chown -R www:www /www/wwwroot/api.btekno.cloud/api
chmod -R 755 /www/wwwroot/api.btekno.cloud/api

Troubleshooting

Error: vendor/autoload.php not found

• Solusi: Jalankan composer install --no-dev --optimize-autoloader di server
• Vendor folder tidak di-commit ke git, harus di-install manual di setiap environment

📁 Struktur Project

api-btekno/
├── public/              # Entry point (web server root)
├── src/
│   ├── Bootstrap/      # App initialization
│   ├── Config/          # Configuration
│   ├── Middleware/      # Auth & security
│   ├── Modules/         # Business modules
│   └── Support/         # Utilities
├── bin/                 # CLI scripts
├── migrations/          # Database migrations
└── vendor/              # Dependencies

🔐 Environment Variables

Edit .env file:

# App
APP_ENV=production
APP_DEBUG=false

# Database
DB_HOST=localhost
DB_NAME=sql_retribusi
DB_USER=sql_retribusi
DB_PASS=your_password

# JWT
JWT_SECRET=your-secret-key-here
JWT_TTL_SECONDS=3600
JWT_ISSUER=api-btekno

# API Key
RETRIBUSI_API_KEY=your-api-key-here

# CORS (Cross-Origin Resource Sharing)
# Set '*' untuk allow semua origin (development)
# Atau list origin yang diizinkan dipisah koma: http://localhost:3000,https://app.example.com
CORS_ALLOWED_ORIGINS=*
CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-API-KEY,Accept,Origin
CORS_ALLOW_CREDENTIALS=true

📡 API Endpoints

Authentication

• POST /auth/v1/login - Login & get JWT token

Ingest (Mesin)

• POST /retribusi/v1/ingest - Ingest event data (X-API-KEY required)

Frontend CRUD

• GET /retribusi/v1/frontend/locations - List locations
• POST /retribusi/v1/frontend/locations - Create location (operator+)
• PUT /retribusi/v1/frontend/locations/{code} - Update location (operator+)
• DELETE /retribusi/v1/frontend/locations/{code} - Delete location (admin)

Similar endpoints untuk gates dan tariffs.

Summary & Dashboard

• GET /retribusi/v1/summary/daily - Daily summary
• GET /retribusi/v1/summary/hourly - Hourly summary
• GET /retribusi/v1/dashboard/daily - Daily chart data
• GET /retribusi/v1/dashboard/by-category - Category chart data
• GET /retribusi/v1/dashboard/summary - Summary statistics

Realtime

• GET /retribusi/v1/realtime/stream - SSE stream (real-time events)
• GET /retribusi/v1/realtime/snapshot - Snapshot data

🛠️ CLI Tools

Daily Summary

php bin/daily_summary.php [date]
# Default: yesterday

Hourly Summary

php bin/hourly_summary.php [date]
# Default: yesterday

Cron Job Setup

# Daily summary (run at 1 AM)
0 1 * * * cd /path/to/api-btekno && php bin/daily_summary.php

# Hourly summary (run at 1 AM)
0 1 * * * cd /path/to/api-btekno && php bin/hourly_summary.php

🔒 Security

• JWT authentication untuk semua frontend endpoints
• X-API-KEY untuk ingest endpoint
• Role-based access control (viewer/operator/admin)
• Prepared statements (SQL injection prevention)
• Input validation
• Audit logging untuk semua perubahan data

📊 Database Schema

• users - User authentication
• locations - Master lokasi
• gates - Master pintu masuk/keluar
• tariffs - Master tarif
• entry_events - Raw event data
• daily_summary - Rekap harian
• hourly_summary - Rekap per jam
• realtime_events - Ring buffer untuk SSE
• audit_logs - Audit trail

🧪 Testing

Test endpoint dengan curl atau Postman:

# Health check
curl http://localhost/health

# Login
curl -X POST http://localhost/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

# Get locations (with JWT)
curl http://localhost/retribusi/v1/frontend/locations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

📝 Coding Standards

• declare(strict_types=1) di semua file
• Type hints lengkap
• PSR-4 autoloading
• Controller tipis, logic di service
• No ORM (pure PDO)
• Response JSON konsisten

🚀 Deployment

1. Set production environment di .env
2. Run composer install --no-dev --optimize-autoloader
3. Apply semua migrations
4. Setup cron jobs untuk summary
5. Configure web server (Apache/Nginx)
6. Enable HTTPS
7. Monitor logs dan performance

📄 License

Proprietary

👥 Author

BTekno Development Team