# Sistem e-Sijil Acara Larian 2026

Sistem web untuk semakan dan muat turun e-Sijil penyertaan acara larian secara dalam talian tanpa pendaftaran peserta.

**Acara:** Acara Larian Sempena Majlis Peluncuran Bulan Kebangsaan dan Kibar Jalur Gemilang 2026

**Teknologi utama:** Laravel 11, PHP 8.2+, MySQL/MariaDB, Blade dan Bootstrap 5.

## Ciri Utama

- Halaman awam carian sijil menggunakan nama peserta (tanpa login)
- Penjanaan PDF sijil on-demand dengan template boleh konfigurasi
- Import peserta melalui Excel/CSV
- Dashboard pentadbir dengan graf Chart.js
- Laporan dan eksport Excel/PDF
- Perlindungan data peribadi (enkripsi nombor pengenalan dan rate limiting)
- Peranan Super Admin dan Admin

## Keperluan Server

- PHP 8.2 atau lebih baharu (disyorkan 8.3)
- MySQL 8 / MariaDB 10.6+ atau SQLite (development)
- Composer 2.x
- Node.js 18+ & NPM (untuk build asset)
- Web server: Apache/Nginx (document root ke `public/`)

### PHP Extensions Diperlukan

BCMath, Ctype, Fileinfo, JSON, Mbstring, OpenSSL, PDO, PDO MySQL, Tokenizer, XML, GD, Zip, Intl

## Pemasangan

### 1. Clone / Salin Projek

```bash
git clone <repo-url> esijil
cd esijil
```

### 2. Install Dependency Composer

```bash
composer install
```

### 3. Konfigurasi `.env`

```bash
cp .env.example .env
php artisan key:generate
```

Edit `.env`:

```env
APP_NAME="e-Sijil Acara Larian 2026"
APP_URL=http://esijil.test

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=esijil
DB_USERNAME=root
DB_PASSWORD=

ADMIN_NAME="Super Administrator"
ADMIN_EMAIL="admin@example.com"
ADMIN_PASSWORD="ChangeThisPassword123!"
```

### 4. Cipta Database

```sql
CREATE DATABASE esijil CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 5. Migration & Seeder

```bash
php artisan migrate --seed
```

### 6. Storage Link

```bash
php artisan storage:link
```

### 7. Install & Build Asset NPM

```bash
npm install
npm run build
```

### 8. Permission Folder (Linux/VPS)

```bash
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

## Akaun Demo Development

| Peranan | E-mel | Kata Laluan |
|---------|-------|-------------|
| Super Admin | admin@example.com | ChangeThisPassword123! |
| Admin | admin@esijil.test | AdminPassword123! |

## URL Sistem

| Halaman | URL |
|---------|-----|
| Semakan Awam | `/e-sijil` |
| Login Pentadbir | `/admin/login` |
| Dashboard | `/admin/dashboard` |

## Peserta Contoh (Selepas Seeder)

| Nama | No. KP | No. Peserta | Kategori |
|------|--------|-------------|----------|
| AHMAD BIN ABDULLAH | 900101101234 | A001 | 5KM |
| NURUL AIN BINTI ALI | 920202025678 | A002 | 10KM |

## Import Peserta

1. Log masuk ke `/admin/login`
2. Pergi ke **Import Peserta**
3. Muat turun template Excel
4. Isi data mengikut format:

| nama_peserta | no_kp | no_peserta | kategori |
|--------------|-------|------------|----------|
| AHMAD BIN ABDULLAH | 900101101234 | A001 | 5KM |

5. Pilih mod pendua: abaikan / kemas kini / batalkan
6. Muat naik dan import

## Upload Template Sijil

1. Pergi ke **Template Sijil** > Muat Naik
2. Muat naik fail PNG/JPG/PDF
3. Tetapkan kedudukan nama (X, Y), saiz font, warna, penjajaran
4. Aktifkan template
5. Gunakan **Preview Sijil** untuk ujian

## Struktur Seni Bina

```
app/
├── Enums/           # UserRole, CertificateStatus, DownloadType, ImportStatus
├── Exports/         # Excel export classes
├── Http/
│   ├── Controllers/
│   │   ├── Admin/   # Dashboard, Participants, Reports, etc.
│   │   └── Public/  # Certificate search & download
│   ├── Middleware/  # EnsureUserIsActive, EnsureSuperAdmin
│   └── Requests/    # Form validation
├── Imports/         # Excel import
├── Models/          # Eloquent models
├── Repositories/    # ParticipantRepository
└── Services/        # Business logic
    ├── IcNumberService
    ├── ParticipantImportService
    ├── CertificateGeneratorService
    ├── CertificateDownloadService
    ├── CertificateTemplateService
    ├── ReportService
    ├── ActivityLogService
    └── SettingService
```

## Keselamatan

- Rate limit: 10 carian/minit, 5 muat turun/minit per IP
- CAPTCHA selepas 5 carian gagal berturut-turut
- IC disimpan dengan enkripsi Laravel + hash HMAC untuk carian
- IC tidak dipaparkan penuh (`900101-**-****`)
- CSRF protection pada semua borang POST
- Fail import & template disimpan di storage private

## Ujian Automatik

```bash
php artisan test
```

## Cache (Production)

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## Queue (Opsional)

```env
QUEUE_CONNECTION=database
```

```bash
php artisan queue:work
```

Cron job:
```
* * * * * cd /path/to/esijil && php artisan schedule:run >> /dev/null 2>&1
```

## Backup Database

Super Admin boleh muat turun backup melalui **Tetapan Sistem** > Backup Database.

Manual:
```bash
php artisan db:backup  # atau mysqldump
mysqldump -u root -p esijil > backup.sql
```

## Deployment cPanel

1. Upload fail ke `public_html/esijil` (atau subdomain folder)
2. Tetapkan **Document Root** ke folder `public`
3. Pilih PHP 8.2+ dalam cPanel MultiPHP
4. Aktifkan extension PHP yang diperlukan
5. Jalankan `composer install --no-dev --optimize-autoloader` via SSH/Terminal
6. Build asset secara local: `npm run build`, kemudian upload folder `public/build`
7. Salin `.env.example` ke `.env`, konfigurasi database
8. `php artisan key:generate`
9. `php artisan migrate --seed --force`
10. `php artisan storage:link`
11. Set permission `storage/` dan `bootstrap/cache/` ke 775
12. Cache config untuk production

### `.htaccess` (sudah disediakan dalam `public/`)

Pastikan `mod_rewrite` diaktifkan.

## Deployment VPS

1. Install PHP 8.3, MySQL, Nginx/Apache, Composer, Node.js
2. Clone projek ke `/var/www/esijil`
3. Ikuti langkah pemasangan di atas
4. Konfigurasi Nginx:

```nginx
server {
    listen 80;
    server_name esijil.domain.gov.my;
    root /var/www/esijil/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

5. Pasang SSL dengan Certbot
6. Setup supervisor untuk queue worker jika diperlukan

## Senarai Route

```bash
php artisan route:list --except-vendor
```

## Lesen

Hak Cipta Terpelihara © 2026
