Novo esquema de identificação dos pacotes e versões

Implantar o novo esquema e converter dados legados, bem como refatorar todo o repositório para contemplar o novo identificador de pacote, baseado no ID do doador.

Estrutura dos IDs internos

O maior inteiro positivo representado por BigInt (64 bits) é 9223372036854775807, ou seja, dá pra usar 18 dígitos sem preocupação.

Donor.id = 3 + 6 dígitos = 9 dígitos. 3 do ISO country code, 6 do contador local de doador. Formatação usando conversão do país em sigla de 2 letras, ex. "doardor BR123".
PackTpl.id = 9 + 2 = 11 dígitos. 9 do Donor.id, 2 dígitos para o contador de tipos de pacote doado. Formatado com ponto, por exemplo "BR com pacote pk_123.01"
PackFileVersion.id = 11 + 2 = 13 dígitos. 11 do PackTpl.id e 2 da versão. Sendo

Conceituação

A seguir explicação e justificativas.

Modelo de dados

A estrutura das tabelas e relacionamentos continua a mesma, mudam ligeiramente os IDs e o rigor das regras de controle.

Foram acrescentados relacionamentos mais rígidos para o que antes eram denomiados "objetos LayerFile" na ingestão de dados.

Cada PackFileVersion na prática é um arquivo comprimido (ex. zip) caracterizado por sua SHA256 e size, e contendo diversos subarquivos.

Cada subarquivo é descrito como ComponentFile (antiga denominação LayerFile), agregado ao respectivo PackFileVersion como tipo Data, enquanto arquivos adicionais como imagens e PDF da licença, são do tipo Evidence. Todos esses subarquivos ComponentFile são distinguiveis por seu respectivo MD5 (e size).

Pacote, seu make_conf e seu tpl

O aquivo make_conf.yaml da pasta do pacote (por exemplo pacote preserv-BR/PR/Curitiba/_pk002) apresenta os metadados correntes. Ao longo do ciclo de vida do pacote, todavia, pode sofrer modificações, o que no registro git são commits e no banco de dados são as versões.

A caracterização do make_conf.yaml como representante do pacote só é possível, portanto, se abstrairmos a versão através de um template simples, onde o único elemento variável o file, ou seja, os itens da lista de files recebem placeholders no lugar de nomes de arquivo. Ilustrando: o PackFileVersion apresenta algo como:

Screenshot from 2021-12-11 21-03-03

enquanto o PackFileTpl apresenta file: {{file1}} e file: {{file2}}. Com essa pequena modificação conseguimos discriminar o versionamento de dados brutos, e definir com precisão o que é um pacote. Cada PackFileTpl é uma composição de PackFileVersion.

Ano-mês do lançamento de novos dados no git

A principal convenção para o controle de versões estáveis, com workflow já implementado pela equipe, é a data de fechamento de uma versão do repositório git (Preserv ou Preserv-País). O controle de commits será baseado na finalização de git branches. O controle de releases será mais rígido: apenas nos últimos dias do mês poderão ser lançadas releases, e no máximo uma por mês.

Convenção: a pasta _pk tem como referência de versão o commit mais recente, que é justamente o que é apresentado na interface, conforme ilusltrado abaixo.

Screenshot from 2021-12-11 18-24-08

Ideal é que YearMonth (4 digitos) não seja a data dos dados, mas a data de fechamento do pacote git, ou seja, dos files e hashes novos do mês. Exemplo, a primeira versão será registrada como 2112 em https://github.com/digital-guard/preserv-BR/releases

Versionamento dos pacotes

Fazemos distinção entre modificações efetivas nos dados (nova entrega do doador), e demais modificações (no software de makefile, no README ou metadados). Fazemos uso do esquema SemVer, que numera as versões por X.Y.Z, com as seguintes convenções adaptadas deste projeto:

Versão **X.Y.Z**
X é a versão dos dados brutos	É um contador inteiro que inicia em 1. A cada recebimento de novos dados do doador, com subsequente homologação do "novo arquivo do pacote" (com novo SHA256), fica caracterizado um incremento em X.
Y é a versão dos dados filtrados	É um contador inteiro que inicia em 0, e incrementa quando os dados são afetados. Por exemplo a modificação do parâmetro SRID afeta a geometria dos dados gerados, portanto caracteriza um incremento em Y.
Z é a versão "do restante".	É um contador inteiro que inicia em 0, e incrementa apenas quando os dados não são afetados. Por exemplo a modificação do parâmetro name ou no arquivo README não afetam os dados, portanto caracterizam um incremento em Z.

