diff --git a/GeradoresService/README.md b/GeradoresService/README.md new file mode 100644 index 0000000..2cc7897 --- /dev/null +++ b/GeradoresService/README.md @@ -0,0 +1,71 @@ +# 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//` | 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 { ["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//` 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. diff --git a/GeradoresWS/README.md b/GeradoresWS/README.md new file mode 100644 index 0000000..efd346f --- /dev/null +++ b/GeradoresWS/README.md @@ -0,0 +1,64 @@ +# GeradoresWS + +API REST ASP.NET Core (.NET 10, minimal APIs) que expõe os geradores do +[GeradoresService](../GeradoresService/README.md). É só de leitura, não tem autenticação nem base de dados. + +## Executar + +```bash +dotnet run --project GeradoresWS --launch-profile http +# http://localhost:5053 → redirecciona para /docs +``` + +| Perfil (`launchSettings.json`) | URL | +|---|---| +| `http` | http://localhost:5053 | +| `https` | https://localhost:7266 e http://localhost:5053 | +| `Docker` | Visual Studio, usa o `Dockerfile` desta pasta | + +## Endpoints + +| Método | Rota | Descrição | +|---|---|---| +| GET | `/api/v1/generators` | Lista os geradores e as opções de cada um | +| GET | `/api/v1/generators/{id}` | Detalhe de um gerador (404 se não existir) | +| GET | `/api/v1/generators/{id}/generate` | Gera valores. Query: `count` (1–1000, por omissão 1), `seed` (opcional) e as opções do gerador | +| GET | `/api/v1/generators/{id}/validate?value=...` | Valida um valor de um tipo (404 se o tipo não validar) | +| GET | `/api/v1/validate?value=...` | Validador livre: detecta o tipo e valida | +| GET | `/openapi/v1.json` | Documento OpenAPI | +| GET | `/docs` | Documentação interactiva (Scalar) | +| GET | `/health` | Health check | + +Exemplos: + +```bash +curl "http://localhost:5053/api/v1/generators/nif/generate?count=5&tipo=5" +curl "http://localhost:5053/api/v1/generators/iban/validate?value=PT50000201231234567890154" +curl "http://localhost:5053/api/v1/validate?value=123456789" +``` + +Erros de input (opção desconhecida, valor de opção inválido, `count` fora do intervalo) devolvem +`400` com `ValidationProblemDetails`; as restantes falhas devolvem `ProblemDetails`. + +## Configuração + +- **CORS**: qualquer origem pode fazer `GET` (API pública, sem credenciais). +- **Porta em container**: `8080` (`ASPNETCORE_HTTP_PORTS`). +- `InvariantGlobalization` está activo, por isso a imagem não precisa de ICU. + +## Docker + +O `Dockerfile` da raiz do repositório é o usado no `docker compose` e no Jenkins. O `Dockerfile` desta pasta é +equivalente, com o stage `base` que o Visual Studio espera. Em ambos o contexto de build é a raiz do repositório: + +```bash +docker build -t geradoresws . +docker run -p 5050:8080 geradoresws +``` + +## Ficheiros + +| Ficheiro | Conteúdo | +|---|---| +| `Program.cs` | Serviços (registry, OpenAPI, CORS, health checks) e pipeline | +| `GeneratorEndpoints.cs` | Rotas `/api/v1` e DTOs de resposta | diff --git a/README.md b/README.md index d05c990..773f62c 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ matrículas, EAN e UUID. | 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 | +| [`GeradoresService/`](GeradoresService/README.md) | Biblioteca com os algoritmos. Cada tipo é uma classe `IGenerator` em `Generators/` | +| [`GeradoresWS/`](GeradoresWS/README.md) | API ASP.NET Core (.NET 10, minimal APIs, OpenAPI + Scalar) | +| [`UnitTest/`](UnitTest/README.md) | Testes xUnit (algoritmos, valores conhecidos e API) | +| [`geradoresfe/`](geradoresfe/README.md) | Frontend React + Vite + Tailwind. A UI é construída a partir dos metadados da API | ## Desenvolvimento diff --git a/UnitTest/README.md b/UnitTest/README.md new file mode 100644 index 0000000..15608d9 --- /dev/null +++ b/UnitTest/README.md @@ -0,0 +1,20 @@ +# UnitTest + +Testes xUnit da biblioteca [GeradoresService](../GeradoresService/README.md) e da API +[GeradoresWS](../GeradoresWS/README.md). + +```bash +dotnet test UnitTest +``` + +| Ficheiro | O que cobre | +|---|---| +| `GeneratorRoundTripTests.cs` | Para cada gerador e cada valor de cada opção, gera valores e confirma que o validador os aceita. Também: campos da pessoa fictícia válidos, `seed` reprodutível, ids únicos, opções e quantidades inválidas | +| `KnownValuesTests.cs` | Valores reais/conhecidos válidos e inválidos (NIF, NIPC, NISS, CC, IBAN, …) e o dígito de controlo esperado | +| `DetectTests.cs` | Validador livre: ordem dos resultados, quase-acertos (formato certo, controlo errado) e valores sem correspondência | +| `ApiTests.cs` | Testes de integração com `WebApplicationFactory`: listagem, geração em lote, 400/404, validação, detecção, OpenAPI e `/health` | + +Os testes de ida e volta são gerados a partir do `GeneratorRegistry`, por isso um gerador novo fica coberto sem +escrever testes. Os valores conhecidos devem ser acrescentados à mão sempre que se corrige um bug num algoritmo. + +O Jenkins corre `dotnet test UnitTest/UnitTest.csproj -c Release` antes de construir as imagens. diff --git a/geradoresfe/README.md b/geradoresfe/README.md new file mode 100644 index 0000000..ccf0bfb --- /dev/null +++ b/geradoresfe/README.md @@ -0,0 +1,63 @@ +# geradoresfe + +Frontend React 19 + Vite + Tailwind CSS 4 + TypeScript. A UI não conhece os tipos de gerador: lê +`/api/v1/generators` e constrói as páginas e os formulários de opções a partir dos metadados da +[API](../GeradoresWS/README.md). + +## Desenvolvimento + +```bash +npm install +npm run dev # http://localhost:3000 +``` + +O Vite faz proxy de `/api`, `/docs` e `/openapi` para `http://localhost:5053` +(`dotnet run --project GeradoresWS --launch-profile http`). Para outro backend: +`API_PROXY_TARGET=http://host:porta npm run dev`. + +| Script | Descrição | +|---|---| +| `npm run dev` | Servidor de desenvolvimento | +| `npm run build` | Type-check (`tsc -b`) e build de produção em `dist/` | +| `npm run lint` | ESLint | +| `npm test` | Vitest | +| `npm run preview` | Serve o build localmente | + +## Páginas + +| Rota | Página | +|---|---| +| `/` | Lista de geradores por categoria | +| `/gerador/:id` | Opções, geração em lote (até 1000), cópia e exportação CSV/JSON/TXT | +| `/validar` | Validador livre: detecta o tipo e explica porque é (in)válido | +| `/NIF`, `/NISS`, `/CC` | Redireccionam para as rotas novas | + +## Estrutura + +| Caminho | Conteúdo | +|---|---| +| `src/lib/api.ts` | Cliente da API e tipos | +| `src/lib/useGenerators.tsx` | Contexto que carrega a lista de geradores uma vez | +| `src/lib/export.ts` | Exportação CSV/JSON/TXT (testado em `export.test.ts`) | +| `src/pages/` | Páginas das rotas | +| `src/components/` | Cartões, formulário de opções, validador, resultados | +| `src/components/ui/` | Componentes base (botão, input, select, badge, …) | +| `src/layout/` | Cabeçalho, rodapé e layout | +| `src/context/ThemeContext.tsx` | Modo claro/escuro | + +## API + +Por omissão o cliente usa caminhos relativos (`/api/v1`). Em dev é o proxy do Vite; em produção é o nginx. +`VITE_API_URL` (em build time) permite apontar para outro host. + +## Docker + +```bash +docker build -t geradoresfe . +docker run -p 3000:80 -e API_UPSTREAM=http://geradoresws:8080 geradoresfe +``` + +A imagem serve o build com nginx. O `nginx.conf.template` é processado com `envsubst` no arranque, e +`/api`, `/docs` e `/openapi` são encaminhados para `API_UPSTREAM` (por omissão `http://geradoresws:8080`). +A mesma imagem serve em qualquer ambiente sem rebuild. Os ficheiros em `/assets/` têm cache longa e o resto +cai no `index.html` (SPA).