# Dokumentasi Fitur Leads - Adopsi Estimate (Final V1)

## 1. Ringkasan
Dokumen ini menjadi acuan final implementasi integrasi fitur **Estimate** pada modul **Leads**.
Fokus utama implementasi adalah **tracking aktivitas** lead secara lengkap, dengan kontrol akses yang jelas untuk owner, atasan langsung, dan shared user saat kondisi shared aktif.

## 2. Tujuan Bisnis
1. Memastikan aktivitas lead yang terkait estimate tercatat lengkap dan dapat diaudit.
2. Menjaga alur follow-up sales tetap tertib dengan auto-kontrol status shared saat estimate dibuat.
3. Menjamin aturan hak akses antar owner dan shared user berjalan konsisten.

## 3. Scope Fitur
### In Scope
1. Estimate dapat dibuat dari tahap lead mana pun.
2. Auto update `lead_shared` saat create estimate.
3. Permission matrix untuk lead dan estimate pada konteks lead.
4. Audit trail untuk event penting lead dan estimate.
5. Soft delete only untuk seluruh aksi delete.

### Out of Scope
1. Otomasi perubahan lead menjadi client.
2. Hard delete/permanent delete data.
3. Perubahan workflow modul lain di luar lead-estimate.

## 4. Definisi Data dan Entitas
### 4.1 Data Estimate yang Dipakai di Konteks Lead
1. `item`
2. `nilai`
3. `diskon`
4. `pajak`
5. `owner`

### 4.2 Definisi Owner
1. `owner lead` dan `owner estimate` tidak wajib sinkron.
2. Atasan yang diakui untuk eskalasi akses adalah **1 level langsung**.

## 5. Aturan Proses Inti
1. Estimate boleh dibuat pada tahap lead apa pun.
2. Saat terjadi `create estimate` pada lead, sistem wajib auto set `lead_shared = OFF`.
3. `lead_shared` boleh diubah kembali ke `ON` secara manual.
4. Perubahan status lead menjadi `client` hanya melalui aksi manual user berwenang.

## 6. Aturan Akses
### 6.1 Akses Estimate pada Konteks Lead
Aksi `view/edit/cancel` estimate diperbolehkan untuk:
1. `owner estimate`
2. `owner lead`
3. atasan langsung (1 level) dari owner estimate atau owner lead

### 6.2 Akses Shared User pada Lead
Saat `lead_shared = ON`, user dengan shared access diperbolehkan:
1. `edit/update` data lead
2. `deactive` lead (soft delete)

Batasan:
1. Hak shared user hanya untuk data lead, tidak otomatis berlaku ke estimate.
2. Shared user tidak boleh mengubah lead menjadi `client`.

## 7. Aturan Delete
1. Semua delete wajib menggunakan **soft delete**.
2. Hard delete/permanent delete tidak diperbolehkan untuk lead maupun estimate.

## 8. Audit Trail
### 8.1 Jenis Event yang Wajib Dicatat
1. `create`
2. `update`
3. `delete` (soft)
4. `status change`

### 8.2 Cakupan Audit
1. Semua perubahan terkait lead.
2. Semua perubahan estimate yang terkait lead.

### 8.3 Event Kritis yang Harus Eksplisit
1. `create estimate` (termasuk auto `lead_shared = OFF` oleh sistem)
2. perubahan manual `lead_shared` (`ON` atau `OFF`)
3. aksi manual ubah lead menjadi `client`
4. aksi edit/update/deactive oleh shared user saat shared aktif

### 8.4 Metadata Minimal per Log
1. `actor`
2. `timestamp`
3. `action/event_type`
4. `field_changed`
5. `old_value`
6. `new_value`
7. `source` (`manual` atau `system`)

## 9. Timeline Aktivitas Lead
### 9.1 Lokasi
1. Halaman: detail lead (`/leads/view/{id}`).
2. Posisi: panel kanan sebagai **Timeline Aktivitas**.
3. Sumber data: gabungan event lead dan estimate yang terhubung ke lead.

