Generator Laporan Analisis Tiket (GMN Freshservice)

Atribut	Nilai
Versi	1.0.0
Tanggal	20 Oktober 2026
Status	Disetujui (Approved)
Pembaca	Semua Tim (Manajemen, Service Desk, Developer, QA)
Pembaruan Terakhir	Saat penyesuaian aturan klasifikasi SLA

Intinya dalam 3 kalimat:
Aplikasi ini membaca riwayat aktivitas (audit trail) tiket Freshservice dan mengubahnya menjadi laporan Excel 3 sheet yang adil dan transparan. Sistem menghitung secara otomatis berapa lama waktu pengerjaan di pihak IT, waktu tunggu di pihak pemohon/user, waktu vendor, dan waktu rapat bersama. Dengan laporan ini, evaluasi SLA tidak lagi saling menyalahkan karena setiap menit tercatat lengkap dengan bukti pesan dan statusnya.

1. Daftar Dokumen & Panduan Membaca

Seluruh dokumentasi teknis, bisnis, operasional, dan pengujian tersimpan rapi di dalam folder docs/:

Kategori	Dokumen Kunci	Keterangan

| Desain Teknis & Data | docs/03-desain/FDD.md
docs/03-desain/TDD.md
docs/03-desain/Arsitektur.md
docs/03-desain/Kamus-Data-dan-DFD.md
docs/03-desain/ADR/ | Desain fungsional, arsitektur modul Odoo, kamus kolom Excel, dan catatan keputusan arsitektur (ADR-01 s/d ADR-03) |

2. Fitur Utama

Two-Tier Synchronization: Tarik daftar tiket secara instan tanpa freeze, dan ambil rincian lengkap (aktivitas audit trail + riwayat chat) secara on-demand saat tiket dibuka.
Mesin Hitung Jam Kerja Efektif:
- Hari Kerja: Senin – Jumat (08:30 – 17:30 WIB).
- Istirahat: 12:30 – 13:30 WIB (tidak dihitung sebagai jam kerja).
- Libur Nasional: Terintegrasi dengan kalender libur Indonesia (2024–2026) dan kalender Odoo.
- Konversi 8 jam kerja efektif = 1 hari kerja.
Klasifikasi Tanggung Jawab Adil (Fair Responsibility Logic):
- Membagi waktu tiket ke dalam 8 kategori (bucket).
- Deteksi otomatis balasan agen (Ball-in-Court Analysis) untuk menandai status ambigu (needs_verification).
- Deteksi undangan rapat Zoom/Teams otomatis ke bucket Scheduled Meeting (Bersama).
- Pemisahan durasi Resolved oleh bot otomatis sistem (user_after_auto_resolve) agar tidak menyalahkan user secara keliru.
Generator Laporan Excel 3 Sheet:
- Sheet 1 (Ringkasan & Bottleneck KPI): Kartu KPI, breakdown persentase tanggung jawab, dan tabel ranking segmen bottleneck terlama.
- Sheet 2 (Audit Trail & Chronology): Rekonstruksi kronologis setiap menit aktivitas tiket dengan formula total otomatis.
- Sheet 3 (Conversations & Notes): Transkrip lengkap percakapan dan catatan tiket antara agen dan pemohon.
Dukungan Multi-Tiket: Ekspor perbandingan ranking bottleneck untuk bahan rapat koordinasi mingguan tim Service Desk.

3. Panduan Cepat (Quick Start dalam 15 Menit)

3.1 Prasyarat

Odoo 19.0 Community / Enterprise (Python 3.10+)
Modul python xlsxwriter dan requests terpasang di environment Odoo
Akun admin Freshservice dengan hak akses API (API Key)

3.2 Konfigurasi Koneksi

