Documento de Requisitos: invoice-api

Versão: 1.6
Data: 22/03/2026

Histórico de Revisões

Versão	Data	Autor	Descrição
1.0	06/06/2025	Ronaldo Junior	Documento inicial focado no fluxo de envio de e-mail
1.1	06/06/2025	Ronaldo Junior	Escopo expandido e adição de RNs e RNFs
1.3	11/06/2025	Ronaldo Junior	Atualização dos Requisitos Funcionais e Regras de Negócio
1.4	23/07/2025	Ronaldo Junior	Reestruturação do documento: merge com documentação técnica, reorganização das seções para melhor experiência do desenvolvedor, padronização de comandos e configurações
1.5	21/03/2026	Ronaldo Junior	Atualização para o estado atual da API, renomeação da aplicação para invoice-api, revisão de endpoints, scripts e variáveis de ambiente
1.6	22/03/2026	Ronaldo Junior	Documentação das salvaguardas globais da API (timeout e rate limit)

Índice

Introdução
1.1. Propósito
1.2. Público-alvo
1.3. Escopo
Visão Geral do Produto
Arquitetura e Tecnologias
Setup e Desenvolvimento
Requisitos Funcionais
5.1. Autenticação
5.2. Gerenciamento de Clientes
5.3. Envio de E-mail 5.4. Endpoints Atuais da API
Regras de Negócio
Requisitos Não Funcionais
Estrutura do Projeto
Configuração Detalhada
9.1. Docker Services
9.2. Variáveis de Ambiente
9.3. Comandos de Desenvolvimento
Deploy

1. Introdução

1.1 Propósito

Este documento especifica os requisitos para a aplicação invoice-api. Seu propósito é detalhar as funcionalidades, regras e características técnicas necessárias para que a equipe de desenvolvimento possa projetar, implementar e testar a solução de forma eficaz.

1.2 Público-alvo

Este documento destina-se aos desenvolvedores, arquitetos de software e stakeholders do projeto, servindo como a fonte principal de verdade para o escopo e o comportamento esperado do sistema.

1.3 Escopo

O escopo do projeto abrange o desenvolvimento de uma plataforma completa que inclui:

Autenticação de Usuários: Permitir que usuários se cadastrem e façam login no sistema.
Gerenciamento de Clientes: Permitir que usuários autenticados cadastrem seus clientes e os respectivos contadores.
Envio de E-mails: Orquestrar o fluxo de anexo de documentos fiscais, composição e envio de e-mails para os contadores, com tratamento de sucesso e falha.

2. Visão Geral do Produto

O invoice-api é uma plataforma web projetada para otimizar o processo de envio de documentos fiscais. Usuários podem se cadastrar, gerenciar uma base de clientes e contadores, e utilizar a API para enviar arquivos .zip de forma padronizada e automatizada. O sistema notifica o usuário sobre o status de cada envio, garantindo transparência e confiabilidade no processo.

Desenvolvido com Clean Architecture e DDD, organizando o código em camadas: domínio (entidades + regras), aplicação (use cases) e infraestrutura (implementações). Utiliza padrões como Repository, Dependency Injection e Factory, com sistema robusto de tratamento de erros via tuplas [error, result, warning].

3. Arquitetura e Tecnologias

Node.js + TypeScript - Runtime e tipagem estática
Express - Framework web minimalista
Prisma - ORM moderno com type-safety
PostgreSQL - Banco de dados relacional
MinIO - Storage S3-compatible (desenvolvimento)
Tebi.io - S3-compatible storage (produção)
Resend - Serviço de email transacional
Vitest - Framework de testes rápido
Zod - Validação de schemas TypeScript-first
Swagger/OpenAPI - Documentação interativa da API
Scalar - Interface moderna para documentação API

4. Setup e Desenvolvimento

Pré-requisitos: Node.js 18+ e Docker instalados no sistema.

1. Clone o repositório:

git clone https://github.com/rcnald/email-send-backend

2. Acesse a pasta do projeto:

cd email-send-backend

3. Instale as dependências:

yarn install
# ou
npm install

4. Configure o ambiente:

Crie um arquivo .env na raiz do projeto e configure as variáveis com base no .env.example.

5. Inicialize os serviços locais:

yarn setup
# ou
npm run setup

6. Inicie o servidor da invoice-api:

