fix flowchart4.4

flowchart-report/04-BE-FLOWCHARTS.md

@@ -29,32 +29,117 @@ Alur lengkap mesin chat Backend, baik inbound maupun outbound.
 
 ## 4.4 BE Conversation Status Flow
 
-Alur perubahan status conversation.
+Alur perubahan status conversation. Status mengalir **satu arah** (one-way pipeline), tidak bisa mundur.
+
+> **Catatan Penting (Kondisi Aktual):**
+> - **4 status** didefinisikan: `UNASSIGNED`, `ASSIGNED`, `RESOLVED`, `CLOSED`
+> - **CLOSED** didefinisikan di enum tapi **tidak ada implementasi** — tidak ada endpoint/code path yang mengarah ke status ini
+> - **UNASSIGNED ← ASSIGNED (BLOCKED)** — kode secara eksplisit throw error: *"Status cannot be changed to unassigned, you must resolve or reassign to another member."*
+> - **RESOLVED tidak bisa di-reopen** — customer reply setelah RESOLVED akan membuat **conversation BARU** dengan status UNASSIGNED, bukan membuka kembali yang lama
+> - **Chain Mechanism**: Conversation baru di-link ke conversation lama via `previousConversationId` (linked list)
+> - **RESOLVED tidak bisa di-resolve ulang** — kode throw `ConversationAlreadyResolvedError`
+> - **Hanya agent yang di-assign** yang bisa resolve conversation-nya sendiri
+> - **Pesan ke conversation RESOLVED diblok** — kode throw `ConversationAlreadyResolvedError`
+
+### State Diagram
 
 ```mermaid
 stateDiagram-v2
-    [*] --> UNASSIGNED: Customer sends first message
-    UNASSIGNED --> ASSIGNED: Agent claims chat<br/>(POST /get-new-chat)
-    UNASSIGNED --> ASSIGNED: Admin assigns agent<br/>(PATCH /status: assignedTo)
-
-    ASSIGNED --> UNASSIGNED: Agent unassigns<br/>(PATCH /status: assignedTo=null)
-    ASSIGNED --> RESOLVED: Agent resolves<br/>(PATCH /status + resolveCategoryIds)
-    ASSIGNED --> ASSIGNED: Agent sends message<br/>(message flow continues)
-
-    RESOLVED --> ASSIGNED: Customer replies<br/>(new message in chain)
-    RESOLVED --> CLOSED: Admin closes<br/>(PATCH /status: CLOSED)
-
-    CLOSED --> ASSIGNED: Customer replies<br/>(new conversation created,<br/>previous_conversation_id linked)
-
-    UNASSIGNED: Unread count tracked
-    ASSIGNED: first_response_at set
-    ASSIGNED: first_response_by set
-    RESOLVED: resolved_at set
-    RESOLVED: resolved_by set
-    RESOLVED: resolve categories linked
-    CLOSED: conversation ended
+    [*] --> UNASSIGNED: Webhook menerima pesan dari customer<br/>(WA / IG / TG)<br/>→ createConversation()<br/>status: UNASSIGNED
+
+    UNASSIGNED --> ASSIGNED: ① Manual Assign<br/>Admin/Owner assign ke agent<br/>PATCH /conversations/:id/status<br/>body: {conversationStatus:"ASSIGNED", assignedTo}
+
+    UNASSIGNED --> ASSIGNED: ② Get New Chat<br/>Agent klaim chat terlama<br/>POST /conversations/get-new-chat<br/>(hanya role: member,<br/>developer & devops diblok)
+
+    UNASSIGNED --> ASSIGNED: ③ Auto-Assign (WhatsApp)<br/>Agent kirim pesan → otomatis assign<br/>(di-trigger saat WA status: SENT,<br/>skipped untuk campaign blast)
+
+    ASSIGNED --> ASSIGNED: Reassign ke agent lain<br/>PATCH /conversations/:id/status<br/>(member: hanya miliknya,<br/>admin/owner: semua)
+
+    ASSIGNED --> RESOLVED: Resolve<br/>Hanya assigned user yang bisa<br/>PATCH /conversations/:id/status<br/>body: {conversationStatus:"RESOLVED",<br/>resolveCategoryIds, resolvedDescription}
+
+    RESOLVED --> NEW_UNASSIGNED: Customer balas pesan<br/>→ TIDAK reopen!<br/>→ Buat conversation BARU<br/>(previousConversationId = lama)
+
+    state NEW_UNASSIGNED {
+        [*] --> NEW_CONV: findOrCreateConversation()<br/>status: UNASSIGNED
+        note right of NEW_CONV: Ter-chain ke<br/>conversation RESOLVED<br/>sebelumnya via<br/>previousConversationId
+    }
+
+    state "CLOSED<br/>(DEFINED tapi TIDAK DIIMPLEMENTASI)" as CLOSED_NOT_IMPL
 ```
 
