# Jorgasisten Blueprint

## Product Vision

Jorgasisten membantu operator Johan Garage mengelola data operasional melalui Telegram tanpa membuka Google Sheets secara manual. Bot memahami struktur spreadsheet yang berubah, memilih sheet yang sesuai, lalu menjalankan operasi data dengan aman.

## Target User

- Owner atau admin Johan Garage.
- Staff operasional yang perlu mencatat transaksi, booking, stok, atau catatan kerja.
- Operator yang ingin bertanya cepat berdasarkan data Google Sheets.

## Core Features

- Tanya data dari Google Sheets.
- Chat umum seperti ChatGPT untuk ide, penjelasan, rumus, coding, atau pertanyaan umum.
- Input data baru ke sheet paling relevan.
- Update data lama dengan filter yang jelas.
- Hapus data dengan guardrail confidence dan admin check.
- Buat sheet/tabel baru dari Telegram.
- Ganti struktur kolom/header dari Telegram.
- Rename sheet dari Telegram.
- Hapus sheet penuh dengan admin-only guardrail.
- Konfirmasi inline untuk hapus data, ganti header, rename sheet, dan hapus sheet penuh.
- Tombol aksi setelah hasil data: refresh, detail, edit, hapus, dan ringkas sheet.
- Audit log otomatis ke sheet khusus untuk operasi write yang sukses.
- Multi-spreadsheet registry: tambah spreadsheet dari Telegram, pilih spreadsheet aktif per chat, dan set default.
- Ringkasan data berdasarkan sheet, periode, kategori, atau filter.
- Schema discovery otomatis untuk semua sheet.
- JSON decision output yang bisa diaudit.

## User Flow

1. User mengirim pesan natural di Telegram.
2. Bot membaca katalog Google Sheets terbaru.
3. AI parser mengklasifikasikan intent, sheet, operasi, filters, dan data.
4. Executor memvalidasi confidence, permission, dan target sheet.
5. Untuk aksi berisiko, bot meminta konfirmasi inline.
6. Bot menjalankan operasi Google Sheets setelah lolos guardrail.
7. Untuk write yang sukses, bot menulis audit log.
8. Bot mengirim balasan singkat dan jelas ke user.

## Telegram Menu Flow

- Start
- Chat Umum
- Tanya Data
- Tambah Data
- Update Data
- Hapus Data
- Ringkasan
- Sheet/Tabel
- Spreadsheet
- Bantuan

User tetap bisa langsung mengirim pesan bebas tanpa memilih menu.

Submenu Sheet/Tabel:

- Lihat Semua Sheet
- Buat Sheet Baru
- Ganti Header/Kolom
- Rename Sheet
- Hapus Sheet Penuh
- Kembali

Inline action setelah hasil data:

- Refresh
- Detail
- Edit
- Hapus
- Ringkas Sheet Ini

Submenu Spreadsheet:

- Spreadsheet Aktif
- Daftar Spreadsheet
- Tambah Spreadsheet
- Pilih Spreadsheet: realtime via tombol
- Set Default Spreadsheet: realtime via tombol
- Kembali

## Google Sheets Design

Bot tidak membuat asumsi sheet tetap. Setiap request membaca:

- Nama sheet
- Header kolom
- Contoh data
- Jumlah row

Untuk input data, bot hanya mengisi kolom yang sudah ada. Kolom yang tidak diberikan diisi `-` jika operasi sudah cukup jelas.

## AI Decision Flow

Output parser wajib mengikuti bentuk:

```json
{
  "intent": "input_data",
  "sheet_name": "Transaksi",
  "operation": "create",
  "confidence": 92,
  "missing_fields": [],
  "data": {},
  "filters": {},
  "reason": "Sheet cocok dari nama kolom dan contoh data.",
  "user_reply": "Siap, data sudah saya siapkan."
}
```

Jika confidence rendah, executor tidak memaksa operasi dan meminta klarifikasi.

## System Architecture

```text
Telegram User
  -> Aiogram Bot
  -> AssistantService
     -> GoogleSheetsClient: schema and CRUD
     -> OpenAICompatibleClient: decision JSON
     -> OperationExecutor: permission and write guardrail
     -> Audit Log: Bot_Log sheet
  -> Google Sheets API
```

Project ini bot-only. Tidak ada web dashboard, REST API, atau HTTP health endpoint.
Monitoring runtime dilakukan lewat `docker compose ps`, `docker compose logs bot`,
dan command `/health` dari Telegram.

Multi-spreadsheet state disimpan di file JSON lokal `data/spreadsheets.json`.
File ini dimount ke container sebagai volume agar daftar spreadsheet tidak hilang saat restart.

## External Integration Design

- Telegram Bot API: polling mode.
- Google Sheets API: spreadsheet metadata, values read/append/update, batch update for delete.
- OpenAI-compatible Chat Completions API: JSON decision parser.

## Security

- Secret hanya lewat environment variable.
- Daftar spreadsheet tambahan disimpan di file registry lokal, bukan hardcoded di source.
- Service account JSON disimpan sebagai base64.
- Write operation bisa dibatasi ke admin Telegram.
- Delete operation membutuhkan confidence lebih tinggi dan konfirmasi inline.
- Ganti header, rename sheet, dan hapus sheet penuh membutuhkan konfirmasi inline.
- Operasi write yang sukses dicatat ke audit log.
- Error message ke user tidak membocorkan stack trace atau secret.

## Roadmap

1. Tambahkan audit log ke sheet khusus.
2. Tambahkan mode approval untuk update/delete.
3. Tambahkan webhook Telegram jika domain publik sudah tersedia.
4. Tambahkan scheduled report harian.
5. Tambahkan cache schema dengan TTL untuk spreadsheet besar.