Notas internas

setDraft(e.target.value)}
        placeholder="Esta nota é visível apenas pra equipe."
        className="bg-amber-50/40 border-amber-200"
      />
      <div className="flex justify-end">
        <Button
          size="sm"
          variant="secondary"
          disabled={!draft.trim()}
          onClick={async () => {
            await createNote.mutateAsync({ body: draft });
            setDraft("");
          }}
        >
          Salvar nota
        </Button>
      </div>
      <ul className="space-y-2">
        {notes.data?.map((n) => <NoteItem key={n.id} note={n} />)}
      </ul>
    </section>
  );
}
```

### 5.4 Mobile responsive — 2 rotas, 100dvh

```tsx
// app/(app)/inbox/page.tsx
export default async function InboxPage() {
  return (
    <div className="h-[100dvh] grid grid-cols-1 md:grid-cols-[340px_1fr_360px]">
      <ConversationList orgId={...} />
      {/* desktop: thread inline; mobile: empty state */}
      <div className="hidden md:flex md:flex-col">
        <EmptyThread />
      </div>
      <div className="hidden xl:block">
        <EmptyPanel />
      </div>
    </div>
  );
}

// app/(app)/inbox/[conversationId]/page.tsx
export default function ConversationPage({ params }: ...) {
  const isMobile = useMediaQuery("(max-width: 767px)");
  return (
    <div className="h-[100dvh] grid grid-cols-1 md:grid-cols-[340px_1fr_360px]">
      {!isMobile && <ConversationList selectedId={params.conversationId} />}
      <ChatThread conversationId={params.conversationId} ... />
      {isMobile ? (
        <Drawer>
          <DrawerTrigger asChild>
            <Button variant="ghost" size="icon" className="fixed top-3 right-3">
              <Info />
            </Button>
          </DrawerTrigger>
          <DrawerContent className="h-[85dvh]">
            <CRMSidePanel ... />
          </DrawerContent>
        </Drawer>
      ) : (
        <CRMSidePanel ... />
      )}
    </div>
  );
}
```

Pontos críticos mobile:
- `h-[100dvh]` (Tailwind `dvh`) em vez de `100vh` — Safari iOS encolhe viewport com URL bar.
- `pb-[env(safe-area-inset-bottom)]` no Composer.
- `inputMode="text"`, `autoCorrect="off"` no Composer textarea pra evitar aria do iOS.
- Tap targets mínimos 44×44px.

---

## 6. Componente Kanban

### 6.1 `<KanbanBoard>`

```ts
export interface KanbanBoardProps {
  pipelineId: string;
  initialFilters?: BoardFilters;
}

interface BoardData {
  pipeline: Pipeline;
  stages: Stage[];                       // ordenadas por position
  cardsByStage: Record<string, KanbanCardData[]>;
}
```

```tsx
"use client";
export function KanbanBoard({ pipelineId, initialFilters }: KanbanBoardProps) {
  const [filters, setFilters] = useState<BoardFilters>(initialFilters ?? {});
  const [selected, setSelected] = useState<Set<string>>(new Set());
  const board = useBoard(pipelineId, filters);
  const moveCard = useMoveCard(pipelineId);

if (board.isLoading) return <KanbanSkeleton />;
  if (!board.data) return null;

return (
    <div className="flex flex-col h-full">
      <KanbanFilters value={filters} onChange={setFilters} />
      {selected.size > 0 && (
        <BulkActionBar
          count={selected.size}
          pipelineId={pipelineId}
          leadIds={Array.from(selected)}
          onClear={() => setSelected(new Set())}
        />
      )}
      <DragDropContext onDragEnd={onDragEnd}>
        <div className="flex-1 flex gap-3 overflow-x-auto p-3">
          {board.data.stages.map((stage) => (
            <KanbanColumn
              key={stage.id}
              stage={stage}
              cards={board.data!.cardsByStage[stage.id] ?? []}
              selected={selected}
              onToggleSelect={(id) =>
                setSelected((s) => {
                  const n = new Set(s);
                  n.has(id) ? n.delete(id) : n.add(id);
                  return n;
                })
              }
            />
          ))}
        </div>
      </DragDropContext>
    </div>
  );
}
```

### 6.2 `<KanbanCard>`

```ts
interface KanbanCardData {
  id: string;
  title: string;
  value_cents: number | null;
  currency: "BRL";
  owner: { id: string; name: string; avatar_url?: string } | null;
  tags: { id: string; name: string; color: string }[];
  status: "open" | "won" | "lost";
  expected_close_date: string | null;
  last_activity_at: string | null;
  position_in_stage: number;
  is_overdue: boolean;
}

