267 lines
6.8 KiB
Markdown
267 lines
6.8 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone https://git.btekno.cloud/kangmin/api-btekno.git
|
|
cd api-btekno
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
composer install --no-dev --optimize-autoloader
|
|
```
|
|
|
|
3. Setup environment:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env dengan konfigurasi database dan JWT
|
|
```
|
|
|
|
4. Apply migrations:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
cd /www/wwwroot/api.btekno.cloud/api
|
|
git pull origin main
|
|
```
|
|
|
|
2. **WAJIB: Install dependencies** (ini yang menyebabkan error jika di-skip):
|
|
```bash
|
|
composer install --no-dev --optimize-autoloader
|
|
```
|
|
|
|
3. Setup environment:
|
|
```bash
|
|
cp .env.example .env
|
|
nano .env # Edit dengan konfigurasi production
|
|
```
|
|
|
|
4. Apply migrations (jika belum):
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
# 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
|
|
```bash
|
|
php bin/daily_summary.php [date]
|
|
# Default: yesterday
|
|
```
|
|
|
|
### Hourly Summary
|
|
```bash
|
|
php bin/hourly_summary.php [date]
|
|
# Default: yesterday
|
|
```
|
|
|
|
### Cron Job Setup
|
|
```cron
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|