Desenho e componentes

Arquitetura

O Flow Audit é uma ferramenta de linha de comando local: entra evidência e sai um relatório. Hoje existem o esqueleto, o modelo canônico e o dataset sintético. As cinco etapas que transformam a evidência em achados ainda são desenho.

Em construção · versão 0.2.0. Os componentes abaixo são arquivos reais do repositório; as etapas que os analisam ainda não estão escritas.

Pipeline

As cinco etapas: ingestão, reconstrução, detecção, quantificação e relatório 1 · Ingestãoexportações → eventos 2 · Reconstruçãoeventos → jornadas 3 · Detecçãojornadas → achados 4 · Quantificaçãoachados → h e USD 5 · RelatórioHTML + findings.json

As cinco etapas são desenho. Chegam nos milestones M1 a M5 e nenhuma roda hoje. O relatório demo é uma maquete feita à mão, não gerada.

Componentes

Disposição hexagonal (ADR 0002). O domínio não importa nada fora de src/domain/ e um teste quebra o build se isso mudar. Uma seta significa «depende de».

Componentes: cli chama app, app e adapters dependem de ports, ports depende de domain e dataset alimenta adapters cli/audit · dataset app/runAudit() ports/4 interfaces domain/modelo · regras dataset/5.000 pedidos adapters/relógio · export

domain/

O modelo canônico: eventos, catálogo, pedidos, jornadas, achados e impacto. Não tem E/S, nem relógio, nem arquivos. Aqui viverão a reconstrução e as cinco regras. Hoje: os tipos.

ports/

As quatro interfaces das quais o resto do motor depende: EvidenceSource, CatalogSource, ReportRenderer e Clock. Hoje: as quatro estão declaradas; os adaptadores que implementam duas delas não existem.

adapters/

O mundo exterior. Um relógio e os serializadores de exportação dos quatro sistemas. A eles se juntarão os leitores de ingestão (M1) e o renderizador HTML (M4). Hoje: clock/ e export/; ingest/ e report/ estão vazios.

app/

O caso de uso runAudit(). Unirá ingestão, reconstrução, detecção, quantificação e renderização, e não possui nenhum formato. Hoje: um esqueleto que não devolve achados.

cli/

Análise de argumentos, ajuda e códigos de saída. Dois comandos: audit e dataset. Hoje: os dois rodam; audit sai com código 2 porque não há fonte de evidência.

dataset/

Um gerador determinista com semente fixa. Escreve a evidência sintética da Ortelis: 5.000 pedidos em setembro de 2026 e as taxas de impacto. Hoje: roda e as exportações são idênticas byte a byte.

O que roda hoje

Check

deno task check verifica os tipos do CLI, do gerador, do adaptador de relógio e dos testes. Passa.

Test

deno task test passa 34 testes em cinco suítes: dataset, serializadores, fronteira de arquitetura, fronteira de licença e esqueleto.

Auditoria

deno task audit imprime a mensagem de esqueleto e sai com código 2. Ainda não há fonte de evidência.

Dataset

deno task dataset regenera os 5.000 pedidos a partir de uma semente fixa. Duas execuções produzem exportações idênticas byte a byte.

Desenho

Conceito central

O Flow Audit será uma ferramenta de auditoria. Lerá os registros de quatro sistemas e reconstruirá o caminho de cada pedido. Para cada perda calculará as horas, os dólares e a evidência.

Analogia física

Imagine um pacote que cruza quatro armazéns. Cada armazém anota apenas as suas próprias entradas e saídas.

Ninguém sabe onde o pacote ficou parado três dias. O Flow Audit juntará os quatro cadernos. Marcará o armazém onde o pacote esperou e somará o custo dessa espera.

Mecânica técnica

  • Ingestão. Lerá as exportações de catálogo, OMS, BPM e provisionamento.
  • Reconstrução. Unirá os eventos de um pedido por uma janela de tempo, porque os sistemas não compartilham identificador.
  • Regras. Cinco regras detectarão falhas sem nova tentativa, esperas manuais, timers vencidos, duplicidades e falta de identificador.
  • Impacto. Multiplicará os pedidos afetados pelos minutos de trabalho e pelo custo da hora carregada.
  • Severidade. Derivará a severidade das horas por mês. Ninguém a atribuirá à mão.
  • Relatório. Gerará um HTML autocontido e um findings.json com a evidência de cada achado.

Fórmula de impacto planejada

  • Horas por mês = pedidos afetados × minutos de trabalho por pedido ÷ 60
  • USD por mês = horas por mês × USD 45 por hora carregada
  • Exemplo com o dataset sintético (R02). 5.000 pedidos × 5 min ÷ 60 = 417 h. 417 h × USD 45 = USD 18.750.

Licença e componentes de terceiros

  • Motor. MIT. O código, o modelo canônico e as regras podem ser lidos, usados e alterados.
  • Site. MIT para o código. As duas fontes mantêm sua licença: P052 sob AGPL-3.0 com exceção de incorporação, Source Sans 3 sob OFL-1.1.
  • Fonte da demo. Um serviço TMF próprio, MIT, sobre o dataset sintético. Está marcado como simulado.
  • Sistemas de teste. bss-oss-rust é lido apenas por HTTP, em uma máquina local. Não é distribuído aqui, não faz parte da demo pública e mantém sua licença.
  • Fronteira. Nenhum código de terceiros é copiado ou vendorizado, e nenhuma captura de outro sistema é commitada. Só entra dado sintético no repositório.
  • Marcas. TM Forum e TMF pertencem ao TM Forum. O Flow Audit é independente e não é certificado nem endossado pelo TM Forum.