293 lines
13 KiB
Markdown
293 lines
13 KiB
Markdown
# Operator Workspace: Slash Commands, Collision Detection & Alerts Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Enhance the human operator workspace with inline slash command (`/`) quick replies, real-time operator collision detection (preventing two operators from answering the same customer at once), and audio-visual alerts for incoming messages.
|
|
|
|
**Architecture:** Extend the existing WebSocket service with a lightweight `operator.presence` topic broadcast (`viewing`, `typing`, `left`). Integrate slash command trigger into `SharedMessageEditor` for instant macro insertion. Add client-side presence state tracking with automatic TTL decay, rendering an operator collision banner in the chat panel. Provide synthesized Web Audio chime alerts for incoming customer messages.
|
|
|
|
**Tech Stack:** Go 1.26, Gorilla WebSocket, Next.js 16 App Router, TypeScript, Tiptap, Base UI / Tailwind CSS, Web Audio API.
|
|
|
|
**Spec:** Agreed enhancements roadmap (Option 2 - Operator Workspace improvements).
|
|
|
|
## Global Constraints
|
|
|
|
- Follow AGENTS.md layer ownership (no direct SQL in handlers, clean WebSocket envelope structures).
|
|
- Symmetrical 3-locale i18n parity (`zh-CN.json`, `en-US.json`, `ru-RU.json`).
|
|
- Zero external binary/audio assets — synthesize audio chime using native Web Audio API.
|
|
- TypeScript compilation must pass with 0 errors (`tsc --noEmit`).
|
|
- Go formatting (`gofmt`) and all Go tests must pass cleanly.
|
|
|
|
## Review Focus
|
|
|
|
1. Operator presence event storms: typing events must be throttled (max once per 3s).
|
|
2. Presence cleanup: presence records must auto-expire after TTL (15s) so disconnected or crashed tabs don't show ghost operators.
|
|
3. Slash command replacement: selecting a quick reply via `/` must replace the `/` text cleanly without leaving orphan slashes.
|
|
4. Audio context autoplay policies: Web Audio API must initialize lazily upon user interaction and safely no-op when blocked.
|
|
5. Multi-operator collision UI: banner must be informative, non-disruptive, and properly localized across all 3 languages.
|
|
|
|
---
|
|
|
|
### Task 1: Backend Operator Presence Event & WebSocket Protocol
|
|
|
|
**Files:**
|
|
- Modify: `internal/pkg/enums/im.go`
|
|
- Modify: `internal/services/ws_realtime_types.go`
|
|
- Modify: `internal/services/ws_service.go`
|
|
- Test: `internal/services/ws_service_test.go`
|
|
|
|
**Interfaces:**
|
|
- Produces:
|
|
- `enums.IMRealtimeEventOperatorPresence = "operator.presence"`
|
|
- `RealtimeOperatorPresencePayload`:
|
|
```go
|
|
type RealtimeOperatorPresencePayload struct {
|
|
ConversationID int64 `json:"conversationId"`
|
|
UserID int64 `json:"userId"`
|
|
Username string `json:"username"`
|
|
Nickname string `json:"nickname"`
|
|
Action string `json:"action"` // "viewing", "typing", "left"
|
|
At string `json:"at"`
|
|
}
|
|
```
|
|
- `RealtimeOperatorPresenceEvent` implementing `RealtimeDomainEvent`.
|
|
- Client message parsing in `ws_service.go` for `type: "presence"`.
|
|
- `WsService.PublishOperatorPresence(conversationID int64, principal *dto.AuthPrincipal, action string, excludeConnID string)`.
|
|
|
|
- [ ] **Step 1: Write test for Operator Presence publishing**
|
|
|
|
In `internal/services/ws_service_test.go`:
|
|
Add `TestPublishOperatorPresence` verifying that publishing presence sends the event to subscribers on `conversation:{id}` while skipping `excludeConnID`.
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `& 'C:\Program Files\Go\bin\go.exe' test -run TestPublishOperatorPresence ./internal/services/...`
|
|
Expected: FAIL
|
|
|
|
- [ ] **Step 3: Implement enum, payload, event, and WsService methods**
|
|
|
|
1. In `internal/pkg/enums/im.go`: define `IMRealtimeEventOperatorPresence = "operator.presence"`.
|
|
2. In `internal/services/ws_realtime_types.go`: define `RealtimeOperatorPresencePayload` and `RealtimeOperatorPresenceEvent`.
|
|
3. In `internal/services/ws_service.go`:
|
|
- Handle client message `type == "presence"`: parse `conversationId` and `action`, call `PublishOperatorPresence`.
|
|
- Implement `PublishOperatorPresence(conversationID int64, principal *dto.AuthPrincipal, action string, excludeConnID string)`.
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `& 'C:\Program Files\Go\bin\go.exe' test -run TestPublishOperatorPresence ./internal/services/...`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Run gofmt and commit**
|
|
|
|
```bash
|
|
git add internal/pkg/enums/im.go internal/services/ws_realtime_types.go internal/services/ws_service.go internal/services/ws_service_test.go
|
|
git commit -m "feat(ws): support operator.presence realtime event and client presence messages"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Symmetrical i18n Translations for Collision Alerts and Audio Notifications
|
|
|
|
**Files:**
|
|
- Modify: `web/messages/en-US.json`
|
|
- Modify: `web/messages/ru-RU.json`
|
|
- Modify: `web/messages/zh-CN.json`
|
|
- Test: `web/i18n/message-integrity.test.mjs`
|
|
|
|
**Interfaces:**
|
|
- Produces: Symmetrical keys across all 3 locales:
|
|
- `operatorPresence.viewing`: "{name} is viewing this conversation" / "{name} просматривает этот диалог" / "{name} 正在查看此会话"
|
|
- `operatorPresence.typing`: "{name} is typing a reply..." / "{name} печатает ответ..." / "{name} 正在输入回复..."
|
|
- `operatorPresence.multipleViewing`: "{count} operators are viewing this conversation" / "{count} оператора просматривают этот диалог" / "{count} 位客服正在查看此会话"
|
|
- `operatorPresence.collisionWarning`: "Warning: Another operator is active here to avoid duplicate replies." / "Внимание: другой оператор активен в этом диалоге во избежание дублирования ответов." / "注意：其他客服正在处理此会话，请避免重复回复。"
|
|
- `conversation.quickReplySlashHint`: "Type / for quick replies" / "Введите / для быстрого ответа" / "输入 / 快捷回复"
|
|
|
|
- [ ] **Step 1: Check baseline integrity**
|
|
|
|
Run: `node --test web/i18n/message-integrity.test.mjs`
|
|
|
|
- [ ] **Step 2: Add keys symmetrically to all 3 JSON files**
|
|
|
|
Add `operatorPresence.*` and `conversation.quickReplySlashHint` with exact placeholder parity `{name}` and `{count}`.
|
|
|
|
- [ ] **Step 3: Run integrity tests**
|
|
|
|
Run: `node --test web/i18n/message-integrity.test.mjs`
|
|
Expected: PASS (0 missing keys, 0 placeholder mismatches).
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add web/messages/en-US.json web/messages/ru-RU.json web/messages/zh-CN.json
|
|
git commit -m "feat(i18n): add localized messages for operator collision and slash commands"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Slash Commands (`/`) Quick Reply Autocomplete in SharedMessageEditor
|
|
|
|
**Files:**
|
|
- Modify: `web/components/chat/shared-message-editor.tsx`
|
|
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/agent-message-editor.tsx`
|
|
- Test: `web/node_modules/.bin/tsc.cmd --noEmit` and manual verification
|
|
|
|
**Interfaces:**
|
|
- Consumes: `quickReplies` prop in `SharedMessageEditor`
|
|
- Produces:
|
|
- When typing `/` as first character or when editor text matches `/query`, opens the Quick Replies popover and filters items by `query`.
|
|
- Selecting a quick reply removes the `/query` prefix and inserts the chosen quick reply content.
|
|
- Shows subtle hint `conversation.quickReplySlashHint` in editor toolbar for operator variant.
|
|
|
|
- [ ] **Step 1: Implement slash trigger and query tracking**
|
|
|
|
In `web/components/chat/shared-message-editor.tsx`:
|
|
1. In `editor.on("update")`:
|
|
- Inspect plain text of current block.
|
|
- If text matches `^/([^\s]*)$`:
|
|
- Open quick replies popover.
|
|
- Set quick reply search query to match the typed characters.
|
|
2. In `handleInsertQuickReply(item)`:
|
|
- If current text starts with `/`, delete the slash prefix before inserting `item.content`.
|
|
3. In toolbar: show subtle hint for operators (`conversation.quickReplySlashHint`).
|
|
|
|
- [ ] **Step 2: Run typecheck**
|
|
|
|
Run: `& "web/node_modules/.bin/tsc.cmd" --noEmit --project web/tsconfig.json`
|
|
Expected: 0 errors.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add web/components/chat/shared-message-editor.tsx web/app/\(dashboard\)/dashboard/conversations/_components/agent-message-editor.tsx
|
|
git commit -m "feat(editor): support slash command / for quick reply autocomplete"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Operator Presence Tracking & Collision Warning UI
|
|
|
|
**Files:**
|
|
- Create: `web/lib/operator-presence-state.ts`
|
|
- Create: `web/lib/operator-presence-state.test.mjs`
|
|
- Modify: `web/hooks/use-agent-conversation-realtime.ts`
|
|
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/chat-panel.tsx`
|
|
- Test: `node --test web/lib/operator-presence-state.test.mjs` and `web/node_modules/.bin/tsc.cmd --noEmit`
|
|
|
|
**Interfaces:**
|
|
- Produces:
|
|
- `resolveOperatorPresence(currentList, incomingEvent, currentUserId)` -> pure function returning active peer presences, purging expired entries (>15s TTL).
|
|
- Outgoing presence messages:
|
|
- `"viewing"` sent when selecting conversation.
|
|
- `"typing"` sent when operator types (throttled to 3s).
|
|
- `"left"` sent when unselecting conversation.
|
|
- In `chat-panel.tsx`:
|
|
- Renders an alert banner above the message editor or below conversation header if peer operators are active.
|
|
- Displays avatar badge and text e.g. "Jane is viewing this conversation" or "Jane is typing a reply...".
|
|
|
|
- [ ] **Step 1: Write unit tests for pure presence state transitions**
|
|
|
|
Create `web/lib/operator-presence-state.test.mjs` verifying:
|
|
- Adds new peer operator with timestamp.
|
|
- Ignores self (currentUserId).
|
|
- Updates action from "viewing" to "typing".
|
|
- Removes operator on action "left".
|
|
- Filters out records older than 15 seconds.
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `node --test web/lib/operator-presence-state.test.mjs`
|
|
Expected: FAIL
|
|
|
|
- [ ] **Step 3: Implement `web/lib/operator-presence-state.ts`**
|
|
|
|
Export:
|
|
- `OperatorPresenceRecord`
|
|
- `updateOperatorPresenceList`
|
|
- `purgeExpiredOperatorPresences`
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `node --test web/lib/operator-presence-state.test.mjs`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Integrate into `use-agent-conversation-realtime.ts` and `chat-panel.tsx`**
|
|
|
|
1. In `use-agent-conversation-realtime.ts`:
|
|
- Send `{"type": "presence", "conversationId": id, "action": "viewing"}` on subscribe.
|
|
- Send `{"type": "presence", "conversationId": id, "action": "left"}` on unsubscribe.
|
|
- Listen for `operator.presence` events and update store presence state.
|
|
2. In `chat-panel.tsx`:
|
|
- When active peer operators exist on `currentConversation.id`:
|
|
- Render collision warning banner with `UsersIcon` and localized description.
|
|
|
|
- [ ] **Step 6: Run typecheck and tests**
|
|
|
|
Run: `& "web/node_modules/.bin/tsc.cmd" --noEmit --project web/tsconfig.json`
|
|
Run: `node --test web/lib/operator-presence-state.test.mjs`
|
|
Expected: ALL PASS with 0 errors.
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add web/lib/operator-presence-state.ts web/lib/operator-presence-state.test.mjs web/hooks/use-agent-conversation-realtime.ts web/app/\(dashboard\)/dashboard/conversations/_components/chat-panel.tsx
|
|
git commit -m "feat(presence): detect operator collision and render warning banner"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Incoming Message Audio & Expanded Browser Alerting
|
|
|
|
**Files:**
|
|
- Create: `web/lib/sound-alert.ts`
|
|
- Create: `web/lib/sound-alert.test.mjs`
|
|
- Modify: `web/hooks/use-agent-conversation-realtime.ts`
|
|
- Test: `node --test web/lib/sound-alert.test.mjs` and `web/node_modules/.bin/tsc.cmd --noEmit`
|
|
|
|
**Interfaces:**
|
|
- Produces:
|
|
- `playIncomingMessageSound()`: synthesizes a clean 587Hz -> 880Hz (D5 -> A5) chime via Web Audio API. Safe when audio is suspended or unsupported.
|
|
- In `use-agent-conversation-realtime.ts`:
|
|
- When `message.created` arrives from a customer:
|
|
- If message is from customer and either:
|
|
- assigned to current operator, OR
|
|
- conversation is unassigned / pending
|
|
- Play sound alert via `playIncomingMessageSound()`.
|
|
- Show browser notification if tab is in background.
|
|
|
|
- [ ] **Step 1: Write unit test for sound alert helper**
|
|
|
|
In `web/lib/sound-alert.test.mjs`:
|
|
Test safe fallback when `AudioContext` is undefined (Node.js/SSR environment).
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `node --test web/lib/sound-alert.test.mjs`
|
|
Expected: FAIL
|
|
|
|
- [ ] **Step 3: Implement `web/lib/sound-alert.ts`**
|
|
|
|
Synthesizes gentle dual-tone sine oscillator with exponential decay.
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `node --test web/lib/sound-alert.test.mjs`
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Wire into `use-agent-conversation-realtime.ts`**
|
|
|
|
Trigger `playIncomingMessageSound()` on new customer messages for assigned/pending conversations.
|
|
|
|
- [ ] **Step 6: Run typecheck and all tests**
|
|
|
|
Run: `& "web/node_modules/.bin/tsc.cmd" --noEmit --project web/tsconfig.json`
|
|
Run: `node --test web/lib/*.test.mjs web/i18n/*.test.mjs`
|
|
Run: `& 'C:\Program Files\Go\bin\go.exe' test ./internal/...`
|
|
Expected: ALL PASS with 0 errors.
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add web/lib/sound-alert.ts web/lib/sound-alert.test.mjs web/hooks/use-agent-conversation-realtime.ts
|
|
git commit -m "feat(notification): add audio chime and expanded alerts for incoming customer messages"
|
|
```
|