### 9.2 Struktur Informasi per Baris
1. `timestamp`
2. `event_type` (`create/update/delete/status change`)
3. `entity` (`lead` atau `estimate`)
4. `actor`
5. ringkasan perubahan singkat (mis. `lead_shared: ON -> OFF`)
6. indikator `source` (`manual/system`)

### 9.3 Aksi pada Timeline
1. Tombol `Lihat` untuk membuka detail perubahan (`field_changed`, `old_value`, `new_value`).
2. Tombol `Banding` untuk membandingkan nilai sebelum dan sesudah pada event update/status change.
3. Jika event tidak memiliki pasangan pembanding (mis. create), tombol `Banding` tidak aktif.

### 9.4 Filter dan Default Perilaku
1. Filter tipe event: `Semua`, `create`, `update`, `delete`, `status change`.
2. Filter entitas: `Semua`, `lead`, `estimate`.
3. Filter sumber: `Semua`, `manual`, `system`.
4. Sorting default: terbaru ke terlama.
5. Default tampilan awal: 20 event terbaru.
6. Pagination bertahap menggunakan `Load more`.

### 9.5 Rule Integritas Timeline
1. Event wajib append-only di histori (tidak boleh diubah/hapus dari aplikasi).
2. Event auto sistem wajib ditandai `source=system` (contoh: auto `lead_shared OFF` saat create estimate).
3. Event aksi user wajib ditandai `source=manual`.
4. Event soft delete tampil jelas sebagai `delete (soft)` pada timeline.

## 10. State Transition Ringkas
1. `lead_shared ON` -> shared user boleh edit/update/deactive lead.
2. `create estimate` -> sistem auto ubah `lead_shared OFF`.
3. `lead_shared OFF` -> hak edit/update shared user berhenti sampai diaktifkan manual lagi.
4. `lead status -> client` hanya lewat aksi manual oleh user berwenang.

## 11. Acceptance Criteria
1. User dapat membuat estimate dari stage lead apa pun.
2. Create estimate otomatis mematikan `lead_shared`.
3. `lead_shared` dapat dinyalakan kembali secara manual.
4. Shared user (saat shared ON) bisa edit/update/deactive lead.
5. Shared user tidak bisa mengubah lead menjadi client.
6. Hak akses estimate mengikuti rule owner/atasan langsung (1 level).
7. Tidak ada hard delete; seluruh delete berjalan soft delete.
8. Semua event audit yang disepakati muncul di activity history.
9. Lead dapat menjadi `client` melalui aksi manual.

## 12. Checklist Implementasi
- [x] Rule create estimate dari stage lead mana pun aktif.
- [x] Auto `lead_shared OFF` saat create estimate aktif.
- [x] Toggle manual `lead_shared ON/OFF` tersedia sesuai hak akses.
- [x] Permission estimate (owner lead, owner estimate, atasan 1 level) aktif.
- [x] Shared access lead (edit/update/deactive) berjalan hanya saat shared ON.
- [x] Pembatasan shared user untuk status `client` aktif.
- [x] Soft delete diterapkan pada lead dan estimate.
- [x] Hard delete dinonaktifkan dari aplikasi.
- [x] Activity history mencatat seluruh event wajib + metadata minimal.
- [x] Panel Timeline Aktivitas tampil pada detail lead.
- [x] Filter timeline (event type/entity/source) berfungsi.
- [x] Default 20 data terbaru + `Load more` aktif.
- [x] Detail `Lihat` dan `Banding` berjalan sesuai rule.