interface KanbanCardProps {
  card: KanbanCardData;
  index: number;
  selected: boolean;
  onToggleSelect: (id: string) => void;
}
```

```tsx
export function KanbanCard({ card, index, selected, onToggleSelect }: KanbanCardProps) {
  const vocab = usePipelineVocabulary();
  return (
    <Draggable draggableId={card.id} index={index}>
      {(provided, snapshot) => (
        <div
          ref={provided.innerRef}
          {...provided.draggableProps}
          {...provided.dragHandleProps}
          className={cn(
            "group rounded-lg border bg-card p-3 shadow-sm",
            "hover:shadow-md transition-shadow",
            snapshot.isDragging && "ring-2 ring-primary shadow-lg rotate-1",
            selected && "ring-2 ring-primary",
          )}
          aria-label={`${vocab.deal} ${card.title}`}
        >
          <div className="flex items-start gap-2">
            <Checkbox
              checked={selected}
              onCheckedChange={() => onToggleSelect(card.id)}
              onClick={(e) => e.stopPropagation()}
              aria-label="Selecionar card"
            />
            <div className="flex-1 min-w-0">
              <p className="text-sm font-medium truncate">{card.title}</p>
              {card.value_cents != null && (
                <p className="text-xs text-muted-foreground">
                  {formatCurrency(card.value_cents, card.currency)}
                </p>
              )}
            </div>
            {card.owner && (
              <Avatar className="h-6 w-6">
                <AvatarImage src={card.owner.avatar_url} />
                <AvatarFallback>{initials(card.owner.name)}</AvatarFallback>
              </Avatar>
            )}
          </div>
          <div className="mt-2 flex flex-wrap gap-1">
            {card.tags.slice(0, 3).map((t) => (
              <Badge key={t.id} style={{ backgroundColor: t.color }}>
                {t.name}
              </Badge>
            ))}
            {card.tags.length > 3 && (
              <Badge variant="outline">+{card.tags.length - 3}</Badge>
            )}
            {card.is_overdue && (
              <Badge variant="destructive" className="ml-auto">
                Atrasado
              </Badge>
            )}
          </div>
          {card.last_activity_at && (
            <p className="mt-2 text-[10px] text-muted-foreground">
              {formatDistanceToNow(new Date(card.last_activity_at), {
                addSuffix: true,
                locale: ptBR,
              })}
            </p>
          )}
        </div>
      )}
    </Draggable>
  );
}
```

### 6.3 Drag-drop com `@hello-pangea/dnd`

Fluxo exato `onDragEnd`:

1. Calcular `midpoint(prev, next)` localmente — `lib/utils/fractional-index.ts`:

```ts
export function midpoint(prev: number | null, next: number | null): number {
  if (prev == null && next == null) return 1000;
  if (prev == null) return next! - 1;
  if (next == null) return prev + 1;
  return (prev + next) / 2;
}
```

2. Patch otimista no cache:

```ts
// hooks/data/useMoveCard.ts
export function useMoveCard(pipelineId: string) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (vars: MoveCardVars) =>
      api.leads.move(vars.leadId, {
        stage_id: vars.stageId,
        position_in_stage: vars.positionInStage,
      }),
    onMutate: async (vars) => {
      await qc.cancelQueries({ queryKey: ["board", pipelineId] });
      const prev = qc.getQueryData<BoardData>(["board", pipelineId]);
      qc.setQueryData<BoardData>(["board", pipelineId], (old) =>
        old ? applyMoveOptimistic(old, vars) : old,
      );
      return { prev };
    },
    onError: (_err, _vars, ctx) => {
      if (ctx?.prev) qc.setQueryData(["board", pipelineId], ctx.prev);
    },
    onSettled: () => {
      // não invalida — Realtime virá com a versão final
    },
  });
}
```

3. Em 409 (conflito), `onError` rollback + toast + refetch (handler no `onDragEnd`).

### 6.4 Filtros

```tsx
export function KanbanFilters({ value, onChange }: KanbanFiltersProps) {
  return (
    <div className="flex items-center gap-2 p-3 border-b">
      <OwnerSelect value={value.ownerId} onChange={(id) => onChange({ ...value, ownerId: id })} />
      <StatusMultiSelect value={value.status} onChange={(s) => onChange({ ...value, status: s })} />
      <TagMultiSelect value={value.tagIds} onChange={(t) => onChange({ ...value, tagIds: t })} />
      <Input
        placeholder="Buscar pelo título…"
        value={value.search ?? ""}
        onChange={(e) => onChange({ ...value, search: e.target.value })}
        className="w-64 ml-auto"
      />
    </div>
  );
}
```

Filtros sincronizam com URL via `useSearchParams` (Next.js):

```ts
useEffect(() => {
  const params = new URLSearchParams();
  if (filters.ownerId) params.set("owner", filters.ownerId);
  if (filters.search) params.set("q", filters.search);
  router.replace(`?${params.toString()}`, { scroll: false });
}, [filters]);
```

### 6.5 Bulk actions

```ts
type BulkAction =
  | { type: "move_stage"; stage_id: string }
  | { type: "assign_owner"; user_id: string }
  | { type: "add_tag"; tag_id: string }
  | { type: "remove_tag"; tag_id: string };

