UNPKG

@anpdgovbr/shared-types

Version:

Biblioteca central de tipos TypeScript compartilhados para os projetos da ANPD (BETA)

758 lines (597 loc) 22.4 kB
# ANPD Shared Types (BETA) ![NPM Version](https://img.shields.io/npm/v/@anpdgovbr/shared-types?color=orange) ![Language](https://img.shields.io/badge/language-TypeScript-blue) ![Beta](https://img.shields.io/badge/status-beta-orange) ![License](https://img.shields.io/npm/l/@anpdgovbr/shared-types) Repositório central de tipos, DTOs, enums e interfaces compartilhadas para os projetos da ANPD. > ⚠️ **VERSÃO BETA** - Esta biblioteca está em desenvolvimento ativo. Use com cautela em produção. --- ## 🚨 Migração para v0.2.0 (API Quarkus) A versão 0.2.0 introduz **breaking changes** significativos para suportar a nova API Quarkus de Controladores. Se você está migrando de versões anteriores, consulte a [seção de migração](#-guia-de-migração-v010-v020). ### Principais Mudanças - **IDs agora são UUID (string)** ao invés de `number` - **Campos de contato são arrays** (`emails[]`, `telefones[]`) - **Novos enums**: `SetorEmpresarial`, `Esfera`, `Poder` - **ControladorDto redesenhado** com campos obrigatórios da API Quarkus - **EncarregadoDto redesenhado** sem referências diretas a controlador --- ## 🎯 Visão Geral Este pacote centraliza todos os tipos TypeScript reutilizáveis, Data Transfer Objects (DTOs), enums e interfaces utilizados nos diversos serviços e aplicações da ANPD. O objetivo é garantir padronização, reuso de código e consistência tipada em toda a stack, servindo como a **fonte única da verdade** para os contratos de dados. > **📦 Publicado no NPM:** [@anpdgovbr/shared-types](https://www.npmjs.com/package/@anpdgovbr/shared-types) ## 🔄 Compatibilidade de APIs | Faixa de versão | Backend oficial | Observações principais | | --------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- | | `0.1.x` | `controladores-api-nest` | IDs numéricos e campos singulares (`email`, `telefone`). | | `0.2.x` | `controladores-api-quarkus` | IDs em UUID v4, contatos em arrays (`emails`, `telefones`) e enums `SetorEmpresarial`, `Esfera`, `Poder`. | > As versões `0.2.x` são compatíveis apenas com os contratos gerados pelo OpenAPI `controladores-openapi.json` (Quarkus). Consumidores ainda integrados ao backend NestJS devem permanecer em `0.1.x` até finalizar a migração. ### Migração Controladores Quarkus (`0.2.x`) - `BaseEntity.id` agora é um `UUID` (`string`) seguindo `[a-f0-9-]{36}`. Utilize `crypto.randomUUID()` para gerar IDs em testes/mocks. - Contatos de Controladores e Encarregados passam a ser arrays (`EmailContatoDto[]`, `TelefoneContatoDto[]`) alinhados ao contrato OpenAPI. - Novos enums `SetorEmpresarial`, `Esfera`, `Poder` e `TipoPessoaEnum` orientam os campos obrigatórios do backend Quarkus. - DTOs atualizados: - `ControladorDto` reflete os campos `nomeEmpresarial`, `setorEmpresarial`, `setorId` e `cnaeId` em UUID, além de `emails`/`telefones`. - `CnaeDto`, `SetorDto` e `SocioControladorDto` utilizam UUIDs e expõem `exclusionDate` como string ISO. - `EncarregadoDto` remove vínculos diretos com Controladores, preservando apenas os dados de contato e identificação. - `BaseQueryParams.orderBy` agora aceita apenas campos expostos pelo Quarkus (`nomeEmpresarial`, `codigo`, `nome`), evitando divergências de ordenação. #### Checklist de migração para times consumidores 1. **Atualize a dependência** para `@anpdgovbr/shared-types@0.2.x` em `backlog-dim`, portais públicos e ferramentas de auditoria. 2. **Ajuste IDs**: substitua tipos numéricos (`number`) por `string`/`UUID` em stores, schemas e payloads. 3. **Normalize contatos**: adeque formulários e persistência para lidar com arrays de e-mails/telefones. 4. **Reveja filtros e ordenações**: garanta que `orderBy`, `setorEmpresarial`, `esfera` e `poder` estejam sincronizados com os novos enums. 5. **Regenerar mocks**: utilize `crypto.randomUUID()` ou fixtures equivalentes para cenários de teste. ## 📦 Como Usar ### 1. Instalação ```bash # Com npm (fixando a versão beta) npm install @anpdgovbr/shared-types@0.2.0-beta.0 # Com yarn yarn add @anpdgovbr/shared-types@0.2.0-beta.0 # Com pnpm pnpm add @anpdgovbr/shared-types@0.2.0-beta.0 ``` ### 2. Suporte a Múltiplos Módulos Esta biblioteca suporta tanto **CommonJS** quanto **ES Modules**, permitindo uso flexível em diferentes ambientes: ```typescript // Import padrão (funciona em ambos os módulos) import { UserDto, AcaoAuditoria } from "@anpdgovbr/shared-types" // Import específico de tipos import type { BaseQueryParams, BasePaginatedResponse, } from "@anpdgovbr/shared-types" // Import de utilitários (funções runtime) import { isStatusInterno, coerceStatusInterno } from "@anpdgovbr/shared-types" ``` ### 3. Importação de Tipos Importe os tipos diretamente do pacote. O ponto de entrada principal exporta todas as entidades "core" do sistema. ```typescript import { UserDto, AcaoAuditoria, BaseQueryParams, BasePaginatedResponse } from "@anpdgovbr/shared-types" // Exemplo de uso em paginação const params: BaseQueryParams = { page: 1, pageSize: 10, search: "termo de busca", orderBy: "nome", ascending: true } // Exemplo de resposta tipada const response: BasePaginatedResponse<UserDto> = { data: [...], total: 50 } ``` #### Trabalhando com Usuários e Auditoria ```typescript import { UserDto, AuditLogDto, AcaoAuditoria } from "@anpdgovbr/shared-types" // Definindo um usuário const usuario: UserDto = { id: "uuid-123", email: "joao@anpd.gov.br", nome: "João Silva", perfilId: 1, active: true, } // Log de auditoria const auditLog: AuditLogDto = { id: 1, tabela: "usuarios", acao: AcaoAuditoria.CREATE, registroId: 123, userId: usuario.id, email: usuario.email, // Metadados de contexto (herdados de AuditContext) ip: "203.0.113.10", userAgent: "Mozilla/5.0", contexto: "Cadastro inicial", // Identificadores de correlação / trace distribuído (opcionais) requestId: "req-01HQZ0X9W5K7M6N7JZ8R4XYTQ2", traceId: "0af7651916cd43dd8448eb211c80319c", spanId: "b7ad6b7169203331", criadoEm: new Date(), } ``` #### Sistema de Permissões ```typescript import { PermissaoDto, PermissaoPayload, AcaoPermissao, RecursoPermissao, } from "@anpdgovbr/shared-types" // Criando uma permissão const novaPermissao: PermissaoPayload = { perfilId: 1, acao: "Editar" as AcaoPermissao, recurso: "Processo" as RecursoPermissao, permitido: true, } // Resultado da criação const permissaoCriada: PermissaoDto = { id: 10, acao: "Editar", recurso: "Processo", permitido: true, perfilId: 1, } ``` #### Domínio RH (Cargos e Estrutura) ```typescript import type { Cargo, AllowedField, ALLOWED_FIELDS, } from "@anpdgovbr/shared-types" // Exemplo de uso dos tipos em posições de tipo type CargoResumo = Pick<Cargo, "id" | "titulo_canonico" | "familia"> // Campos AD permitidos (array somente leitura) const campos: ReadonlyArray<AllowedField> = ALLOWED_FIELDS ``` #### Transversal: Microsoft Graph ```typescript import type { GraphUser, GraphGroup, GraphPagedResponse, } from "@anpdgovbr/shared-types" async function listarUsuarios(): Promise<GraphPagedResponse<GraphUser>> { // ... sua chamada ao Graph aqui return { value: [], "@odata.nextLink": undefined } } ``` #### Trabalhando com Controladores (API Quarkus - v0.2.0+) ```typescript import { ControladorDto, EmailContatoDto, TelefoneContatoDto, TipoControlador, SetorEmpresarial, Esfera, Poder, PageResponseDto, UUID, } from "@anpdgovbr/shared-types" // Criando um controlador público federal const controlador: ControladorDto = { nomeEmpresarial: "Ministério da Economia", nomeFantasia: "ME", tipo: TipoControlador.PESSOA_JURIDICA, cpf: "12345678900", // CPF do responsável cnpj: "00000000000191", site: "https://www.gov.br/economia", emails: [ { email: "contato@economia.gov.br" }, { email: "dpo@economia.gov.br" }, ], telefones: [{ codigoPais: "+55", telefone: "6132255000" }], politicaPrivacidadeUrl: "https://www.gov.br/economia/privacidade", setorEmpresarial: SetorEmpresarial.PUBLICO, esfera: Esfera.FEDERAL, poder: Poder.EXECUTIVO, setorId: "550e8400-e29b-41d4-a716-446655440000", cnaeId: "660e8400-e29b-41d4-a716-446655440000", active: true, } // Trabalhando com respostas paginadas da API Quarkus const response: PageResponseDto<ControladorDto> = { data: [controlador], page: 0, pageSize: 10, totalElements: 1, totalPages: 1, } // Validando UUID import { isUUID, assertUUID } from "@anpdgovbr/shared-types" const id: UUID = "550e8400-e29b-41d4-a716-446655440000" if (isUUID(id)) { console.log("UUID válido") } ``` #### Trabalhando com Encarregados (v0.2.0+) ```typescript import { EncarregadoDto, TipoControlador, EmailContatoDto, TelefoneContatoDto, } from "@anpdgovbr/shared-types" // Encarregado interno (pessoa natural) const encarregado: EncarregadoDto = { id: "770e8400-e29b-41d4-a716-446655440000", nome: "Maria Silva", tipo: TipoControlador.PESSOA_NATURAL, cpf: "12345678900", externo: false, emails: [{ email: "maria.silva@empresa.com.br" }], telefones: [{ codigoPais: "+55", telefone: "61999999999" }], active: true, } // Encarregado externo (empresa de consultoria) const encarregadoExterno: EncarregadoDto = { nome: "DPO Consultoria LTDA", tipo: TipoControlador.PESSOA_JURIDICA, cpf: "98765432100", // CPF do responsável cnpj: "12345678000190", externo: true, emails: [{ email: "contato@dpoconsultoria.com.br" }], telefones: [{ codigoPais: "+55", telefone: "1133334444" }], active: true, } ``` ## 📚 Estrutura do Projeto ``` src/ ├── base/ # 🏗️ Interfaces base e contratos fundamentais ├── base-entity.interface.ts # Entidade base com ID ├── named-entity.interface.ts # Entidade nomeada ├── soft-delete.interface.ts # Exclusão lógica ├── audit-context.interface.ts # Contexto de auditoria └── audited-entity.interface.ts # Entidade auditável ├── dto/ # 📄 Data Transfer Objects ├── user.dto.ts # Usuário do sistema ├── processo.dto.ts # Processos (Input/Output/Importação) ├── controlador.dto.ts # Controladores de dados ├── permissao.dto.ts # Sistema de permissões └── ... # Outros DTOs ├── enums/ # 🔢 Enumerações e tipos constantes ├── acao-auditoria.enum.ts # Ações de auditoria ├── permissao.enum.ts # Tipos de permissão ├── status-interno.enum.ts # Status internos └── ... # Outros enums ├── interfaces/ # 🔌 Interfaces utilitárias ├── base-query-params.interface.ts # Parâmetros de consulta ├── base-paginated-response.interface.ts # Resposta paginada └── enum-data.interface.ts # Dados enumerados ├── domain/ # 🧭 Tipos de domínios específicos (ex.: RH) └── rh/ # Cargos, Estrutura Organizacional, Vocabulários RH └── index.ts # 📥 Ponto de entrada principal ``` ## 🛠️ Para Desenvolvedores ### Scripts Disponíveis ```bash # Compilar o projeto (CommonJS + ESM) npm run build # Modo watch para desenvolvimento npm run watch # Limpar arquivos de build npm run clean # Verificar lint npm run lint # Corrigir problemas de lint automaticamente npm run lint:fix # Formatar código npm run format # Verificar formatação npm run format:check # Verificar tipos sem gerar arquivos npm run type-check # Gerar documentação com Typedoc npm run docs # Servir documentação localmente npm run docs:serve ``` ## 📖 Documentação A documentação completa da API é gerada automaticamente usando [Typedoc](https://typedoc.org/) a partir dos comentários TSDoc no código fonte. ### Gerar e Visualizar Documentação ```bash # Gerar documentação HTML em ./docs npm run docs # Servir documentação localmente para visualização interativa npm run docs:serve ``` Após executar `npm run docs`, abra o arquivo `./docs/index.html` no navegador para navegar pela documentação interativa dos tipos, interfaces, enums e DTOs disponíveis. ### Adicionando Novos Tipos 1. **Tipos Core (Transversais)** - Adicione em `src/` na pasta apropriada (`dto/`, `enums/`, `interfaces/`, `base/`) - Exporte no `index.ts` da pasta - Documente usando TSDoc 2. **Exemplo de novo DTO:** ````typescript // src/dto/novo-tipo.dto.ts import { BaseEntity } from "../base" /** * Representa um novo tipo no sistema. * * @remarks * Descrição detalhada do propósito e uso do tipo. * * @example * ```typescript * const exemplo: NovoTipoDto = { * id: 1, * nome: "Exemplo" * } * ``` */ export interface NovoTipoDto extends BaseEntity { nome: string // outras propriedades... } ```` 3. **Adicione no barrel export:** ```typescript // src/dto/index.ts export { NovoTipoDto } from "./novo-tipo.dto" ``` ## ⚠️ Status Beta Esta biblioteca está atualmente em **versão beta (0.1.7-beta-x)**. Isso significa: - **Funcional**: Os tipos estão funcionais e podem ser usados - ⚠️ **Em desenvolvimento**: Pode haver mudanças que quebrem compatibilidade - 🧪 **Testando**: Estamos refinando a API e estrutura - 🤝 **Feedback bem-vindo**: Sugestões e issues são muito apreciados ### Para Desenvolvedores - **Desenvolvimento**: Fique à vontade para usar e testar - **Produção**: Use com cautela e fixe a versão específica - **Atualizações**: Acompanhe o CHANGELOG para mudanças importantes ## 🤝 Manutenção e Contribuição ### Padrões de Código - **📝 Documentação:** Todos os novos tipos devem ser documentados utilizando o padrão TSDoc. - **🎯 Novos Tipos:** - Se o tipo for transversal e aplicável a múltiplos domínios, adicione-o em `src/`. - Se o tipo for específico de um contexto de negócio, crie ou utilize a pasta do domínio correspondente (futura implementação). - **🔧 Consistência:** Mantenha a padronização de nomenclatura e estrutura de arquivos. ### Versionamento Este projeto segue o [Semantic Versioning](https://semver.org/): - **MAJOR**: Mudanças que quebram compatibilidade - **MINOR**: Novas funcionalidades mantendo compatibilidade - **PATCH**: Correções de bugs mantendo compatibilidade - **BETA**: Versões de desenvolvimento (ex: 0.1.7-beta) ### Publicação Para publicar uma nova versão beta: ```bash # 1. Atualizar versão no package.json para X.Y.Z-beta npm version prerelease --preid=beta # 2. O script prepublishOnly irá rodar automaticamente: # - build, lint e format:check # 3. Publicar no NPM com tag beta npm publish --tag beta ``` Para publicar versão estável: ```bash # 1. Atualizar versão no package.json (remover -beta) npm version patch|minor|major # 2. Publicar no NPM npm publish ``` --- ## 📖 Guia de Migração (v0.1.x → v0.2.0) ### Breaking Changes A versão 0.2.0 introduz mudanças significativas para suportar a nova API Quarkus de Controladores. Este guia ajudará você a migrar seu código. #### 1. IDs agora são UUID (string) **Antes (v0.1.x):** ```typescript interface BaseEntity { id: number } const controlador: ControladorDto = { id: 123, setorId: 456, cnaeId: 789, // ... } ``` **Depois (v0.2.0):** ```typescript import { UUID } from "@anpdgovbr/shared-types" interface BaseEntity { id: UUID // string } const controlador: ControladorDto = { id: "550e8400-e29b-41d4-a716-446655440000", setorId: "660e8400-e29b-41d4-a716-446655440001", cnaeId: "770e8400-e29b-41d4-a716-446655440002", // ... } ``` **Ações necessárias:** - Atualize todos os campos `id` para aceitar `string` ao invés de `number` - Use `crypto.randomUUID()` para gerar novos IDs - Atualize queries de banco de dados e comparações de ID - Use `isUUID()` para validar IDs recebidos de entrada externa #### 2. ControladorDto: Campos Renomeados e Reestruturados **Antes (v0.1.x):** ```typescript const controlador: ControladorDto = { id: 123, nome: "Empresa ABC", email: "contato@empresa.com", telefone: "(61) 99999-9999", setorId: 1, cnaeId: 2, grupoEconomicoId: 3, } ``` **Depois (v0.2.0):** ```typescript const controlador: ControladorDto = { id: "550e8400-e29b-41d4-a716-446655440000", nomeEmpresarial: "Empresa ABC Ltda", // nome nomeEmpresarial nomeFantasia: "Empresa ABC", tipo: TipoControlador.PESSOA_JURIDICA, cpf: "12345678900", // obrigatório cnpj: "12345678000190", site: "https://empresa.com", emails: [ // email emails (array) { email: "contato@empresa.com" }, ], telefones: [ // telefone telefones (array) { codigoPais: "+55", telefone: "61999999999" }, ], politicaPrivacidadeUrl: "https://empresa.com/privacidade", setorEmpresarial: SetorEmpresarial.PRIVADO, setorId: "660e8400-e29b-41d4-a716-446655440001", cnaeId: "770e8400-e29b-41d4-a716-446655440002", // grupoEconomicoId removido active: true, } ``` **Ações necessárias:** - Renomeie `nome` para `nomeEmpresarial` - Converta `email` string para `emails: EmailContatoDto[]` - Converta `telefone` string para `telefones: TelefoneContatoDto[]` - Adicione campos obrigatórios: `cpf`, `site`, `politicaPrivacidadeUrl`, `setorEmpresarial` - Remova referências a `grupoEconomicoId` - Para controladores públicos, adicione `esfera` e `poder` #### 3. EncarregadoDto: Redesenhado **Antes (v0.1.x):** ```typescript const encarregado: EncarregadoDto = { id: 123, nome: "Maria Silva", email: "maria@empresa.com", telefone: "(61) 99999-9999", externo: false, controladorId: 456, } ``` **Depois (v0.2.0):** ```typescript const encarregado: EncarregadoDto = { id: "550e8400-e29b-41d4-a716-446655440000", nome: "Maria Silva", tipo: TipoControlador.PESSOA_NATURAL, cpf: "12345678900", externo: false, emails: [{ email: "maria@empresa.com" }], telefones: [{ codigoPais: "+55", telefone: "61999999999" }], active: true, // controladorId removido } ``` **Ações necessárias:** - Converta `email` para `emails: EmailContatoDto[]` - Converta `telefone` para `telefones: TelefoneContatoDto[]` - Adicione campo `tipo` (TipoControlador) - Adicione campo `cpf` obrigatório - Remova `controladorId` e `controladorEmpresaExternaId` - O relacionamento encarregado-controlador agora é gerenciado por endpoints específicos #### 4. CnaeDto e SetorDto: Campos Atualizados **Antes (v0.1.x):** ```typescript const cnae: CnaeDto = { id: 123, name: "Comércio varejista", code: "47.89-0-99", } ``` **Depois (v0.2.0):** ```typescript const cnae: CnaeDto = { id: "550e8400-e29b-41d4-a716-446655440000", nome: "Comércio varejista", // name nome codigo: "47.89-0-99", // code codigo active: true, exclusionDate: null, } ``` **Ações necessárias:** - Use `nome` ao invés de `name` (ou use alias deprecado temporariamente) - Use `codigo` ao invés de `code` (ou use alias deprecado temporariamente) - Os aliases `name` e `code` serão removidos na v1.0.0 #### 5. SoftDelete: Aceita Datas como String **Antes (v0.1.x):** ```typescript interface SoftDelete { active: boolean exclusionDate?: Date | null } ``` **Depois (v0.2.0):** ```typescript interface SoftDelete { active: boolean exclusionDate?: Date | string | null // aceita ISO 8601 string } ``` **Ações necessárias:** - APIs agora retornam `exclusionDate` como string ISO 8601 - Converta para `Date` no cliente se necessário: `new Date(exclusionDate)` #### 6. Novos Tipos e Enums ```typescript import { SetorEmpresarial, Esfera, Poder, EmailContatoDto, TelefoneContatoDto, PageResponseDto, ControladoresFiltroDto, UUID, isUUID, } from "@anpdgovbr/shared-types" // Novos enums para classificação de controladores públicos const setor = SetorEmpresarial.PUBLICO const esfera = Esfera.FEDERAL const poder = Poder.EXECUTIVO // Novo formato de resposta paginada da API Quarkus const response: PageResponseDto<ControladorDto> = { data: [], page: 0, pageSize: 10, totalElements: 0, totalPages: 0, } ``` ### Checklist de Migração - [ ] Atualizar dependência para `@anpdgovbr/shared-types@^0.2.0` - [ ] Alterar todos os campos `id` de `number` para `UUID` (string) - [ ] Atualizar formulários e hooks de `ControladorDto` com novos campos - [ ] Converter campos de contato para arrays (`emails[]`, `telefones[]`) - [ ] Remover referências a `grupoEconomicoId` de controladores - [ ] Atualizar `EncarregadoDto` removendo `controladorId` - [ ] Migrar de `BasePaginatedResponse` para `PageResponseDto` onde apropriado - [ ] Atualizar queries de filtro para usar `ControladoresFiltroDto` - [ ] Executar testes end-to-end com a nova API - [ ] Atualizar documentação interna ### Compatibilidade entre APIs | Funcionalidade | API NestJS (v0.1.x) | API Quarkus (v0.2.0) | | ---------------------------- | ------------------- | -------------------- | | ID Type | `number` | `UUID` (string) | | Email/Telefone | String único | Array de objetos | | ControladorDto.nome | | nomeEmpresarial | | SetorEmpresarial enum | | | | Esfera/Poder enums | | | | grupoEconomicoId | | | | EncarregadoDto.controladorId | | | | PageResponseDto | | | --- ## 📞 Suporte - **Issues:** [GitHub Issues](https://github.com/anpdgovbr/shared-types/issues) - **Documentação:** Este README e comentários TSDoc no código - **Equipe:** DDSS/CGTI/ANPD --- > 💻 Projeto mantido pela equipe DDSS/CGTI/ANPD. > > 📄 Licença: MIT