gmn_custom_module_v18/README.md

# 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 |
|---|---|---|
<!-- | **Daftar Isi & Indeks** | [`docs/00-INDEX.md`](docs/00-INDEX.md) | Peta navigasi seluruh dokumen dan urutan baca pemula |
| **Bisnis & Kebutuhan** | [`docs/01-bisnis/BRD.md`](docs/01-bisnis/BRD.md)<br>[`docs/02-kebutuhan/SRS.md`](docs/02-kebutuhan/SRS.md)<br>[`docs/02-kebutuhan/Katalog-Aturan-Bisnis.md`](docs/02-kebutuhan/Katalog-Aturan-Bisnis.md) | Alasan proyek dibuat, spesifikasi kebutuhan FR/NFR, dan katalog aturan RULE-01 s/d RULE-12 | -->
| **Desain Teknis & Data** | [`docs/03-desain/FDD.md`](docs/03-desain/FDD.md)<br>[`docs/03-desain/TDD.md`](docs/03-desain/TDD.md)<br>[`docs/03-desain/Arsitektur.md`](docs/03-desain/Arsitektur.md)<br>[`docs/03-desain/Kamus-Data-dan-DFD.md`](docs/03-desain/Kamus-Data-dan-DFD.md)<br>[`docs/03-desain/ADR/`](docs/03-desain/ADR/) | Desain fungsional, arsitektur modul Odoo, kamus kolom Excel, dan catatan keputusan arsitektur (ADR-01 s/d ADR-03) |
<!-- | **Pengujian & Validasi** | [`docs/04-pengujian/Test-Plan.md`](docs/04-pengujian/Test-Plan.md)<br>[`docs/04-pengujian/Test-Case.md`](docs/04-pengujian/Test-Case.md)<br>[`docs/04-pengujian/Laporan-Validasi.md`](docs/04-pengujian/Laporan-Validasi.md)<br>[`docs/04-pengujian/UAT.md`](docs/04-pengujian/UAT.md) | Rencana uji, skenario uji TC-01 s/d TC-08, bukti validasi Tiket #9658, dan lembar UAT pengguna |
| **Operasional & Panduan** | [`docs/05-operasional/Panduan-Pengguna.md`](docs/05-operasional/Panduan-Pengguna.md)<br>[`docs/05-operasional/SOP-Status-Tiket.md`](docs/05-operasional/SOP-Status-Tiket.md)<br>[`docs/05-operasional/Runbook.md`](docs/05-operasional/Runbook.md)<br>[`docs/05-operasional/Konfigurasi.md`](docs/05-operasional/Konfigurasi.md) | Panduan langkah demi langkah agen/supervisor, SOP pemilihan status, instalasi, dan parameter konfigurasi |
| **Manajemen & Tata Kelola**| [`docs/06-manajemen/Risiko-dan-Known-Issues.md`](docs/06-manajemen/Risiko-dan-Known-Issues.md)<br>[`docs/06-manajemen/Change-Request-Perbaikan-Logic.md`](docs/06-manajemen/Change-Request-Perbaikan-Logic.md)<br>[`docs/06-manajemen/Keamanan-dan-Privasi.md`](docs/06-manajemen/Keamanan-dan-Privasi.md)<br>[`docs/06-manajemen/Traceability-Matrix.md`](docs/06-manajemen/Traceability-Matrix.md)<br>[`docs/06-manajemen/Roadmap.md`](docs/06-manajemen/Roadmap.md)<br>[`docs/06-manajemen/Glosarium.md`](docs/06-manajemen/Glosarium.md)<br>[`CHANGELOG.md`](CHANGELOG.md) | Daftar risiko, analisis dampak CR-01, matriks ketelusuran BR-FR-RULE-TC, peta jalan rilis, dan glosarium istilah | -->

---

## 2. Fitur Utama
1. **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.
2. **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.
3. **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.
4. **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.
5. **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
1. Masuk ke Odoo dengan hak akses Administrator.
2. Buka menu **Settings** > **Freshservice Configuration**.
3. Masukkan URL Freshservice (contoh: `https://servicedesk.perusahaan.co.id`) dan **API Key**.
4. Atur batas sinkronisasi (default: `200` tiket).
5. Klik tombol **Uji Koneksi** untuk memastikan status terhubung.

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

---

## 4. Struktur Folder Modul
```text
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)

1. **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`
2. **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).
3. **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`.
4. **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).
5. **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.