# Seidor Tax Core

Biblioteca TypeScript completa para gestão de obrigações fiscais brasileiras, oferecendo estruturas de dados, regras de negócio, conversão de documentos e geração de relatórios fiscais (SPED, EFD, REINF e outros).

## Motivação

Desde a recepção de documentos, a apuração de impostos e a geração das obrigações fiscais, costuma haver muitas similaridades de regras entre si. Muitas vezes, essas similaridades são implementadas de forma isolada em cada parte do sistema, o que gera retrabalho e inconsistências.

Esta biblioteca centraliza e padroniza:
- Modelos de documentos fiscais brasileiros (NF-e, NFC-e, NFSe, CT-e, CCe)
- Geração de arquivos SPED (Fiscal, Contribuições, ICMS/IPI)
- Validação e formatação de dados fiscais (CNPJ, CPF, códigos IBGE)
- Perfis de estabelecimentos e regimes tributários
- Conversão entre formatos de documentos
- Gerenciamento de dados mestres (municípios, estados, códigos de serviço)

---

## 📦 Módulos

### 1. **taxReport** - Framework de Geração de Relatórios Fiscais
Geração de relatórios fiscais brasileiros (SPED Fiscal, SPED Contribuições, EFD-ICMS/IPI) com API type-safe.

**Características principais:**
- Classes base: `TaxReport`, `Block`, `Register`
- Decorators TypeScript para definição de campos (`@Key`, `@Numeric`, `@Decimal`, `@Alphanumeric`)
- Estratégias de duplicação configuráveis (Error, Ignore, Overwrite)
- Sistema de eventos para validação (`RegisterEventNotifier`)
- Otimizado para grandes volumes (1M+ registros)
- Múltiplas estratégias de output (Console, StringArray, File)

**Documentação completa:** [`lib/taxReport/README.md`](lib/taxReport/README.md)

---

### 2. **documents** - Modelo de Domínio de Documentos Fiscais
Definição completa de entidades para documentos fiscais e seus componentes.

**Classes principais:**
- `Document` - Documento fiscal com metadados, datas, valores e referências
- `Item` - Itens/linhas de documentos
- `Person` - Entidades (emitente, destinatário)
- `Address` - Informações de endereço
- `Tax` - Cálculos e rastreamento de impostos
- `ImportDeclaration` - Declarações de importação

**Builders fluentes:**
- `BuilderDocument`, `BuilderItem`, `BuilderPerson`, `BuilderAddress`, `BuilderTax`

**Enumerações:** 25+ enums para tipos de documentos, status, operações, pagamentos, origens de produtos, códigos de serviço e classificações fiscais brasileiras.

**Persistência:** Suporte a MongoDB via `infra/db/mongo/` com repositórios e builders.

---

### 3. **conversionDocuments** - Conversão de Formatos de Documentos
Conversão entre diferentes formatos de documentos fiscais brasileiros.

**Formatos suportados:**
- **NF-e** - Nota Fiscal Eletrônica
- **NFC-e** - Nota Fiscal ao Consumidor Eletrônica
- **NFSe** - Nota Fiscal de Serviços Eletrônica
- **CCe** - Carta de Correção Eletrônica
- **CT-e** - Conhecimento de Transporte Eletrônico
- **Communication** - Documentos de comunicação genéricos
- **Payment** - Documentos de pagamento
- **Receipt** - Documentos de recibo

Cada tipo possui interfaces de request/input para componentes (Address, Person, Item, Tax) e utilitários de conversão.

---

### 4. **documentRollback** - Reversão de Estado de Documentos
Gerenciamento de rollback e reversão de estados de documentos fiscais.

**Funcionalidades:**
- Reversão de alterações em documentos
- Recriação de estados anteriores
- Capacidade de auditoria
- Suporte para todos os tipos de documentos (CCe, CT-e, NF-e, NFSe, etc.)

---

### 5. **profiles** - Gestão de Perfis de Estabelecimentos
Gerenciamento de perfis fiscais e configurações de regimes tributários especializados.

**Classes principais:**
- `Profile` - Perfil fiscal com validade e configurações
- `Establishment` - Filiais/estabelecimentos com identificação fiscal e endereço

**Perfis especializados por regime tributário:**
- `EcdSpecializedProfile` - Escrituração Contábil Digital (ECD)
- `EcfSpecializedProfile` - Escrituração Contábil Fiscal (ECF)
- `EfdContribSpecializedProfile` - SPED Contribuições (PIS/COFINS)
- `EfdIcmsIpiSpecializedProfile` - SPED ICMS/IPI
- `ReinfSpecializedProfile` - REINF (Retenções e Informações Fiscais)

**Infraestrutura:** `ProfileRestRepository` para integração via REST API.

---

### 6. **valueObjects** - Objetos de Valor do Domínio
Objetos de valor reutilizáveis e imutáveis para conceitos fiscais brasileiros.

**Classes:**
- `CPF` - Validação e formatação de CPF (pessoa física)
- `CNPJ` - Validação e formatação de CNPJ (pessoa jurídica), com suporte a CNPJ alfanumérico
- `Email` - Validação de e-mail
- `OurDate` - Manipulação de datas com formatos brasileiros
  - Suporte a múltiplos formatos (`LayoutDateFormat`)
  - Parsing e formatação

**CNPJ — regex exportadas (evitam reimplementar regex numérica em cada serviço):**
- `CNPJ_RAW_REGEX`, `CNPJ_MASKED_REGEX`, `CNPJ_FLEXIBLE_REGEX` - aceitam CNPJ alfanumérico, prontas para schemas (`yup`, `class-validator` `@Matches`, etc.). A validação completa (formato + dígito verificador) continua sendo feita pela classe `CNPJ` (`isValid()`/`validationErrors()`) — as regex servem para validação de formato na borda da API, antes de instanciar a classe.

