📐 Design — Cidade 3D Fase 2

Arquitetura, componentes, fluxo de dados e testes — revise seção por seção

1. Arquitetura

A cena Three.js passa de órbita isométrica para exploração a pé. O backend continua o mesmo (Sanctum + /city/data), mas o payload ganha: ruas, prédios gerados, e um streaming de mensagens de chat via SSE (Server-Sent Events) por agente — sem dependência nova.

Frontend (Three.js)
├── CameraController  — WASD + mouse, colisão AABB
├── CityGenerator     — ruas, quadras, prédios de preenchimento
├── CharacterFactory  — carrega modelos GLTF por tipo de agente
├── HudOverlay        — painel POSIÇÃO + minimapa
└── ChatPanel         — fluxo SSE /city/chat/{agent}

Backend (Laravel)
├── CityViewerController::data()  — stores + agents + city layout
├── ChatController                — SSE endpoint por agente
└── AgentThinkJob (queue)         — chama OpenRouter, persiste last_decision

2. Componentes

CameraController	Pointer-lock, WASD, gravidade simples, raycast contra colisores AABB de prédios
CityGenerator	Rua central + quadras laterais a partir das posições das lojas; prédios de preenchimento procedural (seed determinística)
StreetMesh	Asfalto (canvas texture com faixas), calçada de ladrilho, postes a cada N metros
CharacterFactory	GLTF por `agent.type`; fallback: cápsula texturizada. Animação Idle/Walk/Run
HudOverlay	Painel POSIÇÃO (x,y,z, triângulos) + minimapa 2D no canto
ChatPanel	Abre ao clicar no NPC; mostra nome, status (pensando/respondendo), mensagens; envia via POST e recebe via SSE

3. Fluxo de dados

Viewport carrega → GET /city/data → lojas + agentes + layout de ruas
CityGenerator monta ruas e prédios; prédios de loja ganham fachada custom
Usuário anda (WASD) → colisão por AABB → câmera segue
Clica em NPC → ChatPanel abre → GET /city/chat/{agent}/stream (SSE)
Envia mensagem → POST /city/chat/{agent} → job enfileirado → OpenRouter → persiste last_decision → SSE emite resposta
HUD recalcula posição a cada frame

4. Tratamento de erros

SSE cai → reconexão automática com backoff, indicador "reconectando"
OpenRouter falha → error_count++, backoff exponencial, status vira error no painel
GLTF ausente → fallback silencioso para cápsula (nunca quebra a cena)
Colisão detecta NaN → reposiciona no spawn

5. Testes

PHPUnit: CityViewerController::data() retorna layout; ChatController valida input e rate-limit; job persiste last_decision
JS: CameraController (colisão, WASD), CityGenerator (determinístico com seed), reconexão SSE
Manual: navegar, colidir, conversar com NPC, verificar HUD

Esse design está correto? Aprovo para escrever a especificação formal.

✅

Aprovar design

Escrever spec → revisão → plano de implementação

✏️

Revisar

Quero mudar algo antes de seguir