export function useBulkAction(pipelineId: string) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (vars: { leadIds: string[]; action: BulkAction }) => {
      // AT-06: limite 50
      if (vars.leadIds.length > 50) {
        throw new ApiError(422, "bulk_too_large", {
          message: "Selecione até 50 cards por vez.",
        });
      }
      return api.leads.bulk(vars);
    },
    onSuccess: () => qc.invalidateQueries({ queryKey: ["board", pipelineId] }),
  });
}
```

`<BulkActionBar>` aparece flutuante no topo quando `selected.size > 0`:

```
┌──────────────────────────────────────────────┐
│ 12 selecionados   [Mover ▾] [Atribuir ▾] ... │
│                                       [Limpar] │
└──────────────────────────────────────────────┘
```

### 6.6 Refetch vs patch in-place

**Decisão:** patch in-place. Após drop bem-sucedido, NÃO invalidamos `["board", ...]` no `onSettled` — confiamos no Realtime para confirmar (e ele virá com `(stage_id, position_in_stage)` igual ao otimista, então o merge é no-op).

UPDATE de Realtime que chega para card em `dragging` é silenciado (§4.4) — protege contra "salto" enquanto o usuário ainda segura o card.

UPDATE com a mesma `(stage_id, position_in_stage)` que já está no cache é detectado e ignorado em `mergeLead`:

```ts
function mergeLead(board: BoardData, payload: PostgresChange<LeadRow>): BoardData {
  const lead = payload.new as LeadRow;
  // detecta no-op
  const current = findCard(board, lead.id);
  if (
    current &&
    current.stage_id === lead.stage_id &&
    current.position_in_stage === lead.position_in_stage &&
    current.status === lead.status
  ) {
    return board;
  }
  return rebuildBoard(board, lead);
}
```

---

## 7. Send Message Hook

### 7.1 `useSendMessage`

```ts
// hooks/data/useSendMessage.ts
import { v4 as uuid } from "uuid";

interface SendMessageVars {
  type: MessageType;
  body?: string;
  media?: { storage_path: string; mime_type: string };
  internal?: boolean;                    // nota interna
  client_message_id?: string;
}

export function useSendMessage(conversationId: string) {
  const qc = useQueryClient();
  const currentUser = useCurrentUser();

return useMutation({
    mutationFn: async (vars: SendMessageVars) => {
      const cmid = vars.client_message_id ?? uuid();
      return api.messages.create(conversationId, {
        ...vars,
        client_message_id: cmid,
      });
    },
    onMutate: async (vars) => {
      await qc.cancelQueries({ queryKey: ["messages", conversationId] });
      const cmid = vars.client_message_id ?? uuid();
      const optimistic: MessageRow = {
        id: `optimistic-${cmid}`,
        client_message_id: cmid,
        conversation_id: conversationId,
        type: vars.type,
        body: vars.body ?? null,
        direction: "outbound",
        sent_by_user_id: currentUser.id,
        status: "sending",
        is_internal: vars.internal ?? false,
        created_at: new Date().toISOString(),
        media: vars.media ?? null,
      };
      qc.setQueryData<MessageRow[]>(
        ["messages", conversationId],
        (prev) => [...(prev ?? []), optimistic],
      );
      return { cmid, optimistic };
    },
    onError: (err, _vars, ctx) => {
      if (!ctx) return;
      qc.setQueryData<MessageRow[]>(
        ["messages", conversationId],
        (prev) =>
          (prev ?? []).map((m) =>
            m.client_message_id === ctx.cmid
              ? { ...m, status: "failed" as const, error: serialize(err) }
              : m,
          ),
      );
      toast.error("Falha ao enviar. Toque na bolha pra reenviar.");
    },
    onSuccess: (server, _vars, ctx) => {
      if (!ctx) return;
      qc.setQueryData<MessageRow[]>(
        ["messages", conversationId],
        (prev) =>
          (prev ?? []).map((m) =>
            m.client_message_id === ctx.cmid ? server : m,
          ),
      );
    },
  });
}
```

Bolha em `status='sending'` mostra ícone de relógio; em `status='failed'`, ícone de alerta vermelho com `onClick={retry}`.

### 7.2 `<Composer>`

```tsx
"use client";
export function Composer({ conversationId, disabled }: ComposerProps) {
  const [body, setBody] = useState("");
  const [internal, setInternal] = useState(false);
  const send = useSendMessage(conversationId);
  const { emitTyping } = useTypingIndicator(conversationId, useCurrentUser().id);

const onSubmit = async (e?: React.FormEvent) => {
    e?.preventDefault();
    const text = body.trim();
    if (!text || send.isPending) return;
    setBody("");
    // AT-07: chunking >4096 é feito server-side; cliente envia 1 mensagem
    await send.mutateAsync({
      type: internal ? "note" : "text",
      body: text,
      internal,
    });
  };

return (
    <form
      onSubmit={onSubmit}
      className={cn(
        "border-t bg-background p-2 pb-[max(0.5rem,env(safe-area-inset-bottom))]",
        internal && "bg-amber-50",
      )}
    >
      <div className="flex items-center gap-2 mb-1">
        <Switch
          id="internal-toggle"
          checked={internal}
          onCheckedChange={setInternal}
          disabled={disabled}
        />
        <Label htmlFor="internal-toggle" className="text-xs">
          Nota interna (não envia ao cliente)
        </Label>
      </div>
      <div className="flex items-end gap-2">
        <AttachmentButton conversationId={conversationId} disabled={disabled} />
        <Textarea
          value={body}
          onChange={(e) => {
            setBody(e.target.value);
            if (!internal) emitTyping();
          }}
          onKeyDown={(e) => {
            if ((e.metaKey || e.ctrlKey) && e.key === "Enter") onSubmit();
            if (e.key === "/" && body === "") {
              e.preventDefault();
              setQuickReplyOpen(true);
            }
          }}
          rows={1}
          maxLength={8000}
          placeholder={
            internal ? "Nota interna…" : "Digite uma mensagem…"
          }
          disabled={disabled}
          className="resize-none min-h-[40px] max-h-[200px]"
        />
        <EmojiButton onPick={(e) => setBody((b) => b + e)} />
        <Button type="submit" disabled={disabled || !body.trim() || send.isPending}>
          <Send className="h-4 w-4" />
        </Button>
      </div>
    </form>
  );
}
```

### 7.3 Quick replies / templates

```ts
interface QuickReplyTemplate {
  id: string;
  title: string;                         // "Saudação"
  body: string;                          // "Olá {nome}, vi que..."
  required_vars: string[];               // ["nome"]
}