---

### 7. **errors** - Gestão de Erros e Mensagens
Tratamento centralizado de erros com templates de mensagens localizadas.

**Exports:**
- `MessageCode` & `MessageCodeType` - Enumeração de códigos de erro
- `Messages` - Templates de mensagens localizadas
- `formatMessage` & `logWithContext` - Utilitários de formatação e logging

**Características:**
- Sistema de dicionário organizado
- Mensagens baseadas em templates
- Type-safe na formatação de mensagens
- Suporte a múltiplos idiomas

---

### 8. **masterData** - Gestão de Dados de Referência
Gerenciamento de dados de referência brasileiros.

**Classes:**
- `State` - Informações de estados brasileiros
- `Municipality` - Dados de municípios com códigos IBGE
- `MunicipalObligation` - Metadados de obrigações municipais
- `ServiceCode` - Códigos de classificação de serviços

**Infraestrutura:** `MemoryMasterDataRepository` para cache em memória.

---

## 🏗️ Arquitetura

A biblioteca é organizada em **arquitetura em camadas**:

1. **Camada de Domínio** (`documents`, `profiles`, `masterData`)
   - Entidades de negócio e objetos de valor
   - Enumerações e tipos

2. **Camada de Aplicação** (`conversionDocuments`, `documentRollback`)
   - Casos de uso e transformações
   - Conversões de formatos de documentos

3. **Camada de Framework** (`taxReport`)
   - Framework genérico para relatórios fiscais
   - Arquitetura extensível para diferentes tipos de relatórios

4. **Camada de Infraestrutura** (diretórios `infra` dentro dos módulos)
   - Persistência em banco de dados (MongoDB)
   - Integrações REST
   - Implementações em memória

5. **Preocupações Transversais**
   - Gestão de erros (`errors`)
   - Objetos de valor (`valueObjects`)
   - Dados de referência (`masterData`)

---

## 🚀 Começando

### Instalação

```bash
npm install @seidor-cloud-produtos/tax-core
```

### Uso Básico

#### Criando um Documento Fiscal

```typescript
import { BuilderDocument, DocumentType, DocumentStatus } from '@seidor-cloud-produtos/tax-core';

const document = new BuilderDocument()
  .setId('doc-123')
  .setDocumentType(DocumentType.NFE)
  .setStatus(DocumentStatus.AUTHORIZED)
  .setAmount(1000.00)
  .build();
```

#### Validando CNPJ/CPF

Suporta CNPJ numérico clássico e CNPJ alfanumérico (Receita Federal, 2026): os 12 primeiros caracteres podem conter letras maiúsculas, os 2 dígitos verificadores continuam numéricos.

```typescript
import { CNPJ, CPF } from '@seidor-cloud-produtos/tax-core';

const cnpj = new CNPJ('12.345.678/0001-90');
if (cnpj.isValid()) {
  console.log('CNPJ válido:', cnpj.formattedValue);
}

const cpf = new CPF('123.456.789-00');
if (cpf.isValid()) {
  console.log('CPF válido:', cpf.formattedValue);
}
```

Para validação de formato em schemas, sem instanciar a classe, use as regex exportadas em vez de escrever `/^\d{14}$/`:

```typescript
import { CNPJ_FLEXIBLE_REGEX } from '@seidor-cloud-produtos/tax-core';

CNPJ_FLEXIBLE_REGEX.test('12.ABC.345/01DE-35'); // true — aceita mascarado ou não, com letras
```

Em DTOs de serviços NestJS (`class-validator`), use a própria regex exportada com o decorator `@Matches` já existente, em vez de `@Matches(/^\d{14}$/)`:

```typescript
import { Matches } from 'class-validator';
import { CNPJ_FLEXIBLE_REGEX } from '@seidor-cloud-produtos/tax-core';

class CreateEstablishmentDto {
  @Matches(CNPJ_FLEXIBLE_REGEX, { message: 'CNPJ inválido' })
  cnpj: string;
}
```

Em ambos os casos, a regex valida só o **formato**; o dígito verificador continua sendo checado pela classe `CNPJ` (`isValid()`).

#### Gerando Relatório SPED

```typescript
import { TaxReport, Block, Register } from '@seidor-cloud-produtos/tax-core';

// Consulte a documentação completa em lib/taxReport/README.md
```

---

## 📚 Documentação Adicional

- **Tax Report Framework:** [`lib/taxReport/README.md`](lib/taxReport/README.md)
  - [Arquitetura](lib/taxReport/ARCHITECTURE.md)
  - [Guia Rápido](lib/taxReport/QUICKSTART.md)
  - [Exemplos](lib/taxReport/EXAMPLES.md)
  - [FAQ](lib/taxReport/FAQ.md)

---

## 🔑 Características Principais

- **Type-Safe:** Uso extensivo de TypeScript, decorators e enums
- **Orientado a Padrões:** Builder pattern, Repository pattern, Observer pattern
- **Extensível:** Classes abstratas e interfaces em toda a biblioteca
- **Otimizado para Performance:** Preparado para processar grandes volumes de registros fiscais
- **Específico para o Brasil:** Suporte completo aos requisitos fiscais brasileiros
- **Bem Documentado:** README, exemplos e documentação de arquitetura extensivos

---

## 📄 Licença

Consulte o arquivo LICENSE para mais informações.