DeskPoint

DeskPoint adalah aplikasi IT service desk berbasis fullstack Next.js.

Tech Stack

• Next.js 16 App Router
• TypeScript
• Tailwind CSS v4
• Prisma ORM
• MySQL native
• Custom JWT session via httpOnly cookie
• Zod, React Hook Form

Development

npm install
npm run prisma:generate
npm run prisma:migrate
npm run db:seed
npm run dev

Environment

DATABASE_URL="mysql://user:password@127.0.0.1:3306/deskpoint"
AUTH_SECRET="change-this-secret-in-production"
APP_URL="http://localhost:3000"
ALLOWED_DEV_ORIGINS=""
SESSION_COOKIE_SECURE="true"
SETTINGS_ENCRYPTION_KEY=""

DATABASE_URL, AUTH_SECRET, dan APP_URL wajib tersedia saat deploy. Untuk production, gunakan secret kuat dan APP_URL domain HTTPS production.

Telegram bot token dan webhook secret dikonfigurasi lewat halaman Settings. Nilai disimpan terenkripsi di database memakai SETTINGS_ENCRYPTION_KEY jika tersedia, fallback ke AUTH_SECRET.

ALLOWED_DEV_ORIGINS opsional dan hanya diperlukan untuk development origin tambahan. Isi hostname tanpa path; protocol http:// atau https:// akan dinormalisasi otomatis. Pisahkan beberapa origin dengan koma.

SESSION_COOKIE_SECURE=false hanya untuk testing production lewat HTTP. Untuk production HTTPS, biarkan true atau kosong.

Jangan commit credential, export data, attachment, atau dump database ke repository.

Production Deploy

Deploy production disiapkan untuk PM2 pada port 3015.

Prasyarat server:

• Node.js dan npm tersedia.
• PM2 tersedia secara global: npm install -g pm2.
• Database MySQL/MariaDB production sudah dibuat.
• File .env sudah dibuat di server dan tidak dipull dari repository.

Jalankan:

chmod +x ./deploy.sh
./deploy.sh

Script deploy menjalankan:

• Validasi env wajib.
• Validasi folder upload public/uploads tersedia dan writable.
• npm ci.
• npm run prisma:generate.
• npm run prisma:migrate:deploy.
• npm run build.
• pm2 startOrReload ecosystem.config.cjs --env production.

Jika folder upload tidak writable, perbaiki ownership di server:

sudo chown -R $(whoami):$(whoami) public/uploads
chmod 755 public public/uploads

Manual command untuk migrasi production:

npm run prisma:migrate:deploy

Telegram Webhook

Admin dapat menyimpan bot token, webhook secret, dan set webhook dari halaman Settings. Webhook target memakai <APP_URL>/api/telegram/webhook.

Telegram Bot Commands

Command Telegram bersifat opsional, tapi direkomendasikan agar user mudah menemukan action bot.

Rekomendasi command yang diset via BotFather:

start - Mulai bot dan tampilkan menu
refresh - Refresh tombol menu sesuai role login

Cara set command lewat BotFather:

1. Buka chat Telegram dengan @BotFather.
2. Jalankan /mybots.
3. Pilih bot DeskPoint.
4. Pilih Edit Bot.
5. Pilih Edit Commands.
6. Kirim daftar command:

start - Mulai bot dan tampilkan menu
refresh - Refresh tombol menu sesuai role login

Command /refresh akan meminta bot mengirim ulang tombol menu utama sesuai role user yang terhubung ke telegramChatId.

Role dan Order Behavior

Role aplikasi:

• ADMIN: mengelola user, kategori, unit kerja, settings Telegram, report, semua order, dan action order penuh.
• TECHNICIAN: melihat order terbuka dan order yang ditugaskan, lalu menjalankan action teknisi.
• USER: membuat order dan melihat order miliknya sendiri.

Behavior menu order di web:

