@anpdgovbr/shared-types
Version:
Biblioteca central de tipos TypeScript compartilhados para os projetos da ANPD (BETA)
758 lines (597 loc) • 22.4 kB
Markdown
# ANPD Shared Types (BETA)




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