`<QuickReplyMenu>` abre via `/`, renderiza `<Command>` (cmdk) com fuzzy search:

```tsx
<Command>
  <CommandInput placeholder="Buscar template…" />
  <CommandList>
    {templates.map((t) => (
      <CommandItem
        key={t.id}
        onSelect={() => {
          const interp = interpolate(t.body, contextVars);
          if (!interp.ok) {
            toast.error(`Variáveis pendentes: ${interp.missing.join(", ")}`);
            return;
          }
          setBody(interp.result);
          close();
        }}
      >
        {t.title}
      </CommandItem>
    ))}
  </CommandList>
</Command>
```

---

## 8. Atendimento — Status do Atendente

### 8.1 `<AttendantStatusToggle>`

```ts
type AgentStatus = "online" | "busy" | "offline";

export interface AttendantStatusToggleProps {
  // sem props — lê do hook
}
```

```tsx
export function AttendantStatusToggle() {
  const { status, setStatus, pinned, setPinned } = useAgentStatus();
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" size="sm" className="gap-2">
          <StatusDot status={status} />
          {labelFor(status)}
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {(["online", "busy", "offline"] as const).map((s) => (
          <DropdownMenuItem key={s} onClick={() => setStatus(s)}>
            <StatusDot status={s} /> {labelFor(s)}
          </DropdownMenuItem>
        ))}
        <DropdownMenuSeparator />
        <DropdownMenuCheckboxItem
          checked={pinned}
          onCheckedChange={setPinned}
        >
          Manter online (não auto-offline)
        </DropdownMenuCheckboxItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}
```

`StatusDot`: bolinha colorida — `bg-green-500` (online), `bg-amber-500` (busy), `bg-zinc-400` (offline).

### 8.2 Heartbeat de UI (60s) + auto-offline 15min — AT-08

```ts
// hooks/presence/useHeartbeat.ts
const HEARTBEAT_MS = 60_000;

export function useHeartbeat() {
  const { status, pinned } = useAgentStatus();
  useEffect(() => {
    if (status === "offline") return;
    const tick = () => api.presence.heartbeat({ status, pinned });
    tick();
    const id = setInterval(tick, HEARTBEAT_MS);
    return () => clearInterval(id);
  }, [status, pinned]);
}

// hooks/presence/useInactivityDetector.ts
const INACTIVITY_MS = 15 * 60_000;

export function useInactivityDetector() {
  const { status, setStatus, pinned } = useAgentStatus();
  const lastActivityRef = useRef(Date.now());

useEffect(() => {
    const bump = () => (lastActivityRef.current = Date.now());
    const events = ["mousemove", "keydown", "click", "touchstart"] as const;
    events.forEach((e) => window.addEventListener(e, bump, { passive: true }));
    return () =>
      events.forEach((e) => window.removeEventListener(e, bump));
  }, []);

useEffect(() => {
    if (pinned || status !== "online") return;
    const id = setInterval(() => {
      if (Date.now() - lastActivityRef.current > INACTIVITY_MS) {
        setStatus("offline");
        toast.info("Status alterado para offline por inatividade.");
      }
    }, 30_000);
    return () => clearInterval(id);
  }, [status, pinned, setStatus]);
}
```

Worker server-side complementar (Spec 01): se servidor não recebe heartbeat por 90s, marca atendente como `offline` (defesa contra fechar aba sem `beforeunload`).

### 8.3 Auto-assignment hook

UI side é apenas exibir "fila Sem responsável" quando `assigned_to_user_id IS NULL`. Lógica de round-robin (AT-03) é worker server-side. Frontend apenas:

```tsx
function UnassignedQueueAlert() {
  const { data } = useQuery({
    queryKey: ["unassigned-count"],
    queryFn: api.conversations.unassignedCount,
    refetchInterval: 30_000,
  });
  if (!data?.count) return null;
  return (
    <Alert variant="warning">
      <AlertTriangle />
      {data.count} conversas sem responsável.{" "}
      <Link href="/inbox?filter=unassigned">Ver fila</Link>
    </Alert>
  );
}
```

