Finance Open

Plataforma de gestão financeira com API modular e front-end Blazor para cadastros, lançamentos, planejamento, conciliações, relatórios e assinaturas SaaS. O repositório contém uma solução .NET completa com seed de dados fictícios para acelerar testes locais.

Stack e módulos principais

• .NET 10 / ASP.NET Core (Finance.Api) com Minimal APIs por domínio (MasterData, Accounting, Planning, Reconciliation, Reporting, Assets e Subscriptions).
• Entity Framework Core + PostgreSQL (Finance.Infrastructure) com migrações, seeds saneados e naming snake_case.
• Blazor Server + WebAssembly (Finance.Web) usando Fluent UI Components e autenticação por cookies.
• .NET Aspire AppHost (Finance.AppHost) orquestra o PostgreSQL, aplica migrações e sobe API + Web com observabilidade padrão.
• Migrators dedicados (Finance.Migrator e MyCompany.Migrator) para automatizar dotnet ef database update em cenários sem Aspire.

Estrutura da solução

Finance.slnx
+-- Finance.Api/                ? API principal
+-- Finance.Web/                ? Blazor Server + WASM client
+-- Finance.Infrastructure/     ? EF Core, seeds e módulos de domínio
+-- Finance.Application & Domain? Camadas de aplicação e entidades
+-- Finance.AppHost/            ? Projeto Aspire (Postgres + serviços)
+-- Finance.Migrator/           ? Hosted service para migrations
+-- MyCompany.Migrator/         ? Migrator multi-schema de exemplo

Pré-requisitos

1. .NET SDK 8/10 preview (o projeto está em net10.0).
2. Docker Desktop (necessário para o AppHost provisionar o PostgreSQL).
3. Opcional: dotnet user-secrets para armazenar cadeias sensíveis durante o desenvolvimento.

Configuração de segredos

As chaves foram removidas do repositório. Configure antes de rodar:

Variável	Descrição
ConnectionStrings__financedb	Connection string completa para o PostgreSQL (ex.: Host=localhost;Port=5432;Database=finance;Username=finance;Password=finance)
AbacatePay:ApiKey ou ABACATEPAY_API_KEY	Token da integração de pagamentos utilizada no módulo de assinaturas

Exemplo usando dotnet user-secrets no Finance.Api:

dotnet user-secrets init --project Finance.Api
dotnet user-secrets set "ConnectionStrings:financedb" "Host=localhost;Port=5432;Database=finance;Username=finance;Password=finance" --project Finance.Api
dotnet user-secrets set "AbacatePay:ApiKey" "SUA_CHAVE_AQUI" --project Finance.Api

Repita o mesmo ConnectionStrings__financedb para Finance.Web, Finance.Migrator e MyCompany.Migrator (ou exporte a variável no shell antes de executar cada projeto).

Executando com o Aspire AppHost (recomendado)

1. Certifique-se de que o Docker esteja ativo.
2. Rode: dotnet run --project Finance.AppHost
3. O AppHost provisiona um contêiner PostgreSQL, aplica as migrações via Finance.Migrator e sobe Finance.Api e Finance.Web com descoberta de serviços (https+http://finance-api / finance-web).
4. Acesse o painel do Aspire em https://localhost:15000 para acompanhar logs e health checks. O front-end Blazor fica exposto na porta definida pelo host (ver logs de saída).

Execução manual (sem Aspire)

1. Suba um PostgreSQL local e garanta que ConnectionStrings__financedb esteja configurado.
2. Aplique migrações:

   dotnet run --project Finance.Migrator

3. Inicie a API:

   ConnectionStrings__financedb="<sua-connection-string>" dotnet run --project Finance.Api

4. Inicie o front-end:

   ConnectionStrings__financedb="<sua-connection-string>" dotnet run --project Finance.Web

5. Ajuste Finance.Web para apontar a Finance.Api (por padrão usa service discovery https+http://finance-api — configure FinanceApi__BaseAddress ou reverse proxy conforme seu ambiente).

Seeds e dados de demonstração

• A base é criada já com uma empresa fictícia (Finance Demo Ltda), plano de contas completo, centros de custo e meios de pagamento.
• Contrapartes e transações usam nomes genéricos (Cliente Aurora, Cliente Horizonte, Fornecedor Boreal) com documentos e e-mails aleatórios para evitar qualquer dado sensível.
• Planejamento, reconciliação e assinaturas recebem valores de exemplo em Finance.Infrastructure/**/*.Seed*.cs e respectivas migrações (20251128180445_InitialCreate*).
• Sempre que novas seeds forem editadas, gere uma nova migration (dotnet ef migrations add ...) ou atualize manualmente os arquivos de designer/model snapshot.

Boas práticas

• Nunca commit secrets: use variáveis de ambiente ou dotnet user-secrets.
• Limpe bin/ e obj/ antes de publicar o repositório público.
• Use dotnet format/dotnet test para garantir qualidade antes de abrir PRs.
• Para integrações externas (AbacatePay), configure timeouts e key rotation via variáveis (ABACATEPAY_API_KEY).

Em caso de dúvidas sobre módulos ou seeds, consulte Finance.Infrastructure – todos os dados de demonstração estão em arquivos sob MasterData, Accounting, Planning, Reconciliation, Assets e Subscriptions.