kangmin/api-btekno

Fork 0

Files

mwpn 1aa462d9da Fix hourly summary: default to today for realtime updates, add hour parameter for efficient updates

2025-12-17 17:41:27 +07:00

7.5 KiB

Raw Blame History

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

Clone repository:

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

Install dependencies:

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

Setup environment:

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

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!

Clone atau pull repository:

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

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

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

Setup environment:

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

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

Setup web server (aaPanel):
- DocumentRoot: /www/wwwroot/api.btekno.cloud/api/public
- PHP Version: 8.2 atau 8.3
- Enable rewrite rules
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

# Update hari ini (default, untuk realtime)
php bin/hourly_summary.php

# Rekap kemarin
php bin/hourly_summary.php yesterday

# Rekap tanggal tertentu
php bin/hourly_summary.php 2025-01-01

# Update jam tertentu saja (untuk efisiensi)
php bin/hourly_summary.php today 14  # Update jam 14 hari ini
php bin/hourly_summary.php 2025-01-01 13  # Update jam 13 tanggal tertentu

Cron Job Setup

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

# Hourly summary - REALTIME (run every hour, update jam yang baru saja berlalu)
# Contoh: jam 2:00 update jam 1:00, jam 3:00 update jam 2:00
0 * * * * cd /path/to/api-btekno && php bin/hourly_summary.php today $(date -d '1 hour ago' +\%H)

# Hourly summary - FINAL RECAP (run at 1 AM, rekap semua jam kemarin)
# Opsional: untuk memastikan semua jam kemarin sudah ter-rekap
0 1 * * * cd /path/to/api-btekno && php bin/hourly_summary.php yesterday

🔒 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

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

📄 License

Proprietary

👥 Author

BTekno Development Team

7.5 KiB Raw Blame History