yarn dev
# ou
npm run dev

7. Acesse a API e documentação:

API: http://localhost:3333
Healthcheck: http://localhost:3333/health
API Reference (Scalar): http://localhost:3333/reference

5. Requisitos Funcionais

5.1 Autenticação

RF-12: O sistema deve permitir que um novo usuário se cadastre fornecendo nome, email e senha.
RF-13: O sistema deve permitir que um usuário existente faça login utilizando email e senha.
RF-14: Após um login ou cadastro bem-sucedido, o sistema deve gerar e retornar um token de acesso (JWT) para autenticar as requisições subsequentes.

5.2 Gerenciamento de Clientes

RF-15: O sistema deve permitir que um usuário autenticado cadastre um novo cliente, fornecendo os seguintes atributos:
- Cliente: nome, CNPJ.
- Contador: nome do contador, email do contador.
RF-16: O sistema deve permitir que o usuário visualize uma lista de todos os clientes que ele cadastrou.
RF-17: O sistema deve permitir que o usuário edite as informações de um cliente ou contador existente.
RF-18: O sistema deve permitir que o usuário remova o cadastro de um cliente.

5.3 Envio de E-mail

5.4 Endpoints Atuais da API

Públicos:

GET /health
POST /auth/register
POST /auth/login
PATCH /auth/token/refresh

Protegidos (JWT por cookie httpOnly ou Bearer Token):

POST /auth/logout
GET /me
GET /clients
POST /clients
POST /attachments
DELETE /attachments/:id/delete
POST /emails

Salvaguardas Globais (todas as rotas):

408 REQUEST_TIMEOUT: requisição excedeu 25 segundos de processamento.
429 TOO_MANY_REQUESTS: mesma origem excedeu 10 requisições em uma janela de 1 minuto.

6. Regras de Negócio

7. Requisitos Não Funcionais

RNF-01 (Desempenho): O upload do arquivo e o disparo do e-mail devem ser concluídos em um tempo de resposta rápido, idealmente em menos de 5 segundos sob condições normais de rede.
RNF-02 (Usabilidade): A interface para anexar arquivos e selecionar clientes deve ser clara e intuitiva, minimizando a chance de erro do usuário.
[] RNF-03 (Confiabilidade): O sistema deve garantir a entrega dos e-mails utilizando um serviço externo confiável (como o Resend). Falhas na comunicação com o serviço devem ser tratadas de forma elegante, sem perda de dados.
RNF-04 (Segurança): Os arquivos fiscais anexados devem ser tratados de forma segura, com armazenamento temporário e exclusão automática após o período definido. O acesso à funcionalidade de envio deve ser restrito a usuários autenticados.
RNF-05 (Disponibilidade): O serviço de envio de e-mail deve estar disponível 99.9% do tempo.
RNF-06 (Comunicação): As notificações de sucesso e falha para o usuário devem ser exibidas em tempo real (via Socket.IO, conforme sugerido no diagrama), sem a necessidade de recarregar a página.
RNF-07 (Resiliência): Toda requisição HTTP deve encerrar com timeout após 25 segundos para evitar conexões pendentes indefinidamente.
RNF-08 (Proteção de Tráfego): A API deve limitar cada IP a 10 requisições por minuto para reduzir abuso e preservar estabilidade.

8. Estrutura do Projeto

src/
├── core/                   # Tipos e utilitários base
├── domain/
│   ├── enterprise/         # Entidades e value objects
│   └── application/        # Use cases e interfaces
├── infra/
│   ├── database/          # Prisma e repositórios
│   ├── http/              # Controllers e rotas
│   ├── storage/           # Implementação S3
│   └── lib/               # Clientes externos
test/                      # Utilitários de teste

9. Configuração Detalhada

9.1 Docker Services

# PostgreSQL - Banco de dados principal
- Porta: 5432
- User: docker
- Password: docker
- Database: invoice-api

# MinIO - S3-compatible storage
- API: http://localhost:9000
- Console: http://localhost:9001
- User: testuser
- Password: testpassword

9.2 Variáveis de Ambiente

DATABASE_URL="postgresql://docker:docker@localhost:5432/invoice-api"

APP_URL="http://localhost:3000"
PORT=3333

