docs(ccui): CCui V2 - Guia Completo para Onboarding

[PedroGiudice]

CCui V2 - Onboarding para LGP

Resumo Executivo

Este PR adiciona documentação completa do CCui V2 (Claude Code UI), uma interface de chat integrada ao Legal Workbench que replica a experiência do Claude Code CLI na web.

---

O Que Foi Implementado

Backend (FastAPI + WebSocket)

• Serviço: api-ccui-ws rodando na porta 8005
• Endpoints:
  • GET /health - Health check
  • POST /api/chat - Recebe mensagens, faz streaming via WS
  • WS /ws?token=<token> - WebSocket para streaming
• Features:
  • Streaming token-by-token
  • Comandos: /help, /status, /clear, /model
  • Session tracking por cliente

Frontend (React + TypeScript)

• Rota: /ccui-v2
• Componentes:
  • CCuiApp - Container principal
  • CCuiHeader - Header com path e modelo
  • CCuiIconRail - 5 botões (Chats, Explorer, Search, Controls, Theme)
  • CCuiSidebar - Sidebar dinâmica
  • CCuiChatArea - Área de mensagens
  • CCuiInputTerminal - Input estilo terminal (>_)
  • CCuiStatusBar - Status bar inferior

Hooks

• useChatWebSocket - Gerencia conexão WS com retry automático
• useChatMessages - Estado de mensagens

---

Arquitetura

Browser → React Components → useChatWebSocket
                │
                ▼
POST /api/chat → api-ccui-ws (FastAPI) → WebSocket streaming → Frontend

Routing (Traefik):

• /ws → api-ccui-ws:8005 (priority 20)
• /api/chat → api-ccui-ws:8005 (priority 15)
• /ccui-v2 → frontend-react:3000

---

Como Testar

# 1. Subir ambiente
cd legal-workbench
docker compose up -d

# 2. Acessar
http://localhost/ccui-v2

# 3. Testar
- Digite "hello" no input
- Veja resposta aparecer com streaming
- Teste comandos: /help, /status
- Clique nos ícones da Icon Rail

---

Issues Conhecidos (Para Próximas Iterações)

P0: Problema de Proporções

CCui dentro do shell do LW causa redundância de sidebars (~350px ocupados). Soluções propostas:

• A: Rota standalone sem RootLayout
• B: RootLayout colapsável
• C: Redesign compacto

P1: Views Não Implementadas

View	Status
Chats	✅
Explorer	✅ (mock)
Search	❌
Controls	❌
Theme	❌

P2: Backend Mock

generate_response() é mock. Para produção:

• Integrar Claude API
• Autenticação real
• Persistência de histórico

---

Arquivos Chave

Arquivo	Descrição
docker/services/ccui-ws/main.py	Backend FastAPI
frontend/src/components/ccui-v2/	Componentes React
frontend/src/hooks/useChatWebSocket.ts	Hook de WebSocket
frontend/src/pages/CCuiV2Module.tsx	Página principal
docs/CCUI-V2-DEVELOPER-GUIDE.md	Este guia completo
docs/e2e-tests/CCUI-V2-E2E-REPORT.md	Relatório de testes

---

Checklist para LGP

• Ler docs/CCUI-V2-DEVELOPER-GUIDE.md
• Rodar docker compose up -d e testar em /ccui-v2
• Verificar logs: docker compose logs -f api-ccui-ws
• Escolher solução para problema de proporções (A, B ou C)
• Decidir próxima feature (Search view? Theme toggle?)

---

Screenshots

Screenshots dos testes E2E disponíveis em docs/e2e-tests/:

• Estado inicial, input preenchido, explorer view, chat funcionando

---

🤖 Generated with Claude Code