114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# Especificação Técnica: Microserviç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.
|