Política de nomenclatura e padrões CAF.

ContractForge usa uma política de nomenclatura determinística para artefatos gerados. A nomenclatura no estilo CAF é a referência padrão quando o usuário não fornece uma política explícita específica da organização.

O que CAF significa no ContractForge

CAF refere-se ao estilo de nomenclatura do Cloud Adoption Framework: os nomes devem ser determinísticos, legíveis, conscientes do ambiente e consistentes entre as equipes. ContractForge usa essa ideia como linha de base padrão para nomes gerados, como artefatos auxiliares, ativos de controle e saída de modelo.

Os nomes dos destinos físicos não são reescritos silenciosamente

Se o contrato definir explicitamente target.catalog, target.schema e target.table, esses identificadores continuarão sendo a fonte da verdade. A política de nomenclatura afeta nomes derivados/gerados, a menos que uma substituição explícita indique o contrário.

Por que a nomeação faz parte do contrato

Capacidade de revisão

Os artefatos gerados devem ser previsíveis em solicitações pull e revisões operacionais.

Consistência multiequipe

As equipes podem compartilhar padrões sem copiar regras de nomenclatura em todos os blocos de anotações.

Separação de ambiente

Os nomes de desenvolvimento, preparação e produção podem incluir tokens controlados em vez de sufixos ad-hoc.

Substituições seguras

Nomes explícitos ainda vencem quando uma empresa já possui um padrão de nomenclatura de catálogo ou tabela.

Onde a nomenclatura se aplica

Área	Comportamento	Exemplo típico
Tabela de destino	O valor explícito do contrato é preservado.	main.crm_curated.s_customers
Esquema de controle	Pode ser derivado de ambiente/domínio quando não fornecido pela configuração.	ops_contractforge_dev
Tabelas de quarentena	Pode derivar do contexto de destino e executar a classificação.	q_s_customers
Saída do modelo	Usa política de nomenclatura para criar nomes de arquivos de contratos e tabelas iniciais previsíveis.	silver/s_customers.ingestion.yaml
Artefatos de suporte gerados	Usa tokens estáveis ​​para evitar colisões e tornar a linhagem óbvia.	cf_dev_sales_orders_state

Política padrão

A política padrão é intencionalmente conservadora. Normaliza tokens, remove caracteres inseguros, mantém os nomes em letras minúsculas por padrão e evita alterar nomes físicos que o usuário já declarou.

Regra	Padrão	Razão
Caso	Nomes gerados em letras minúsculas.	Reduz o tempo de execução cruzado e o atrito de cotação SQL.
Separador	Sublinhado.	Legível em SQL, arquivos e painéis.
Personagens inseguros	Normalizado ou removido.	Impede identificadores de catálogo/tabela/arquivo inválidos.
Nomes físicos explícitos	Preservado.	Os contratos não devem surpreender os usuários ao renomear objetos de destino.
Linha de base CAF	Usado para derivar nomes.	Fornece uma convenção empresarial sem forçar um padrão personalizado.

Configuração do contrato

Use o bloco naming quando um projeto precisar de nomes gerados para seguir tokens específicos da organização ou quando um artefato gerado precisar de uma substituição explícita.

YAML

target:
  catalog: main
  schema: crm_curated
  table: s_customers

layer: silver
domain: crm

naming:
  policy: caf
  environment: dev
  product: customer360
  component: ingestion
  separator: _
  lowercase: true
  overrides:
    quarantine_table: q_s_customers
    state_table: cf_dev_crm_s_customers_state

Python

from contractforge import ingest

result = ingest(
    catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    layer="silver",
    domain="crm",
    naming={
        "policy": "caf",
        "environment": "dev",
        "product": "customer360",
        "component": "ingestion",
        "separator": "_",
        "lowercase": True,
        "overrides": {
            "quarantine_table": "q_s_customers",
            "state_table": "cf_dev_crm_s_customers_state",
        },
    },
    source={"type": "table", "name": "main.raw.b_customers"},
    mode="hash_diff_upsert",
    merge_keys=["customer_id"],
)

Como escolher uma política

Situação	Escolha recomendada
Ainda não existe nenhum padrão de nomenclatura de empresa.	Use o padrão CAF e mantenha nomes de destino explícitos no contrato.
Uma empresa já possui prefixos de tabela ou regras de catálogo.	Mantenha essas regras em target e use a política de nomenclatura apenas para artefatos derivados.
Equipes diferentes usam domínios diferentes.	Incluir tokens de domínio/produto/ambiente estáveis ​​na política.
Um nome gerado deve corresponder a um objeto existente.	Use uma substituição explícita em vez de confiar na derivação.

Regra de projeto

A política de nomenclatura deve tornar os artefatos gerados previsíveis e não ocultar decisões físicas. O contrato ainda deve mostrar o catálogo de destino real, o esquema e a tabela que serão escritos.