LibFiscalRecords

Core do produto Fiscal Records, distribuído como biblioteca compartilhada .NET 8. É a fonte de verdade das regras, casos de uso e persistência do ecossistema.

⚡ Quick Start

Novo? Comece aqui:

• 🛠️ CONTRIBUTING.md — ambiente, testes e fluxo de contribuição
• 🔐 SECURITY.md — reporte e tratamento de temas de segurança
• 🔧 AGENTS.md — instruções para IA e agentes de código, incluindo referência técnica completa (seção 16), processo de release (seção 16.8) e perspectivas estratégicas (seção 17.1)
• 📋 CHANGELOG.md — log completo de mudanças desde 2026-03-22
• 📦 Distribuição interna — o feed NuGet e o registry são infraestrutura privada, não serviços públicos; consulte SECURITY.md e AGENTS.md antes de os utilizar

Este projeto mantém documentação apenas em quatro arquivos: README.md, AGENTS.md, CHANGELOG.md e, quando aplicável, UX_AGENT.md — mais SECURITY.md/CONTRIBUTING.md como exceção por serem convenções nativas do GitHub. Não crie novos arquivos em docs/ para governança, estratégia ou templates.

Como começar

1. Leia este README.md para entender o papel da lib e os consumidores.
2. Use AGENTS.md (seção 16) para regras técnicas e padrões de implementação.
3. Configure o host com services.AddFiscalRecords(...) e um NpgsqlDataSource.
4. Execute dotnet test LibFiscalRecords.sln antes de fazer mudanças.

AI / Codex guidance

For agent rules, ownership boundaries, protected files, and commit policy, see AGENTS.md.

Histórico de mudanças

O histórico de releases e todas as mudanças significativas pertencem exclusivamente ao CHANGELOG.md. O README descreve somente o estado atual, a configuração e a forma de uso da biblioteca; não replique aqui listas de mudanças por data.

Papel no ecossistema

lib-fiscal-records é o Core do produto e a fonte de verdade das regras, casos de uso e persistência. Centraliza domínio, políticas, billing, quotas, tenancy, ledger, documentos, faturas, extratos, movimentos bancários, reconciliação, classificação, deduplicação, normalização, regras de confiança, estados canônicos, repositórios, Unit of Work, contratos internos e integrações reutilizáveis.

Consumidores diretos atuais:

• ../api-fiscal-records — fronteira HTTP externa e versionada
• ../web-fiscal-records — aplicação web (UI + orquestração HTTP)
• ../worker-fiscal-records-document — worker de processamento de documentos com IA
• ../worker-fiscal-records-delivery — worker de processamento de webhooks

Cliente externo atual:

• ../app-fiscal-records — aplicação Expo/React Native, exclusivamente via API

A arquitetura atual permanece:

web-fiscal-records → lib-fiscal-records
api-fiscal-records → lib-fiscal-records
app-fiscal-records → api-fiscal-records
worker-fiscal-records-document → lib-fiscal-records
worker-fiscal-records-delivery → lib-fiscal-records

A principal decisão de frontend ainda aberta é uma eventual aplicação React web:

React web → api-fiscal-records → lib-fiscal-records

A API já é responsável por transporte e contratos externos, consome os casos de uso do Core e não deve duplicar regras ou persistência. O app já existe em Expo/React Native e consome a API. Os workers continuam consumindo a lib diretamente, sem passar pela API.

O estado atual web-fiscal-records → lib-fiscal-records permanece suportado e coexiste com a API. Não existe obrigação ou prazo para migrar o web para React, remover Razor ou eliminar a referência direta do web à lib. Dois hosts consumirem o mesmo caso de uso do Core representa reutilização; duplicação ocorre quando regras semelhantes são reimplementadas nos hosts.

A separação por camadas ainda possui dívida conhecida: dois serviços de deduplicação executam SQL em Application, implementações concretas de I/O permanecem fora de Infrastructure, e web/worker de documentos conservam repositories legados. Essas exceções descrevem o código atual, não um padrão autorizado para novo trabalho; o inventário crítico e a regra de evolução estão em AGENTS.md seção 5.1.

A orientação normativa completa, inclusive para classificação de mudanças e estados transitórios, está em AGENTS.md.

Direção estratégica (resumo)

O produto já possui Core, API, web Razor, app Expo/React Native e workers. A prioridade recomendada é tornar releases, migrations e consumidores verificavelmente coerentes antes de ampliar o escopo. As opiniões consultivas de CEO, CTO, CMO, arquiteto de sistemas e developer estão centralizadas em AGENTS.md; elas orientam propostas futuras, mas não constituem roadmap automático. Prioridade e escopo de trabalho vêm sempre do pedido corrente do usuário e de validação explícita do product owner.

