Guia do Desenvolvedor de MvA
Como construir uma Aplicação de Verificação de Metodologia — padrões de implementação e testes.
Para quem é este guia?
Este guia é destinado a desenvolvedores que implementam regras da metodologia para o Ecossistema Carrot. Ele apresenta como construir uma Aplicação de Verificação de Metodologia (MvA) — o software que avalia documentos MassID contra a especificação de um Framework de Verificação de Metodologia (MvF).
Pré-requisitos
- Proficiência com a linguagem de programação e ferramentas do monorepo
- Compreensão de padrões de funções serverless
- Familiaridade com os conceitos de dMRV e a especificação do MvF que você está implementando
- Conhecimento dos requisitos do Padrão dMRV Carrot para desenvolvedores de MvA
Repositório e ferramentas
As regras da metodologia são implementadas em um monorepo open-source:
- Repositório: github.com/carrot-foundation/methodology-rules
- Licença: LGPL-3.0
Consulte o README do repositório para instruções de configuração, instalação de dependências e configuração de desenvolvimento local.
Visão geral da arquitetura
O código segue uma arquitetura de duas camadas:
- Bibliotecas de regras compartilhadas — Contêm a lógica de verificação propriamente dita. Processadores de regras compartilhados são reutilizados em todas as metodologias BOLD. Cada regra é um módulo independente com seus próprios testes.
- Wrappers de aplicação da metodologia — Camadas de implantação finas que encapsulam bibliotecas compartilhadas como funções serverless. Cada metodologia implanta seu próprio conjunto de regras, incluindo quaisquer regras específicas da metodologia.
Essa separação significa que regras comuns (como identificação de atores, pesagem ou geolocalização) são implementadas uma vez e reutilizadas, enquanto regras específicas da metodologia (como cálculos de emissões) são isoladas na metodologia alvo.
Implementando uma regra
Etapa 1: Criar o projeto
Cada regra reside em seu próprio diretório de projeto com uma estrutura de arquivos padrão. Os metadados do projeto incluem tags para descoberta e categorização dentro do monorepo.
Etapa 2: Implementar o processador
Toda regra implementa o padrão de processador de regra — uma interface padronizada com cinco métodos:
process()— Ponto de entrada que orquestra a avaliação.generateDocumentQuery()— Constrói a consulta para buscar o documento MassID e dados relacionados.collectDocuments()— Busca os documentos necessários para avaliação.getRuleSubject()— Extrai os elementos de dados específicos que a regra precisa avaliar.evaluateResult()— Aplica a lógica de verificação e retorna PASSED ou FAILED com uma explicação.
A explicação em evaluateResult() é crítica — ela deve declarar o que foi verificado e por que o resultado é PASSED ou FAILED. Essas explicações formam a trilha de auditoria.
Etapa 3: Escrever testes
Toda regra deve ter cobertura de testes abrangente:
- Testes unitários — Testam métodos individuais e casos extremos.
- Testes de integração com documentos seed — Testam o fluxo completo de avaliação com documentos MassID realistas.
- Testes end-to-end — Testam a função implantada em um ambiente que espelha produção.
Etapa 4: Criar o wrapper da aplicação
Para cada metodologia que usa a regra, crie um wrapper de aplicação fino que instancia o processador da biblioteca compartilhada e o exporta como uma função serverless.
Princípios de design
Todas as implementações de regras devem seguir estes princípios:
- Fidelidade — O código deve implementar fielmente cada regra na especificação do MvF. A lógica em
evaluateResult()deve corresponder exatamente à especificação. - Rastreabilidade — Todo resultado PASSED ou FAILED deve referenciar os dados específicos que foram avaliados, permitindo verificação independente do resultado.
- Determinismo — A mesma entrada deve sempre produzir a mesma saída. Sem aleatoriedade, sem dependência de estado externo que possa mudar entre execuções.
Requisitos de testes
Antes que uma regra possa ser implantada em produção:
- Todos os testes unitários devem passar
- Testes de integração devem cobrir os cenários principais de PASSED e FAILED
- Testes end-to-end devem demonstrar que a regra funciona em um ambiente similar à produção
- A regra deve corresponder à entrada correspondente da especificação do MvF na matriz de rastreabilidade
Implantação
As regras são implantadas como funções serverless através do pipeline de build e implantação do monorepo. Cada metodologia define quais regras estão incluídas em sua configuração de implantação.
Consulte a documentação do repositório para procedimentos de implantação e configuração de ambiente.