BKS.Back

Este documento complementa o README.md do repositório e cobre apenas a biblioteca lib/BKS.Back.csproj.

Papel da biblioteca

BKS.Back.csproj é a biblioteca de domínio do produto BackOffice.

Hoje ela concentra principalmente:

• regras de negócio compartilhadas entre os fluxos de BackOffice
• acesso e orquestração de persistência
• recursos SQL embarcados usados pelos dispatchers
• integrações com bibliotecas compartilhadas do ecossistema BKS
• superfície reutilizável pelo app/WebAppBackOffice.csproj e pelo pacote NuGet

Em termos práticos, o projeto app/WebAppBackOffice.csproj é o host ASP.NET Web Forms, mas a lógica reutilizável e grande parte do contrato técnico do produto ficam nesta biblioteca.

Target e estratégia de versionamento

O projeto usa:

• netstandard2.0
• LangVersion 12.0

O AssemblyVersion está fixado em 8.0.0.0, acompanhando a próxima linha major do pacote após 7.11.0-beta-26S40-1-32eaf340.

Isso existe para evitar problemas de binding em consumidores .NET Framework, enquanto:

• PackageVersion varia pela pipeline
• FileVersion acompanha a versão gerada
• InformationalVersion leva versão + commit

Na prática, quem evolui semanticamente no dia a dia é o pacote NuGet, não o AssemblyVersion.

Os metadados do pacote ficam no próprio BKS.Back.csproj. O empacotamento não depende de arquivo .nuspec separado e inclui este README no .nupkg.

Dependências

Dependências por pacote

O projeto consome, entre outras:

• BKS.Clientes
• BKS.Dados
• BKS.Padrao
• BKS.Util

Diferente de cenários híbridos como BKS.Cartao, aqui o projeto hoje usa PackageReference direto para BKS.Padrao, sem troca dinâmica entre ProjectReference e PackageReference.

Estrutura interna relevante

Sem repetir toda a árvore, os diretórios mais importantes são:

• BLL/: regras de negócio e orquestração
• DAL/: dispatchers, acesso a dados e recursos SQL
• DAL/Dispatchers/**/SQL/**: scripts SQL embarcados como recurso
• DML/: contratos e estruturas de domínio usadas pelo BackOffice

O volume de EmbeddedResource é alto e faz parte do contrato atual da biblioteca.

Recursos SQL embarcados

A biblioteca carrega um conjunto grande de .sql como EmbeddedResource.

Isso significa que a lib não é só código C#: ela também empacota artefatos SQL usados em runtime pela camada de acesso e pelos dispatchers.

Existe inclusive um target de validação no projeto:

• CheckSqlFilesAreEmbedded

Esse target falha o build se existir .sql dentro da árvore do projeto que não esteja marcado como EmbeddedResource.

Implicações:

• adicionar um .sql novo exige registrar no .csproj
• mover scripts entre pastas pode quebrar build se a lista não for atualizada
• este é um ponto importante de manutenção e de custo de merge

Relação com o pipeline

Os jobs de biblioteca são acionados a partir do .gitlab-ci.yml do WebAppBackOffice, mas usam templates compartilhados.

Jobs diretamente relacionados à BKS.Back:

• validate_lib_version_impact
• package_nuget
• publish_nuget

validate_lib_version_impact

Valida se uma alteração realmente impacta a biblioteca e, em MR, exige marcador de versão quando necessário.

O foco desse job é evitar geração de pacote sem mudança relevante em:

• lib/**
• dependências que afetem a lib
• Directory.Packages.props, quando a seção alterada impacta BKS.Back

package_nuget

Empacota a biblioteca BKS.Back como NuGet.

Esse job:

• usa o template de versionamento compartilhado
• roda dotnet pack dentro de lib
• injeta PackageVersion, FileVersion e InformationalVersion via pipeline

publish_nuget

Publica o .nupkg gerado no feed corporativo.

Esse job depende de package_nuget e não deveria recompilar a biblioteca.

Feed do pacote:

• https://nuget.banksofttecnologia.com.br/packages/bks.back

Observação:

Hoje o feed costuma ser a forma mais rápida de identificar a última beta gerada da biblioteca. A futura geração automática de tag Git para betas deve reduzir essa dificuldade de rastreio.

Testes da biblioteca

No estado atual do repositório, não existe um job dedicado de testes_unitarios_lib equivalente ao do WebAppCartao.

Isso significa que:

• a esteira já empacota e publica a lib
• mas ainda não expõe um job específico de testes automatizados da BKS.Back
• também não existe badge de cobertura específico desta biblioteca neste diretório

Esse é um ponto de evolução natural caso a lib passe a ter suíte própria de testes.

Regras atuais de geração de versão da lib

O pacote da BKS.Back segue o fluxo comum de versionamento da esteira NuGet:

• alpha em feature/*, fix/*, hotfix/*
• beta em dev
• stable em tag vX.Y.Z

Além disso, a geração depende de marcador explícito de impacto:

• #major
• #minor
• #patch

Esse modelo existe para impedir que qualquer merge gere pacote novo sem intenção explícita de versionamento.

Pontos de atenção para manutenção

1. Tamanho e acoplamento do projeto

BKS.Back hoje mistura:

• domínio
• persistência
• SQL embarcado
• integrações

Isso funciona, mas aumenta:

• tempo de build
• custo de restore/load do workspace
• impacto de mudanças pequenas

2. Custo de edição no .csproj

O arquivo do projeto é grande porque precisa declarar muitos EmbeddedResource.

Qualquer automação futura de CI/CD ou refactor deve tratar esse .csproj com cuidado, porque ele não é um projeto SDK simples com convenções implícitas para SQL.

3. Dependência direta de pacotes compartilhados

Como BKS.Back depende diretamente de pacotes como BKS.Dados, BKS.Util e BKS.Padrao, mudanças em Directory.Packages.props podem ter efeito imediato na biblioteca mesmo sem alteração direta em lib/**.

Por isso a validação de impacto da pipeline considera tanto a árvore da biblioteca quanto dependências centralizadas.

Quando editar este diretório

Atualize este README.md quando houver mudança em:

• estratégia de versionamento do pacote
• estrutura principal de BLL/DAL/DML
• política de EmbeddedResource
• forma como dependências compartilhadas são resolvidas
• jobs específicos de package_nuget / publish_nuget / validate_lib_version_impact