Changes
Co-authored-by: Reifonas <211114984+Reifonas@users.noreply.github.com>
This commit is contained in:
gpt-engineer-app[bot]
+77
-92
@@ -1,111 +1,96 @@
|
||||
## Objetivo
|
||||
|
||||
Construir uma **"giga de teste"** (DevKit) que vista o app com simulação completa de XR + instrumentação, permitindo:
|
||||
Adicionar um botão **"Escala"** com presets de redução (1:2, 1:4, 1:8, 1:10, 1:20, 1:33, 1:50, 1:100, 1:200) e ampliação (2:1, 4:1, 10:1), disponível tanto no Viewer 2D quanto no XR. Ao mudar a escala, o app ajusta automaticamente as ferramentas que dependem de tamanho real (medições, sensibilidade do ajuste fino, snap, hover auto-detect), mantendo todos os números exibidos em **mm reais da peça**.
|
||||
|
||||
1. **Você (sem Quest):** validar quase 100% do fluxo direto no navegador, incluindo grab, posicionamento e medição.
|
||||
2. **Testador (com Quest):** receber um build com painel de diagnóstico visível e log persistente, devolvendo feedback objetivo.
|
||||
3. **Remoção limpa:** quando o app estiver maduro, apagar 1 pasta + remover 3 imports + apagar 1 flag → app puro restaurado.
|
||||
## Conceito chave
|
||||
|
||||
## Princípios de isolamento
|
||||
- "1:N" significa: o modelo é renderizado **N vezes menor** que o real (renderScale = 1/N).
|
||||
- "N:1" significa: renderizado N vezes maior (renderScale = N).
|
||||
- Os dados do modelo continuam em mm reais. Só o `scale` aplicado ao `<group>` muda.
|
||||
- **Medições, sensibilidades, indicadores e relatório PDF continuam exibindo mm REAIS** — o app multiplica/divide pelo fator quando necessário.
|
||||
|
||||
- Todo código do DevKit vive em **`src/devkit/`** (pasta nova). Nada de código de simulação espalhado pelo app.
|
||||
- Ativação por **flag única** `?devkit=1` na URL **OU** `localStorage.setItem('devkit', '1')`. Sem flag → app roda exatamente como hoje.
|
||||
- Componentes do DevKit são montados condicionalmente em **3 pontos de injeção** apenas (todos em `XRSession.tsx`). Esses pontos ficam marcados com comentário `// DEVKIT: remove this block` para facilitar a limpeza futura.
|
||||
- Zero alteração de lógica de negócio. Tudo que o DevKit faz é **observar** (logger), **simular** (fake inputs) ou **adicionar UI extra** (painel).
|
||||
## Mudanças
|
||||
|
||||
## Componentes do DevKit
|
||||
### 1. Store (`useModelStore.ts`)
|
||||
|
||||
### 1. `devkit/DevKitFlag.ts` — detector de modo
|
||||
Hook `useDevKit()` retorna `boolean`. Lê `URLSearchParams` + `localStorage`. Se `true`, ativa todo o resto.
|
||||
|
||||
### 2. `devkit/SimXRSession.tsx` — modo "Faux-XR" pra desktop
|
||||
**Resolve seu problema #1:** validar tudo sem headset.
|
||||
|
||||
Quando ativado (botão "🧪 Simular XR" no header, só aparece com `?devkit=1`):
|
||||
- Não chama `store.enterAR()` (que falha sem HTTPS/headset compatível).
|
||||
- Em vez disso, força `inXR=true` num estado paralelo `simXR`.
|
||||
- Renderiza a árvore `XRGrabbable + XRModel` **sem** `XRHitTestPlacement` (auto-posiciona em `[0,0,-1.5]`).
|
||||
- Substitui leitura de `session.inputSources` por uma fonte **fake** (ver #3).
|
||||
- Câmera fica controlável por `OrbitControls` (você navega como quiser).
|
||||
|
||||
### 3. `devkit/FakeControllers.tsx` — controles virtuais com mouse/teclado
|
||||
**Resolve seu problema #2:** testar grab sem Touch Plus.
|
||||
|
||||
- Desenha 2 esferas coloridas (L=azul, R=vermelho) na cena, posicionáveis por **arrastar com mouse**.
|
||||
- Atalhos teclado:
|
||||
- `Q` / `W` → segurar grip esquerdo / direito (analógico simulado em 1.0)
|
||||
- `A` / `S` → segurar trigger esquerdo / direito
|
||||
- `Setas` → mover controle ativo
|
||||
- `Shift + Setas` → mover controle no eixo Z
|
||||
- Expõe um `FakeInputProvider` (Context) que `useControllerGrab` consome **quando em modo DevKit**. Sem DevKit, hook continua lendo `session.inputSources` real.
|
||||
- **Mudança mínima em `useControllerGrab.ts`:** uma linha checando `if (devkit) return useFakeInputs()`. Removível.
|
||||
|
||||
### 4. `devkit/DevPanel.tsx` — painel de diagnóstico flutuante
|
||||
Painel HTML overlay (canto direito), só visível com `?devkit=1`:
|
||||
- **Aba "Inputs":** valores ao vivo de cada controle (real ou fake) — grip, trigger, axes, hasPose
|
||||
- **Aba "Cena":** posição/rotação/escala do grupo grabável, contagem de meshes, bbox
|
||||
- **Aba "XR":** `session?.mode`, hit-test ativo, planos detectados (count + labels), FPS
|
||||
- **Aba "Logs":** últimos 100 console.logs com timestamp, filtro por tag (`[XR]`, `[grab]`, `[HitTest]`)
|
||||
- Botão **"Exportar relatório"** → baixa JSON com snapshot atual + screenshot do canvas. **Você pede pro testador clicar isso e te enviar o arquivo.**
|
||||
|
||||
### 5. `devkit/XRDevHud.tsx` — HUD in-world expandido (substitui o `XRDebugHud` atual quando ativo)
|
||||
Painel 3D maior, ancorado no pulso esquerdo (não na câmera, pra não atrapalhar). Mostra mesmas infos da aba "Inputs" + "XR" do DevPanel. Visível **dentro do headset**, essencial pro testador.
|
||||
|
||||
### 6. `devkit/SmokeTest.tsx` — roteiro automático
|
||||
Rota nova `/devkit/smoke` (só roteada com `?devkit=1`):
|
||||
- Sequência scriptada: carrega demo → simula grip esquerdo → move 50cm → solta → mede 2 pontos → screenshot → checklist.
|
||||
- Cada passo mostra ✅/❌ + tempo.
|
||||
- Você roda antes de mandar build pro testador.
|
||||
|
||||
### 7. `devkit/RecordSession.tsx` — gravador de "macros"
|
||||
Botão "Gravar" no DevPanel: captura por 30s todos inputs + posições da cena num JSON. Botão "Reproduzir": replay do macro. Útil pra reproduzir um bug que o testador relatou ("clico aqui, viro assim, peça desaparece").
|
||||
|
||||
## Pontos de injeção em `XRSession.tsx`
|
||||
|
||||
Apenas 3 blocos curtos, todos cercados por `{devkit && <... />}`:
|
||||
|
||||
```tsx
|
||||
// DEVKIT: remove this block
|
||||
{devkit && <SimXRButton onActivate={setSimXR} />}
|
||||
|
||||
// DEVKIT: remove this block
|
||||
{devkit && simXR && <FakeControllers />}
|
||||
|
||||
// DEVKIT: remove this block
|
||||
{devkit && <DevPanel />}
|
||||
```
|
||||
|
||||
E uma linha em `useControllerGrab.ts`:
|
||||
Adicionar:
|
||||
```ts
|
||||
// DEVKIT: remove this conditional
|
||||
if (typeof window !== 'undefined' && useDevKitFake()) return fakeRef;
|
||||
scaleRatio: { label: '1:1', factor: 1 } // factor = renderScale
|
||||
setScaleRatio: (r) => void
|
||||
```
|
||||
Lista de presets exportada (label + factor).
|
||||
|
||||
`fineTuning.scale` continua existindo para o gesto two-hand do XR; o novo `scaleRatio` é aplicado **por cima** (multiplicado) no grupo do modelo.
|
||||
|
||||
### 2. Cálculo de medições (`addMeasurePoint`)
|
||||
|
||||
Pontos A/B vêm em coordenadas world já escaladas. Para reportar mm reais:
|
||||
```
|
||||
distanceMM_real = distanciaWorld_mm / scaleRatio.factor
|
||||
```
|
||||
Atualizar a função `addMeasurePoint` para dividir pela escala atual antes de salvar `distanceMM`. Tooltips e PDF continuam usando o valor salvo (sem mudança).
|
||||
|
||||
### 3. Ajuste fino (`FineTuningControls` + XRHud joystick)
|
||||
|
||||
`POSITION_STEP` deve representar **1 mm real**. Aplicar:
|
||||
```
|
||||
worldStep = POSITION_STEP * scaleRatio.factor
|
||||
```
|
||||
Isso garante que clicar "+" desloca visualmente proporcional à escala (em escala 1:100, mexer "1 mm real" desloca 0,01 mm na cena — coerente).
|
||||
|
||||
Mesmo tratamento para o joystick no XR (incremento por frame multiplicado por `scaleRatio.factor`).
|
||||
|
||||
### 4. Auto-detect (hover hole/edge) e snap
|
||||
|
||||
Os limiares de detecção de furo/aresta e raio de snap são em metros world. Multiplicar pelo `scaleRatio.factor` para que continuem capturando os mesmos elementos físicos da peça.
|
||||
|
||||
### 5. ModelViewer
|
||||
|
||||
No `<group>` do modelo, multiplicar o scale final:
|
||||
```
|
||||
finalScale = fineTuning.scale * scaleRatio.factor
|
||||
```
|
||||
|
||||
## Como remover o DevKit no futuro (1 minuto)
|
||||
### 6. UI — novo componente `ScaleSelector`
|
||||
|
||||
1. `rm -rf src/devkit/`
|
||||
2. Em `XRSession.tsx`: deletar 3 blocos marcados `// DEVKIT:` + import.
|
||||
3. Em `useControllerGrab.ts`: deletar linha marcada `// DEVKIT:`.
|
||||
4. Pronto — app puro, zero resíduo.
|
||||
Botão com ícone de régua + label atual ("1:1", "1:50"…). Ao clicar abre um Popover/Sheet com grid:
|
||||
|
||||
## Entregas desta primeira leva (priorizadas)
|
||||
```text
|
||||
Reduzir Ampliar
|
||||
[1:1*] [1:2] [1:4] [1:8] [2:1]
|
||||
[1:10] [1:20] [1:33] [1:50] [4:1]
|
||||
[1:100] [1:200] [10:1]
|
||||
```
|
||||
|
||||
Pra não fazer tudo de uma vez, **proponho entregar nesta ordem**, validando cada etapa antes da próxima:
|
||||
Toast ao trocar: *"Escala 1:50 — medições e controles ajustados para mm reais"*.
|
||||
|
||||
**Fase 1 (essencial — destrava você hoje):**
|
||||
- DevKitFlag + SimXRSession + FakeControllers + DevPanel (aba Inputs + Logs)
|
||||
Inserir o componente em:
|
||||
- **`ViewerControls`** (canto dos controles flutuantes do Viewer 2D)
|
||||
- **`XRHud`** (linha de ferramentas, próximo ao toggle "Escala ON/OFF" two-hand)
|
||||
|
||||
**Fase 2 (essencial — instrumenta o testador):**
|
||||
- XRDevHud expandido + DevPanel aba Cena/XR + Exportar relatório
|
||||
### 7. MeasurementsList & FineTuningControls
|
||||
|
||||
**Fase 3 (qualidade de vida):**
|
||||
- SmokeTest + RecordSession
|
||||
Adicionar pequeno badge "Escala atual: 1:50" no topo dos painéis de Medições e Ajuste Fino para o usuário lembrar que os valores exibidos são mm reais.
|
||||
|
||||
Posso entregar a **Fase 1 inteira** agora numa única leva, e as fases 2 e 3 sob demanda quando você validar que a 1 te serve. Cabe?
|
||||
## O que NÃO muda
|
||||
|
||||
## Detalhes técnicos
|
||||
- Gesto two-hand de escala (`allowScale`) continua funcionando para ajuste livre — mas se o usuário usar o preset, o gesto reseta para 1.0 e o preset assume.
|
||||
- Relatório PDF: registra a escala atual no cabeçalho.
|
||||
- Grid e checklist: sem alteração.
|
||||
|
||||
- **Sem novas dependências.** Tudo com Three.js, R3F, Zustand já presentes.
|
||||
- **TypeScript rigoroso.** Tipos compartilhados entre real e fake (mesma interface `ControllerGrabSnapshot`).
|
||||
- **Zero impacto em produção:** sem flag, bundle do DevKit nem é importado se usarmos `React.lazy()` na entrada.
|
||||
- **Hot-swappable:** ligar/desligar o DevKit não recarrega a página (estado da cena preservado).
|
||||
## Arquivos tocados
|
||||
|
||||
- `src/stores/useModelStore.ts` — novo estado + ajuste em `addMeasurePoint`
|
||||
- `src/components/ScaleSelector.tsx` — novo (popover com presets)
|
||||
- `src/components/ViewerControls.tsx` — incluir `<ScaleSelector />`
|
||||
- `src/components/XRHud.tsx` — incluir `<ScaleSelector />` + multiplicar passos do joystick
|
||||
- `src/components/FineTuningControls.tsx` — multiplicar passos pela escala + badge
|
||||
- `src/components/MeasurementsList.tsx` — badge da escala
|
||||
- `src/components/three/ModelViewer.tsx` — aplicar `scaleRatio.factor` no group + ajustar threshold de snap/hover
|
||||
- `src/lib/generateReport.ts` — incluir escala no cabeçalho do PDF
|
||||
|
||||
## Validação
|
||||
|
||||
- Carregar viga demo, medir uma aresta conhecida em 1:1 → trocar para 1:10 → remedir mesma aresta → valor em mm deve permanecer igual.
|
||||
- Em 1:50, clicar "+" no ajuste fino X uma vez → modelo desloca visualmente pouquíssimo (esperado), mas valor exibido sobe 1 mm.
|
||||
- No XR, joystick em 1:100 não "voa" o modelo a metros de distância.
|
||||
|
||||
Reference in New Issue
Block a user