---

## 9. "Eu cuido" Flow — claim atômico (AT-02)

### 9.1 Modal de confirmação

```tsx
export function ClaimButton({ conversationId, status, assigned_to }: ClaimButtonProps) {
  const claim = useClaimConversation(conversationId);
  const [open, setOpen] = useState(false);

if (assigned_to) return null; // só aparece se não tiver dono

return (
    <>
      <Button onClick={() => setOpen(true)} variant="default" size="sm">
        Eu cuido
      </Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Assumir esta conversa?</DialogTitle>
            <DialogDescription>
              Você ficará responsável por responder este cliente até resolver
              ou reatribuir.
            </DialogDescription>
          </DialogHeader>
          <DialogFooter>
            <Button variant="ghost" onClick={() => setOpen(false)}>
              Cancelar
            </Button>
            <Button
              onClick={async () => {
                await claim.mutateAsync();
                setOpen(false);
              }}
              disabled={claim.isPending}
            >
              {claim.isPending ? "Assumindo…" : "Sim, assumir"}
            </Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}
```

### 9.2 API atomic UPDATE

Server-side (resumo — Spec 01 detalha):

```sql
UPDATE conversations
SET assigned_to_user_id = $caller, updated_at = now()
WHERE id = $conv AND assigned_to_user_id IS NULL
RETURNING *;
```

Se 0 rows retornadas, API responde 409 com `{ code: "conversation_already_claimed", details: { assigned_to_user_id } }`.

### 9.3 Tratamento de 409

```ts
export function useClaimConversation(conversationId: string) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: () => api.conversations.claim(conversationId),
    onSuccess: (server) => {
      qc.setQueryData(["conversation", conversationId], server);
      toast.success("Você assumiu esta conversa");
    },
    onError: (err) => {
      if (err instanceof ApiError && err.code === "conversation_already_claimed") {
        toast.error(
          `Outro atendente já assumiu esta conversa.${err.details?.assigned_to_name ? " (" + err.details.assigned_to_name + ")" : ""}`,
        );
        // refetch pra UI refletir o vencedor
        qc.invalidateQueries({ queryKey: ["conversation", conversationId] });
      } else {
        toast.error("Erro ao assumir. Tente novamente.");
      }
    },
  });
}
```

---

## 10. Supervisor Read-Only Mode (AT-04)

### 10.1 Detecção

```ts
export function useSupervisorView(conversationId: string): boolean {
  const me = useCurrentUser();
  const conv = useConversation(conversationId);
  if (!conv.data) return false;
  const isOwner = conv.data.assigned_to_user_id === me.id;
  const canSupervise = ["manager", "admin", "platform_admin"].includes(me.role);
  return canSupervise && !isOwner;
}
```

### 10.2 UI desabilita composer

`<ChatThread>` recebe `isSupervisorView`; `<SupervisorBanner>` renderiza acima do scroll:

```tsx
export function SupervisorBanner() {
  return (
    <div
      role="status"
      className="flex items-center gap-2 px-4 py-2 bg-violet-100 text-violet-900 text-sm border-b"
    >
      <Eye className="h-4 w-4" />
      <span>Modo supervisor — você está visualizando, não pode enviar mensagens.</span>
    </div>
  );
}
```

Composer recebe `disabled={isSupervisorView}` (§5.2). API server-side também valida (camada de defesa) — se um atendente tentar `POST /messages` sem ser owner, recebe 403.

### 10.3 Audit log

Ao montar `<ChatThread>` em modo supervisor, dispara endpoint de audit (fire-and-forget):

```ts
useEffect(() => {
  if (isSupervisorView) {
    api.audit.log({
      action: "conversation.observed_by_supervisor",
      resource_type: "conversation",
      resource_id: conversationId,
    });
  }
}, [isSupervisorView, conversationId]);
```

Importante: dedup server-side por `(user_id, conversation_id, hour_bucket)` evita spam de audit a cada montagem.

---

## 11. Pipeline Vocabulary Integration (P-07)

### 11.1 `usePipelineVocabulary`

```ts
// hooks/pipeline/usePipelineVocabulary.ts
export interface PipelineVocabulary {
  lead: string;       // "Cliente"
  deal: string;       // "Pedido"
  deals: string;      // "Pedidos"
  stage: string;      // "Estágio"
  won: string;        // "Pago"
  lost: string;       // "Cancelado"
  openTicket: string; // "Abrir ticket"
  // …
}

export function usePipelineVocabulary(
  pipelineId?: string,
): PipelineVocabulary {
  const ctx = useContext(PipelineContext);
  const id = pipelineId ?? ctx?.pipelineId;
  const { data } = useQuery({
    queryKey: ["pipeline-vocabulary", id],
    queryFn: () => api.pipelines.vocabulary(id!),
    enabled: !!id,
    staleTime: 5 * 60_000,
  });
  return data ?? DEFAULT_VOCAB;
}

const DEFAULT_VOCAB: PipelineVocabulary = {
  lead: "Cliente",
  deal: "Pedido",
  deals: "Pedidos",
  stage: "Estágio",
  won: "Pago",
  lost: "Cancelado",
  openTicket: "Abrir ticket",
};
```

