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 15) e processo de release (seção 15.8)
• 📋 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 15) 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 internos atuais:

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

A arquitetura atual permanece:

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

A arquitetura-alvo, sem autorização automática de execução, é:

React web → api-fiscal-records → lib-fiscal-records
app-fiscal-records → api-fiscal-records → lib-fiscal-records
external integrations → api-fiscal-records → lib-fiscal-records
workers → lib-fiscal-records

A API futura será responsável por transporte e contratos externos, mas consumirá os casos de uso do Core e não duplicará regras ou persistência. O app continua previsto em Expo/React Native, sujeito a validação quando sua implementação for explicitamente solicitada. Os workers continuarão consumindo a lib diretamente, sem passar pela API.

O estado atual web-fiscal-records → lib-fiscal-records permanece suportado e pode coexistir com a API futura. Não existe obrigação ou prazo para criar a API ou o app, 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 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 backlog de produto e seu mapeamento a lentes de decisão (CEO/CFO/CTO/CMO/Sales/UX), restaurados do histórico Azure DevOps, foram revisados pela última vez em 2026-05-17 e não devem ser tratados como prioridades atuais sem revalidação explícita do product owner. Prioridade e escopo de trabalho vêm sempre do pedido corrente do usuário, nunca de um roadmap arquivado.

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, checklist de decisão (seção 16) e política do próprio arquivo (seção 11)

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 resolvem a conexão nesta ordem:

1. LIB_FISCAL_RECORDS_TEST_POSTGRES;
2. arquivo indicado por LIB_FISCAL_RECORDS_TEST_APPSETTINGS;
3. ../web-fiscal-records/src/appsettings.local.json, usando ConnectionStrings:FinancialFlow ou Postgres:FinancialFlow.

As conexões de teste 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
• docs/cross-project-integration/WORKER_DRIVE_PROCESSING.md — contrato técnico específico de integração cross-repo, mantido fora dos 4 arquivos canônicos por documentar um contrato compartilhado com outro repositório, não governança deste