Browse Source
- Add Repository Registry to Workspace-Context.md with mysupperapps_FE_PWA - Deprecate duplicate context-index in server-connection and GeoNetAgent .cursor - Update SESSION-HANDOVER and folder-structure for docs/context-index.md - Record changes in GeoNetAgent and server-connection changelogs Co-authored-by: Cursor <cursoragent@cursor.com>master
9 changed files with 95 additions and 1081 deletions
@ -1,495 +1,11 @@
@@ -1,495 +1,11 @@
|
||||
# Context Index (AI Entry Point) |
||||
# Context Index — Deprecated |
||||
|
||||
> **Versi Dokumen:** 1.0.0 |
||||
> **Terakhir Diperbarui:** 2026-06-23 |
||||
> **Status:** Aktif |
||||
> **Pemilik:** Tim Pengembang GeoNetAgent |
||||
> **Status:** Deprecated — jangan gunakan file ini. |
||||
> **Entry point resmi:** [`docs/context-index.md`](../docs/context-index.md) |
||||
> **Deprecated sejak:** 2026-07-02 |
||||
|
||||
--- |
||||
|
||||
# Tujuan |
||||
File ini adalah versi lama (v1.0.0, 2026-06-23) dan sudah digantikan oleh `docs/context-index.md`. |
||||
|
||||
Dokumen ini merupakan **titik masuk utama (Single Entry Point)** bagi seluruh AI Agent dan Developer GeoNetAgent. |
||||
|
||||
Setiap AI **WAJIB** membaca dokumen ini terlebih dahulu sebelum melakukan analisis, implementasi, perubahan kode, refactoring, penghapusan, deployment, maupun pembuatan dokumentasi. |
||||
|
||||
Dokumen ini **bukan** tempat menyimpan seluruh informasi proyek, melainkan **peta navigasi** menuju seluruh dokumentasi yang tersedia. |
||||
|
||||
--- |
||||
|
||||
# Filosofi Proyek |
||||
|
||||
Proyek ini menerapkan prinsip **AI Native Development**. |
||||
|
||||
Artinya: |
||||
|
||||
* Dokumentasi adalah bagian dari source code. |
||||
* Setiap perubahan wajib terdokumentasi. |
||||
* Repository merupakan sumber kebenaran utama (Single Source of Truth). |
||||
* AI tidak boleh mengandalkan riwayat percakapan. |
||||
* Seluruh pengetahuan proyek harus tersimpan dalam repository. |
||||
* Developer sering berpindah perangkat (PC, Laptop, Workstation) — AI Agent harus tetap bisa melanjutkan tanpa riwayat chat. |
||||
|
||||
--- |
||||
|
||||
# Aturan Utama AI |
||||
|
||||
Sebelum melakukan pekerjaan apa pun, AI wajib: |
||||
|
||||
1. Membaca file ini (`context-index.md`). |
||||
2. Membaca dokumentasi yang berkaitan dengan tugas. |
||||
3. Memahami arsitektur yang ada. |
||||
4. Memastikan tidak ada konflik dengan keputusan arsitektur sebelumnya (cek ADR). |
||||
5. Memperbarui dokumentasi setelah implementasi selesai. |
||||
6. Mengikuti protokol sync di `perintah.md` sebelum menyatakan pekerjaan selesai. |
||||
|
||||
Implementasi tanpa dokumentasi dianggap **belum selesai**. |
||||
|
||||
--- |
||||
|
||||
# Urutan Membaca Dokumentasi |
||||
|
||||
AI wajib membaca dokumen sesuai urutan berikut: |
||||
|
||||
1. `context-index.md` (file ini) |
||||
2. `blueprint.md` — Master blueprint, visi, arsitektur, modul |
||||
3. `progress.md` — Fase aktif & snapshot progress |
||||
4. Dokumen spesifik modul (lihat tabel Struktur Dokumentasi di bawah) |
||||
5. `agent-playbook.md` — Workflow multi-tab & koordinasi |
||||
6. `perintah.md` — Protokol sync dokumentasi (wajib akhir sesi) |
||||
|
||||
Jangan membaca seluruh repository apabila tidak diperlukan. |
||||
|
||||
--- |
||||
|
||||
# Struktur Dokumentasi |
||||
|
||||
## 1. Blueprint |
||||
|
||||
**Lokasi:** `.cursor/blueprint.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Visi produk & masalah yang diselesaikan |
||||
* Non-goals (sengaja TIDAK dibangun) |
||||
* Boundary System — ownership matrix (Zabbix, FastAPI, Laravel) |
||||
* Alur data utama (agent, Zabbix, Proxmox, user dashboard) |
||||
* Modul aplikasi & prioritas (M1-M9) |
||||
* Keputusan teknis locked (PostgreSQL, monorepo, API versioning) |
||||
* Entity domain ringkas |
||||
* Integrasi eksternal (Zabbix, Proxmox, MikroTik, QNAP, AD) |
||||
* Security blueprint |
||||
* Deployment target |
||||
* Roadmap & Definition of Done per fase |
||||
* Glossarium |
||||
|
||||
**Baca saat:** Selalu — cek visi & batas modul sebelum coding. |
||||
|
||||
--- |
||||
|
||||
## 2. Progress |
||||
|
||||
**Lokasi:** `.cursor/progress.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Snapshot status (fase aktif, agent version, collector status) |
||||
* Progress ringkas per fase (0-4) |
||||
* Checklist detail per fase dengan DoD (Definition of Done) |
||||
* Agent feature log (versi & fitur per versi) |
||||
* Backlog agent (fitur yang belum diimplementasi) |
||||
* Riwayat milestone (tanggal & milestone penting) |
||||
|
||||
**Baca saat:** Selalu — cek fase aktif sebelum coding. Jangan implement fase 3 saat fase 1 belum DoD. |
||||
|
||||
--- |
||||
|
||||
## 3. Agent Playbook |
||||
|
||||
**Lokasi:** `.cursor/agent-playbook.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Prinsip koordinasi multi-tab Cursor Agent |
||||
* Workflow multi-tab (DB, API, UI, Infra, Zabbix) |
||||
* Assignment tab → scope & folder |
||||
* Checklist sebelum & sesudah coding |
||||
* Dokumen — kapan diupdate (mapping event → file) |
||||
* Release agent protocol (publish + deploy + milestone log) |
||||
* Handling deviasi blueprint |
||||
* Conflict prevention |
||||
* Prompt template untuk user |
||||
* Status tracking |
||||
* Protokol sync dokumentasi |
||||
|
||||
**Baca saat:** Saat paralel development atau koordinasi antar tab. |
||||
|
||||
--- |
||||
|
||||
## 4. Database Schema |
||||
|
||||
**Lokasi:** `.cursor/db-schema.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Konvensi (PK UUID, timestamptz, snake_case) |
||||
* ERD (Mermaid) |
||||
* Tabel detail (`locations`, `assets`, `asset_snapshots`, `asset_disks`, `users`, `software_installations`, `licenses`, `asset_invoices`, `tickets`, `document_attachments`, `alerts`, `agent_tokens`, `sync_logs`) |
||||
* View `v_asset_hardware_latest` |
||||
* Laravel auth tables (`portal_users`) |
||||
* Sample queries |
||||
* Migration order |
||||
|
||||
**Baca saat:** Saat kerja database/migration, schema change, atau query data. |
||||
|
||||
--- |
||||
|
||||
## 5. API Contracts |
||||
|
||||
**Lokasi:** `.cursor/api-contracts.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Overview service & base URL |
||||
* FastAPI — Agent Ingress (`POST /api/v1/agent/report`) |
||||
* FastAPI — Read API CMDB (GET assets, snapshots, software) |
||||
* FastAPI — Proxmox sync (`POST /api/v1/sync/proxmox`) |
||||
* Laravel — Portal API (pages, asset documents, tickets) |
||||
* Laravel — Zabbix Webhook (`POST /webhooks/zabbix`) |
||||
* Laravel → Zabbix API (read-only host status) |
||||
* Proxmox API (FastAPI sync job) |
||||
* PowerShell Agent — Local Contract |
||||
* Error format standar |
||||
* Versioning policy |
||||
|
||||
**Baca saat:** Saat kerja backend/API, integrasi agent, atau webhook. |
||||
|
||||
--- |
||||
|
||||
## 6. Repository Structure |
||||
|
||||
**Lokasi:** `.cursor/repo-structure.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Root layout (`.cursor/`, `agent/`, `collector/`, `portal/`, `infra/`, `samples/`) |
||||
* Keputusan migration DB (Alembic vs Laravel) |
||||
* Naming conventions (Python, PHP, PowerShell) |
||||
* Environment variables |
||||
* Docker Compose dev |
||||
* Git branch strategy |
||||
* File ownership per agent tab |
||||
* README.md root target content |
||||
|
||||
**Baca saat:** Saat scaffold/buat file baru atau struktur folder. |
||||
|
||||
--- |
||||
|
||||
## 7. Profil & Infrastruktur |
||||
|
||||
**Lokasi:** `.cursor/me.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Profil user (IT end-to-end: network, server, storage, GIS, licensing) |
||||
* Stack & aset yang sudah dimiliki (Laravel, FastAPI, Zabbix, AD, Proxmox, QNAP, MikroTik) |
||||
* Lingkungan development (workspace, OS dev, contoh endpoint) |
||||
* Ruang lingkup tanggung jawab |
||||
* Preferensi kerja (Bahasa Indonesia, jangan duplikasi Zabbix, PostgreSQL untuk baru) |
||||
* File konteks terkait |
||||
* Status proyek |
||||
* URL operasional |
||||
|
||||
**Ringkasan Profil User:** |
||||
|
||||
User adalah **IT Administrator** yang mengelola infrastruktur end-to-end: |
||||
|
||||
- **Network & Security:** MikroTik CCR2004 (gateway, routing, firewall) |
||||
- **Compute & Virtualization:** Proxmox (VM host), PostgreSQL/SQL Server (database), Docker (containers) |
||||
- **Identity:** Windows Server 2012 R2 Active Directory (domain user management, GPO deploy) |
||||
- **Storage:** QNAP TS-932X (NAS, Object Storage untuk dokumen) |
||||
- **Monitoring:** Zabbix (alerting real-time) |
||||
- **Endpoint:** Banyak laptop user (Windows, domain-joined) |
||||
- **GIS & Licensing:** Software licensing tracking |
||||
|
||||
**Preferensi Kerja:** |
||||
|
||||
- Bahasa komunikasi: **Bahasa Indonesia** |
||||
- Jangan duplikasi fungsi Zabbix — Zabbix tetap pusat alerting real-time |
||||
- PostgreSQL untuk aplikasi/CMDB baru; SQL Server untuk legacy/GIS |
||||
- Minimalkan scope perubahan; ikuti konvensi existing code |
||||
- Jangan commit kecuali diminta eksplisit |
||||
- Sering berpindah perangkat (PC, Laptop, Workstation) — gunakan `.cursor/` sebagai shared memory |
||||
|
||||
**Baca saat:** Selalu — konteks lingkungan & preferensi user. |
||||
|
||||
--- |
||||
|
||||
## 8. Server & SSH |
||||
|
||||
**Lokasi:** `.cursor/server.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* SSH commands ke seluruh server (MikroTik, reverse proxy, main database, webserver, AD-LDAP, Zabbix, Ollama, QNAP) |
||||
* Port & credential hints |
||||
* Service per server |
||||
|
||||
**Baca saat:** Saat deploy / akses infra. |
||||
|
||||
--- |
||||
|
||||
## 9. Architecture Decision Records (ADR) |
||||
|
||||
**Lokasi:** `.cursor/adr/` |
||||
|
||||
**Berisi:** |
||||
|
||||
* `001-agent-asset-identity.md` — Strategi identitas asset (serial → smbios_uuid → MAC → machine_id → hostname) |
||||
* `002-asset-split-by-hardware.md` — Split asset dengan hardware campur (laptop + PC dalam 1 chassis) |
||||
* `003-asset-documents-qnap.md` — Dokumen procurement/service/complain di QNAP Object Storage |
||||
|
||||
**Baca saat:** Saat keputusan desain baru atau implementasi fitur yang terdampak ADR. |
||||
|
||||
**Catatan:** ADR tidak boleh dihapus. Jika berubah, buat ADR baru. |
||||
|
||||
--- |
||||
|
||||
## 10. Perintah (Sync Protocol) |
||||
|
||||
**Lokasi:** `perintah.md` (root repo) |
||||
|
||||
**Berisi:** |
||||
|
||||
* Indeks cepat operasional (progress, SSH, API, QNAP, install agent, nginx, deploy) |
||||
* URL produksi (domain `gisportal.id`) |
||||
* Install agent (PowerShell commands) |
||||
* Admin — deploy & DB commands |
||||
* Agent versi saat ini |
||||
* Pertanyaan sync (checklist AI wajib akhir sesi) |
||||
* Sync terakhir (changelog singkat) |
||||
|
||||
**Baca saat:** Akhir sesi / sebelum nyatakan done (wajib). |
||||
|
||||
--- |
||||
|
||||
## 11. Rules |
||||
|
||||
**Lokasi:** `.cursor/rules/` |
||||
|
||||
**Berisi:** |
||||
|
||||
* `project-context.mdc` — Rule Cursor: muat konteks proyek otomatis |
||||
* Rules tambahan (coding standard, security, dll) — akan ditambah sesuai kebutuhan |
||||
|
||||
**Baca saat:** Saat perlu rules spesifik atau konvensi coding. |
||||
|
||||
--- |
||||
|
||||
## 12. Monitoring Architecture |
||||
|
||||
**Lokasi:** `.cursor/monitoring-architecture.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Layer Zabbix/FastAPI/Laravel |
||||
* DXDiag integration |
||||
* Roadmap fase monitoring |
||||
|
||||
**Baca saat:** Saat kerja monitoring/integrasi Zabbix. |
||||
|
||||
--- |
||||
|
||||
## 13. Collector API Documentation |
||||
|
||||
**Lokasi:** `collector/docs/API.md` |
||||
|
||||
**Berisi:** |
||||
|
||||
* Panduan konsumsi Collector API |
||||
* Contoh curl/PowerShell/Python |
||||
* Detail endpoint & response |
||||
|
||||
**Baca saat:** Integrasi agent / aplikasi lain ke collector. |
||||
|
||||
--- |
||||
|
||||
# Informasi Infrastruktur |
||||
|
||||
Seluruh informasi server berada di `.cursor/server.md`. |
||||
|
||||
## Audit Server (OS & Aplikasi) |
||||
|
||||
| Server | IP | OS / Versi | Digunakan di GeoNetAgent? | Fungsi | |
||||
|--------|-----|------------|---------------------------|--------| |
||||
| MikroTik CCR2004 | 10.100.1.1 / 192.168.0.1 | RouterOS | ☐ | Gateway, routing, firewall | |
||||
| Reverse Proxy (nginx) | 10.100.1.24 | CentOS Linux 8 | ☑ YES | GeoNetAgent collector, agent.gisportal.id, collector.gisportal.id | |
||||
| Main Database | 10.100.1.25 | Ubuntu 18.04.6 LTS | ☑ YES | PostgreSQL 12 — `geonetagent_dev` | |
||||
| Main Webserver | 10.100.1.41 | Windows Server 2012 R2 (6.3.9600) | ☐ | Web server | |
||||
| AD-LDAP | 10.100.1.40 | Windows Server 2012 R2 (6.3.9600) | ☐ | Active Directory (GPO deploy agent - fase 2) | |
||||
| Zabbix | 10.100.1.42 | Ubuntu 22.04.1 LTS | ☐ | Monitoring Server (integrasi webhook - fase 2) | |
||||
| Ollama | 10.100.1.26 | Ubuntu 22.04.1 LTS | ☐ | AI inference (opsional - fase 4) | |
||||
| QNAP TS-932X | 10.100.1.10 | QTS 5.2.9 (ARM64) | ☑ YES | NAS / Object Storage (dokumen ADR 003) | |
||||
|
||||
**Catatan:** |
||||
- ☑ = Sudah dikonfirmasi digunakan di GeoNetAgent |
||||
- ☐ = Belum dikonfirmasi atau belum digunakan di fase saat ini |
||||
- User dapat mengisi checkbox ini sesuai kebutuhan |
||||
|
||||
AI tidak boleh mengubah konfigurasi server tanpa memperbarui dokumentasi. |
||||
|
||||
--- |
||||
|
||||
# Informasi API |
||||
|
||||
Semua API wajib memiliki dokumentasi di `.cursor/api-contracts.md`. |
||||
|
||||
**FastAPI Collector:** |
||||
|
||||
* Base URL dev: `http://localhost:8000` |
||||
* Base URL prod: `https://collector.gisportal.id` |
||||
* Auth: Bearer token |
||||
* Endpoint: `POST /api/v1/agent/report`, GET `/api/v1/assets`, dll |
||||
|
||||
**Laravel Portal:** |
||||
|
||||
* Base URL dev: `http://localhost:8080` |
||||
* Base URL prod: `https://portal.geonet.internal` |
||||
* Auth: Session / Sanctum |
||||
|
||||
--- |
||||
|
||||
# Informasi Database |
||||
|
||||
Seluruh perubahan database wajib memperbarui `.cursor/db-schema.md`. |
||||
|
||||
**Database:** `geonetagent` (prod) · `geonetagent_dev` (dev/testing) |
||||
|
||||
**Engine:** PostgreSQL 12+ |
||||
|
||||
**Ownership:** FastAPI = write ingress otomatis | Laravel = read + manual CRUD terbatas |
||||
|
||||
**Migration tool:** Alembic (core schema) + Laravel migrations (portal-specific) |
||||
|
||||
Tidak boleh ada perubahan database tanpa dokumentasi. |
||||
|
||||
--- |
||||
|
||||
# Checklist Sebelum Implementasi |
||||
|
||||
AI wajib memastikan: |
||||
|
||||
☐ Sudah membaca `context-index.md` |
||||
|
||||
☐ Sudah membaca `blueprint.md` — cek fase & DoD |
||||
|
||||
☐ Sudah membaca `progress.md` — cek fase aktif |
||||
|
||||
☐ Sudah membaca dokumentasi spesifik modul (db-schema, api-contracts, dll) |
||||
|
||||
☐ Sudah memahami ADR yang relevan |
||||
|
||||
☐ Sudah memahami infrastruktur di `me.md` & `server.md` |
||||
|
||||
☐ Sudah memastikan dependency tab lain sudah ada di disk (jika paralel) |
||||
|
||||
--- |
||||
|
||||
# Checklist Setelah Implementasi |
||||
|
||||
AI wajib memperbarui: |
||||
|
||||
☐ `progress.md` — centang item selesai, update snapshot, tambahkan milestone jika perlu |
||||
|
||||
☐ ADR baru (jika ada perubahan arsitektur/desain) |
||||
|
||||
☐ Dokumentasi spesifik (db-schema.md, api-contracts.md, repo-structure.md, dll) |
||||
|
||||
☐ `blueprint.md` — jika modul/fase baru |
||||
|
||||
☐ `agent-playbook.md` — jika workflow berubah |
||||
|
||||
☐ `perintah.md` — sync terakhir (wajib akhir sesi) |
||||
|
||||
☐ `me.md` — jika infrastruktur berubah |
||||
|
||||
☐ `context-index.md` — jika ada dokumen baru |
||||
|
||||
☐ Deploy agent (jika bump versi): `publish_agent_install.ps1` + `push_collector.ps1` |
||||
|
||||
--- |
||||
|
||||
# Prinsip Pengembangan |
||||
|
||||
Setiap perubahan harus memenuhi prinsip berikut: |
||||
|
||||
* Mudah dipahami developer baru. |
||||
* Mudah dipahami AI Agent lain (tanpa riwayat chat). |
||||
* Mudah diaudit. |
||||
* Mudah di-maintain. |
||||
* Memiliki rollback plan. |
||||
* Memiliki dokumentasi lengkap. |
||||
* Tidak menghasilkan technical debt yang tidak terdokumentasi. |
||||
* Mengikuti fase di `progress.md` — jangan loncat fase. |
||||
* Repository adalah sumber kebenaran utama. |
||||
|
||||
--- |
||||
|
||||
# Quick Reference |
||||
|
||||
## URL Produksi |
||||
|
||||
| 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/` | |
||||
|
||||
## Agent Version |
||||
|
||||
**Current:** `v0.1.10-phase0` — `cpu{}` detail, `physical_disks[]`, RAM/GPU detail, `system.form_factor`, auto-update via manifest. |
||||
|
||||
## Fase Aktif |
||||
|
||||
**Fase 1 — Foundation** 🔄 |
||||
|
||||
DoD: Agent di 1 laptop test POST → data di DB → Laravel tampilkan halaman asset list. |
||||
|
||||
Progress: 8 / 9 item selesai. Blocker: Laravel asset index belum scaffold. |
||||
|
||||
## Deploy Commands |
||||
|
||||
```powershell |
||||
# Publish agent |
||||
.\infra\collector\publish_agent_install.ps1 |
||||
|
||||
# Deploy collector |
||||
.\infra\collector\push_collector.ps1 |
||||
|
||||
# Deploy nginx |
||||
infra/collector/deploy_nginx.sh |
||||
``` |
||||
|
||||
--- |
||||
|
||||
# Penutup |
||||
|
||||
Repository ini dirancang agar: |
||||
|
||||
* Developer baru dapat memahami proyek dengan cepat. |
||||
* AI Agent mana pun dapat melanjutkan pekerjaan tanpa kehilangan konteks. |
||||
* Seluruh pengetahuan proyek tersimpan di dalam repository. |
||||
* Dokumentasi selalu selaras dengan implementasi. |
||||
|
||||
Repository adalah sumber kebenaran utama. |
||||
|
||||
Jika terjadi perbedaan antara implementasi dan dokumentasi, AI wajib memperbarui dokumentasi hingga keduanya konsisten. |
||||
|
||||
--- |
||||
|
||||
# Bahasa & Gaya |
||||
|
||||
* Komunikasi dengan user: **Bahasa Indonesia** |
||||
* Kode & komentar: **English** (konvensi industri) |
||||
* Dokumentasi `.cursor/`: **Bahasa Indonesia** (kecuali istilah teknis) |
||||
AI Agent dan developer **wajib** membaca [`docs/context-index.md`](../docs/context-index.md) sebagai Single Entry Point. |
||||
|
||||
Loading…
Reference in new issue