### 11.2 Cache + invalidation

Quando `manager+` edita vocabulary em `/pipeline/[id]/settings`:

```ts
export function useUpdateVocabulary(pipelineId: string) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (vocab: Partial<PipelineVocabulary>) =>
      api.pipelines.updateVocabulary(pipelineId, vocab),
    onSuccess: (server) => {
      qc.setQueryData(["pipeline-vocabulary", pipelineId], server);
      // invalida componentes que renderizaram com strings velhas
      qc.invalidateQueries({ queryKey: ["pipeline", pipelineId] });
    },
  });
}
```

Realtime: vocabulary é parte de `crm_pipelines.settings`. Subscribe em `pipelines` filter `id=eq.${pipelineId}` propaga mudança a outros admins logados.

### 11.3 Linter custom contra strings hardcoded em PT

Plugin `eslint-plugin-deskcomm` com regra `no-hardcoded-vocabulary`. Bloqueia em `.tsx` strings literais que parecem vocabulary:

```js
// eslint-plugin-deskcomm/rules/no-hardcoded-vocabulary.js
const FORBIDDEN = [
  "Cliente", "Clientes",
  "Pedido", "Pedidos",
  "Negócio", "Negócios",
  "Lead", "Leads",
  "Ticket", "Tickets",
  "Estágio", "Estágios",
  "Pago", "Cancelado", "Ganho", "Perdido",
];

module.exports = {
  meta: { type: "problem", schema: [] },
  create(context) {
    const filename = context.getFilename();
    if (!/components\/(inbox|kanban|attendance|dashboard)/.test(filename)) {
      return {};
    }
    return {
      Literal(node) {
        if (typeof node.value !== "string") return;
        if (FORBIDDEN.includes(node.value)) {
          context.report({
            node,
            message:
              `String "${node.value}" parece vocabulary; use vocab.${suggest(node.value)}() ou import de DEFAULT_VOCAB.`,
          });
        }
      },
    };
  },
};
```

Whitelist via `// deskcomm-allow-vocab: <razão>`. CI roda `eslint --max-warnings 0` no diff dos PRs.

---

## 12. Notas Internas (AT-05)

### 12.1 Toggle "interno" no composer

Já mostrado em §7.2. Switch `internal` muda:
- `body` aparece com background `bg-amber-50`
- placeholder vira "Nota interna…"
- send dispara `type='note'` `internal=true`

### 12.2 Activity tipo `note`

Server-side (worker outbound) **NÃO consome** `activity.type='note'` — garantia AT-05. Cliente apenas envia metadata correta.

### 12.3 UI distintiva

`<NoteBubble>`:

```tsx
export function NoteBubble({ message }: { message: MessageRow }) {
  return (
    <div
      role="article"
      aria-label="Nota interna"
      className="mx-auto max-w-[80%] rounded-md bg-amber-50 border border-amber-200 px-3 py-2 my-2 text-sm flex items-start gap-2"
    >
      <StickyNote className="h-4 w-4 text-amber-600 mt-0.5 shrink-0" />
      <div className="flex-1">
        <div className="text-[10px] text-amber-700 mb-1 flex items-center gap-1">
          <Badge variant="outline" className="text-[10px] py-0">Nota interna</Badge>
          <span>{message.author_name}</span>
          <span>·</span>
          <span>{formatRelative(message.created_at)}</span>
        </div>
        <p className="text-amber-900 whitespace-pre-wrap">{message.body}</p>
      </div>
    </div>
  );
}
```

Centralizada na thread (não align-left/right) para diferenciar visualmente de qualquer mensagem outbound humana ou IA.

---

## 13. Dashboard Lite (admin do tenant)

Rota `/dashboard/atendimento`. Grid 2×2 de cards.

### 13.1 Conversas abertas por atendente

```tsx
export function OpenConversationsCard() {
  const { data } = useQuery({
    queryKey: ["dash", "open-by-agent"],
    queryFn: api.dashboards.openByAgent,
    refetchInterval: 30_000,
  });
  return (
    <Card>
      <CardHeader>
        <CardTitle>Conversas abertas por atendente</CardTitle>
      </CardHeader>
      <CardContent>
        <ul>
          {data?.map((row) => (
            <li key={row.user_id} className="flex justify-between py-1">
              <span>{row.name}</span>
              <Badge>{row.count}</Badge>
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  );
}
```

### 13.2 Tempo médio de primeira resposta (hoje)

```tsx
<MetricCard
  title="Tempo médio 1ª resposta (hoje)"
  value={data?.avg_seconds ? formatDuration(data.avg_seconds) : "—"}
  delta={data?.delta_pct}
  goal="< 5min"
/>
```

### 13.3 Conversas pendentes (cliente esperando >10min)