• Semua role aktif dapat membuat order lewat tombol Create Order di menu order, termasuk upload foto pelapor opsional maksimal 5 foto per order, maksimal 5MB per file, format JPG/PNG/WEBP/GIF.
• Nomor order memakai format YY.NNNNN, contoh 26.00001, dengan counter berurutan per tahun.
• USER hanya melihat order dengan requesterId miliknya.
• TECHNICIAN melihat order OPEN, order yang menjadi teknisi utama, dan order yang masuk assignment teknisi tersebut.
• ADMIN melihat semua order.
• ADMIN dapat assign/delegasi teknisi dan menghapus order sesuai status yang diizinkan.
• ADMIN dan TECHNICIAN dapat mengubah status order sesuai action yang tersedia di detail order.
• Detail matriks action per status ada di docs/ticket-order-behavior.md.

Dashboard

Dashboard menampilkan ringkasan sesuai role login:

• Total order, order aktif, selesai/verified, dan resolved rate.
• Jumlah order per status.
• Order yang butuh perhatian: open belum didelegasikan, pending, running lebih dari 1 hari, done belum verified.
• Quick actions sesuai permission role.
• Order terbaru sesuai akses role.

Menu /tickets memiliki summary cards auto-refresh tiap 10 detik lewat GET /api/tickets/summary. Polling berhenti saat tab browser tidak aktif.

Settings dan Role Access

Halaman /settings memiliki tab:

• Profil Akun: semua user aktif, untuk ganti nama, username, dan password.
• Telegram: admin only, untuk konfigurasi webhook bot.
• Manajemen Role: admin only, untuk custom akses role.

Admin selalu hardcoded full access agar tidak terkunci dari sistem.

Role TECHNICIAN dan USER bisa diatur akses menu dan CRUD:

• Lihat.
• Tambah.
• Ubah.
• Hapus.

Permission disimpan di tabel AppSetting key role_permissions.

Setup Master Data

Menu /setup memakai tab:

• Kategori Order.
• Unit Kerja.

Unit kerja disimpan di tabel Unit, dipakai oleh form user web dan registrasi Telegram. Route lama /setup/categories dan /setup/units redirect ke tab yang sesuai.

Attachment Storage

Attachment image disimpan lokal ke:

public/uploads/<orderNumber>/

Validasi upload:

• Maksimal 5 foto pelapor per order.
• Maksimal 5 foto teknisi per order.
• Maksimal 5MB per file.
• Format JPG/PNG/WEBP/GIF.

Jenis attachment:

• REQUESTER: foto pelapor saat create order web/Telegram.
• TECHNICIAN: foto teknisi saat action photo.

Catatan production:

• Cocok untuk VPS/PM2/npm start dengan filesystem persistent.
• Pastikan public/uploads writable dan tidak terhapus saat deploy.
• Untuk serverless atau multi-instance, gunakan shared volume atau object storage seperti S3/MinIO/R2.

Behavior bot Telegram:

• User belum terdaftar melihat menu Register Member dan Login.
• Register Member menjalankan registrasi interaktif: nama lengkap, username, pilih unit kerja dari data setup, lalu nomor telepon lewat tombol share contact Telegram. User baru dibuat role USER, status belum aktif, password default 12345; admin perlu aktivasi user.
• Setelah login, USER mendapat menu ➕ Buat Order, 📋 Order Saya, dan 🚫 Signout.
• USER dapat membuat order dari bot: pilih kategori, isi nama pelapor, isi lokasi, isi ext/telp, isi detail order, lalu bot membuat order dengan requester user tersebut. Setelah order dibuat, user bisa mengirim maksimal 5 foto problem/kondisi atau mengetik skip.
• USER dapat membuka 📋 Order Saya untuk melihat 20 order terbaru miliknya dan membuka detail order.
• Setelah login, TECHNICIAN mendapat menu 📝 My Jobs, 💬 Faq, dan 🚫 Signout.
• TECHNICIAN memakai My Jobs untuk melihat job NEW/RUNNING, membuka detail, check order, upload foto, set done, dan forward teknisi sesuai status.
• Setelah login, ADMIN mendapat menu Task List, Find Job, Create Order, Faq, dan Signout.
• ADMIN dapat melihat semua order per status, mencari order by nomor, membuat order, edit order, delegasi follow up, forward teknisi, hapus order, close order, dan melihat foto/history sesuai status.

Default Seed Login

Seed default membuat satu user admin untuk development lokal. Jangan gunakan credential seed untuk production. Ganti password setelah login pertama jika seed pernah dijalankan di environment selain lokal.

Lihat prisma/seed.ts untuk credential development default.