## 13. Checklist UAT
- [x] Estimate berhasil dibuat pada setiap stage lead.
- [x] Setelah estimate dibuat, `lead_shared` langsung OFF otomatis.
- [x] `lead_shared` dapat diaktifkan manual kembali.
- [x] Shared user dapat edit/update lead saat shared ON.
- [x] Shared user dapat deactive lead (soft delete) saat shared ON.
- [x] Shared user tidak dapat set status lead ke client.
- [x] Owner/atasan 1 level dapat view/edit/cancel estimate sesuai aturan.
- [x] Tidak ada hard delete di lead/estimate.
- [x] Log audit menampilkan actor, waktu, perubahan lama/baru, dan sumber aksi.
- [x] Timeline menampilkan gabungan event lead dan estimate terkait secara urut.
- [x] Event `source=system` dan `source=manual` tampil benar.
- [x] Event `delete (soft)` terbaca jelas pada timeline.
- [x] Tombol `Lihat` menampilkan detail perubahan field secara akurat.
- [x] Tombol `Banding` hanya aktif pada event yang bisa dibandingkan.

### 13.1 Bukti UAT Teknis (Verifikasi Kode)
1. Endpoint delete file lead hanya soft delete record, tanpa hapus fisik file:
   `app/Controllers/Leads.php` (`delete_file`).
2. Update foto contact lead tidak lagi menghapus file lama secara permanen:
   `app/Controllers/Leads.php` (`save_profile_image`).
3. Delete comment estimate hanya soft delete record, tanpa hapus fisik attachment:
   `app/Controllers/Estimates.php` (`delete_comment`).
4. Delete image estimate tidak lagi menghapus file fisik di storage:
   `app/Controllers/Estimates.php` (`delete_image`).
5. Validasi scan kode:
   Tidak ada pemanggilan `delete_app_files(...)` atau `delete_file_from_directory(...)`
   pada `Leads.php`, `Estimates.php`, dan `Clients_model.php`.
6. Shared-only user diblokir untuk convert lead ke client:
   `app/Controllers/Leads.php` (`make_client_modal_form`, `save_as_client`)
   dengan helper guard akses convert.

## 14. Metadata Dokumen
- Nama dokumen: `LEADS_PRIORITAS_DATA_SPEC.md`
- Tanggal final: 2026-04-17
- Status: Final Disetujui User
- Catatan: Dokumen ini menggantikan draft sebelumnya untuk kebutuhan integrasi lead-estimate.

## 15. Acuan Implementasi Teknis (Tahap Lanjutan)
Catatan fase:
1. Bagian **otomasi convert-to-client** diabaikan pada fase ini (guard akses shared user tetap diterapkan).
2. Fokus fase ini hanya pada shared behavior, permission estimate, audit, dan timeline lead.

### 15.1 Prioritas P0 (Wajib Dulu)
1. Auto shared OFF saat create estimate.
2. Penyesuaian permission estimate sesuai matrix final.
3. Shared user boleh edit/update/deactive lead saat shared ON.
4. Hardening endpoint share agar validasi akses per-lead wajib.

### 15.2 Breakdown Per File (P0)
1. `app/Controllers/Estimates.php`
- Tambahkan langkah setelah create estimate sukses untuk set lead sharing ke OFF (`is_public=0`, `is_selected_members=0`) pada lead terkait estimate.
- Gunakan transaksi yang sama dengan save estimate agar perubahan konsisten.
- Tambahkan event audit bertipe `system` untuk aksi auto shared OFF.

2. `app/Controllers/Security_Controller.php`
- Refactor `can_access_this_estimate()` agar akses estimate mengikuti:
  - owner estimate, atau
  - owner lead, atau
  - atasan langsung 1 level dari owner estimate/owner lead.
- Pertahankan kompatibilitas dengan scope permission existing (`all/team/own/own_only`), namun tambahkan rule matrix final sebagai guard utama akses data estimate.

3. `app/Models/Estimates_model.php`
- Selaraskan query list/filter estimate agar hasil data konsisten dengan rule akses pada `can_access_this_estimate()`.
- Pastikan shared lead tidak otomatis berarti boleh akses estimate jika tidak memenuhi matrix final.

