# Development Guide

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

---

## Setup Lokal — FastAPI Collector

### Prerequisites

- Python 3.11+
- PostgreSQL 12+ (atau koneksi ke 10.100.1.25)

### Install & Run

```bash
cd GeoNetAgent/collector
python -m venv .venv
.\.venv\Scripts\activate   # Windows
# atau: source .venv/bin/activate   # Linux/Mac

pip install -e ".[dev]"

cp ../.env.example .env
# Edit .env: isi DATABASE_URL dan AGENT_BEARER_TOKEN

uvicorn app.main:app --reload --port 8000
```

API tersedia di `http://localhost:8000`
Swagger UI: `http://localhost:8000/docs`
UI CMDB: `http://localhost:8000/ui/`

---

## Setup Lokal — PowerShell Agent

Agent berjalan di endpoint Windows. Untuk pengembangan:

```powershell
# Jalankan collect lokal (tanpa kirim ke server)
cd GeoNetAgent\agent
.\Collect-GeoNetReport.ps1

# Kirim laporan ke server dev
.\Send-GeoNetReport.ps1 -CollectorUrl "http://localhost:8000/api/v1/agent/report" -Token "dev-agent-token-change-me"
```

---

## Struktur Kode Collector

```
collector/
├── app/
│   ├── main.py          — FastAPI app init, lifespan, mount UI
│   ├── config.py        — Settings dari .env (pydantic-settings)
│   ├── api/             — Route handlers
│   │   ├── agent.py     — POST /api/v1/agent/report
│   │   ├── assets.py    — GET /api/v1/assets (read API)
│   │   └── health.py    — GET /health
│   ├── schemas/         — Pydantic schemas (request/response)
│   ├── services/        — Business logic
│   ├── db/              — DB session, models
│   └── core/            — Middleware, dependencies
├── static/              — UI files (HTML/CSS/JS) untuk /ui/
└── tests/               — pytest tests
```

---

## Struktur Kode Agent

```
agent/
├── Collect-GeoNetReport.ps1    — Entry point collect (gather payload)
├── Send-GeoNetReport.ps1       — Entry point kirim laporan
├── UserAgent.ps1               — Script user: cek VERSION + kirim laporan
├── Install-GeoNetAgent.ps1     — Installer (setup files + scheduled task)
├── lib/
│   ├── Get-SystemInfo.ps1      — OS, manufacturer, model, BIOS
│   ├── Get-CpuInfo.ps1         — CPU cores, clock, cache, arch
│   ├── Get-MemoryInfo.ps1      — RAM detail, DDR type, part no
│   ├── Get-GpuInfo.ps1         — GPU dedicated memory
│   ├── Get-DiskInfo.ps1        — Logical disk info
│   ├── Get-PhysicalDiskInfo.ps1 — Physical disk model, serial
│   ├── Get-NetworkInfo.ps1     — NIC, MAC, IP, is_built_in
│   ├── Get-PeripheralsInfo.ps1 — USB/BT/audio/monitor, is_external
│   ├── Get-DisplaySettings.ps1 — Monitor EDID, resolusi
│   ├── Get-HealthInfo.ps1      — Disk usage, battery
│   ├── Get-SoftwareInfo.ps1    — Installed software list
│   ├── Get-AssetIdentity.ps1   — Resolve agent_id (ADR-001)
│   ├── Build-GeoNetReportPayload.ps1 — Assemble full JSON payload
│   ├── Agent-InstallCore.ps1   — Instalasi file + task
│   ├── Update-GeoNetAgent.ps1  — Auto-update dari manifest server
│   └── Send-CollectorReport.ps1 — HTTP POST ke collector
└── gpo/                        — GPO startup scripts
```

---

## Coding Standard

### Python (FastAPI)
- `snake_case` untuk variabel, fungsi, file
- Type hints wajib di semua function signature
- Pydantic v2 untuk schema validasi
- Route handler tipis — logic di `services/`
- Gunakan `Depends(get_db)` untuk DB session

### PowerShell (Agent)
- Satu file per sensor di `lib/`
- Fungsi nama: `Get-<Sensor>Info` → return hashtable
- Jangan hardcode token/URL — baca dari `config.json`
- Jangan gunakan `$env:` literal di file yang di-serve Nginx

### SQL
- PK: UUID (`gen_random_uuid()`)
- Timestamp: `timestamptz`
- Soft delete: kolom `deleted_at`
- Nama tabel: `snake_case` plural

---

## Commit Convention

Format: `<type>: <deskripsi>`

| Type | Kapan |
|------|-------|
| `feat` | Fitur baru |
| `fix` | Bug fix |
| `agent` | Perubahan PowerShell agent |
| `collector` | Perubahan FastAPI collector |
| `infra` | Nginx, Docker, DB migration |
| `docs` | Dokumentasi |
| `chore` | Config, deps |

---

## Testing

```bash
# Run tests collector
cd collector
pytest tests/ -v

# Manual test agent report
curl -X POST https://agent.gisportal.id/api/v1/agent/report \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @samples/agent-reports/sample-report-v0.1.10.json
```

---

## Menambah Sensor Baru ke Agent

1. Buat `agent/lib/Get-<Sensor>Info.ps1`
2. Import di `Build-GeoNetReportPayload.ps1`
3. Tambah field ke schema Pydantic di `collector/app/schemas/`
4. Update `collector/docs/API.md` + `docs/api/service-collector.md`
5. Bump versi di `agent/VERSION` + `agent/install/manifest.json`
6. Publish: `.\infra\collector\publish_agent_install.ps1`
7. Update `docs/project-status.md` + `.cursor/progress.md`