Recursos e uso do designer de domínio

Este documento é o guia técnico para todos os recursos do Domain Designer MVP dentro de:

• aplicativos/gerenciamento de serviço/

Abrange o que cada recurso faz e como usá-lo na prática.

1) Tela e navegação

Características:

• Retângulos de domínio (codificados por cores)
• Cartões de entidade dentro de domínios
• Panorâmica, zoom, ajuste, redefinição
• Snap-to-grid
• Visualização compacta/completa
• Modo de desempenho em tela grande
• Navegação no minimapa
• Desfazer/refazer

Como usar:

1. Crie domínios e entidades no painel esquerdo.
2. Arraste os cabeçalhos de domínio e de entidade para reposicionar.
3. Uso:
   • Ctrl/Cmd + roda do mouse para zoom
   • Espaço + arrastar para panorâmica
   • Fit e Reset View para enquadramento rápido
4. Ative Large Canvas para diagramas de alta densidade.
5. Use o minimapa para focar um domínio rapidamente.

2) Design de Relacionamento

Características:

• Criação de relacionamento baseado em formulário (de, para, cardinalidade)
• Modo pick-on-canvas
• Conectores de arrasto âncora a âncora
• Relacionamento reverso
• Geração automática de FK
• Controles de deslocamento de rótulo (x, y)
• Controles de caminho de curvatura (bendX, bendY)
• Comportamento da âncora (auto, center)
• Estilo de roteamento (curvo, ortogonal)

Como usar:

1. Selecione as entidades de origem e destino e clique em Conectar.
2. Ou clique em Pick On Canvas e selecione as entidades diretamente.
3. Para conexões com reconhecimento de âncora, arraste das âncoras de borda (superior/direita/inferior/esquerda) entre as entidades.
4. Selecione um relacionamento na lista e ajuste:
   • deslocamento da etiqueta
   • pontos de curvatura
   • comportamento âncora
5. Clique em Salvar relacionamento.

3) Metadados de contexto de domínio

Metadados por domínio:

• Linguagem onipresente
• Equipe proprietária
• Dependências ascendentes
• Dependências a jusante
• Canal de integração
• Dependências de pacotes
• Objetos de valor compartilhado

Como usar:

1. Selecione um domínio.
2. Preencha os valores em Contexto Limitado.
3. Clique em Salvar contexto.

Esses campos são persistidos no estado do designer e exportados por meio de fluxos JSON/pacote.

4) Edição de entidades e modelos

Recursos em nível de entidade:

• Renomear, mover, duplicar, excluir
• Sinalizador raiz agregado
• Editor de invariantes
• Campo CRUD com metadados alinhados ao OpenAPI
• Modelos de campo (tenantRef, auditTrail, softDelete, contactPack)
• Modelos de entidade:
  • crudAgregado
  • eventSourced
  • referênciaDados
  • tenantOwned

Como usar:

1. Selecione uma entidade.
2. Use o Inspetor de Entidades para renomear/mover/regras.
3. Adicione campos manualmente ou aplique modelos de campo.
4. Aplique modelos de entidade do painel Entidades.

5) Mapeamento de políticas RBAC

Política de ação por entidade, alinhada ao contrato de autorização de tenant e RBAC (TENANT-RBAC-AUTHORIZATION-CONTRACT.pt-BR.md, JUM-477):

• Ações:
  • lista
  • getById
  • criar
  • atualizar
  • excluir
• Alternância de função (as funções normalizadas do contrato):
  • superadministrador
  • administrador
  • usuário
• Escopo do locatário: derivado das funções selecionadas, não um sinalizador livre. O runtime (Rbac.ts / TenantAuthorizationPolicy.ts) restringe os principais admin e user à própria organização e concede ao superadmin um limite global — não existe um botão independente de escopo de locatário a ser honrado, portanto o editor exibe o valor derivado como uma caixa de seleção somente leitura. Políticas armazenadas são reparadas para o valor derivado no carregamento.
• Escopos diretos legados (read_user, create_organization, …) continuam suportados pelo runtime e sobrevivem à importação/exportação, mas não são editáveis no inspetor; a validação os aceita como expressíveis pelo contrato.
• Uma função fora do vocabulário do contrato é rejeitada no momento da gravação com uma mensagem acionável, e a validação do modelo relata qualquer função armazenada desse tipo como error, de modo que o portão de qualidade de exportação a bloqueia em vez de descartá-la.

Como usar:

1. Selecione entidade e ação.
2. Marque as funções permitidas; o indicador de escopo do locatário acompanha as funções.
3. Clique em Salvar regra RBAC.
4. Revise a matriz gerada na lista RBAC.

6) Designer de contrato de mensagem

Tipos de contrato suportados:

• evento
• comando
• pedido
• resposta

Campos do contrato:

• nome
• digite
• canal/tópico
• versão
• esquema de carga útil (editor JSON)

Como usar:

1. Selecione a entidade.
2. Preencha o nome/tipo/canal/versão do contrato.
3. Clique em Adicionar contrato.
4. Use o botão payload para editar o esquema JSON.

As exportações incluem esses contratos em:

• Extensão OpenAPI (x-message-contracts)
• Exportação AsyncAPI

7) Composição Avançada OpenAPI

Controles por entidade:

• oneOf, allOf, anyOf
• lista de referências de esquema
• lista externa $ref
• propriedade discriminadora

Como usar:

1. Selecione a entidade.
2. Escolha o modo de composição.
3. Adicione referências de esquema e referências externas opcionais.
4. Defina o discriminador, se necessário.
5. Salve a composição.

8) Validação, Portão de Qualidade e Diferença

Características:

• Verificações de modelo com gravidade:
  • erro
  • avisar
  • informações
• Filtro de gravidade mínima configurável
• Bloco de exportação em questões críticas
• Salvar/limpar linha de base do esquema
• Diferença de esquema e dicas de migração

Como usar:

1. Clique em Validar modelo.
2. Ajuste o filtro de gravidade, se necessário.
3. Habilite o bloqueio de exportação em questões críticas para impor o controle de qualidade.
4. Salve uma linha de base e execute diff para detectar alterações.

9) Exemplo e geração de código

Saídas geradas:

• Exemplos de carga útil de solicitação/resposta
• Visualização do esqueleto do código:
  • modelo
  • porta do repositório
  • caso de uso
  • controlador
  • manipulador

Como usar:

1. Selecione uma entidade para saída focada ou mantenha nenhuma selecionada para saída em tela inteira.
2. Clique em:
   • Gerar Exemplos
   • Visualização do código

10) Destinos de exportação e importação

Exportar:

• modelo JSON -OpenAPI 3.1
• Remarcação
• Esquema JSON
• API assíncrona
• Pacote padrão
• Pacote de domínio

Importar:

• modelo JSON -OpenAPI 3.1
• Pacote de domínio

Como usar:

1. Use os botões de exportação no painel Exportar.
2. Use botões de importação para JSON/OAS/pacote.
3. Para exportação de pacotes, o domínio selecionado é usado como pacote de origem.

10.1) Contrato de exportação OAS 3.1 (Requisito 036, JUM-474)

A exportação OpenAPI 3.1 produz um documento em conformidade com o Requisito 036 e com a verificação de resolução de rotas (ci-cd/check-oas-route-resolution.js):

• Toda operação carrega um operationId único no esquema de verbos canônico do spec/1.0.0.yml (getAll*, create*, get*ById, update*, delete*), qualificado pelo nome do schema (getAllBilling_Invoice).
• Corpos de requisição referenciam os objetos de porta de entrada RequestCreate<Schema> / RequestUpdate<Schema> via $ref; respostas 2xx referenciam o schema da entidade, seu wrapper <Schema>ArrayOf ou ResourceDeleteResponse. Sem schemas inline de requisição/resposta, e todo schema referenciado tem descrição.
• Os wrappers de porta de entrada/saída são marcados com 'x-port-object': true e ignorados na importação OAS, de modo que uma ida e volta não cria entidades fantasmas.
• Respostas de erro usam os códigos canônicos de ERROR-CONTRACTS-AND-RESPONSES (400/401/403/404/409).
• Entidades cujos nomes colapsam para o mesmo nome de schema OAS ou rota (por exemplo Foo Bar vs Foo-Bar) falham no portão de qualidade de exportação em vez de sobrescrever silenciosamente uma à outra no documento.

10.2) Ida e volta OAS sem perdas (JUM-478)

A travessia OAS é um contrato entre o exportador e o importador: o que o OAS não consegue expressar nativamente atravessa como extensões x- acordadas e é normalizado de volta em entity.meta na importação, de modo que exportar → importar → exportar atinge um ponto fixo com uma lista de perdas no nível do modelo vazia (verificado por designerRoundTrip.test.ts).

• x-aggregate-root e x-invariants carregam a declaração de agregado e as invariantes quando presentes.
• x-rbac carrega a política RBAC normalizada da entidade, emitida apenas quando diverge do padrão do designer (um x-rbac ausente normaliza de volta para a política padrão, com tenantScoped derivado dos papéis conforme o contrato RBAC de tenant).
• x-fieldless: true preserva o conjunto vazio de campos de uma entidade na travessia (um schema sem marcação e sem propriedades ainda recebe os campos padrão id/createdAt/updatedAt do importador).
• x-field-flags: { pk, fk, unique } carrega as flags de um campo apenas quando divergem da heurística de nomes do importador (id → PK/unique, *Id → FK).
• As linhas de x-relations carregam { name, fromSchema, toSchema, fromCardinality, toCardinality } — nomes de schema, não ids do modelo — e o importador restaura os relacionamentos religados aos ids recomputados das entidades, descartando linhas cujos extremos não foram importados.
• Documentos externos sem as marcações do designer (o canônico spec/1.0.0.yml) são reconhecidos pelas mesmas convenções de objetos de porta: nomes Request<Action>* e *ArrayOf, ResourceDeleteResponse, descrições “Port input/output object” que não são contratos de entidade <Name> resource, e schemas não-objeto nunca viram entidades.
• Perdas remanescentes nomeadas para documentos externos: facetas example/default/minItems/maxItems e vínculos $ref de itens de array (referências a objetos de valor achatam para o vocabulário itemsType), blocos de contexto delimitado do domínio, posições no canvas e operationIds legados (não canônicos).

11) Cobertura de fumaça

Testes de fumaça de gerenciamento de serviços:

• apps/backend-template/test/integration/ServiceManagement/domainDesigner.smoke.test.ts
• apps/service-management/test/unit/mvp.roadmap.features.test.ts

Correr:

bun run test:integration:service-management
NODE_ENV=dev bun x jest apps/service-management/test/unit/mvp.roadmap.features.test.ts --runInBand