4. `app/Controllers/Leads.php`
- Ubah gate edit/update/deactive lead agar shared user yang valid saat shared ON dapat melakukan aksi sesuai rule.
- Endpoint `update_share()` wajib memanggil `validate_lead_access($lead_id)` sebelum update data.
- Pastikan operasi deactive tetap soft delete.

5. `app/Views/leads/lead_form_fields.php` dan rendering row di `app/Controllers/Leads.php`
- Lepas pola UI “shared by = view only” untuk skenario shared ON.
- Sesuaikan disable/lock icon agar mengikuti permission final, bukan sekadar membership shared.

### 15.3 Prioritas P1 (Setelah P0 Stabil)
1. `app/Controllers/Leads.php` + `app/Views/leads/view.php`
- Tambah panel **Timeline Aktivitas Lead** pada detail lead (gabungan event lead + estimate terkait).

2. Service/Model histori lead-estimate (baru atau ekstensi service existing)
- Siapkan endpoint data timeline dengan filter `event_type`, `entity`, `source`, `limit`, `offset`.
- Siapkan endpoint detail `Lihat` dan `Banding` untuk event yang dapat dibandingkan.

3. Audit trail terstruktur
- Wajib simpan metadata minimum: `actor`, `timestamp`, `action/event_type`, `field_changed`, `old_value`, `new_value`, `source`.
- Tandai auto action (contoh auto shared OFF) sebagai `source=system`.

### 15.4 Urutan Eksekusi Rekomendasi
1. Implement `Estimates.php` auto shared OFF + audit system event.
2. Refactor `Security_Controller.php` + sinkron `Estimates_model.php` untuk matrix akses estimate.
3. Rapikan `Leads.php` + `lead_form_fields.php` untuk shared user edit/update/deactive.
4. Tambahkan timeline gabungan di detail lead.
5. Jalankan UAT checklist bagian P0 dulu, lalu lanjut P1.

### 15.5 Kriteria Siap Fase Ini (tanpa convert-to-client)
1. Create estimate selalu mematikan shared lead otomatis.
2. Shared user (saat shared ON) bisa edit/update/deactive lead.
3. Akses estimate mengikuti matrix owner/atasan 1 level.
4. Event audit penting tercatat dengan metadata minimal.
5. Timeline lead gabungan tampil dan dapat difilter.

## 16. Gap-to-Compliance RBAC ISO/IEC 27001 (Execution Checklist)
Catatan penting:
1. Checklist ini untuk menutup gap implementasi teknis dan governance agar siap audit.
2. Status "compliant" hanya sah jika kontrol teknis + prosedur + bukti audit sudah lengkap.
3. Mapping menggunakan praktik umum ISO/IEC 27001:2022 Annex A terkait access control, logging, dan review.

### 16.1 Ringkasan Status Saat Ini
1. RBAC per role sudah ada (`roles.permissions`) dan enforcement akses sudah berjalan di controller.
2. Row-level access (`own/team/all/shared`) untuk lead-estimate sudah tersedia.
3. Gap terbesar ada pada governance evidence: audit perubahan hak akses belum konsisten, review akses periodik belum terdokumentasi, dan SoD belum diformalkan.

### 16.2 Checklist Kontrol dan Gap
1. Kontrol: Kebijakan access control terdokumentasi (least privilege, need-to-know).
   Status: Partial.
   Gap: Belum ada SOP formal versi kontrol dokumen (approval, review periodik).
   Aksi:
   1. Buat SOP "Access Control Policy" untuk modul lead-estimate.
   2. Tetapkan owner kebijakan dan siklus review (minimal per 6 bulan).
   Evidence:
   1. Dokumen SOP bertanggal, nomor versi, approver.
   2. Notulen review berkala.

2. Kontrol: Role-based access management terpusat.
   Status: Implemented (teknis).
   Gap: Masih ada beberapa pengecekan role ID hardcoded di controller.
   Aksi:
   1. Refactor hardcoded role check menjadi permission-based check.
   2. Simpan mapping role-ke-permission hanya di layer role settings.
   Evidence:
   1. PR diff refactor.
   2. Test case akses sebelum/sesudah.

