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)

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:

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):

.\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

6.5 KiB Raw Permalink Blame History