Para controle interno mais efetivo o make_conf deve obrigaoriamente indicar a versão corrente (p. ex. pack_vers: 1.0.0), a data de versionamento dos dados brutos (p. ex. pack_release: 2020-10 full para expressar "outubro de 2020 completa"), usando a convenção do ano-mês descrita acima. O parser do YAML faz a validação do ano-mês com a versão, inclusive consistindo com histórico do versionamento do pacote.

API e funções SQL de controle

As planilhas de controle manual podem se ater apenas ao X do cógigo X.Y.Z da versão. As APIs e funções internas podem também converter strings de versão contendo o ano-mês ao invés do contador X.

Acrescenta-se a função de formatação das pastas Unix, _pkDDDD.CC para Donor_id e Counter_pack em destaque.

Ver e comparar com https://github.com/digital-guard/preserv/blob/main/src/lib-dg_preserv.sql

É hora de rever os CREATE TABLEs

optim.donatedpack

    Column     |  Type   | Collation | Nullable | Default 
---------------+---------+-----------+----------+---------
 pack_id       | integer |           | not null | 
 donor_id      | integer |           | not null | 
 user_resp     | text    |           | not null | 
 accepted_date | date    |           | not null | 
 escopo        | text    |           | not null | 
 about         | text    |           |          | 
 config_commom | jsonb   |           |          | 
 info          | jsonb   |           |          |

Indexes:

"donatedpack_pkey" PRIMARY KEY, btree (pack_id)
"donatedpack_donor_id_accepted_date_escopo_key" UNIQUE CONSTRAINT, btree (donor_id, accepted_date, escopo)

Foreign-key constraints:

"donatedpack_donor_id_fkey" FOREIGN KEY (donor_id) REFERENCES optim.donor(id)
"donatedpack_user_resp_fkey" FOREIGN KEY (user_resp) REFERENCES optim.auth_user(username)

Referenced by:

TABLE "optim.origin" CONSTRAINT "origin_pack_id_fkey" FOREIGN KEY (pack_id) REFERENCES optim.donatedpack(pack_id)

optim.donor

   Column    |  Type   | Collation | Nullable |                 Default                 
-------------+---------+-----------+----------+-----------------------------------------
 id          | integer |           | not null | nextval('optim.donor_id_seq'::regclass)
 scope       | text    |           |          | 
 vat_id      | text    |           |          | 
 shortname   | text    |           |          | 
 legalname   | text    |           | not null | 
 wikidata_id | bigint  |           |          | 
 url         | text    |           |          | 
 info        | jsonb   |           |          | 
 kx_vat_id   | text    |           |          |

Indexes:

"donor_pkey" PRIMARY KEY, btree (id)
"donor_kx_vat_id_idx" UNIQUE, btree (kx_vat_id)
"donor_scope_legalname_key" UNIQUE CONSTRAINT, btree (scope, legalname)
"donor_vat_id_key" UNIQUE CONSTRAINT, btree (vat_id)

Referenced by:

TABLE "optim.donatedpack" CONSTRAINT "donatedpack_donor_id_fkey" FOREIGN KEY (donor_id) REFERENCES optim.donor(id)

Triggers:

check_kx_vat_id BEFORE INSERT OR UPDATE ON optim.donor FOR EACH ROW EXECUTE FUNCTION optim.input_donor()

Ações no git e ingest1

Reestruturar optim.Donor conforme o modelo. Refazer make para atualizar conforme CSV de cada país (ingerir do zero). Usar INSERT com ON CONFLICT UPDATE, restringindo update às colunas scope, shortname, legalname, wikidata_id. url, info.
Criar uma função que faça ingestão de optim.PackTpl
Reestruturar optim.DonatedPack conforme o modelos PackTpl e PackFileVersion
Renomear e reestruturar antigo ingest.layer_file com ingest.ComponentFiles amarrando a optim.PackFileVersion.

Ações no DL03

Backup, o mais simples é recriar do zero DL03, já temos dump mas vale renomear atual dl03t_main para old_dl03.
Diretiva geral: ALTER TABLE onde for preciso ou DROP seguido de INSERT dos dados antigos.
Antigas tabelas optim.origin e ingest.layer_file precisam agora se realinhar com PackFileVersion e seus ComponentFiles

Implementação de scan coforme eclusa

Já tivemos sucesso em fazer scan filesystem de forma controlada, com validações e confirmações do SQL.

