BKS.Cmss

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

Papel da biblioteca

BKS.Cmss.csproj é a biblioteca de domínio do produto de comissões.

Hoje ela concentra principalmente:

• regras de negócio dos fluxos de comissão
• 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/WebAppComissoes.csproj e pelo pacote NuGet

Em termos práticos, app/WebAppComissoes.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
• LangVersion 12.0
• Nullable enable

O AssemblyVersion está fixado em 4.0.0.0 por decisão explícita do projeto.

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.

Dependências

Dependências por pacote

O projeto consome, entre outras:

• BKS.Acesso
• BKS.Clientes
• BKS.Dados
• BKS.Modelos.QITech
• BKS.Padrao
• BKS.Util

Diferente de cenários híbridos como BKS.Cartao, aqui a biblioteca usa PackageReference direto para dependências compartilhadas, inclusive BKS.Padrao.

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 de comissão

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

Jobs diretamente relacionados à BKS.Cmss:

• 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.Cmss

package_nuget

Empacota a biblioteca BKS.Cmss como NuGet.

Esse job:

• usa o template de versionamento compartilhado
• roda dotnet pack dentro de lib
• lê os metadados do pacote diretamente de BKS.Cmss.csproj, sem arquivo .nuspec
• inclui este README no pacote
• 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.

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 nem sempre isso fica claro apenas 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.Cmss
• 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.Cmss 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.Cmss 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.Cmss depende diretamente de pacotes como BKS.Dados, BKS.Util, BKS.Acesso 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 / tag_beta_git / validate_lib_version_impact