S3_URL="http://localhost:9000"
S3_BUCKET="attachments"
S3_ACCESS_KEY_ID="testuser"
S3_SECRET_KEY="testpassword"
S3_REGION="us-east-1"

JWT_SECRET="your-super-secret-key-with-at-least-32-characters"
JWT_ACCESS_TOKEN_EXPIRATION="15m"
JWT_REFRESH_TOKEN_EXPIRATION="7d"
JWT_ACCESS_TOKEN_MAX_AGE=900000
JWT_REFRESH_TOKEN_MAX_AGE=604800000

ENVIRONMENT="development"  # development | test | production

RESEND_API_KEY="your-resend-key"

RESEND_API_KEY é validada na inicialização da aplicação. Utilize um valor real em produção.

9.3 Comandos de Desenvolvimento

Comandos Principais

1. Rodar em desenvolvimento:

yarn dev
# ou
npm run dev

2. Subir dependências locais e preparar banco:

yarn setup
# ou
npm run setup

3. Gerar e atualizar documentação OpenAPI (swagger.json):

yarn swagger
# ou
npm run swagger

4. Exportar documentação estática (Scalar) para /public:

yarn build:docs
# ou
npm run build:docs

5. Executar testes unitários:

yarn test
# ou
npm test

6. Executar testes E2E:

yarn test:e2e
# ou
npm run test:e2e

7. Executar verificação de qualidade:

yarn check
# ou
npm run check

8. Aplicar correções automáticas:

yarn fix
# ou
npm run fix

Estrutura de Testes

test/
├── in-memory-repositories/    # Repositórios fake
├── email/                     # Email sender fake
├── storage/                   # Storage fake
└── setup-test-environment.ts  # Setup de DI para testes

10. Deploy

Comportamento por Ambiente

Desenvolvimento e Teste:

ENVIRONMENT=development

Emails são simulados (fake sender) - não envia emails reais.

Produção:

ENVIRONMENT=production

Emails são enviados via Resend API.

Configuração de Produção

1. Defina o ambiente:

ENVIRONMENT=production

2. Configure o banco de dados:

DATABASE_URL=<prod-database-url>

3. Configure o storage S3:

S3_URL=<prod-s3-endpoint>
S3_BUCKET=<prod-bucket>
S3_ACCESS_KEY_ID=<prod-access-key>
S3_SECRET_KEY=<prod-secret-key>
S3_REGION="global"

4. Configure o serviço de email:

RESEND_API_KEY=<prod-resend-key>

⚠️ Obrigatório para production

Build e Deploy

1. Build da aplicação:

yarn build
# ou
npm run build

2. Inicie o servidor:

yarn start
# ou
npm start

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.vscode		.vscode
.zed		.zed
docs		docs
prisma		prisma
src		src
test		test
.env.example		.env.example
.env.test		.env.test
.gitignore		.gitignore
.yarnrc.yml		.yarnrc.yml
AGENTS.md		AGENTS.md
README.md		README.md
biome.jsonc		biome.jsonc
client.http		client.http
docker-compose.yml		docker-compose.yml
dockerfile		dockerfile
package.json		package.json
scalar.config.json		scalar.config.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.e2e.ts		vitest.config.e2e.ts
vitest.config.ts		vitest.config.ts
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

Documento de Requisitos: invoice-api

Histórico de Revisões

Índice

1. Introdução

1.1 Propósito

1.2 Público-alvo

1.3 Escopo

2. Visão Geral do Produto

3. Arquitetura e Tecnologias

4. Setup e Desenvolvimento

1. Clone o repositório:

2. Acesse a pasta do projeto:

3. Instale as dependências:

4. Configure o ambiente:

5. Inicialize os serviços locais:

6. Inicie o servidor da invoice-api:

7. Acesse a API e documentação:

5. Requisitos Funcionais

5.1 Autenticação

5.2 Gerenciamento de Clientes

5.3 Envio de E-mail

5.4 Endpoints Atuais da API

6. Regras de Negócio

7. Requisitos Não Funcionais

8. Estrutura do Projeto

9. Configuração Detalhada

9.1 Docker Services

9.2 Variáveis de Ambiente

9.3 Comandos de Desenvolvimento

Comandos Principais

Estrutura de Testes

10. Deploy

Comportamento por Ambiente

Configuração de Produção

Build e Deploy

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages