Documentação

# Manual Técnico — VIN V3

Estado: atualizado após API/decoder/UX.

## Arquitetura

A V3 é autónoma e não deve depender do V1 em runtime.

Componentes principais:

- `public/v3/index.php` — UX de pesquisa VIN.
- `public/v3/scan.php` — scan QR/barcode/foto.
- `public/v3/ai_vision.php` — AI Vision para VIN sticker, matrícula/cor e dashboard.
- `public/v3/api/web/*` — endpoints internos usados pelo UX.
- `public/v3/api/external/*` — API externa com API key obrigatória.
- `includes/v3/Services/WebVinViewService.php` — agregação principal da consulta VIN.
- `includes/v3/Services/V1DecodeEngineV3Service.php` — motor V1 portado para V3 usando tabelas V3/importadas.
- `includes/v3/Services/EngineCodeDecoderService.php` — decoder explícito de códigos de motor.
- `includes/v3/Services/TransmissionCodeDecoderService.php` — decoder explícito de códigos de transmissão.

## Segurança API

Endpoints externos devem usar `ApiAuth::requireKey()`.

A API key pode ser enviada por header configurado, por defeito `X-API-Key`, ou por query string `api_key` apenas para testes controlados.

## Decoders reais

O decoder real não usa inferência.

Fontes permitidas:

1. factory sheet explícita;
2. sales code explícito;
3. tabela decoder correspondente.

Não permitido no decoder:

- fallback;
- fuzzy text;
- profile persistido;
- mapping genérico;
- inferência por VIN;
- valores prováveis.

## Engine decoder

Tabela: `v3_engine_code_decoder`.

Serviço: `EngineCodeDecoderService`.

Exemplo: `2.5L TD ENG(ENC)/5SP MAN TRANS(DDQ)` resolve `ENC = 2.5L I4 Turbo Diesel Engine`.

## Transmission decoder

Tabela: `v3_transmission_code_decoder`.

Serviço: `TransmissionCodeDecoderService`.

Exemplo: `TRANS(DDQ)` resolve `DDQ = 5-Speed Manual (AX15) (AX5) Transmission`.

O serviço não resolve texto genérico como `5-Speed Manual Transmission`.

## OpenAI Vision

Modos suportados:

- `vin_sticker`
- `plate_color`
- `dashboard`

Endpoints externos:

- `api/external/vision.php`
- `api/external/scan_photo.php`
- `api/external/plate_color.php`
- `api/external/dashboard.php`

Todos exigem API key.

## UX loaders

Há loaders para:

- consulta VIN/factory sheet;
- envio de foto para OpenAI Vision;
- OCR pesado no scan.

## Documentação admin

Página: `public/v3/admin_docs.php`.