Invariantes de conciliação

• O score-base de candidatos usa a mesma política para fatura → movimento e movimento → fatura; classificadores específicos podem acrescentar evidências sem alterar essa base.
• A gravação N:N bloqueia deterministicamente o movimento e as faturas envolvidas durante a transação e valida tanto o saldo do movimento quanto o saldo disponível de cada fatura.
• Correspondência exata é uma recomendação do Core, não autorização para um GET ou carregamento de tela persistir uma conciliação.

Nota de nomenclatura

• superowner é apenas referência interna; nunca expor em UI, help ou copy
• Use administrador interno ou bypass administrativo em superfícies visíveis ao cliente

Stack

• .NET 8 (C#)
• Dapper + Npgsql (PostgreSQL)
• Google Drive API v3 + Google.Apis.Auth (OAuth)
• Microsoft.Extensions.DependencyInjection / Options
• xUnit (testes)
• BCrypt.Net-Next (hash de senhas)
• Microsoft.Extensions.Http (HttpClient)

Estrutura de pastas (src/)

Abstractions/        → interfaces/contratos (repositórios, serviços)
Domain/              → entidades, enums, records e regras puras
Application/         → serviços de orquestração e políticas aplicadas
Infrastructure/      → implementações concretas (Dapper, Drive, OAuth, locking)
Common/              → utilitários transversais
Google/              → modelos e helpers reutilizáveis para Google/Drive
Options/             → modelos de configuração
DependencyInjection/ → ponto único de registro DI (AddFiscalRecords)

Como consumir

// No host (web ou worker)
services.AddFiscalRecords(options =>
{
    options.RootFolderName = "FiscalRecords";
});

// IInvoiceExtractor é registrado como MissingInvoiceExtractor por padrão.
// O host que processa documentos DEVE sobrescrever:
services.AddScoped<IInvoiceExtractor, MeuGeminiExtractor>();

// Para extratos bancários, a lib também expõe:
// - IBankStatementOperationTypeResolver
// - IBankStatementCounterpartyResolver
// - IBankStatementExtractionPostProcessor
// - IBankMovementCounterpartyAliasRepository

// AppUser expõe DisabledUtc; o host web usa isso para desativar contas via admin.

Pré-requisitos no host:

• NpgsqlDataSource registrado no container DI
• Configurações Google (Google:ClientId, Google:ClientSecret, etc.) quando usar OAuth/Drive

Regra obrigatória para hosts

• web-fiscal-records, worker-fiscal-records-delivery e worker-fiscal-records-document não devem criar novos repositórios de dados, serviços de domínio ou contratos canônicos.
• Quando surgir necessidade de novo repositório ou serviço de domínio, implementar primeiro na lib-fiscal-records e consumir via DI nos hosts.

Governança e decisões

• AGENTS.md — regras vinculativas, limites arquiteturais, referência técnica (seção 16), checklist estratégico (seção 17) e política do próprio arquivo (seção 12)

Canonical Rules

• IUnitOfWork + Dapper for all repository access.
• InvoiceFileStatus and InvoiceFileSource stay canonical and lowercased where already established.
• InvoiceFileLifecycle is the canonical user-facing classification: intermediate audit states are Processing, persisted is Completed, and failed is RequiresAttention. Consumers should navigate by these groups without renaming or discarding the underlying audit status.
• Deduplication logic lives in BankStatementMovementDeduplicationPolicy.cs and related services.
• Repositories that use INSERT/UPDATE ... RETURNING with date/time columns must have a Postgres integration test that asserts the returned CLR types and round-trips the persisted values.
• Update CHANGELOG.md and run dotnet test LibFiscalRecords.sln before finishing a non-trivial change.

Testes PostgreSQL locais

Os testes de integração aceitam exclusivamente LIB_FISCAL_RECORDS_TEST_POSTGRES. Quando a variável não está definida, os testes PostgreSQL são reportados como ignorados; não há descoberta automática de appsettings do web ou da máquina do desenvolvedor.

O banco deve ser descartável, conter test no nome e possuir o marcador criado por tests/LibFiscalRecords.Tests/TestDoubles/provision-test-database.sql. As conexões usam search_path=pg_temp, impedindo acesso acidental às tabelas permanentes por nomes não qualificados. Os schemas temporários dos testes precisam acompanhar as consultas atuais dos repositórios.

Documentation

• AGENTS.md
• CONTRIBUTING.md
• SECURITY.md
• CHANGELOG.md

O contrato técnico de Drive e integração com workers está consolidado na seção 16.6.1 do AGENTS.md; não há documentação canônica paralela em docs/.