LDAPWeb/GeoNetAgent/docs/development.md

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

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:

# 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

# 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