refatora funções de validação e normalização, melhora mensagens de erro e...

refatora funções de validação e normalização, melhora mensagens de erro e adiciona verificações de integridade

scripts/validacao.R

@@ -4,12 +4,17 @@ library(stringr)
 library(purrr)
 library(arrow)
 
+# funcao para obter linhas com mudancas de codigo em cada revisao NCM
 filtra_mudancas <- function(x, padrao) {
   x |>
     select(matches(padrao)) |>
     filter(
+      # seleciona as linhas que tem algum valor diferente de NA, excluindo
+      # a primeira coluna da comparacao
       if_any(-1, ~ !is.na(.))
     ) |>
+    # cria uma coluna preenchida com o primeiro valor nao NA da
+    # direita para a esquerda
     mutate(!!padrao := do.call(coalesce, rev(as.list(across(-1))))) |>
     select(
       ncm_original = 1,
@@ -18,6 +23,25 @@ filtra_mudancas <- function(x, padrao) {
     distinct()
 }
 
+amostra_valores <- function(x, n = 5) {
+  x <- unique(x)
+  x <- x[!is.na(x)]
+
+  if (length(x) == 0) {
+    return("sem amostra")
+  }
+
+  paste(head(sort(x), n), collapse = ", ")
+}
+
+sinaliza_validacao <- function(...) {
+  warning(sprintf(...), call. = FALSE)
+}
+
+interrompe_execucao <- function(...) {
+  stop(sprintf(...), call. = FALSE)
+}
+
 normaliza_ncm <- function(x, validar = FALSE, contexto = "NCM") {
   x <- as.character(x)
   x <- str_trim(x)
@@ -28,14 +52,11 @@ normaliza_ncm <- function(x, validar = FALSE, contexto = "NCM") {
     invalidos <- unique(invalidos)
 
     if (length(invalidos) > 0) {
-      stop(
-        sprintf(
-          "%s contem %s NCM(s) com formato invalido. Amostra: %s",
-          contexto,
+      sinaliza_validacao(
+        "Foram encontrados %s NCM(s) com formato invalido em %s. Amostra: %s",
         length(invalidos),
-          paste(head(sort(invalidos), 5), collapse = ", ")
-        ),
-        call. = FALSE
+        contexto,
+        amostra_valores(invalidos)
       )
     }
   }
@@ -43,30 +64,32 @@ normaliza_ncm <- function(x, validar = FALSE, contexto = "NCM") {
   x
 }
 
+# carrega caminhos para dados
 general_dir <- Sys.getenv("general")
 if (!nzchar(general_dir)) {
-  stop("Variavel de ambiente general vazia.", call. = FALSE)
+  interrompe_execucao("A variavel de ambiente general esta vazia.")
 }
 
 if (!dir.exists(general_dir)) {
-  stop(
-    sprintf("Diretorio general nao existe: %s", general_dir),
-    call. = FALSE
+  interrompe_execucao(
+    "O diretorio indicado pela variavel general nao existe: %s",
+    general_dir
   )
 }
 
 path_tec <- Sys.getenv("tec")
 if (!nzchar(path_tec)) {
-  stop("Variavel de ambiente tec vazia.", call. = FALSE)
+  interrompe_execucao("A variavel de ambiente tec esta vazia.")
 }
 
 if (!file.exists(path_tec)) {
-  stop(
-    sprintf("Arquivo TEC nao encontrado: %s", path_tec),
-    call. = FALSE
+  interrompe_execucao(
+    "O arquivo TEC indicado pela variavel tec nao foi encontrado: %s",
+    path_tec
   )
 }
 
+# caminho correlacao normal
 path_ncm <- file.path(
   general_dir,
   "Bases",
@@ -76,6 +99,7 @@ path_ncm <- file.path(
   "correlacao_completa_ncm.xlsx"
 )
 
+# caminho correlacao expandida
 path_ncm_detalhada <- file.path(
   general_dir,
   "Bases",
@@ -85,6 +109,8 @@ path_ncm_detalhada <- file.path(
   "correlacao_completa_ncm_detalhada.xlsx"
 )
 
+# Na pasta dados_gerados, "snapshot" identifica a ultima versao gerada
+# e salva para servir de referencia nas comparacoes com os arquivos atuais.
 path_ncms_originais_snapshot <- "dados_gerados/ncms_originais.rds"
 path_dataset_ncm_snapshot <- "dados_gerados/dataset_ncm.parquet"
 
@@ -98,21 +124,18 @@ arquivos_necessarios <- c(
 
 arquivos_faltantes <- arquivos_necessarios[!file.exists(arquivos_necessarios)]
 if (length(arquivos_faltantes) > 0) {
-  stop(
-    sprintf(
-      "Arquivos obrigatorios ausentes: %s",
+  interrompe_execucao(
+    "Os seguintes arquivos obrigatorios nao foram encontrados: %s",
     paste(
       sprintf("%s=%s", names(arquivos_faltantes), arquivos_faltantes),
       collapse = "; "
     )
-    ),
-    call. = FALSE
   )
 }
 
-message("Ambiente ok.")
-message("Arquivos obrigatorios encontrados.")
+message("Ambiente configurado e caminhos obrigatorios validados.")
 
+# leitura dos arquivos obrigatorios
 correlacao_ncm_detalhada <- read_xlsx(path_ncm_detalhada, guess_max = 1e6)
 correlacao_completa_ncm_raw <- read_xlsx(path_ncm, guess_max = 1e6)
 tec <- read_xlsx(path_tec, guess_max = 1e6)
@@ -121,15 +144,15 @@ dataset_ncm_snapshot <- read_parquet(path_dataset_ncm_snapshot)
 
 message("Dados carregados.")
 
+# cria lista de nomes para usar como input em filtra_mudancas
 revisoes_ncm <- names(correlacao_ncm_detalhada) |>
   str_extract("NCM_\\d{4}") |>
   discard(is.na) |>
   unique()
 
 if (length(revisoes_ncm) == 0) {
-  stop(
-    "Nenhuma coluna NCM_#### encontrada na correlacao detalhada.",
-    call. = FALSE
+  interrompe_execucao(
+    "Nenhuma coluna no formato NCM_#### foi encontrada na correlacao detalhada."
   )
 }
 
@@ -138,81 +161,84 @@ indice_ultima_revisao <- which.max(anos_revisoes)
 coluna_ultima_revisao <- revisoes_ncm[[indice_ultima_revisao]]
 nome_ultima_revisao <- str_replace(coluna_ultima_revisao, "_", " ")
 
+# obtem lista vigente com os NCMs originais das revisoes
 ncms_originais <- revisoes_ncm |>
   map(~ filtra_mudancas(correlacao_ncm_detalhada, padrao = .x))
 
 names(ncms_originais) <- str_replace(revisoes_ncm, "_", " ")
 
 if (!nome_ultima_revisao %in% names(ncms_originais)) {
-  stop(
-    sprintf(
-      "Revisao mais recente %s nao foi gerada na correlacao detalhada.",
+  interrompe_execucao(
+    "A revisao mais recente %s nao foi gerada a partir da correlacao detalhada.",
     nome_ultima_revisao
-    ),
-    call. = FALSE
   )
 }
 
-if (!is.list(ncms_originais_snapshot) || is.null(names(ncms_originais_snapshot))) {
-  stop(
-    "Snapshot anterior de ncms_originais invalido.",
-    call. = FALSE
+if (
+  !is.list(ncms_originais_snapshot) || is.null(names(ncms_originais_snapshot))
+) {
+  interrompe_execucao(
+    "O arquivo snapshot de ncms_originais esta invalido ou sem nomes de revisao."
   )
 }
 
 if (indice_ultima_revisao > length(ncms_originais_snapshot)) {
-  stop(
-    sprintf(
-      "Snapshot anterior nao possui o indice %s para %s.",
+  interrompe_execucao(
+    "O snapshot de ncms_originais nao possui o indice %s correspondente a %s.",
     indice_ultima_revisao,
     nome_ultima_revisao
-    ),
-    call. = FALSE
   )
 }
 
 if (!nome_ultima_revisao %in% names(ncms_originais_snapshot)) {
-  stop(
-    sprintf(
-      "Snapshot anterior nao possui a revisao %s.",
+  interrompe_execucao(
+    "O snapshot de ncms_originais nao possui a revisao %s.",
     nome_ultima_revisao
-    ),
-    call. = FALSE
   )
 }
 
-if (!identical(names(ncms_originais_snapshot)[[indice_ultima_revisao]], nome_ultima_revisao)) {
-  stop(
-    sprintf(
-      "Snapshot anterior tem %s no indice %s; esperado %s.",
+if (
+  !identical(
     names(ncms_originais_snapshot)[[indice_ultima_revisao]],
-      indice_ultima_revisao,
     nome_ultima_revisao
+  )
+) {
+  interrompe_execucao(
+    paste(
+      "O snapshot de ncms_originais tem %s no indice %s,",
+      "mas o esperado para a revisao atual era %s."
     ),
-    call. = FALSE
+    names(ncms_originais_snapshot)[[indice_ultima_revisao]],
+    indice_ultima_revisao,
+    nome_ultima_revisao
   )
 }
 
+# separa a revisao mais recente do arquivo atual e do snapshot correspondente
 ultima_revisao_atual <- ncms_originais[[nome_ultima_revisao]]
-ultima_revisao_anterior <- ncms_originais_snapshot[[nome_ultima_revisao]]
+ultima_revisao_snapshot <- ncms_originais_snapshot[[nome_ultima_revisao]]
 
-if (!all(c("ncm_original", coluna_ultima_revisao) %in% names(ultima_revisao_atual))) {
-  stop(
-    sprintf(
-      "Revisao atual %s nao contem as colunas esperadas.",
-      nome_ultima_revisao
-    ),
-    call. = FALSE
+if (
+  !all(
+    c("ncm_original", coluna_ultima_revisao) %in% names(ultima_revisao_atual)
+  )
+) {
+  interrompe_execucao(
+    "A revisao atual %s nao contem as colunas esperadas ncm_original e %s.",
+    nome_ultima_revisao,
+    coluna_ultima_revisao
   )
 }
 
-if (!all(c("ncm_original", coluna_ultima_revisao) %in% names(ultima_revisao_anterior))) {
-  stop(
-    sprintf(
-      "Snapshot anterior de %s nao contem as colunas esperadas.",
-      nome_ultima_revisao
-    ),
-    call. = FALSE
+if (
+  !all(
+    c("ncm_original", coluna_ultima_revisao) %in% names(ultima_revisao_snapshot)
+  )
+) {
+  interrompe_execucao(
+    "O snapshot de %s nao contem as colunas esperadas ncm_original e %s.",
+    nome_ultima_revisao,
+    coluna_ultima_revisao
   )
 }
 
@@ -221,116 +247,140 @@ ultima_revisao_atual <- ultima_revisao_atual |>
     ncm_original = normaliza_ncm(
       ncm_original,
       validar = TRUE,
-      contexto = sprintf("%s ncm_original atual", nome_ultima_revisao)
+      contexto = sprintf(
+        "%s na coluna ncm_original do arquivo atual",
+        nome_ultima_revisao
+      )
     ),
     !!coluna_ultima_revisao := normaliza_ncm(
       .data[[coluna_ultima_revisao]],
       validar = TRUE,
-      contexto = sprintf("%s atual", nome_ultima_revisao)
+      contexto = sprintf(
+        "%s na coluna %s do arquivo atual",
+        nome_ultima_revisao,
+        coluna_ultima_revisao
+      )
     )
   )
 
-ultima_revisao_anterior <- ultima_revisao_anterior |>
+ultima_revisao_snapshot <- ultima_revisao_snapshot |>
   mutate(
     ncm_original = normaliza_ncm(
       ncm_original,
       validar = TRUE,
-      contexto = sprintf("%s ncm_original anterior", nome_ultima_revisao)
+      contexto = sprintf(
+        "%s na coluna ncm_original do snapshot",
+        nome_ultima_revisao
+      )
     ),
     !!coluna_ultima_revisao := normaliza_ncm(
       .data[[coluna_ultima_revisao]],
       validar = TRUE,
-      contexto = sprintf("%s anterior", nome_ultima_revisao)
+      contexto = sprintf(
+        "%s na coluna %s do snapshot",
+        nome_ultima_revisao,
+        coluna_ultima_revisao
+      )
     )
   )
 
 message(sprintf("Revisao mais recente identificada: %s.", nome_ultima_revisao))
 
-# compara coluna ncm original de agora com anterior
-# indica que codigos que não estavam na revisão original apareceram agora. Isso é
-# importante pois alguns códigos podem ter sido alterados agora ou podem ter sido esquecidos e não inseridos anteriorermente
+# compara a coluna ncm_original do arquivo atual com a do snapshot
+# indica codigos que nao estavam na revisao original e passaram a aparecer agora.
+# Isso e importante porque alguns codigos podem ter sido alterados agora ou podem
+# ter sido esquecidos na geracao anterior.
 ncm_original_so_atual <- setdiff(
   unique(ultima_revisao_atual$ncm_original),
-  unique(ultima_revisao_anterior$ncm_original)
+  unique(ultima_revisao_snapshot$ncm_original)
 )
 if (length(ncm_original_so_atual) > 0) {
-  stop(
-    sprintf(
-      "Diferenca em ncm_original para %s: %s codigo(s) so no atual. Amostra: %s",
+  sinaliza_validacao(
+    paste(
+      "A coluna ncm_original da revisao atual %s contem %s codigo(s)",
+      "que nao aparecem no snapshot. Amostra: %s"
+    ),
     nome_ultima_revisao,
     length(ncm_original_so_atual),
-      paste(head(sort(ncm_original_so_atual), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    amostra_valores(ncm_original_so_atual)
   )
 }
 
-ncm_original_so_anterior <- setdiff(
-  unique(ultima_revisao_anterior$ncm_original),
+ncm_original_so_snapshot <- setdiff(
+  unique(ultima_revisao_snapshot$ncm_original),
   unique(ultima_revisao_atual$ncm_original)
 )
-if (length(ncm_original_so_anterior) > 0) {
-  warning(
-    sprintf(
-      "Diferenca em ncm_original para %s: %s codigo(s) so no anterior. Amostra: %s",
-      nome_ultima_revisao,
-      length(ncm_original_so_anterior),
-      paste(head(sort(ncm_original_so_anterior), 5), collapse = ", ")
+if (length(ncm_original_so_snapshot) > 0) {
+  sinaliza_validacao(
+    paste(
+      "A coluna ncm_original do snapshot de %s contem %s codigo(s)",
+      "que nao aparecem no arquivo atual. Amostra: %s"
     ),
-    call. = FALSE
+    nome_ultima_revisao,
+    length(ncm_original_so_snapshot),
+    amostra_valores(ncm_original_so_snapshot)
   )
 }
 
-# compara coluna de mudanças dentro da revisão. Indica códigos que
-# apareceram agora em relação ao ultimo arquivo. Aqui vale a pena conferir se
-# todos os códigos que aparececem foram de fato criados. Vale a pena conferir se todos os
-# códigos criados (olhar nas resoluções) aparecem dentros os códigos seguintes.
+# compara a coluna de mudancas dentro da revisao. Indica codigos que
+# apareceram agora em relacao ao snapshot. Aqui vale a pena conferir se
+# todos os codigos que aparecem foram de fato criados. Tambem vale conferir se
+# todos os codigos criados (olhar nas resolucoes) aparecem nos codigos seguintes.
 codigos_revisao_so_atual <- setdiff(
   unique(ultima_revisao_atual[[coluna_ultima_revisao]]),
-  unique(ultima_revisao_anterior[[coluna_ultima_revisao]])
+  unique(ultima_revisao_snapshot[[coluna_ultima_revisao]])
 )
 if (length(codigos_revisao_so_atual) > 0) {
-  stop(
-    sprintf(
-      "Diferenca em %s: %s codigo(s) so no atual. Amostra: %s",
-      nome_ultima_revisao,
-      length(codigos_revisao_so_atual),
-      paste(head(sort(codigos_revisao_so_atual), 5), collapse = ", ")
+  sinaliza_validacao(
+    paste(
+      "A coluna %s da revisao atual contem %s codigo(s)",
+      "que nao aparecem no snapshot. Amostra: %s"
     ),
-    call. = FALSE
+    coluna_ultima_revisao,
+    length(codigos_revisao_so_atual),
+    amostra_valores(codigos_revisao_so_atual)
   )
 }
 
-codigos_revisao_so_anterior <- setdiff(
-  unique(ultima_revisao_anterior[[coluna_ultima_revisao]]),
+# mostra códigos que saíram do arquivo atual em relação ao snapshot.
+codigos_revisao_so_snapshot <- setdiff(
+  unique(ultima_revisao_snapshot[[coluna_ultima_revisao]]),
   unique(ultima_revisao_atual[[coluna_ultima_revisao]])
 )
-if (length(codigos_revisao_so_anterior) > 0) {
-  stop(
-    sprintf(
-      "Diferenca em %s: %s codigo(s) so no anterior. Amostra: %s",
-      nome_ultima_revisao,
-      length(codigos_revisao_so_anterior),
-      paste(head(sort(codigos_revisao_so_anterior), 5), collapse = ", ")
+if (length(codigos_revisao_so_snapshot) > 0) {
+  sinaliza_validacao(
+    paste(
+      "A coluna %s do snapshot contem %s codigo(s)",
+      "que nao aparecem na revisao atual. Amostra: %s"
     ),
-    call. = FALSE
+    coluna_ultima_revisao,
+    length(codigos_revisao_so_snapshot),
+    amostra_valores(codigos_revisao_so_snapshot)
   )
 }
 
-message(sprintf("Comparacao com snapshot de %s ok.", nome_ultima_revisao))
+message(
+  sprintf(
+    "Comparacao da revisao %s com o snapshot de ncms_originais concluida.",
+    nome_ultima_revisao
+  )
+)
 
+# compara codigos NCM da tabela de correlacao NCM atual
+# e verifica se todos estao presentes na TEC vigente.
 correlacao_completa_ncm <- correlacao_completa_ncm_raw |>
-  rename_with(~ str_to_upper(.x))
+  rename_with(~ str_to_upper(.x)) |>
+  tidyr::drop_na()
 
 linhas_duplicadas <- nrow(correlacao_completa_ncm) -
   nrow(distinct(correlacao_completa_ncm))
 if (linhas_duplicadas > 0) {
-  stop(
-    sprintf(
-      "Dataset NCM atual contem %s linha(s) duplicada(s).",
-      linhas_duplicadas
+  sinaliza_validacao(
+    paste(
+      "O dataset NCM atual contem %s linha(s) duplicada(s);",
+      "elas serao removidas com distinct()."
     ),
-    call. = FALSE
+    linhas_duplicadas
   )
 }
 
@@ -341,19 +391,15 @@ colunas_ncm_dataset <- names(correlacao_completa_ncm) |>
   str_subset("^NCM_\\d{4}$")
 
 if (length(colunas_ncm_dataset) == 0) {
-  stop(
-    "Dataset NCM atual nao contem colunas NCM_####.",
-    call. = FALSE
+  interrompe_execucao(
+    "O dataset NCM atual nao contem colunas no formato NCM_####."
   )
 }
 
 if (!coluna_ultima_revisao %in% colunas_ncm_dataset) {
-  stop(
-    sprintf(
-      "Dataset NCM atual nao contem a coluna %s.",
+  interrompe_execucao(
+    "O dataset NCM atual nao contem a coluna %s correspondente a ultima revisao.",
     coluna_ultima_revisao
-    ),
-    call. = FALSE
   )
 }
 
@@ -362,15 +408,14 @@ colunas_com_na <- colunas_ncm_dataset[
 ]
 
 if (length(colunas_com_na) > 0) {
-  linhas_com_na <- sum(rowSums(is.na(correlacao_completa_ncm[colunas_ncm_dataset])) > 0)
+  linhas_com_na <- sum(
+    rowSums(is.na(correlacao_completa_ncm[colunas_ncm_dataset])) > 0
+  )
 
-  stop(
-    sprintf(
-      "Dataset NCM atual contem NA em %s linha(s). Colunas: %s",
+  sinaliza_validacao(
+    "O dataset NCM atual contem NA em %s linha(s). Colunas afetadas: %s",
     linhas_com_na,
-      paste(head(colunas_com_na, 5), collapse = ", ")
-    ),
-    call. = FALSE
+    amostra_valores(colunas_com_na)
   )
 }
 
@@ -380,22 +425,22 @@ correlacao_ncm_atual <- correlacao_completa_ncm |>
     ncm = normaliza_ncm(
       ncm,
       validar = TRUE,
-      contexto = sprintf("Dataset NCM atual %s", nome_ultima_revisao)
+      contexto = sprintf("dataset NCM atual para %s", nome_ultima_revisao)
     )
   )
 
-message("Dataset NCM atual ok.")
+message("Leitura do dataset NCM atual concluida.")
 
 if (!"ncm" %in% names(tec)) {
-  stop("TEC nao contem a coluna ncm.", call. = FALSE)
+  interrompe_execucao("O arquivo TEC nao contem a coluna ncm.")
 }
 
 if (!"descricao_tec" %in% names(tec)) {
-  stop("TEC nao contem a coluna descricao_tec.", call. = FALSE)
+  interrompe_execucao("O arquivo TEC nao contem a coluna descricao_tec.")
 }
 
 if (anyNA(tec$ncm)) {
-  stop("TEC contem NA na coluna ncm.", call. = FALSE)
+  sinaliza_validacao("O arquivo TEC contem NA na coluna ncm.")
 }
 
 tec <- tec |>
@@ -403,7 +448,7 @@ tec <- tec |>
     ncm = normaliza_ncm(
       ncm,
       validar = TRUE,
-      contexto = "TEC"
+      contexto = "arquivo TEC"
     )
   )
 
@@ -411,17 +456,17 @@ duplicados_tec <- tec$ncm[duplicated(tec$ncm)] |>
   unique()
 
 if (length(duplicados_tec) > 0) {
-  stop(
-    sprintf(
-      "TEC contem %s NCM(s) duplicado(s). Amostra: %s",
+  sinaliza_validacao(
+    "O arquivo TEC contem %s NCM(s) duplicado(s). Amostra: %s",
     length(duplicados_tec),
-      paste(head(sort(duplicados_tec), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    amostra_valores(duplicados_tec)
   )
 }
 
-faltantes_snapshot_tec <- ultima_revisao_anterior |>
+# observa mudancas nos codigos NCM do snapshot da revisao
+# e verifica se alguma NCM nao esta mais na TEC vigente.
+# Se um codigo aparecer, esse codigo deve ter sido alterado. Conferir.
+faltantes_snapshot_tec <- ultima_revisao_snapshot |>
   transmute(
     ncm = .data[[coluna_ultima_revisao]]
   ) |>
@@ -435,14 +480,11 @@ faltantes_snapshot_tec <- ultima_revisao_anterior |>
   pull(ncm)
 
 if (length(faltantes_snapshot_tec) > 0) {
-  stop(
-    sprintf(
-      "TEC vigente nao cobre %s NCM(s) do snapshot anterior em %s. Amostra: %s",
+  sinaliza_validacao(
+    "A TEC vigente nao cobre %s NCM(s) presentes no snapshot de %s. Amostra: %s",
     length(faltantes_snapshot_tec),
     nome_ultima_revisao,
-      paste(head(sort(faltantes_snapshot_tec), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    amostra_valores(faltantes_snapshot_tec)
   )
 }
 
@@ -458,100 +500,116 @@ faltantes_atual_tec <- correlacao_ncm_atual |>
   pull(ncm)
 
 if (length(faltantes_atual_tec) > 0) {
-  stop(
-    sprintf(
-      "TEC vigente nao cobre %s NCM(s) do dataset atual em %s. Amostra: %s",
+  sinaliza_validacao(
+    "A TEC vigente nao cobre %s NCM(s) presentes no dataset atual de %s. Amostra: %s",
     length(faltantes_atual_tec),
     nome_ultima_revisao,
-      paste(head(sort(faltantes_atual_tec), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    amostra_valores(faltantes_atual_tec)
   )
 }
 
-message("Validacao contra TEC ok.")
+message("Comparacao com a TEC concluida.")
 
 if (!coluna_ultima_revisao %in% names(dataset_ncm_snapshot)) {
-  stop(
-    sprintf(
-      "Snapshot dataset_ncm.parquet nao contem a coluna %s.",
+  interrompe_execucao(
+    "O snapshot de dataset_ncm nao contem a coluna %s correspondente a ultima revisao.",
     coluna_ultima_revisao
-    ),
-    call. = FALSE
   )
 }
 
-correlacao_ncm_anterior <- dataset_ncm_snapshot |>
+correlacao_ncm_snapshot <- dataset_ncm_snapshot |>
   rename(ncm = all_of(coluna_ultima_revisao)) |>
   mutate(
     ncm = normaliza_ncm(
       ncm,
       validar = TRUE,
-      contexto = sprintf("Snapshot dataset_ncm %s", nome_ultima_revisao)
+      contexto = sprintf("snapshot de dataset_ncm para %s", nome_ultima_revisao)
     )
   )
 
-codigos_entraram_dataset <- setdiff(
+# compara codigos que entraram e sairam no dataset atual com o snapshot.
+# Os resultados devem bater com as mudancas observadas na ultima revisao.
+
+# codigos correlacao ncm que entraram
+codigos_entraram_dataset_snapshot <- setdiff(
   unique(correlacao_ncm_atual$ncm),
-  unique(correlacao_ncm_anterior$ncm)
+  unique(correlacao_ncm_snapshot$ncm)
 )
 
-codigos_sairam_dataset <- setdiff(
-  unique(correlacao_ncm_anterior$ncm),
+# codigos correlacao ncm que sairam
+codigos_sairam_dataset_snapshot <- setdiff(
+  unique(correlacao_ncm_snapshot$ncm),
   unique(correlacao_ncm_atual$ncm)
 )
 
-codigos_entraram_revisao <- setdiff(
+# ncms originais - codigos que entraram
+codigos_entraram_revisao_snapshot <- setdiff(
   unique(ultima_revisao_atual[[coluna_ultima_revisao]]),
-  unique(ultima_revisao_anterior[[coluna_ultima_revisao]])
+  unique(ultima_revisao_snapshot[[coluna_ultima_revisao]])
 )
 
-codigos_sairam_revisao <- setdiff(
-  unique(ultima_revisao_anterior[[coluna_ultima_revisao]]),
+# ncms originais - codigos que sairam
+codigos_sairam_revisao_snapshot <- setdiff(
+  unique(ultima_revisao_snapshot[[coluna_ultima_revisao]]),
   unique(ultima_revisao_atual[[coluna_ultima_revisao]])
 )
 
-entradas_so_dataset <- setdiff(codigos_entraram_dataset, codigos_entraram_revisao)
-entradas_so_revisao <- setdiff(codigos_entraram_revisao, codigos_entraram_dataset)
+entradas_so_dataset_atual <- setdiff(
+  codigos_entraram_dataset_snapshot,
+  codigos_entraram_revisao_snapshot
+)
+entradas_so_revisao_atual <- setdiff(
+  codigos_entraram_revisao_snapshot,
+  codigos_entraram_dataset_snapshot
+)
 
-if (length(entradas_so_dataset) > 0 || length(entradas_so_revisao) > 0) {
-  stop(
-    sprintf(
+if (
+  length(entradas_so_dataset_atual) > 0 || length(entradas_so_revisao_atual) > 0
+) {
+  sinaliza_validacao(
     paste(
-        "Entradas de codigos divergem em %s.",
-        "So no dataset: %s codigo(s). Amostra: %s.",
-        "So na revisao: %s codigo(s). Amostra: %s"
+      "As entradas de codigos divergem entre o dataset atual e a revisao",
+      "comparada com o snapshot de %s.",
+      "Somente no dataset atual: %s codigo(s). Amostra: %s.",
+      "Somente na revisao atual: %s codigo(s). Amostra: %s."
     ),
     nome_ultima_revisao,
-      length(entradas_so_dataset),
-      paste(head(sort(entradas_so_dataset), 5), collapse = ", "),
-      length(entradas_so_revisao),
-      paste(head(sort(entradas_so_revisao), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    length(entradas_so_dataset_atual),
+    amostra_valores(entradas_so_dataset_atual),
+    length(entradas_so_revisao_atual),
+    amostra_valores(entradas_so_revisao_atual)
   )
 }
 
-saidas_so_dataset <- setdiff(codigos_sairam_dataset, codigos_sairam_revisao)
-saidas_so_revisao <- setdiff(codigos_sairam_revisao, codigos_sairam_dataset)
+saidas_so_dataset_atual <- setdiff(
+  # codigos que sairam da correlacao ncm completa snapshot
+  codigos_sairam_dataset_snapshot,
+  # codigos que sairam da correlacao ncm detalhada snapshot
+  codigos_sairam_revisao_snapshot
+)
+saidas_so_revisao_atual <- setdiff(
+  codigos_sairam_revisao_snapshot,
+  codigos_sairam_dataset_snapshot
+)
 
-if (length(saidas_so_dataset) > 0 || length(saidas_so_revisao) > 0) {
-  stop(
-    sprintf(
+if (
+  length(saidas_so_dataset_atual) > 0 || length(saidas_so_revisao_atual) > 0
+) {
+  sinaliza_validacao(
     paste(
-        "Saidas de codigos divergem em %s.",
-        "So no dataset: %s codigo(s). Amostra: %s.",
-        "So na revisao: %s codigo(s). Amostra: %s"
+      "Análise apenas para fins de controle. É normal ter alguma divergência.",
+      "As saidas de codigos divergem entre o dataset correlacao ncm e a correlacao ncm detalhada",
+      "de %s.",
+      "Saídas presentes em correlacao ncm completa e ausentes em ncm completa detalhada: %s codigo(s). Amostra: %s.",
+      "Saídas presentes em correlacao ncm detalhada e ausentes em correlacao ncm completa: %s codigo(s). Amostra: %s."
     ),
     nome_ultima_revisao,
-      length(saidas_so_dataset),
-      paste(head(sort(saidas_so_dataset), 5), collapse = ", "),
-      length(saidas_so_revisao),
-      paste(head(sort(saidas_so_revisao), 5), collapse = ", ")
-    ),
-    call. = FALSE
+    length(saidas_so_dataset_atual),
+    amostra_valores(saidas_so_dataset_atual),
+    length(saidas_so_revisao_atual),
+    amostra_valores(saidas_so_revisao_atual)
   )
 }
 
-message("Comparacao com dataset_ncm anterior ok.")
+message("Comparacao com o snapshot de dataset_ncm concluida.")
 message("Validacao concluida.")