+### Detail Per Transisi
+
+```mermaid
+flowchart TD
+    subgraph CREATE["① PEMBUATAN (UNASSIGNED)"]
+        WEBHOOK["Webhook menerima pesan"] --> FIND{"Cari conversation aktif?\n(not RESOLVED + 24h window)"}
+        FIND -->|"Ditemukan"| UPDATE_EXIST["Update existing:\nlast_message, last_message_at,\nunread_counts++"]
+        FIND -->|"Tidak ditemukan"| CREATE_NEW["Create conversation BARU:\nstatus: UNASSIGNED,\nunread_counts: 1"]
+        FIND -->|"RESOLVED ditemukan"| CREATE_CHAIN["Create conversation BARU:\nstatus: UNASSIGNED,\npreviousConversationId = lama"]
+    end
+
+    subgraph ASSIGN["② ASSIGN (UNASSIGNED → ASSIGNED)"]
+        A1["Manual Assign (PATCH)"] --> SET_ASSIGNED["assignedTo = userId\nassignedAt = now()\nassignedBy = callerId"]
+        A2["Get New Chat (POST)"] --> FIND_OLDEST["Find UNASSIGNED tertua\nper contact (row_number)"]
+        FIND_OLDEST --> SET_ASSIGNED
+        A3["Auto-Assign (WA)"] --> CHECK_SENT{"WA status = SENT?\n+ bukan campaign blast?"}
+        CHECK_SENT -->|"Ya"| AUTO_SET["assignedTo = sender\nfirst_response_at = now()\nfirst_response_by = sender"]
+        CHECK_SENT -->|"Tidak"| SKIP["Skip auto-assign"]
+    end
+
+    subgraph RESOLVE["③ RESOLVE (ASSIGNED → RESOLVED)"]
+        R1["Agent resolve (PATCH)"] --> CHECK{assignedTo === userId?\n+ resolvedAt === null?}
+        CHECK -->|"Ya"| SET_RESOLVED["conversationStatus: RESOLVED\nresolvedAt = now()\nresolvedBy = userId\n+ resolve categories\n+ system message (type 4)"]
+        CHECK -->|"Tidak"| ERR_RESOLVE["Error:\n- Bukan assigned user\n- Sudah pernah di-resolve"]
+    end
+
+    subgraph BLOCKED["④ DIBLOKIR / TIDAK BISA"]
+        B1["ASSIGNED → UNASSIGNED"] --> ERR1["BLOCKED\n'Status cannot be changed to\nunassigned'"]
+        B2["RESOLVED → RESOLVED"] --> ERR2["BLOCKED\nConversationAlreadyResolvedError"]
+        B3["Kirim pesan ke RESOLVED"] --> ERR3["BLOCKED\nConversationAlreadyResolvedError"]
+        B4["RESOLVED → CLOSED"] --> ERR4["NOT IMPLEMENTED\nCLOSED hanya ada di enum"]
+    end
+
+    style CREATE fill:#E8F5E9,stroke:#4CAF50
+    style ASSIGN fill:#FFF3E0,stroke:#FF9800
+    style RESOLVE fill:#E3F2FD,stroke:#1976D2
+    style BLOCKED fill:#FFCDD2,stroke:#F44336
+```
+
+### Chain Mechanism (Customer Reply Setelah RESOLVED)
+
+```mermaid
+flowchart TD
+    subgraph SCENARIO["CUSTOMER BALAS PESAN SETELAH RESOLVED"]
+        OLD_CONV["Conversation A\nstatus: RESOLVED\nassignedTo: Agent 1\nresolvedAt: 10:00"] --> CUSTOMER_REPLY["Customer kirim pesan baru"]
+        CUSTOMER_REPLY --> FIND{"findConversation()\nCari: not RESOLVED + 24h window"}
+        FIND -->|"A sudah RESOLVED"| NOT_FOUND["Tidak ditemukan!"]
+        NOT_FOUND --> FIND_PREV{"Cari conversation RESOLVED\ntersebelumnya\n(contact + channel)"}
+        FIND_PREV -->|"Ditemukan: Conv A"| CREATE_NEW["Create Conversation B:\nstatus: UNASSIGNED\npreviousConversationId = Conv A\nunread_counts: 1"]
+    end
+
+    subgraph CHAIN_VIEW["HASIL CHAIN DI UI"]
+        CONV_A["Conv A (RESOLVED)\nassignedTo: Agent 1\nresolvedAt: 10:00\n↑ previousConversationId = null"]
+        CONV_B["Conv B (UNASSIGNED)\n↑ previousConversationId = Conv A"]
+        CONV_A -->|"chain"| CONV_B
+    end
+
+    style SCENARIO fill:#FFF3E0,stroke:#FF9800
+    style CHAIN_VIEW fill:#E3F2FD,stroke:#1976D2
+```
+
+### Tabel Perubahan Field Per Transisi
+
+| Transisi | `conversationStatus` | `assignedTo` | `assignedAt` | `assignedBy` | `resolvedAt` | `resolvedBy` | `resolvedDescription` | `unreadCounts` | `readBy` |
+|---|---|---|---|---|---|---|---|---|---|
+| **Create** | `UNASSIGNED` | `null` | `null` | `null` | `null` | `null` | `null` | `0` atau `1` | `null` |
+| **→ ASSIGNED** | `ASSIGNED` | `userId` | `now()` | `callerId` | — | — | — | — | — |
+| **Reassign** | `ASSIGNED` | `newUserId` | `now()` | `callerId` | — | — | — | — | — |
+| **→ RESOLVED** | `RESOLVED` | *(tidak di-clear)* | *(tidak di-clear)* | *(tidak di-clear)* | `now()` | `callerId` | optional | — | — |
+| **→ UNASSIGNED** | **BLOCKED** | — | — | — | — | — | — | — | — |
+| **Mark Read** | — | — | — | — | — | — | — | `0` | `userId` |
+| **Pesan Masuk** | — | — | — | — | — | — | — | `+1` | `null` |
+
 ---
 
 ## 4.5 BE Campaign Execution Flow (Detailed)