Initial commit: Slim Framework 4 API Retribusi dengan modular architecture
This commit is contained in:
mwpn
207
README.md
Normal file
207
README.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# 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
|
||||
- **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
|
||||
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
5. Setup web server:
|
||||
- DocumentRoot: `public/`
|
||||
- PHP 8.2+
|
||||
- Enable mod_rewrite (Apache) atau nginx config
|
||||
|
||||
## 📁 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
|
||||
```
|
||||
|
||||
## 📡 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
|
||||
|
||||
Reference in New Issue
Block a user