# Development Guide

> **Terakhir Diperbarui:** 2026-06-29

---

## Model Kerja

Pengembangan dilakukan **remote** — kode di-edit di laptop Windows, build & run di server `10.100.1.24`. Tidak ada Docker lokal.

```
Laptop (edit kode) → deploy script → Server 10.100.1.24 (build + run)
```

---

## Setup Lokal (geonet-console)

### Prerequisites

- PowerShell 5.1+
- Git
- SSH key terdaftar di server (lihat `readme.txt`)

### Workflow Development

```powershell
# 1. Edit kode di laptop
# (VS Code → geonet-console/)

# 2. Deploy ke server untuk testing
.\scripts\deploy-geonet-console.ps1

# 3. Cek log untuk debug
ssh -m hmac-sha1 root@10.100.1.24 -p 22 "docker logs geonet-console --tail 50"
```

### Setup SSH Key (Sekali)

```powershell
ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\id_ed25519" -C "dev@$(hostname)" -N ""

# Daftarkan ke reverse proxy
type "$env:USERPROFILE\.ssh\id_ed25519.pub" | ssh -m hmac-sha1 root@10.100.1.24 -p 22 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
```

---

## Struktur Kode — geonet-console

```
geonet-console/
├── app/
│   ├── Http/Controllers/Api/V1/   — API controllers
│   ├── Models/                    — Eloquent models
│   ├── Services/                  — Business logic
│   └── Support/                   — ApiActor, helpers
├── config/
│   ├── database.php               — Koneksi DB (pgsql, audit, mssql, project_search)
│   └── filesystems.php            — Disk 'oss' (QNAP OSS S3)
├── database/migrations/           — Migration files
├── routes/api.php                 — Semua route API v1
├── docapi/                        — Dokumentasi API (WAJIB BACA sebelum tambah endpoint)
├── docker/entrypoint.sh           — Startup: migrate, cache, OAuth keys
├── compose.yaml                   — Docker Compose
└── .env.example                   — Template env vars
```

---

## Coding Standard (Laravel)

- **Service Layer**: Logic bisnis di `app/Services/`, bukan di controller
- **Controller tipis**: Controller hanya validasi input → call service → return response
- **ApiActor**: Gunakan `ApiActor` (dari `ApiAuthService`) untuk identitas user, bukan `Auth::user()`
- **Audit log**: Setiap aksi write wajib log ke `AuditLogService`
- **Response format**: Gunakan format standar — lihat `docapi/common-response.md`
- **Error handling**: Gunakan error code standar — lihat `docapi/common-error.md`

---

## Commit Convention

```
<type>: <deskripsi singkat>
```

| Type | Kapan |
|------|-------|
| `feat` | Fitur baru |
| `fix` | Bug fix |
| `api` | Perubahan API endpoint |
| `db` | Migration atau perubahan DB |
| `infra` | Nginx, Docker, deploy scripts |
| `docs` | Dokumentasi |
| `chore` | Config, deps, cleanup |

---

## Menambah Endpoint API Baru

1. Buat controller di `app/Http/Controllers/Api/V1/`
2. Buat service di `app/Services/`
3. Daftarkan route di `routes/api.php`
4. Tambah middleware auth + audit log
5. **Update `geonet-console/docapi/index.md`**
6. Buat file dokumentasi di `geonet-console/docapi/services/<service>/`
7. Update `docs/api/` jika endpoint termasuk scope publik

---

## Environment di Server (Edit Langsung)

```bash
ssh -m hmac-sha1 root@10.100.1.24 -p 22
nano /opt/stacks/geonet-console/.env
docker compose -f /opt/stacks/geonet-console/compose.yaml restart geonet-console
```

---

## Debugging

```bash
# Log real-time
ssh -m hmac-sha1 root@10.100.1.24 -p 22 "docker logs geonet-console -f"

# Laravel log
ssh -m hmac-sha1 root@10.100.1.24 -p 22 "docker exec geonet-console tail -f storage/logs/laravel.log"

# PHP artisan tinker
ssh -m hmac-sha1 root@10.100.1.24 -p 22 "docker exec -it geonet-console php artisan tinker"

# Cek migration status
ssh -m hmac-sha1 root@10.100.1.24 -p 22 "docker exec geonet-console php artisan migrate:status"
```

---

## Branch Strategy

| Branch | Tujuan |
|--------|--------|
| `main` / `master` | Production — push = deploy manual |
| `dev` | Development — testing sebelum ke main |
| `feature/<name>` | Fitur baru |
| `fix/<name>` | Bug fix |