```tsx
<Card>
  <CardHeader>
    <CardTitle>Aguardando atendimento</CardTitle>
  </CardHeader>
  <CardContent>
    <p className="text-3xl font-semibold">{data?.count ?? 0}</p>
    <p className="text-xs text-muted-foreground">
      Cliente esperando há mais de 10 min
    </p>
    <Button asChild variant="link" size="sm">
      <Link href="/inbox?filter=pending&waiting_min=10">Ver fila</Link>
    </Button>
  </CardContent>
</Card>
```

### 13.4 Taxa de resolução por atendente

```tsx
<Card>
  <CardHeader><CardTitle>Resolução (hoje)</CardTitle></CardHeader>
  <CardContent>
    {data?.map((row) => (
      <div key={row.user_id} className="flex items-center gap-2 py-1">
        <Avatar className="h-5 w-5"><AvatarFallback>{initials(row.name)}</AvatarFallback></Avatar>
        <span className="flex-1 text-sm">{row.name}</span>
        <span className="text-sm tabular-nums">
          {row.resolved}/{row.total}
        </span>
        <span className="text-xs text-muted-foreground tabular-nums w-12 text-right">
          {Math.round((row.resolved / Math.max(row.total, 1)) * 100)}%
        </span>
      </div>
    ))}
  </CardContent>
</Card>
```

`agent` vê apenas a própria linha; `manager+` vê todas (RLS aplica server-side).

---

## 14. Componentes shadcn/ui usados (lista exaustiva)

| Componente | Uso |
|---|---|
| `Avatar`, `AvatarImage`, `AvatarFallback` | ConversationItem, KanbanCard, NoteBubble, ResolutionRateCard |
| `Badge` | unread, tag, "IA", "Atrasado", "Nota interna" |
| `Button` | em todo lugar |
| `Card`, `CardHeader`, `CardTitle`, `CardContent` | Dashboard cards, KanbanCard |
| `Checkbox` | bulk select kanban |
| `Command`, `CommandInput`, `CommandList`, `CommandItem` | QuickReplyMenu |
| `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogFooter` | ClaimButton, ReassignDialog, criar pipeline |
| `Drawer`, `DrawerContent`, `DrawerTrigger` | mobile CRMSidePanel |
| `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuSeparator` | AttendantStatusToggle, ChatHeader "Mais", PipelineSwitcher |
| `Form`, `FormField`, `FormLabel`, `FormControl`, `FormMessage` | settings de pipeline |
| `Input` | search, filtros |
| `Label` | composer toggle, settings |
| `Popover`, `PopoverTrigger`, `PopoverContent` | EmojiPicker container, OwnerSelect filter |
| `ScrollArea` | ConversationList, ChatThread, CRMSidePanel |
| `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem` | DealSection inline stage, filtros |
| `Separator` | divisores no SidePanel e em listas |
| `Sheet`, `SheetTrigger`, `SheetContent` | settings drawer pra criar pipeline em desktop |
| `Skeleton` | loading states |
| `Switch` | composer "interno", AttendantStatusToggle pinned |
| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | DealSection multi-lead |
| `Textarea` | Composer, NotesSection |
| `Tooltip`, `TooltipTrigger`, `TooltipContent` | StatusDot label, ícones do composer |

Custom (não shadcn):
- `<EmojiPicker>` (lazy-loaded `emoji-mart`)
- `<MessageBubble>` family
- `<KanbanCard>`, `<KanbanColumn>`, `<KanbanBoard>`
- `<ChannelStatusBanner>`
- `<TypingIndicator>`
- `<SupervisorBanner>`
- `<BulkActionBar>`

---

## 15. Design tokens

Herda Tailwind config de `01-spec-platform-base.md`. Resumo do que esta camada usa:

**Cores (tokens semânticos via shadcn):**
- `bg-background`, `bg-card`, `bg-muted` — superfícies
- `bg-primary` (envio outbound humano), `text-primary-foreground`
- `bg-violet-50` / `bg-violet-100` (IA, supervisor) — extensão custom
- `bg-amber-50` / `border-amber-200` (notas internas) — extensão custom
- `bg-yellow-100` (banner reconectando)
- `bg-green-500` / `bg-amber-500` / `bg-zinc-400` (status dots)
- `bg-destructive` (badge "Atrasado", erros de send)

**Spacing:** `gap-2/3` em flex; padding interno de cards `p-3` desktop / `p-4` mobile; ConversationItem altura ~76px; KanbanCard largura 280px desktop.

**Tipografia:**
- `text-sm` (14px) — texto padrão
- `text-xs` (12px) — metadata, timestamps
- `text-[10px]` — preview, badge counters
- `font-medium` — títulos de card, nome do contact
- `font-semibold` — títulos de seção do dashboard

**Densidade:** Inbox e Kanban são "high density UI" — alvo é caber 8–10 conversations sem scroll em laptop 13" (768px de altura útil).

---

## 16. Testes

### 16.1 Unit (Vitest + Testing Library)

Cobertura mínima:

