svr-imp/README.md

# Serviço de Impressão

Este documento descreve as especificações técnicas, endpoints e padrões de arquitetura do Microserviço de Impressão. O sistema é projetado para o processamento assíncrono de documentos e integração com hardware de impressão local.

## Arquitetura e Fluxo de Dados

A solução utiliza uma arquitetura baseada em filas para assegurar a resiliência e a escalabilidade do processamento de impressão.

### Componentes Principais

1.  **API REST**: Interface para recepção de requisições de impressão.
2.  **BullMQ (Redis)**: Engine de mensageria para gestão de filas e persistência temporária de tarefas (jobs).
3.  **Queue Worker (PrinterProcessor)**: Componente responsável por consumir a fila, realizar a renderização de documentos via Puppeteer e comunicar-se com os drivers do sistema operacional.
4.  **Persistência (Oracle)**: Integração via TypeORM para registro de dados operacionais em base de dados corporativa.

### Fluxo de Operação

1.  A API recebe uma solicitação de impressão via HTTP.
2.  A tarefa é registrada na fila `printer` gerenciada pelo BullMQ.
3.  O `PrinterProcessor` (WorkerHost) processa a tarefa, converte o conteúdo HTML em PDF e envia para o spooler de impressão.

---

## Configurações do Sistema

### Variáveis de Ambiente

O serviço utiliza as seguintes definições no arquivo `.env`:

| Variável             | Descrição                        | Exemplo                   |
| :------------------- | :------------------------------- | :------------------------ |
| `REDIS_HOST`         | Endereço do servidor Redis       | `localhost`               |
| `REDIS_PORT`         | Porta do servidor Redis          | `6379`                    |
| `DB_USERNAME`        | Usuário do Banco de Dados Oracle | `admin`                   |
| `DB_PASSWORD`        | Senha do Banco de Dados Oracle   | `1234`                   |
| `DB_CONNECT_STRING`  | String de conexão Oracle         | `(DESCRIPTION=...)`       |
| `ORACLE_CLIENT_PATH` | Caminho do Oracle Instant Client | `C:\oracle\instantclient` |

### Pré-requisitos

- Node.js >= 20.0.0
- Redis Server
- Oracle Instant Client (Thick Mode habilitado)

---

## Endpoints da API

### 1. Sistema e Inventário

#### Listar Impressoras Disponíveis

Retorna a lista de periféricos de impressão configurados no host.

- **Método:** `GET`
- **Endpoint:** `/printer/list`
- **Resposta:** `PrinterDto[]`

### 2. Operações de Impressão

#### Impressão de Conteúdo HTML

Enfileira a conversão de HTML para PDF seguido da impressão física.

- **Método:** `POST`
- **Endpoint:** `/printer/:printerName/print-html`
- **Payload:**

```json
{
  "html": "string",
  "width": "string (ex: 80mm)",
  "height": "string (ex: 40mm)",
  "jobId": "string (opcional)"
}
```

#### Impressão Direta (ESC/POS)

Envio de comandos diretamente para impressoras térmicas.

- **Método:** `POST`
- **Endpoint:** `/printer/:printerName/print`
- **Payload:**

```json
{
  "lines": ["string"],
  "alignment": "left | center | right",
  "upsideDown": "boolean"
}
```

---

## Observabilidade e Gestão

### Bull Board

A interface de monitoramento em tempo real das filas está disponível no endpoint:
`http://localhost:3000/queues`

Permite a visualização de tarefas ativas, concluídas e falhas, além da reinjeção manual de jobs.

### Telemetria

O serviço está instrumentado com **OpenTelemetry**, exportando traces via protocolo OTLP para análise de performance e rastreabilidade distribuída.

---

## Estrutura Técnica

O projeto é construído sobre o framework NestJS, utilizando `@nestjs/bullmq` para a gestão de filas. O processador de impressão é injetado como um provider global no `AppModule` para garantir a execução contínua do worker dentro do contexto da aplicação.