3. Kontrol: Joiner-Mover-Leaver (JML) akses user.
   Status: Partial.
   Gap: Proses provisioning/deprovisioning belum dipaketkan sebagai alur audit formal.
   Aksi:
   1. Definisikan workflow JML (buat, ubah, cabut akses).
   2. Tambahkan checklist approval dua pihak untuk role sensitif.
   Evidence:
   1. Ticket JML tersimpan.
   2. Rekaman approval dan timestamp.

4. Kontrol: Segregation of Duties (SoD) untuk role sensitif.
   Status: Partial.
   Gap: Maker-checker perubahan permission belum wajib.
   Aksi:
   1. Wajibkan approval kedua untuk perubahan role/permission kritikal.
   2. Batasi siapa yang bisa memberi hak `can_manage_user_role_and_permissions`.
   Evidence:
   1. Matriks SoD.
   2. Log approval berpasangan (requester + approver).

5. Kontrol: Logging dan accountability perubahan akses.
   Status: Partial.
   Gap: Perubahan permission role belum konsisten masuk audit trail standar.
   Aksi:
   1. Pastikan endpoint perubahan permission/role selalu `init_activity_log` atau audit logger ekuivalen.
   2. Simpan before/after JSON permission.
   3. Simpan actor, waktu, alasan perubahan.
   Evidence:
   1. Record log perubahan permission.
   2. Query laporan audit perubahan hak akses.

6. Kontrol: Monitoring dan review akses berkala.
   Status: Belum formal.
   Gap: Belum ada job review owner/team/shared access periodik.
   Aksi:
   1. Buat report bulanan: user-role-permission, owner hierarchy, shared members.
   2. Jalankan recertification akses per kuartal.
   Evidence:
   1. Hasil export review akses.
   2. Berita acara approval/cabut akses.

7. Kontrol: Validasi berkelanjutan (testing).
   Status: Partial.
   Gap: Belum ada suite automated authorization test yang memadai.
   Aksi:
   1. Tambahkan integration test untuk matrix akses (`all/team/own/own_only/shared`).
   2. Tambahkan negative test untuk privilege escalation.
   Evidence:
   1. File test + CI result.
   2. Coverage skenario akses minimum.

### 16.3 Rencana Eksekusi Bertahap
1. Tahap 1 (Quick Wins, 1-2 minggu):
   1. Aktifkan audit log penuh pada perubahan permission/role.
   2. Refactor hardcoded role check paling kritis.
   3. Susun template SOP access control + SoD.

2. Tahap 2 (Hardening, 2-4 minggu):
   1. Implement maker-checker untuk perubahan role sensitif.
   2. Tambahkan report recertification akses.
   3. Lengkapi integration tests authorization.

3. Tahap 3 (Audit Readiness, 1-2 minggu):
   1. Kumpulkan evidence 3 bulan terakhir.
   2. Lakukan internal control review.
   3. Tutup temuan minor dari dry-run audit.

### 16.4 Definisi Done (Siap Audit Internal)
- [ ] Semua perubahan role/permission tercatat dengan before/after, actor, waktu, alasan.
- [ ] Tidak ada hardcoded bypass untuk role sensitif; seluruh akses melalui policy/permission.
- [ ] Recertification akses berjalan periodik dan terdokumentasi.
- [ ] Maker-checker aktif untuk perubahan hak akses kritikal.
- [ ] Test authorization lulus untuk skenario positif dan negatif utama.
- [ ] SOP access control + SoD disetujui manajemen dan dipublikasikan.

### 16.5 Artefak Bukti Minimum yang Wajib Disimpan
1. Dokumen kebijakan access control dan SoD (versi + approval).
2. Log perubahan role/permission (before/after).
3. Daftar user-role-permission bulanan.
4. Berita acara review akses berkala.
5. Hasil test authorization dan bukti eksekusi CI.