# Factory Id — Geradores

Geradores e validadores de dados portugueses para testes de software: NIF, NIPC, NISS, Cartão de Cidadão,
IBAN/NIB, cartões de pagamento, referências Multibanco, telefones, códigos postais, emails, pessoas fictícias,
matrículas, EAN e UUID.

- **Geração em lote** (até 1000 de cada vez) com exportação CSV, JSON e TXT
- **Validador livre**: cola-se um valor qualquer, o tipo é detectado e é explicado porque é (in)válido
- **API REST** documentada em `/docs`

## Estrutura

| Pasta | Conteúdo |
|---|---|
| `GeradoresService/` | Biblioteca com os algoritmos. Cada tipo é uma classe `IGenerator` em `Generators/` |
| `GeradoresWS/` | API ASP.NET Core (.NET 10, minimal APIs, OpenAPI + Scalar) |
| `UnitTest/` | Testes xUnit (algoritmos, valores conhecidos e API) |
| `geradoresfe/` | Frontend React + Vite + Tailwind. A UI é construída a partir dos metadados da API |

## Desenvolvimento

```bash
# API em http://localhost:5053 (docs em /docs)
dotnet run --project GeradoresWS --launch-profile http

# Frontend em http://localhost:3000 (faz proxy de /api para a API)
cd geradoresfe && npm install && npm run dev
```

Testes:

```bash
dotnet test UnitTest
cd geradoresfe && npm test && npm run lint
```

## Docker

```bash
docker compose up --build
# Frontend: http://localhost:3000   API directa: http://localhost:5050/docs
```

O nginx do frontend encaminha `/api`, `/docs` e `/openapi` para `API_UPSTREAM`
(por omissão `http://geradoresws:8080`), por isso a mesma imagem funciona em qualquer ambiente
sem rebuild.

## API

| Método | Rota | Descrição |
|---|---|---|
| GET | `/api/v1/generators` | Lista de geradores e opções |
| GET | `/api/v1/generators/{id}/generate?count=10&<opção>=<valor>` | Gera valores (`seed` opcional para resultados reprodutíveis) |
| GET | `/api/v1/generators/{id}/validate?value=...` | Valida um valor de um tipo |
| GET | `/api/v1/validate?value=...` | Detecta o tipo e valida |
| GET | `/health` | Health check |

Exemplo: `GET /api/v1/generators/nif/generate?count=5&tipo=5` gera 5 NIF de pessoa colectiva.

## Adicionar um gerador

1. Criar uma classe em `GeradoresService/Generators/<Categoria>/` que herde de `GeneratorBase`.
2. Registá-la em `GeneratorRegistry`.
3. Pronto: aparece na API, no frontend e é coberta automaticamente pelo teste de ida e volta
   (`GeneratorRoundTripTests`), que gera valores com todas as opções e confirma que o validador os aceita.