| Componente / hook | Casos críticos |
|---|---|
| `midpoint()` | prev/next null, valores intermediários, números muito grandes/pequenos |
| `interpolate()` | variável presente, ausente (retorna `missing`), múltiplas, escapes |
| `useSendMessage` (com `MutationCache` mock) | optimistic insert, rollback em erro, dedup ao receber server response |
| `<MessageBubble>` (snapshot por tipo) | text, image, audio, document, location, note, IA |
| `<KanbanCard>` | render com 0/3/5 tags (overflow), is_overdue, sem owner |
| `<Composer>` | Cmd+Enter envia; "/" abre QuickReply; toggle internal muda placeholder |
| `<ConversationItem>` | unread badge, selected highlight, supervisor view badge |
| `useSupervisorView` | retorna false se owner; true se manager + não owner |

### 16.2 Integration

| Cenário | Verifica |
|---|---|
| Send + receive na mesma thread (mockando Realtime) | dedup por `client_message_id`, sem bolha duplicada |
| Drag-drop via `userEvent.pointer()` | `onDragEnd` chamado com source/destination corretos; `useMoveCard` invocado com `midpoint` certo |
| Claim concorrente | mock 409 → toast de erro + invalidação de cache |
| Supervisor abre conversa de outro atendente | banner aparece; composer disabled; audit é chamado |
| Quick reply com variável faltando | toast erro, body não é setado |

### 16.3 E2E (Playwright)

| Fluxo | Steps |
|---|---|
| Drag-drop persistente | login agent, abrir kanban, mover card "Pago" → "Em separação", reload, validar persistência |
| Send + Realtime cross-tab | abrir 2 abas mesma conversation, enviar de uma, validar bubble na outra em <2s |
| Claim concorrente | 2 contextos Playwright, ambos clicam "Eu cuido" simultaneamente, 1 vence, outro vê toast |
| Supervisor read-only | login manager, abrir conversa de outro agent, validar composer disabled |
| Mobile inbox | viewport iPhone 14, navegar `/chat` → tap item → `/chat/[id]`, abrir drawer painel CRM |
| Reconexão Realtime | usar Playwright `context.setOffline(true)` por 5s, validar banner; voltar online, validar recuperação sem duplicar |

---

## 17. Performance

### 17.1 Memoization

- `KanbanColumn` envolvida em `React.memo` com comparação rasa em `(stage.id, cards.length, cards[0]?.id, cards[last]?.id, selected.size)` — drop em coluna não dispara re-render das outras.
- `MessageBubble` em `React.memo` por `message.id, status, body`.
- `ConversationItem` em `React.memo` por `conversation.id, last_message_at, unread_count, selected`.
- Callbacks que descem props de muitos filhos via `useCallback`; estado de filtros lifted ao topo, não passado em cascata.

### 17.2 Virtualização

- **Conversations list:** `@tanstack/react-virtual` quando `items.length > 50`. Altura fixa 76px facilita.
- **Kanban column:** virtualização vertical quando uma coluna passa de **150 cards**. Threshold sai da literatura `react-window` (cards de altura variável exigem `VariableSizeList` ou medição). Decisão: **`@tanstack/react-virtual` com `estimateSize` 120px e `measureElement`**.
- **Timeline:** virtualização ao passar de 100 entries.

### 17.3 Code-splitting

- `<EmojiPicker>` lazy via `next/dynamic` (`ssr: false`).
- Kanban inteiro é client component em rota dedicada — sem bundling no `/inbox`.
- Settings de pipeline são rota separada.

### 17.4 Network

- TanStack Query `staleTime` defaults:
  - `["conversations", ...]` — 0s (sempre fresco; Realtime mantém)
  - `["messages", ...]` — 0s
  - `["board", ...]` — 30s
  - `["pipeline-vocabulary", ...]` — 5min
  - `["dash", ...]` — 30s
- Imagens via `next/image` com `loading="lazy"`.
- Mídias de mensagem: thumbnail no preview, lazy-load quando entra no viewport.

### 17.5 Realtime budget

≤ 4 canais por aba (PRD §3.12). Assertion runtime em desenvolvimento:

```ts
if (process.env.NODE_ENV === "development") {
  const channels = supabase.getChannels();
  if (channels.length > 4) {
    console.warn(`[realtime-budget] ${channels.length} canais ativos:`, channels.map(c => c.topic));
  }
}
```

Estratégia de consolidação: 1 canal `org-{id}-conversations` agrega INSERT/UPDATE de todas as conversations do tenant; thread atual abre `conv-{id}-messages` apenas enquanto montada; kanban abre `pipeline-{id}-leads` apenas na rota.

---

## Anexos

- `docs/prd/04-prd-pipeline-attendance.md` — sub-PRD origem
- `docs/business-rules/00-business-rules-catalog.md` — regras P-05, P-06, P-07, AT-01 a AT-08
- `docs/research/reference-synthesis.md` — §5 Frontend/Realtime, §9 Anti-patterns
- `docs/specs/01-spec-platform-base.md` — auth, audit, API conventions
- `docs/specs/02-spec-customer-360.md` — schema crm_*, fractional indexing
- `docs/specs/03-spec-whatsapp-waha.md` — conversations, messages, sessões

{vocab("deals")}

Notas internas