🏪 Asisten Kasir Warung Madura (AI Telegram Bot)

Asisten pintar berbasis AI untuk pemilik Warung Madura. Cukup kirim pesan di Telegram seperti ngobrol biasa, semua catatan penjualan, stok barang, barang masuk (kulakan), pemakaian sendiri, dan laporan omzet langsung tercatat otomatis dan rapi di Google Sheets.

Tidak perlu aplikasi kasir yang ribet atau mesin kasir mahal. Pemilik warung cukup pakai HP dan mengetik bahasa sehari-hari!

✨ Kemampuan Utama

• 🗣️ Paham Bahasa Sehari-hari: Tidak perlu menghafal kode perintah seperti /help, /start, atau tombol kaku. Ketik saja seperti ngomong ke kasir.

• 📒 Buku Kas Otomatis di Google Sheets: Semua transaksi langsung tersimpan rapi di Google Sheets, bisa dicek langsung dari HP kapan saja dan di mana saja.

• 🍜 Pintar Membedakan Barang: Kalau mengetik barang yang punya banyak varian (misal "indomie"), bot akan bertanya ramah: "Indomie yang mana Bos? Goreng atau Soto?".

• 💳 Mendukung Berbagai Cara Bayar: Catat bayar Tunai, Transfer, atau QRIS. Kalau lupa sebut cara bayar, bot akan mengingatkan dengan ramah.

• 🔒 Aman dari Salah Catat (Dobel Input): Bot menjaga agar pesan yang terkirim dua kali tidak mencatat transaksi berulang.

Related MCP server: TaskUp MCP Server

💬 Contoh Cara Ngobrol dengan Bot

Pemilik warung atau penjaga toko cukup mengetik seperti ini di Telegram:

1. 🛒 Catat Penjualan

Bos: terjual 2 indomie goreng tunai
Bot: Siap Bos! 2 Indomie Goreng Spesial sudah dicatat (Tunai). Total Rp6.000.

(Kalau tidak sebut cara bayar)
Bos: jual 1 aqua
Bot: Siap Bos, penjualan sudah dicatat sementara. Bayarnya Tunai, Transfer, atau QRIS?
Bos: tunai dong
Bot: Siap Bos! Penjualan Aqua 600ml sudah dicatat Tunai.

2. 📦 Cek Stok Barang

Bos: stok rokok marlboro tinggal berapa?
Bot: Stok Marlboro Filter Black sisa 12 bungkus, Bos.

Bos: barang apa aja yang mau habis?
Bot: Ini barang yang stoknya menipis, Bos: Telur Ayam (sisa 3 butir), Aqua 600ml (sisa 4 botol).

3. ➕ Catat Kulakan / Barang Masuk

Bos: indomie masuk 2 kardus
Bot: Siap Bos! Stok Indomie Goreng berhasil ditambah 80 bungkus.

4. 🍜 Catat Barang Dipakai Sendiri

Bos: aku ambil 1 indomie buat makan
Bot: Dicatat Bos, 1 Indomie dipakai sendiri. Stok sudah dikurangi tanpa masuk omzet kasir.

5. 💰 Cek Omzet & Penjualan Hari Ini

Bos: omzet hari ini berapa?
Bot: Laporan penjualan hari ini: Total 18 transaksi, 42 barang terjual. Total omzet Rp245.000, Bos!

📋 Struktur Buku Warung (Google Sheets)

Semua data tersimpan di spreadsheet Google Sheets Anda dengan tab-tab berikut:

1. Produk: Daftar barang, harga jual, harga modal, stok, dan batas stok minimum.

2. Transaksi: Riwayat nota penjualan beserta tanggal dan metode pembayaran.

3. Detail_Transaksi: Rincian produk apa saja yang dibeli pada setiap transaksi.

4. Stok_Log: Catatan keluar-masuk stok barang (penjualan, kulakan, atau barang terpakai).

🚀 Panduan Memulai (Setup Singkat)

1. Kebutuhan Awal

• Komputer / Server dengan Python 3.11+.

• Akun Google Cloud dengan akses Google Sheets API (menggunakan Service Account).

• Spreadsheet Google Sheets yang sudah di-share akses Editor ke email service account.

• Token Bot Telegram dari @BotFather.

• API Key Google Gemini AI dari Google AI Studio.

2. Pemasangan

1. Unduh dan pasang dependensi:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. Atur konfigurasi (.env): Salin berkas .env.example menjadi .env:

   cp .env.example .env

   Lalu buka berkas .env dan isi data Anda:

   # Kunci Google Sheets
   GOOGLE_CREDENTIALS_PATH=credentials/google-service-account.json
   GOOGLE_SPREADSHEET_ID=masukkan_id_spreadsheet_anda_disini
   
   # Kunci AI & Telegram
   GEMINI_API_KEY=masukkan_api_key_gemini_anda
   TELEGRAM_BOT_TOKEN=masukkan_token_bot_telegram_anda

3. Jalankan Bot:

   python -m app.main --telegram

   Buka bot Anda di Telegram, lalu sapa dengan: Halo! atau langsung ketik transaksi pertama Anda!

🛠️ Informasi untuk Pengembang (Developer Notes)

Bagi pengembang yang ingin memodifikasi atau menguji sistem:

• Menjalankan Tes Otomatis (Unit & Integration Tests):

  .venv/bin/pytest -q

  (Pengujian menggunakan mock data, tidak memotong kuota API Google maupun Telegram).

• Menjalankan Mode MCP (Model Context Protocol):

  .venv/bin/python -m app.main --mcp

• Menjalankan via Docker:

  docker compose run --rm warung-agent

Dibuat untuk memudahkan wirausaha dan UMKM warung mengelola usaha dengan bantuan kecerdasan buatan tanpa ribet. 🇮🇩