# Database Documentation

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

---

## Overview

| Item | Value |
|------|-------|
| DBMS | PostgreSQL 12+ |
| Host | 10.100.1.25 |
| DB Dev | `geonetagent_dev` |
| DB Prod | `geonetagent` |
| Timezone | `Asia/Jakarta` |
| PK Convention | UUID (`gen_random_uuid()`) |
| Timestamp | `timestamptz` |
| Credentials | `/root/geonetagent_dev.credentials` di server 10.100.1.25 |

**Ownership:**
- **FastAPI Collector** = write ingress otomatis (agent reports, Proxmox sync)
- **Laravel Portal** = read + manual CRUD terbatas

---

## ERD (MVP)

```mermaid
erDiagram
    locations ||--o{ assets : has
    assets ||--o{ asset_snapshots : has
    assets ||--o{ software_installations : has
    assets ||--o{ asset_user_assignments : has
    users ||--o{ asset_user_assignments : assigned
    users ||--o{ license_assignments : has
    licenses ||--o{ license_assignments : has
    assets ||--o{ license_assignments : assigned
    assets ||--o{ alerts : triggers
    assets ||--o{ assets : parent_host
```

---

## Tabel Detail

### `assets`

Entitas utama — setiap device/VM/server.

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID PK | `gen_random_uuid()` |
| `asset_type` | varchar | `endpoint`, `server`, `vm`, `proxmox_host`, `network_device`, `nas`, `gis_server` |
| `hostname` | varchar UNIQUE | Hostname device |
| `machine_id` | varchar | OS machine-id (tidak lagi UNIQUE sejak migration 003) |
| `smbios_uuid` | varchar | BIOS UUID |
| `serial_number` | varchar | Serial number hardware |
| `primary_physical_mac` | varchar | MAC address utama (untuk identity fallback) |
| `zabbix_host_id` | varchar nullable | ID host di Zabbix |
| `location_id` | UUID FK → locations | Lokasi fisik |
| `parent_asset_id` | UUID FK → assets | Untuk VM: parent Proxmox host |
| `status` | varchar | `active`, `inactive`, `unknown` |
| `metadata` | jsonb | Field fleksibel/rare |
| `last_seen_at` | timestamptz | Terakhir laporan masuk |
| `deleted_at` | timestamptz nullable | Soft delete |

---

### `asset_snapshots`

Point-in-time snapshot dari laporan agent.

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID PK | |
| `asset_id` | UUID FK → assets | |
| `payload` | jsonb | Full payload agent (system, cpu, gpu, disks, network, dll) |
| `agent_version` | varchar | Versi agent saat collect |
| `collected_at` | timestamptz | Waktu collect di endpoint |

> Idempotent berdasarkan `(hostname, collected_at)` — laporan duplikat diabaikan.

---

### `software_installations`

Daftar software terinstall dari scan agent.

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID PK | |
| `asset_id` | UUID FK | |
| `name` | varchar | Nama software |
| `version` | varchar nullable | |
| `publisher` | varchar nullable | |
| `install_date` | date nullable | |
| `collected_at` | timestamptz | |

---

### `users`

User/karyawan (dari AD atau manual entry Laravel).

| Kolom | Tipe |
|-------|------|
| `id` | UUID PK |
| `username` | varchar UNIQUE |
| `display_name` | varchar |
| `email` | varchar nullable |
| `department` | varchar nullable |

---

### `locations`

Lokasi fisik asset.

| Kolom | Tipe |
|-------|------|
| `id` | UUID PK |
| `name` | varchar |
| `code` | varchar |
| `address` | varchar nullable |

---

### `alerts`

Alert dari Zabbix webhook (Fase 2).

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID PK | |
| `asset_id` | UUID FK nullable | |
| `zabbix_event_id` | varchar UNIQUE | ID event Zabbix |
| `severity` | varchar | `info`, `warning`, `average`, `high`, `disaster` |
| `message` | text | |
| `status` | varchar | `problem`, `resolved` |
| `fired_at` | timestamptz | |
| `resolved_at` | timestamptz nullable | |

---

### `agent_tokens`

Token autentikasi agent (jika `AGENT_TOKEN_CHECK_DB=true`).

| Kolom | Tipe |
|-------|------|
| `id` | UUID PK |
| `token_hash` | varchar UNIQUE |
| `description` | varchar |
| `is_active` | boolean |
| `created_at` | timestamptz |

---

### `asset_invoices`, `tickets`, `document_attachments` (Fase 3 — Belum Apply)

Draft di `infra/db/005_asset_documents.sql`. Belum dijalankan di DB.

| Tabel | Domain |
|-------|--------|
| `asset_invoices` | Procurement / pembelian |
| `tickets` | Service request + complain |
| `document_attachments` | File di QNAP Object Storage (ADR-003) |

---

## View

### `v_asset_hardware_latest` (migration 004, dev DB)

View yang merangkum hardware terbaru per asset dari `asset_snapshots`.

```sql
-- Contoh query
SELECT hostname, cpu_model, ram_gb, gpu_model, os_name
FROM v_asset_hardware_latest
ORDER BY hostname;
```

---

## Migration History

| File | Tanggal | Keterangan |
|------|---------|------------|
| `001_initial_schema.sql` | 2026-06-17 | Schema awal: assets, snapshots, software, users, licenses, alerts, agent_tokens |
| `002_disk_model.sql` | 2026-06-17 | Tambah kolom disk_model |
| `003_drop_machine_id_unique.sql` | 2026-06-22 | Hapus UNIQUE constraint machine_id (asset campur hardware) |
| `004_view_hardware_latest.sql` | 2026-06-22 | Buat view `v_asset_hardware_latest` |
| `005_asset_documents.sql` | 2026-06-22 | Draft: asset_invoices, tickets, document_attachments — **belum apply** |

Cara apply migration: lihat `infra/db/README.md`

---

## Catatan Penting

- **Split asset:** Satu laptop bisa punya dua asset record (ADR-002). `smbios_uuid` tidak lagi UNIQUE per laptop dual-boot.
- **Snapshot flatten:** Field hardware di payload ada di root object sekarang, bukan nested `.system` lagi untuk data baru.
- **Soft delete:** Tabel master punya `deleted_at` — jangan `DELETE` langsung.