# Protokol Sync Dokumentasi AI

> **Wajib** di akhir sesi pengembangan. Repository = sumber kebenaran; percakapan bukan dokumentasi.

## Indeks cepat (operasional)

| Topik | File / URL |
|-------|------------|
| Progress & fase | `.cursor/progress.md` |
| SSH server | `.cursor/server.md` |
| Collector API | `collector/docs/API.md` |
| QNAP Object Storage (dokumen) | `infra/qnap/README.md` · ADR `003-asset-documents-qnap.md` |
| Install agent user | https://agent.gisportal.id/install/ · `agent/README.md` |
| Nginx reverse proxy | `infra/nginx/README.md` |
| Publish paket agent | `.\infra\collector\publish_agent_install.ps1` (Windows) · `bash infra/collector/publish_agent_install.sh` |
| Deploy collector | `.\infra\collector\push_collector.ps1` (Windows) · `bash infra/collector/push_collector.sh` |
| Deploy nginx collector | `infra/collector/deploy_nginx.sh` |
| ADR identitas / split / dokumen | `.cursor/adr/001-agent-asset-identity.md`, `002-asset-split-by-hardware.md`, `003-asset-documents-qnap.md` |

### URL produksi (domain `gisportal.id`)

| Fungsi | URL |
|--------|-----|
| Agent POST (internet) | `https://agent.gisportal.id/api/v1/agent/report` |
| Install / update agent | `https://agent.gisportal.id/install/` |
| UI + read API HTTPS | `https://collector.gisportal.id/ui/` |
| UI + read API HTTP LAN | `http://10.100.1.24:8000/ui/` |

### Install agent (PowerShell Admin — 2 baris berurutan)

```powershell
Invoke-WebRequest -Uri 'https://agent.gisportal.id/install/GeoNetAgent-Install.ps1' -OutFile "$env:TEMP\GeoNetAgent-Install.ps1" -UseBasicParsing
& "$env:TEMP\GeoNetAgent-Install.ps1" -SkipInitialRun
```

Alternatif unduh: `curl.exe -fsSL --tlsv1.2 "https://agent.gisportal.id/install/GeoNetAgent-Install.ps1" -o "$env:TEMP\GeoNetAgent-Install.ps1"`

> **Urutan:** unduh dulu (baris 1), baru jalankan (baris 2). Jangan kebalik.

Path install: `%ProgramData%\GeoNetAgent` · Task: `GeoNetAgent-Report`, `GeoNetAgent-Report-Startup` (interval **3 jam**)

Kirim laporan manual / cek auto-update:

```powershell
Get-Content "$env:ProgramData\GeoNetAgent\VERSION"
& "$env:ProgramData\GeoNetAgent\UserAgent.ps1"
```

### Admin — deploy & DB

| Aksi | Perintah |
|------|----------|
| Publish agent | `.\infra\collector\publish_agent_install.ps1` (PowerShell) atau `bash infra/collector/publish_agent_install.sh` |
| Deploy collector | `.\infra\collector\push_collector.ps1` (PowerShell) atau `bash infra/collector/push_collector.sh` |
| Deploy nginx | `infra/collector/deploy_nginx.sh` |
| Migration DB | `002`–`004` applied dev · `005_asset_documents.sql` (Fase 3, belum apply) |
| View hardware | `v_asset_hardware_latest` (migration 004) |
| Split asset (hardware campur) | `docker exec geonet-collector python /app/scripts/split_asset_by_hardware.py <uuid>` |

### Agent versi saat ini

**v0.1.10-phase0** — `cpu{}` detail, `physical_disks[]`, RAM/GPU detail, `system.form_factor`, auto-update via manifest.

**Deploy wajib setiap bump versi agent** (urutan):

```powershell
.\infra\collector\publish_agent_install.ps1   # upload ke agent.gisportal.id/install/
.\infra\collector\push_collector.ps1          # rebuild UI/API jika ada perubahan collector
```

Tanpa publish, installer/auto-update user tetap dapat versi lama dari server.

---

## PERTANYAAN SYNC (checklist AI)

