api-btekno/README.md

# 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

### 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
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
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
```

## 📡 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