# GeradoresService

Biblioteca .NET 10 com os algoritmos de geração e validação. Não tem dependências externas e é usada pela API
([GeradoresWS](../GeradoresWS/README.md)) e pelos testes ([UnitTest](../UnitTest/README.md)).

## Estrutura

| Caminho | Conteúdo |
|---|---|
| `Core/IGenerator.cs` | Contrato de um gerador/validador e as categorias |
| `Core/GeneratorBase.cs` | Classe base com valores por omissão e o helper `Option(...)` |
| `Core/Models.cs` | `GeneratorOption`, `GeneratedItem`, `ValidationResult`, `GeneratorContext` |
| `Core/Checksums.cs` | Algoritmos partilhados: módulo 11, Luhn (com letras), MOD 97-10, limpeza de input |
| `Data/PtData.cs` | Nomes, apelidos, localidades, bancos e outros dados portugueses fictícios |
| `Generators/<Categoria>/` | Um ficheiro por tipo |
| `GeneratorRegistry.cs` | Lista de geradores, geração em lote e detecção automática do tipo |

## Geradores

| Id | Nome | Categoria | Validação |
|---|---|---|---|
| `nif` | NIF | Identificação | Módulo 11, pesos 9..2 |
| `nipc` | NIPC | Identificação | Igual ao NIF, só prefixos de pessoa colectiva |
| `niss` | NISS | Identificação | 9 − (Σ dígito × peso) mod 10, pesos 29, 23, 19, 17, 13, 11, 7, 5, 3, 2 |
| `cc` | Cartão de Cidadão | Identificação | Módulo 11 no NIC + Luhn (A=10..Z=35) no documento |
| `passaporte` | Passaporte | Identificação | Só formato (letra + 6 dígitos) |
| `iban` | IBAN | Financeiro | ISO 7064 MOD 97-10; aceita IBAN de qualquer país |
| `nib` | NIB | Financeiro | 98 − (NIB19 × 100 mod 97) |
| `cartao-credito` | Cartão de crédito | Financeiro | Luhn |
| `multibanco` | Referência Multibanco | Financeiro | 98 − (Σ dígito × peso mod 97) sobre entidade + referência + montante |
| `pessoa` | Pessoa fictícia | Contactos e Morada | Não valida (gerador composto) |
| `telefone` | Telefone | Contactos e Morada | Só formato (Plano Nacional de Numeração) |
| `codigo-postal` | Código postal | Contactos e Morada | Só formato (NNNN-NNN) |
| `email` | Email | Contactos e Morada | Só formato |
| `matricula` | Matrícula | Outros | Só formato (todos os formatos desde 1937) |
| `ean` | EAN / Código de barras | Outros | Dígito GS1 (pesos 3,1,3,1…) |
| `uuid` | UUID / GUID | Outros | Só formato (v4 ou v7) |

`HasChecksum` indica se a validação verifica um dígito de controlo ou apenas o formato; `CanValidate` é
`false` para geradores compostos como `pessoa`.

## Utilização

```csharp
var registry = new GeneratorRegistry();
var nif = registry.Find("nif")!;

// 10 NIF de pessoa colectiva, reprodutíveis com seed
var items = registry.Generate(nif, 10, new Dictionary<string, string?> { ["tipo"] = "5" }, seed: 42);

// Validação de um tipo
ValidationResult r = nif.Validate("123456789");   // IsValid, FormatMatch, Message, Normalized, Details

// Detecção automática: válidos primeiro, depois os que têm o formato mas falham o controlo
var matches = registry.Detect("PT50 0002 0123 1234 5678 9015 4");
```

- O lote vai de 1 a `GeneratorRegistry.MaxBatch` (1000); fora disso lança `ArgumentOutOfRangeException`.
- Um valor de opção que não esteja nas escolhas do gerador lança `ArgumentException`.
- `ValidationResult.Details` traz os passos do cálculo, para explicar porque um valor é (in)válido.

## Adicionar um gerador

1. Criar uma classe em `Generators/<Categoria>/` que herde de `GeneratorBase` e implemente `Id`, `Name`,
   `Category`, `Description`, `Generate` e `Validate`. As opções declaram-se com `Option(key, label, default, choices...)`
   e lêem-se com `context.Option(Options[i])`.
2. Usar sempre `context.Random` (nunca `Random.Shared`), para que o `seed` produza resultados reprodutíveis.
3. Registar a instância no construtor de `GeneratorRegistry`.

O novo tipo aparece automaticamente na API e no frontend, e o `GeneratorRoundTripTests` passa a gerá-lo com
todas as opções e a confirmar que o validador aceita os valores gerados.