```
1. Sinkronisasi Dokumentasi

- Pastikan seluruh keputusan, perubahan arsitektur, perubahan desain, perubahan implementasi, dan hasil diskusi pada sesi ini sudah didokumentasikan.
- Minimal periksa dan update:
    - .cursor/rules/
    - .cursor/*.md
    - Architecture Decision Record (ADR) bila terdapat perubahan desain.

2. Sinkronisasi AI Context

- Project ini menggunakan folder .cursor sebagai single source of truth untuk seluruh AI Agent.
- Karena saya sering berpindah perangkat (PC, Laptop, Workstation), AI Agent tidak boleh bergantung pada riwayat percakapan.
- Seluruh konteks penting harus selalu tersimpan di repository.

3. Konsistensi Dokumentasi

- Pastikan tidak ada informasi yang hanya ada di percakapan tetapi belum terdokumentasi.
- Seluruh keputusan teknis wajib dipindahkan ke dokumentasi project.
- Percakapan bukan merupakan sumber dokumentasi.
- Repository adalah sumber dokumentasi utama.

4. Rules Update

- Apabila hasil diskusi mengubah cara pengembangan project, maka AI wajib memperbarui file rules yang relevan.
- atau membuat rules baru apabila diperlukan.

5. Dokumentasi Sebelum Coding

- Jika terdapat perubahan desain, arsitektur, atau workflow, dokumentasi harus diperbarui terlebih dahulu sebelum implementasi kode dilanjutkan.
- Documentation First, Code Second.

6. Final Checklist

- Sebelum menjawab "selesai", AI wajib melakukan checklist berikut:
    - Semua keputusan pada percakapan ini sudah terdokumentasi.
    - Semua file .cursor yang relevan telah diperbarui.
    - Tidak ada konteks penting yang hanya tersimpan di percakapan.
    - Dokumentasi konsisten dengan implementasi.
    - Rules AI tetap menjadi acuan utama pengembangan.
    - Project tetap dapat dipahami AI Agent meskipun riwayat chat tidak tersedia.
    - **Bump versi agent**: `publish_agent_install.ps1` + `push_collector.ps1` (jika collector/UI berubah) sudah dijalankan atau user diberi tahu; **Riwayat milestone** di `progress.md` ditambah (rule: `.cursor/rules/agent-release-deploy.mdc`).

- Jika salah satu poin belum terpenuhi, jangan nyatakan pekerjaan selesai.
```

### Sync terakhir: 2026-06-22

- **ADR 003** — dokumen procurement/service/complain di QNAP S3; `asset_invoices`, `tickets`, `document_attachments` (migration 005 draft, belum apply)
- View **`v_asset_hardware_latest`** — CPU/GPU/RAM/display per asset (migration 004, applied dev)
- Agent **v0.1.10-phase0**: `cpu{}` detail, section CPU di UI, `Get-CpuInfo.ps1` (21 file manifest)
- **Deploy Windows**: `.\infra\collector\publish_agent_install.ps1` + `.\infra\collector\push_collector.ps1` (WSL tidak wajib)
- **Auto-update**: `UserAgent.ps1` bandingkan `VERSION` lokal vs `manifest.json` server sebelum kirim laporan
- **Periferal bawaan vs eksternal**: `peripherals[].is_external` (monitor/USB/BT); printer & upgrade hardware belum — lihat backlog di `progress.md`
- Agent **v0.1.9**: `physical_disks[]`, RAM (DDR label, part no), GPU detail, `form_factor` Laptop/PC
- Agent **v0.1.8**: GPU `gpus[]`, disk model, merge rule disk-clone, fix nginx truncate `$env:` di file served
- Collector: UI badge Laptop/PC, split asset by hardware (ADR 002), `machine_id` non-UNIQUE (migration 003)
- Pilot `DESKTOP-RRJ9G01`: split laptop Dell vs PC Gigabyte; domain `*.gisportal.id`
- Nginx `agent.gisportal.id`: `ssi off`, hindari `$env:` di file `.ps1` yang di-serve