eclusa/mkCpHashFiles.sh: a função SQL gera e grava o script bash em pg_io. Em seguida o mesmo make que executou o SQL executa o script gerado.
Reusando algo de eclusa/step1-ini.sql:
- As funções de varredura do filesystem controlam as áreas usuárias e podem ser adaptadas para rodar com /var/gits/_dg/ e suas pastas. A ideia é similar fazer um ls recursivo e obter o path de todos os make_conf.
- As funções contendo pg_file_write() que gravam script bash (cityfolder_runhashes e cityfolder_cmds_to_run). Outra opção seria executar direto nas funções... Ver como em https://dba.stackexchange.com/a/128254/90651

O sql do schema optim é mantido em AddressForAll/WS/src/optim-step1-ini.sql e AddressForAll/WS/src/optim-step1-ini.sq. Esses arquivos podem ser carregados na base de dados (DL03) pelo makefile, de AddressForAll/WS, em L118 ou L135.

O schema ingest é uma das dependências do schema optim. O schema ingest foi migrado para preserv. Isso implica que antes do schema optim ser criado na DL03 (pelo makefile de A4A/WS/src) o schema ingest deve ser criado na DL03 executando o makefile de preserv.

O arquivo preserv/src/lib-dg_preserv.sql cria tabelas jurisdiction, auth_user, donor, donated_PackTpl, donated_PackVers no schema dg_preserv, já adequadas ao novo modelo de identificação. Observação: o sql em lib-dg_preserv.sql atualmente não está sendo executado no makefile de preserv.

Já o schema optim cria tabelas jurisdiction, auth_user, donor, donatedPack_commom, donated_Pack, que devem ser adequadas ao novo modelo (onde for necessário). jurisdiction, a meu ver, precisa ainda ser adequada para atender a mudança de LIXO-digital-preservation-BR (um arquivo para jurisdições) para preserv-BR (vários arquivos para jurisdições).

O schema api depende do schema optim. Atualmente o schema api pode ser carregado em DL03 em dois lugares: na L114 do makefile de WS ou na L59 do makefile de preserv.

A issue https://github.com/digital-guard/preserv/issues/37 trata sobre dividir responsabilidades entre WS e preserv e sobre o preserv rodar como standalone e antes de WS.

Então, se não estou deixando de considerar alguma coisa importante, preserv não pode rodar standalone sem o schema optim. assim acho que os schema optim (e por consequência o schema api) podem ser responsabilidade do preserv. E que as tabelas criadas em dg_preserv.sql#L86, façam parte do schema optim.

O sql do schema optim é mantido em ...

Ops, não vamos nos preocupar com WS ainda, por hora inclusive vamos manter o rótulo optim por ser o antigo padrão, suficiente para distinguir do SQL-schema ingest.

CUIDADO: apesar do schema optim necessitar da ingestão de dados tais como os arquivos CSV de Donor, é um processo de ingestão apartado e mais simples, exclusivo do "core data". Já o SQL-schema ingest é para operacionalizar ingestões efetivas da proposta Preserv, por exemplo de Preserv-BR.

PS: na prática as operações de ingestão Preserv-XX estarão até em bases de dados diferentes, demandando referência FDW ao optim. Tipicamente a base DL03 terá o optim de referência, e as bases INGEST1, INGEST2, etc. serão preparadas com o SQL-schema ingest.

lib-dg_preserv.sql

O arquivo preserv/src/lib-dg_preserv.sql cria tabelas Jurisdiction, Auth_user, Donor, Donated_PackTpl, Donated_PackVers ...

Todas no SQL-schema optim (!) e já adequadas ao novo modelo de identificação.

Mecanimos de scan de CSV de carga do optim

houve uma mudança nos CSVs de Jurisdiction, então deve-se adequar a sua carga dispersa em múltiplos arquivos... Mas nada de novo se usarmos ou adaptarmos as antigas funções da Eclusa. Ler acima a seção "Implementação de scan coforme eclusa"
algumas cargas, como Jurisdiction_geom, virão do OSM ou entidades oficiais, é um procedimento ainda mais específico e com o qual não nos preocuparemos (usamos o pg_dump para manter como está).

schema API

Esquecer por hora, retomaremos a ele quando adaptarmos a Eclusa. Reparar que antigas APIs aindas funcionam, por exemplo acesso a Donor por http://api-test.addressforall.org/v1/vw_core/donor/cnpj:33787094000140

Modelo de dados de das tabelas conf_yaml

Agora que estamos trazendo para o banco de dados o make_conf é necessário visualizar o modelo de dados na forma de classes UML. Tabelas ingest.lix_conf_yaml, ingest.lix_mkme_srcTpl, ingest.lix_jurisd_tpl, etc. para entender como se relacionam com a conceituação expressa acima

digital-guard / preserv