From d612f05a5056b60d00e511fd2e20d861e6a7696e Mon Sep 17 00:00:00 2001 From: rbsetiawan Date: Thu, 2 Jul 2026 14:38:35 +0700 Subject: [PATCH] docs: consolidate context-index entry points across workspace - 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 --- GeoNetAgent/.cursor/context-index.md | 496 +----------------- GeoNetAgent/CHANGELOG.md | 10 + .../docs/architecture/folder-structure.md | 6 +- SESSION-HANDOVER.md | 52 +- Workspace-Context.md | 21 +- server-connection/.cursor/context-index.md | 486 +---------------- server-connection/context-index.md | 92 +--- server-connection/docs/changelog.md | 11 + server-connection/docs/context-index.md | 2 +- 9 files changed, 95 insertions(+), 1081 deletions(-) diff --git a/GeoNetAgent/.cursor/context-index.md b/GeoNetAgent/.cursor/context-index.md index 4387fb5..8f05123 100644 --- a/GeoNetAgent/.cursor/context-index.md +++ b/GeoNetAgent/.cursor/context-index.md @@ -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. diff --git a/GeoNetAgent/CHANGELOG.md b/GeoNetAgent/CHANGELOG.md index f9f4f68..3e64d8b 100644 --- a/GeoNetAgent/CHANGELOG.md +++ b/GeoNetAgent/CHANGELOG.md @@ -4,6 +4,16 @@ Format: [Semantic Versioning](https://semver.org) — Agent version / Doc versio --- +## [Doc 1.1.0] — 2026-07-02 + +### Changed +- `docs/architecture/folder-structure.md` — `.cursor/context-index.md` ditandai Deprecated; entry point resmi `docs/context-index.md` + +### Deprecated +- `.cursor/context-index.md` — redirect ke `docs/context-index.md` + +--- + ## [Doc 1.0.0] — 2026-06-29 ### Added (Dokumentasi) diff --git a/GeoNetAgent/docs/architecture/folder-structure.md b/GeoNetAgent/docs/architecture/folder-structure.md index a446a13..bc9c030 100644 --- a/GeoNetAgent/docs/architecture/folder-structure.md +++ b/GeoNetAgent/docs/architecture/folder-structure.md @@ -1,6 +1,6 @@ # Architecture — Folder Structure -> **Terakhir Diperbarui:** 2026-06-29 +> **Terakhir Diperbarui:** 2026-07-02 --- @@ -169,9 +169,11 @@ docs/ ## `.cursor/` — AI Context (Detail Teknis) +> Entry point resmi: [`docs/context-index.md`](../context-index.md). File `.cursor/context-index.md` **deprecated** (redirect ke `docs/`). + ``` .cursor/ -├── context-index.md — Entry point lama (versi lama, masih relevan) +├── context-index.md — Deprecated → docs/context-index.md ├── blueprint.md — Master blueprint + modul M1-M9 ├── progress.md — Checklist fase + milestone history ├── db-schema.md — Schema detail + ERD Mermaid diff --git a/SESSION-HANDOVER.md b/SESSION-HANDOVER.md index d2efeb5..3ebfeac 100644 --- a/SESSION-HANDOVER.md +++ b/SESSION-HANDOVER.md @@ -8,11 +8,17 @@ ## BACA INI DULU SEBELUM APAPUN -1. Baca `Workspace-Context.md` → rules dan policy workspace -2. Baca `ARCHITECTURE.md` → 7 diagram Mermaid arsitektur lengkap -3. Baca `backlog.md` → roadmap semua fase + detail teknis tiap microservice -4. Baca `server-audit/host.md` → daftar server, SSH command, catatan ops -5. Baca `server-audit/deploy-log.md` → log semua deploy yang sudah dilakukan +1. Baca `Workspace-Context.md` → rules, policy, dan **Repository Registry** +2. Baca `docs/context-index.md` pada repo yang relevan dengan tugas: + - FE PWA → `mysupperapps_FE_PWA/docs/context-index.md` + - Backend Laravel → `server-connection/docs/context-index.md` (lalu `geonet-console/context-index.md` jika spesifik console) + - Agent/Collector → `GeoNetAgent/docs/context-index.md` +3. Baca `ARCHITECTURE.md` → 7 diagram Mermaid arsitektur lengkap +4. Baca `backlog.md` → roadmap semua fase + detail teknis tiap microservice +5. Baca `server-audit/host.md` → daftar server, SSH command, catatan ops +6. Baca `server-audit/deploy-log.md` → log semua deploy yang sudah dilakukan + +> Jangan gunakan `context-index.md` di root atau `.cursor/` — file tersebut **deprecated**; gunakan `docs/context-index.md` per repo. --- @@ -141,26 +147,30 @@ ssh -m hmac-sha1 root@10.100.1.24 -p 22 "cd /opt/stacks/ && docker comp ``` app on git/ -├── ARCHITECTURE.md ← 7 diagram Mermaid (BACA INI) -├── backlog.md ← Roadmap + detail teknis semua fase -├── Workspace-Context.md ← Rules & policy untuk AI agent -├── SESSION-HANDOVER.md ← File ini +├── ARCHITECTURE.md ← 7 diagram Mermaid (BACA INI) +├── backlog.md ← Roadmap + detail teknis semua fase +├── Workspace-Context.md ← Rules, policy & Repository Registry ⭐ +├── SESSION-HANDOVER.md ← File ini │ ├── server-audit/ -│ ├── host.md ← Daftar server + SSH commands -│ └── deploy-log.md ← Log semua deploy +│ ├── host.md ← Daftar server + SSH commands +│ └── deploy-log.md ← Log semua deploy │ -├── mysupperapps_FE_PWA/ ← Frontend Next.js (repo terpisah, .gitignored di root) -│ ├── context-index.md ← Entry point AI untuk FE -│ ├── CHANGELOG.md ← Changelog FE (terbaru: v1.4.0 feedback) -│ └── docs/ ← Dokumentasi lengkap FE -│ ├── features/feedback.md ← Docs feature feedback -│ └── ... +├── GeoNetAgent/ ← Agent PowerShell + collector FastAPI +│ └── docs/context-index.md ← Entry point AI (repo agent) │ -└── server-connection/ - └── geonet-console/ ← Source code Laravel backend - ├── context-index.md ← Entry point AI untuk backend - ├── routes/api.php ← Semua API routes +├── mysupperapps_FE_PWA/ ← Frontend Next.js (repo Git terpisah, .gitignored di root) +│ ├── docs/context-index.md ← Entry point AI untuk FE ⭐ +│ ├── context-index.md ← Deprecated → docs/context-index.md +│ ├── CHANGELOG.md ← Changelog FE (terbaru: v1.4.0 feedback) +│ └── docs/ +│ └── features/feedback.md ← Docs feature feedback +│ +└── server-connection/ ← Backend Laravel monorepo + ├── docs/context-index.md ← Entry point AI (repo backend) ⭐ + └── geonet-console/ ← Source code Laravel console + ├── context-index.md ← Entry point AI (sub-proyek geonet-console) + ├── routes/api.php ├── app/Models/Feedback.php ├── app/Http/Controllers/Api/V1/FeedbackController.php └── database/migrations/2026_07_01_000001_create_feedback_table.php diff --git a/Workspace-Context.md b/Workspace-Context.md index bc2260f..692b6ff 100644 --- a/Workspace-Context.md +++ b/Workspace-Context.md @@ -17,13 +17,32 @@ Selalu identifikasi repository yang relevan, kemudian baca **`docs/context-index 1. Selalu baca `Workspace-Context.md` terlebih dahulu. 2. Tentukan repository yang relevan. 3. Baca hanya `docs/context-index.md` pada repository tersebut. -4. Ikuti seluruh referensi dokumentasi yang terdapat pada `context-index.md`. +4. Ikuti seluruh referensi dokumentasi yang terdapat pada `docs/context-index.md`. 5. Jangan membaca atau memodifikasi repository lain kecuali benar-benar dibutuhkan. 6. Jika pekerjaan melibatkan lebih dari satu repository, baca `docs/context-index.md` masing-masing repository yang terkait. 7. Jangan membuat asumsi mengenai arsitektur, API, database, server, maupun implementasi tanpa membaca dokumentasi repository terkait. --- +# Repository Registry + +Workspace ini berisi beberapa repository. **Jangan analisis semuanya sekaligus** — pilih yang relevan. + +| Repository | Path lokal | Git remote | Entry point | Peran | +|------------|------------|------------|-------------|-------| +| **LDAPWeb (monorepo)** | `D:\Project\app on git\` | `git.gisportal.id/rbsetiawan/LDAPWeb` | `Workspace-Context.md` | Root workspace, dokumentasi lintas-repo | +| **GeoNetAgent** | `GeoNetAgent/` | (dalam monorepo LDAPWeb) | `GeoNetAgent/docs/context-index.md` | Agent Windows, collector FastAPI, infra asset | +| **server-connection** | `server-connection/` | (dalam monorepo LDAPWeb) | `server-connection/docs/context-index.md` | Backend Laravel: geonet-console, databaselist, sqlservercheck | +| **mysupperapps_FE_PWA** | `mysupperapps_FE_PWA/` | `git.gisportal.id/rbsetiawan/mysupperapps-fe-pwa` | `mysupperapps_FE_PWA/docs/context-index.md` | Frontend PWA Next.js — `https://my.gisportal.id` | + +**Catatan `mysupperapps_FE_PWA`:** +- Repo Git **terpisah** (microservice + FE UI) — sengaja dipisah dari monorepo LDAPWeb. +- Folder lokal di-ignore di `.gitignore` root monorepo; commit & push hanya dari repo FE sendiri. +- Backend API: `server-connection/geonet-console` (`console.gisportal.id/api/v1`). +- Pekerjaan full-stack: baca `docs/context-index.md` **kedua** repo (FE + backend). + +--- + # Repository Ownership Policy * Setiap repository memiliki dokumentasi, aturan, dan lifecycle masing-masing. diff --git a/server-connection/.cursor/context-index.md b/server-connection/.cursor/context-index.md index 1cdc840..1b48e1c 100644 --- a/server-connection/.cursor/context-index.md +++ b/server-connection/.cursor/context-index.md @@ -1,485 +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 GeoNet / GIS Portal +> **Status:** Deprecated — jangan gunakan file ini. +> **Entry point resmi:** [`docs/context-index.md`](../docs/context-index.md) (v2.x) +> **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 untuk repository **server-connection**. - -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. -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. `me.md` — Profil & infrastruktur -3. `perintah.md` — Protokol sync dokumentasi -4. Dokumen spesifik modul (lihat tabel Struktur Dokumentasi di bawah) -5. Rules yang relevan di `.cursor/rules/` - -Jangan membaca seluruh repository apabila tidak diperlukan. - ---- - -# Struktur Dokumentasi - -## 1. Profil & Infrastruktur - -**Lokasi:** `.cursor/me.md` - -**Berisi:** - -* Profil user (IT end-to-end: network, server, storage, GIS, licensing) -* Stack & aset yang sudah dimiliki (Laravel 12, FastAPI, Python, SQL Server, PostgreSQL) -* Monitoring & Identity (Zabbix, Windows Server 2012 R2 AD) -* Compute & Virtualization (Proxmox, VM Database, VM Docker, VM Ollama) -* Network & Storage (MikroTik CCR2004, QNAP TS-932X) -* Endpoint (laptop user, GPO deploy) -* Lingkungan development (OS dev, Docker lokal, deploy, SSH) -* Ruang lingkup tanggung jawab -* Preferensi kerja (Bahasa Indonesia, jangan duplikasi Zabbix, PostgreSQL untuk baru) -* Aplikasi di repo `server-connection` (geonet-console, databaselist, sqlservercheck) -* URL operasional -* File konteks terkait -* Rules Cursor (prioritas) -* Status proyek -* Deploy cepat - -**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 SMB) -- **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 -- Documentation first — sinkronkan `.cursor/` setelah sesi besar - -**Baca saat:** Selalu — konteks lingkungan & preferensi user. - ---- - -## 2. Rules Cursor - -**Lokasi:** `.cursor/rules/` - -**Berisi:** - -| File | Isi | Scope | -|------|-----|-------| -| `00-project-context.mdc` | Struktur repo, host SSH, deploy | Selalu | -| `01-enterprise-principles.mdc` | Prinsip enterprise & UX wajib | Selalu | -| `02-implementation-status.mdc` | Status fitur geonet-console (audit) | Selalu | -| `03-ai-behavior.mdc` | Perilaku agent, larangan, bahasa | Selalu | -| `04-geonet-uiux.mdc` | Standar UI/UX | `geonet-console/`, `databaselist/` | -| `05-laravel-backend.mdc` | Service layer, API, audit | `*.php` di apps | -| `06-infrastructure.mdc` | SSH, Mikrotik, skrip deploy | `scripts/`, `server/` | - -**Baca saat:** Selalu — rules aktif untuk AI Agent. - ---- - -## 3. Perintah (Sync Protocol) - -**Lokasi:** `perintah.md` (root repo) - -**Berisi:** - -* Indeks cepat operasional (profil, konteks repo, status fitur, ringkasan agent) -* Aplikasi & stack produksi -* URL produksi (domain `gisportal.id`) -* Deploy dari laptop (PowerShell scripts) -* File konteks (update saat sync) -* Rules (daftar lengkap) -* Pertanyaan sync (checklist AI wajib akhir sesi) -* Sync terakhir (changelog singkat) - -**Baca saat:** Akhir sesi / sebelum nyatakan done (wajib). - ---- - -## 4. AGENTS.md - -**Lokasi:** `AGENTS.md` - -**Berisi:** - -* Rules aktif (daftar lengkap dengan scope) -* Aplikasi utama (geonet-console, databaselist, sqlservercheck) -* Dokumentasi sumber (referensi lengkap) -* Ollama + NAS Project Search (ringkasan agent) - * Ringkasan keputusan - * Arsitektur - * API (target geonet-console) - * Timeline rekomendasi - * Checklist go-live -* Verifikasi agent aktif - -**Baca saat:** Saat kerja Ollama/NAS search atau verifikasi rules. - ---- - -## 5. Server Documentation - -**Lokasi:** `server/` - -**Berisi:** - -* `host.md` — Daftar host & IP -* Audit server (Mikrotik, database, webserver, AD-LDAP, Zabbix, QNAP, Ollama) -* Konfigurasi Mikrotik (dual-wan, failover, hybrid, split-DNS) -* `migrate-geonet-console.md` — Rencana migrasi databaselist → geonet-console -* `ollama-nas-project-search-requirements.md` — Requirement lengkap Ollama + NAS search -* Konfigurasi nginx, SQL scripts - -**Baca saat:** Saat kerja infrastruktur, Mikrotik, atau migrasi. - ---- - -## 6. README & Quick Reference - -**Lokasi:** `readme.txt` - -**Berisi:** - -* SSH commands (Mikrotik, reverse proxy, main database, AD-LDAP) -* Remote Docker Development (model kerja) -* SSH key setup -* Deploy dari laptop (PowerShell scripts) -* URL setelah deploy -* Edit .env di server - -**Baca saat:** Saat deploy atau SSH ke server. - ---- - -# Informasi Aplikasi - -## Aplikasi di Repo - -| Folder | URL Produksi | Stack Server | Status | -|--------|--------------|--------------|--------| -| `geonet-console/` | https://console.gisportal.id | `/opt/stacks/geonet-console/` | ✅ Aktif | -| `databaselist/` | https://databaselist.gisportal.id | `/opt/stacks/databaselist/` | ⚠️ Redirect ke console | -| `sqlservercheck/` | https://sqlservercheck.gisportal.id | `/opt/stacks/sqlservercheck/` | ✅ Aktif | - -## URL Produksi - -### geonet-console - -| Fungsi | URL | -|--------|-----| -| Login / dashboard | https://console.gisportal.id | -| API Clients (OAuth2 + API Tokens + Service Tokens) | https://console.gisportal.id/api-clients | - -### databaselist (redirect ke console) - -| Fungsi | URL | -|--------|-----| -| Daftar database | https://databaselist.gisportal.id/ | -| LDAP Users | https://databaselist.gisportal.id/ldap-users | -| LDAP Groups | https://databaselist.gisportal.id/ldap-groups | -| DB Connections | https://databaselist.gisportal.id/database-connections | -| Mail SMTP & template | https://databaselist.gisportal.id/mail-settings | -| Audit Logs | https://databaselist.gisportal.id/audit-logs | -| API Docs | https://databaselist.gisportal.id/api-docs | -| Profile (user) | https://databaselist.gisportal.id/profile | -| REST API | https://databaselist.gisportal.id/api/v1 | - -### sqlservercheck - -| Fungsi | URL | -|--------|-----| -| Tool cek SQL Server | https://sqlservercheck.gisportal.id/ts | -| | https://sqlservercheck.gisportal.id/nts | - ---- - -# Service Tokens - -Service Tokens adalah fitur di `geonet-console` untuk mengelola Bearer token microservice secara terpusat. Berbeda dari OAuth2 (flow kompleks) dan API Token (untuk user/script), Service Tokens khusus untuk autentikasi service-to-service sederhana. - -## Arsitektur - -- **Tabel:** `service_tokens` (di database `geonet_console`, bukan `geonetagent_dev`) -- **Model:** `app/Models/ServiceToken.php` -- **Service:** `app/Services/ServiceTokenService.php` -- **Controller (web):** `app/Http/Controllers/ApiClientController.php` -- **Controller (API):** `app/Http/Controllers/Api/V1/ServiceTokenController.php` -- **Migration:** `database/migrations/2026_06_23_130000_create_service_tokens_table.php` -- **UI:** `/api-clients` — tab ketiga di bawah API Tokens dan OAuth2 Clients - -## Schema Tabel - -| Kolom | Tipe | Deskripsi | -|-------|------|-----------| -| `id` | UUID PK | Identifier unik | -| `name` | varchar(100) | Nama token (e.g., "GeoNetAgent-Production") | -| `service` | varchar(50) | Nama service (e.g., "GeoNetAgent", "Databaselist") | -| `token_prefix` | varchar(16) unique | 16 karakter awal untuk identifikasi di UI | -| `token_hash` | varchar(64) unique | SHA256 hash token lengkap | -| `is_active` | boolean | Status aktif/revoked | -| `expires_at` | timestamptz nullable | Waktu kedaluwarsa (null = tidak expire) | -| `created_by` | varchar(100) | Username yang membuat token | -| `created_at` | timestamptz | Waktu pembuatan | -| `last_used_at` | timestamptz nullable | Waktu terakhir digunakan | - -## API Endpoints (REST) - -| Method | Endpoint | Fungsi | -|--------|----------|--------| -| GET | `/api/v1/service-tokens` | List semua token | -| POST | `/api/v1/service-tokens` | Buat token baru | -| GET | `/api/v1/service-tokens/{id}` | Detail token | -| POST | `/api/v1/service-tokens/{id}/revoke` | Revoke (nonaktifkan) | -| POST | `/api/v1/service-tokens/{id}/regenerate` | Regenerate (buat baru, revoke lama) | -| DELETE | `/api/v1/service-tokens/{id}` | Hapus permanen | - -## Web Routes - -| Method | Route | Fungsi | -|--------|-------|--------| -| POST | `/api-clients/service-tokens` | Buat token (redirect ke `/api-clients`) | -| POST | `/api-clients/service-tokens/{id}/revoke` | Revoke token | -| POST | `/api-clients/service-tokens/{id}/regenerate` | Regenerate token | -| DELETE | `/api-clients/service-tokens/{id}` | Hapus token | - -## Sinkronisasi ke geonetagent_dev (Opsi C) - -geonet-console bertindak sebagai **single point of control** — saat token dibuat/direvoke/dihapus di UI, perubahan otomatis disinkronkan ke `geonetagent_dev.agent_tokens` sehingga GeoNetAgent collector langsung merespons. - -| Komponen | Peran | -|----------|-------| -| `AgentTokenSyncService` | Push create/revoke/delete ke `geonetagent_dev.agent_tokens` | -| DB connection `geonetagent` | Config di `config/database.php`, env: `GEONETAGENT_DB_*` | -| DB user | `geonet_portal` — privileges: INSERT, SELECT, UPDATE, DELETE pada `agent_tokens` | -| Fallback | Jika `GEONETAGENT_DB_USERNAME` kosong, sync di-skip (warning log), geonet-console tetap jalan | - -**Alur setelah implementasi:** -``` -UI Create Token (geonet-console) - → INSERT ke service_tokens (geonet_console DB) ← audit trail - → INSERT ke agent_tokens (geonetagent_dev DB) ← validasi aktual collector - → Token ditampilkan sekali → user copy ke config.json agent -``` - -## Zero Impact pada GeoNetAgent - -- GeoNetAgent collector (`auth.py`) tetap membaca `agent_tokens` di `geonetagent_dev` — tidak ada perubahan kode -- Tidak ada perubahan pada agent PowerShell -- Sync bersifat additive — jika geonet-console tidak bisa connect ke `geonetagent_dev`, token di `service_tokens` tetap tersimpan dan error hanya di-log - ---- - -# Informasi Infrastruktur - -## Host SSH - -| Host | IP | Port | User | Fungsi | -|------|-----|------|------|--------| -| Mikrotik | 10.100.1.1 / 192.168.0.1 | 255 | admin | Gateway, routing, firewall | -| Reverse proxy | 10.100.1.24 | 22 | root | Nginx, Docker, stack `/opt/stacks/*` | -| Main database | 10.100.1.25 | 22 | root | PostgreSQL, SQL Server | -| AD-LDAP | 10.100.1.40 | 22 | Administrator | Windows Server 2012 R2 AD | -| Main webserver | 10.100.1.41 | 22 | Administrator | Web server | -| Zabbix | 10.100.1.42 | 22 | root | Monitoring Server | -| Ollama (aiopr) | 10.100.1.26 | 22 | geonet/root | AI inference (POC) | -| QNAP | 10.100.1.10 | 22 | admin | NAS SMB | - -## Model Kerja - -Edit kode di laptop → deploy via SSH → build & run di server. **Kredensial `.env` hanya di server**, jangan sync dari laptop. - -## Deploy Commands - -```powershell -.\scripts\deploy-geonet-console.ps1 -.\scripts\deploy-databaselist.ps1 -.\scripts\deploy-sqlservercheck.ps1 -.\scripts\deploy-databaselist.ps1 -NoBuild # restart tanpa rebuild -``` - ---- - -# Status Fitur (geonet-console) - -## Sudah Ada - -- Laravel 11, PostgreSQL (app + audit), LDAP auth & manajemen user/grup -- Multi database dinamis (SQL Server, PostgreSQL, MySQL/MariaDB) -- Docker + deploy script + Nginx reverse proxy -- Audit log web/API + beacon page-view/duration -- API v1 + Passport OAuth2 + API token + Swagger UI -- **Service Tokens** — Bearer token management untuk microservice (GeoNetAgent, Databaselist, dll.) di `/api-clients` -- Service layer kuat (15+ services, termasuk `ServiceTokenService`) -- UI: Turbo SPA, dark/light/system, PWA install, tabel mobile action sheet - -## Partial - -- API Management (belum gateway/rate-plan penuh) -- Security (belum MFA/SSO/RBAC granular) -- Audit immutable (belum DB trigger/hash chain) -- PWA (belum push notification & background sync) -- Production hardening (Tailwind CDN di prod, default password di compose example) -- Clean architecture (Application layer ada, Domain belum) - -## Belum - -- CMS, MFA, SSO user (SAML/OIDC), Maker Checker, Four Eyes Principle -- Repository pattern, DTO formal, Event driven, Queue processing -- Approval queue UI - ---- - -# Ollama + NAS Project Search - -**Status:** Direncanakan (belum diimplementasi di geonet-console). - -**Dokumen lengkap:** `server/ollama-nas-project-search-requirements.md` - -### Ringkasan Keputusan - -| Pertanyaan | Jawaban | -|------------|---------| -| Ollama bisa langsung scan `\\10.100.1.10\project`? | **Tidak** — perlu **indexer + PostgreSQL** | -| Multi-folder (project, Marketing, dll.)? | **Ya** — via env **indexer**, bukan env Ollama | -| Host Ollama POC & CPU | **VM `10.100.1.26` (aiopr)** — dedicated Ubuntu 22.04 | -| Host Ollama GPU (target) | Migrasi **Windows 11 + GPU** (~6 bulan) | -| Model Ubuntu → Windows portable? | **Ya** — copy `~/.ollama/models/` atau `ollama pull` ulang | -| Indeks RAG pindah ke PC Windows? | **Tidak perlu** — tetap di PostgreSQL `10.100.1.25` | -| License code / tanggal expired dari PDF? | **Ya** — `license_registry` + parser terstruktur | - -### API Target (geonet-console) - -| Endpoint | Method | Fungsi | -|----------|--------|--------| -| `/api/v1/project-search/ask` | POST | Query natural language + optional `sources[]` | -| `/api/v1/project-search/index/status` | GET | Status indeks per source | -| `/api/v1/project-search/sources` | GET | Daftar source dari env | -| `/api/v1/license-search/ask` | POST | Query license natural language | -| `/api/v1/license-search/code/{code}` | GET | Lookup exact license code | -| `/api/v1/license-search/expiring` | GET | License mendekati expired | -| `/api/v1/license-search/reindex` | POST | Re-parse file (admin, audit) | - ---- - -# Checklist Sebelum Implementasi - -AI wajib memastikan: - -☐ Sudah membaca `context-index.md` - -☐ Sudah membaca `me.md` — profil & infrastruktur - -☐ Sudah membaca `perintah.md` — protokol sync - -☐ Sudah membaca rules yang relevan di `.cursor/rules/` - -☐ Sudah memahami status implementasi (`02-implementation-status.mdc`) - -☐ Sudah memahami arsitektur yang ada - ---- - -# Checklist Setelah Implementasi - -AI wajib memperbarui: - -☐ `perintah.md` — sync terakhir (wajib akhir sesi) - -☐ `me.md` — jika infrastruktur berubah - -☐ Rules yang relevan — jika workflow berubah - -☐ `AGENTS.md` — jika ada perubahan roadmap Ollama/NAS - -☐ `context-index.md` — jika ada dokumen baru - ---- - -# 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. -* Repository adalah sumber kebenaran utama. - ---- - -# 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. diff --git a/server-connection/context-index.md b/server-connection/context-index.md index fb20459..d526d7e 100644 --- a/server-connection/context-index.md +++ b/server-connection/context-index.md @@ -1,91 +1,11 @@ -# Context Index (AI Entry Point) — server-connection +# Context Index — Deprecated -> **Versi Dokumen:** 1.0.0 -> **Terakhir Diperbarui:** 2026-06-25 -> **Status:** Aktif -> **Pemilik:** Tim IT GIS Portal +> **Status:** Deprecated — jangan gunakan file ini. +> **Entry point resmi:** [`docs/context-index.md`](docs/context-index.md) (v2.x) +> **Deprecated sejak:** 2026-07-02 --- -## Tujuan +File ini adalah versi lama (v1.0.0, 2026-06-25) dan sudah digantikan oleh `docs/context-index.md`. -Dokumen ini merupakan **titik masuk utama (Single Entry Point)** bagi seluruh AI Agent dan Developer untuk workspace **server-connection**. - -Setiap AI **WAJIB** membaca dokumen ini terlebih dahulu sebelum melakukan analisis, implementasi, perubahan kode, refactoring, penghapusan, deployment, maupun pembuatan dokumentasi. - ---- - -## Filosofi - -- Dokumentasi adalah bagian dari source code. -- Repository merupakan sumber kebenaran utama (Single Source of Truth). -- AI tidak boleh mengandalkan riwayat percakapan. - ---- - -## Proyek dalam Workspace Ini - -| Proyek | URL | Status | Context Index | -|--------|-----|--------|---------------| -| **geonet-console** | https://console.gisportal.id | ✅ Production | [`geonet-console/context-index.md`](./geonet-console/context-index.md) | -| **databaselist** | https://databaselist.gisportal.id | ⚠️ Legacy (digantikan geonet-console) | — | - -> AI yang bekerja pada proyek spesifik **wajib membaca context-index proyek tersebut**, bukan file ini. - ---- - -## Infrastruktur Server - -| Role | IP | OS | SSH Command | -|------|----|----|-------------| -| Reverse Proxy | 10.100.1.24 | Linux (Debian) | `ssh -m hmac-sha1 root@10.100.1.24 -p 22` | -| Database (PostgreSQL + SQL Server) | 10.100.1.25 | Linux | `ssh -m hmac-sha1 root@10.100.1.25 -p 22` | -| Active Directory / LDAP | 10.100.1.40 | Windows Server | `ssh -m hmac-sha1 Administrator@10.100.1.40 -p 22` | -| NAS QNAP TS-932X | 10.100.1.10 | QTS | `ssh -i "$env:USERPROFILE\.ssh\id_ed25519" -o IdentitiesOnly=yes -m hmac-sha1 admin@10.100.1.10 -p 22` | -| Ollama AI (VM) | 10.100.1.26 | Ubuntu 22.04 | `ssh -i "$env:USERPROFILE\.ssh\id_rsa_geonet_laptop" -o IdentitiesOnly=yes -m hmac-sha1 root@10.100.1.26 -p 22` | -| Zabbix Monitor | 10.100.1.42 | Linux | `ssh -m hmac-sha1 root@10.100.1.42 -p 22` | - -> AI **wajib minta persetujuan user** sebelum menjalankan perintah SSH apapun. -> NAS QNAP & Ollama: wajib PowerShell (bukan CMD) agar `$env:USERPROFILE` terbaca. - ---- - -## Stack yang Berjalan di Reverse Proxy (10.100.1.24) - -| Stack | Path | Container | Port | -|-------|------|-----------|------| -| geonet-console | `/opt/stacks/geonet-console` | `geonet-console` | `8091` | -| my-portal (Next.js PWA) | `/opt/stacks/my-portal` | `my-portal` | `8092` | -| databaselist (legacy) | `/opt/stacks/databaselist` | `databaselist` | (legacy) | - -**Nginx configs:** `/etc/nginx/conf.d/production/` -**OSS proxy:** `/etc/nginx/conf.d/nas.conf` - ---- - -## Cara Transfer File ke Server (Windows → Linux) - -```powershell -# 1. Buat archive (tanpa vendor, .git) -tar -czf "$env:TEMP\project.tar.gz" ` - --exclude="vendor" --exclude=".git" --exclude="node_modules" ` - -C "D:\Project\app on git\server-connection\geonet-console" . - -# 2. Upload — WAJIB pakai Start-Process di PowerShell -Start-Process -FilePath "cmd.exe" -ArgumentList ` - '/c ssh -m hmac-sha1 root@10.100.1.24 -p 22 "cat > /tmp/project.tar.gz" < "%TEMP%\project.tar.gz"' ` - -Wait -NoNewWindow - -# 3. Extract di server -ssh -m hmac-sha1 root@10.100.1.24 -p 22 "tar -xzf /tmp/project.tar.gz -C /opt/stacks/geonet-console && rm /tmp/project.tar.gz" -``` - -> ⚠️ **JANGAN overwrite `.env`** saat deploy — `.env` server berisi credentials production. - ---- - -## Penutup - -Untuk detail implementasi setiap proyek, baca context-index masing-masing: - -- **geonet-console** → [`geonet-console/context-index.md`](./geonet-console/context-index.md) +AI Agent dan developer **wajib** membaca [`docs/context-index.md`](docs/context-index.md) sebagai Single Entry Point. diff --git a/server-connection/docs/changelog.md b/server-connection/docs/changelog.md index 3adad8c..0592cd4 100644 --- a/server-connection/docs/changelog.md +++ b/server-connection/docs/changelog.md @@ -2,6 +2,17 @@ --- +## [Doc 1.1.0] — 2026-07-02 + +### Changed +- `docs/context-index.md` — tandai `.cursor/context-index.md` sebagai Deprecated + +### Deprecated +- `context-index.md` (root) — redirect ke `docs/context-index.md` +- `.cursor/context-index.md` — redirect ke `docs/context-index.md` + +--- + ## [Doc 1.0.0] — 2026-06-29 ### Added (Dokumentasi) diff --git a/server-connection/docs/context-index.md b/server-connection/docs/context-index.md index ebc76eb..0db3add 100644 --- a/server-connection/docs/context-index.md +++ b/server-connection/docs/context-index.md @@ -95,7 +95,7 @@ Proyek ini menerapkan **AI Native Development**: | File | Isi | |------|-----| -| `.cursor/context-index.md` | Entry point detail (versi lama) | +| `.cursor/context-index.md` | ~~Entry point detail~~ **Deprecated** → gunakan `docs/context-index.md` | | `.cursor/me.md` | Profil user + inventaris infrastruktur | | `.cursor/rules/00-project-context.mdc` | Struktur repo, host SSH, deploy | | `.cursor/rules/01-enterprise-principles.mdc` | Prinsip enterprise & UX |