BKS.Contabil

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

Papel da biblioteca

BKS.Contabil.csproj é a biblioteca de domínio do produto contábil.

Hoje ela concentra principalmente:

• regras de negócio ligadas a fechamento e cargas contábeis
• 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/WebAppContabil.csproj e pelo pacote NuGet

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

Target e estratégia de versionamento

O projeto usa:

• netstandard2.0

O AssemblyVersion está fixado em 4.0.0.0, acompanhando a linha major atual do pacote sem variar a cada versão minor ou patch.

Na prática:

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

Os metadados NuGet ficam no próprio BKS.Contabil.csproj, e este README é incluído diretamente no .nupkg. O empacotamento não depende de .nuspec manual.

Dependências

Dependências por pacote

O projeto consome, entre outras:

• BKS.Back
• BKS.Clientes
• System.ComponentModel.Annotations

O fato de depender de BKS.Back é relevante porque parte importante do comportamento contábil herda contratos e componentes compartilhados já consolidados no BackOffice.

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 usadas pelos fluxos contábeis

Pelo que o projeto mostra hoje, a biblioteca concentra fortemente a parte de cargas, parâmetros, regulatórios, utilitários e fechamento.

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 WebAppContabil, mas usam templates compartilhados.

Jobs diretamente relacionados à BKS.Contabil:

• validate_lib_version_impact
• package_nuget
• publish_nuget
• tag_beta_git

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.Contabil

package_nuget

Empacota a biblioteca BKS.Contabil 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.contabil

tag_beta_git

Quando a versão calculada for beta, a pipeline pode gerar uma tag Git da versão publicada.

O objetivo desse job é facilitar o rastreio da última beta gerada, já que isso nem sempre fica claro só pelo histórico de commits.

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.Contabil
• também não existe badge de cobertura específico desta biblioteca neste diretório

Esse é um ponto natural de evolução 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.Contabil 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. Dependência estrutural de BKS.Back

Como BKS.Contabil depende diretamente de BKS.Back, mudanças de versão nessa dependência podem impactar a biblioteca mesmo sem alteração direta em lib/**.

Na prática, isso reforça a importância de acompanhar também alterações relevantes em dependências centralizadas.

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. Padronização técnica ainda incompleta

Comparado com outras libs mais recentes do ecossistema, BKS.Contabil ainda não explicita no projeto alguns pontos como:

• LangVersion
• Nullable

Esses pontos não impedem o funcionamento, mas ainda dificultam consistência entre repositórios e troubleshooting quando a equipe compara comportamentos entre soluções.

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 / tag_beta_git / validate_lib_version_impact