Masuk ke Odoo dengan hak akses Administrator.
Buka menu Settings > Freshservice Configuration.
Masukkan URL Freshservice (contoh: https://servicedesk.perusahaan.co.id) dan API Key.
Atur batas sinkronisasi (default: 200 tiket).
Klik tombol Uji Koneksi untuk memastikan status terhubung.

3.3 Menjalankan Sinkronisasi & Analisis

Buka menu Freshservice > Daftar Tiket.
Klik tombol Tarik Tiket Terbaru pada bagian atas tabel.
Buka salah satu tiket yang ingin dianalisis (misal: Tiket #9658).
Klik tombol Analisis Bottleneck (Excel) di pojok kanan atas formulir tiket.
Pilih tipe laporan: Analisis Detail Bottleneck Tiket Tunggal.
Klik Unduh Laporan Excel. File .xlsx 3 sheet akan otomatis diunduh ke komputer Anda.

4. Struktur Folder Modul

gmn_module_v2/
├── README.md                      # Dokumentasi utama proyek ini
├── CHANGELOG.md                   # Catatan rilis dan riwayat perubahan
├── docs/                          # Folder seluruh dokumen pendukung
│   ├── 00-INDEX.md                # Indeks dokumen dan panduan membaca
│   ├── 01-bisnis/                 # BRD (Business Requirements Document)
│   ├── 02-kebutuhan/              # SRS & Katalog Aturan Bisnis
│   ├── 03-desain/                 # FDD, TDD, Arsitektur, Kamus Data, ADR
│   ├── 04-pengujian/              # Test Plan, Test Case, Laporan Validasi, UAT
│   ├── 05-operasional/            # Panduan Pengguna, SOP, Runbook, Konfigurasi
│   └── 06-manajemen/              # Risiko, Change Request, Traceability Matrix, Glosarium
└── gmn_freshservice/              # Kode sumber addon Odoo 19
    ├── __init__.py
    ├── __manifest__.py
    ├── models/                    # Model Odoo: ticket, stage_log, conversation, settings
    ├── services/                  # Client integrasi Freshservice REST API v2
    ├── wizard/                    # Wizard export laporan Excel via xlsxwriter
    ├── views/                     # XML view Odoo (form, list, settings, menu)
    ├── data/                      # Demo data & konfigurasi default
    ├── security/                  # Hak akses ir.model.access.csv
    └── tests/                     # Unit test otomatis & validasi acceptance

5. Catatan Penulisan & Verifikasi Integritas (Self-Check)

Daftar File Kode Sumber yang Dianalisis:
- gmn_freshservice/__manifest__.py
- gmn_freshservice/models/gmn_freshservice_ticket_v01.py
- gmn_freshservice/models/gmn_freshservice_ticket_stage_log_v01.py
- gmn_freshservice/models/gmn_freshservice_ticket_conversation_v01.py
- gmn_freshservice/models/gmn_res_config_settings_v01.py
- gmn_freshservice/services/gmn_freshservice_client_v01.py
- gmn_freshservice/wizard/gmn_freshservice_ticket_bottleneck_wizard_v01.py
- gmn_freshservice/tests/test_responsibility_rules.py
Daftar Item [PERLU KONFIRMASI]:
- PK-01: Nama resmi departemen pemohon SLS apakah ada kepanjangan divisi spesifik di luar data Freshservice? (Asumsi saat ini: SLS merepresentasikan departemen operasional pemohon).
- PK-02: Jadwal rilis resmi ke server staging user apakah mengikuti jadwal sprint dua mingguan tim IT?
- PK-03: Kebijakan retensi data teks pesan percakapan di database Odoo lokal (apakah dipangkas setelah 1 tahun atau disimpan selamanya).
Daftar Aturan yang Semula Direncanakan [PLANNED] dan Telah Berhasil [IMPLEMENTED] di Kode:
- Aturan A (Sticky State & Event Status Eksplisit): Telah diimplementasikan di gmn_freshservice_ticket_v01.py::action_sync_from_freshservice.
- Aturan B (Ball-in-Court Analysis & Deteksi Ambiguitas): Telah diimplementasikan di gmn_freshservice_ticket_v01.py::_ball_in_court_check.
- Aturan C (User Setelah Auto-Resolve Sistem): Telah diimplementasikan di gmn_freshservice_ticket_v01.py::action_sync_from_freshservice.
- Aturan D (Deteksi Rapat Bersama & Pembatalan Zoom): Telah diimplementasikan di gmn_freshservice_ticket_v01.py::action_sync_from_freshservice.
- Aturan E (First Ack vs First Meaningful Response): Telah diimplementasikan di gmn_freshservice_ticket_v01.py::action_sync_from_freshservice.
- Aturan F (Override Manual & Cut-off as_of): Telah diimplementasikan di gmn_freshservice_ticket_stage_log_v01.py dan wizard gmn_freshservice_ticket_bottleneck_wizard_v01.py.
Daftar Baris GAP pada Traceability Matrix:
- GAP-01: Belum ada test otomatis khusus UI/JS web client saat tombol 'Tarik Tiket Terbaru' ditekan (ditutup via pengujian fungsional UAT manual).
Konfirmasi Privasi:
- Seluruh data contoh, transkrip pesan, dan cuplikan pengujian telah dianonimkan 100%. Tidak ada alamat email riil, nomor telepon, link rapat Zoom aktif, maupun passcode rapat yang disertakan dalam dokumentasi ini.

README.md Unescape Escape