# Manual de Instalação — AM2 Print Edge Agent (Docker)

O **AM2 Print Edge Agent** roda dentro da rede da clínica. Ele recebe as impressões DICOM das modalidades (TC, RM, US, RX…), decide para qual impressora mandar de acordo com as regras configuradas no **AM2 Print Cloud** e informa à nuvem tudo o que aconteceu.

> O agente só faz **conexões de saída** (HTTPS) para a nuvem. Não é preciso abrir portas de entrada no firewall do hospital.

---

## 1. O que o agente faz

| Função | Descrição |
|---|---|
| DICOM Print SCP | Recebe impressões das modalidades na porta TCP `11112` (configurável). |
| Montagem de página | Converte o filme DICOM em PDF A3/A4. |
| Roteamento | Aplica as regras da nuvem: por tipo de exame, aparelho, dia, horário, impressão automática ou manual, contingência. |
| Impressão em papel | Envia para impressoras de rede por RAW/JetDirect (9100), IPP (631), LPD (515) ou fila CUPS. |
| Descoberta de impressoras | Varre a rede local quando você clica em “Buscar impressoras” no sistema. |
| PACS (opcional) | Consulta C-FIND para completar dados do paciente. |
| Sincronização | Envia status e histórico de trabalhos para a nuvem a cada 30 segundos. |

### Situação das funções

| Função | Situação |
|---|---|
| Receber DICOM Print e gerar PDF | Disponível |
| Roteamento por regras e contingência | Disponível |
| Impressão RAW / IPP / LPD / CUPS | Disponível — homologar em cada modelo de impressora |
| Consulta PACS (C-FIND) | Disponível, desligada por padrão |
| Envio de nova série ao PACS (C-STORE) | **Em teste (v0.6.0)** — ligue em Configurações DICOM; valide no cliente antes de uso em produção |

### Envio da impressão ao PACS (v0.6.0, em teste)
Fluxo automático: recebe a impressão DICOM → lê nome/acesso/ID na imagem → confirma o exame no PACS → monta cabeçalho e rodapé → envia as páginas ao PACS como a série **AM2 PRINT - IMPRESSAO** no mesmo exame. A impressão física segue a regra da clínica e pode ficar aguardando liberação manual.
- Ligue em **Configurações DICOM → Enviar a impressão montada ao PACS**.
- No PACS, cadastre o AE do agente (ex.: `AM2PRINT2_SCU`) com permissão de **envio (C-STORE)**.
- Se o exame não for confirmado no PACS, a série **não** é enviada (evita gravar no paciente errado); a impressão sai normalmente.
- Para reimprimir depois: **Montar impressão** → buscar o exame → série “AM2 PRINT - IMPRESSAO” → escolher a impressora.

---

## 2. Requisitos

### Novidades da v0.15.1
- Trabalhos mostra o resultado confirmado pelo PACS e a data/hora de envio, separado da impressão física. O histórico permanece após expirar as miniaturas.
- Usuários da clínica: operadores vinculados a um agente acessam apenas Trabalhos e Balcão / Entrega; não alteram configurações nem excluem exames.

### Novidades da v0.15.0
- Trabalhos: Hoje, Ontem, Últimos 7 dias, Todos e intervalo personalizado, com paginação.
- Configurações DICOM: perfil Padrão atual ou Melhoria experimental por clínica. Padrão atual continua selecionado inicialmente.
- Trabalhos → Comparar qualidade: folhas lado a lado e impressão de teste de cada perfil. Exige agente atualizado; trabalhos antigos/expirados podem não ter comparação. Até quatro folhas na comparação.
- A melhoria usa janelamento quando disponível nos DICOM recuperados do PACS e nitidez leve. Impressões já renderizadas pelo aparelho não recebem um segundo janelamento. Não recupera detalhes ausentes, não usa IA e requer avaliação clínica em papel.
- Comparar não imprime nem envia ao PACS. Impressões de teste de montagens também não geram série no PACS.
- Montagens impressas enviam a folha ao PACS quando a opção da clínica estiver ligada e o estudo for confirmado novamente. O retorno aparece na prévia do trabalho. Salvar montagem continua sem imprimir ou arquivar automaticamente.
- Atualize em Agentes locais → Atualizar agente; depois ative o envio em Configurações DICOM na clínica desejada e valide a nova série no PACS. Continua em teste.

- Servidor ou PC na mesma rede das modalidades e das impressoras.
- **Linux** Ubuntu Server 22.04/24.04 (recomendado) **ou** Windows 10/11 Pro / Server com WSL 2 + Docker Desktop.
- 2 vCPU, 4 GB RAM, 20 GB de disco.
- Saída HTTPS (porta 443) liberada para a nuvem.

---

## 3. Instalação no Linux

### 3.1 Docker
```bash
sudo apt update && sudo apt install -y ca-certificates curl unzip
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # saia e entre de novo na sessão
```

### 3.2 Antes de instalar: ver quais portas estão livres
Se o servidor já tem PACS ou outro sistema DICOM, confira as portas em uso:
```bash
ss -tulpn | grep -E ':(104|4210|11112|11114|11115|11116)\b'
```
- Porta que **aparece** na lista = ocupada. Não use.
- Escolha uma que **não aparece** (ex.: 11115) para `PRINT_SCP_PORT`.
- Use também um AE Title diferente do outro sistema (ex.: `AM2PRINT2`).

Depois de instalado, o próprio agente verifica as portas e mostra em **Configurações DICOM** se a porta está livre e quais você pode usar.

### 3.3 Agente
1. No AM2 Print Cloud, abra **Agentes locais → Novo agente** e copie o token.
2. Baixe o pacote em **Download do agente** e descompacte:
```bash
sudo mkdir -p /opt/am2print-edge
sudo unzip am2-edge-agent.zip -d /opt/am2print-edge
sudo chown -R $USER /opt/am2print-edge
cd /opt/am2print-edge
cp .env.example .env
nano .env        # cole o AGENT_TOKEN e confira CLOUD_URL
```
3. Libere a porta DICOM e suba:
```bash
sudo ufw allow 11112/tcp comment "AM2 DICOM Print SCP"
docker compose up -d --build
docker compose logs -f
```
Em até 30 segundos o agente aparece **online** no sistema.

---

## 4. Instalação no Windows

1. Ative a virtualização na BIOS (Intel VT-x / AMD-V).
2. PowerShell como Administrador: `wsl --install -d Ubuntu`
3. Instale o **Docker Desktop** com backend WSL 2.
4. Descompacte o pacote em `C:\am2print-edge\`, copie `.env.example` para `.env` e edite.
5. Libere a porta:
```powershell
New-NetFirewallRule -DisplayName "AM2 DICOM Print SCP" -Direction Inbound -Protocol TCP -LocalPort 11112 -Action Allow
```
6. `cd C:\am2print-edge` e `docker compose up -d --build`

> No Windows, a busca de impressoras funciona melhor configurando `SCAN_SUBNET` no `.env` (ex.: `192.168.1.0/24`), pois o Docker Desktop não enxerga a rede física diretamente.

---

## 5. Arquivo `.env`

```env
CLOUD_URL=https://cloudside-bridge.lovable.app
AGENT_TOKEN=am2_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

PRINT_SCP_AET=AM2_PRINT
PRINT_SCP_PORT=11112

# PACS (opcional)
PACS_ENABLED=false
PACS_AET=PACS_CENTRAL
PACS_HOST=192.168.1.100
PACS_PORT=104
LOCAL_SCU_AET=AM2_PRINT_SCU
AUTO_CSTORE_ENABLED=false

RETENTION_HOURS=48
SCAN_SUBNET=
# Tipo de exame por aparelho (usado nas regras por tipo de exame)
AET_MODALITY_MAP=CT_SALA1=CT,MR_3T=MR
```

> O DICOM Print não informa o tipo de exame. O agente descobre pelo `AET_MODALITY_MAP` ou, se o AE Title do aparelho contiver CT, MR, US etc., automaticamente.

---

## 6. Configurar as modalidades

> **Dica:** porta, AE Title e dados do PACS também podem ser alterados no AM2 Print Cloud em **Configurações DICOM**. O agente aplica em até 30 segundos e substitui os valores do `.env`. Usar a porta 11112 igual ao PACS não tem problema se o agente estiver em outro computador.

No console de cada aparelho, cadastre uma **impressora DICOM** (DICOM Printer / Film Printer):

| Campo | Valor |
|---|---|
| AE Title | `AM2_PRINT` |
| IP | IP do servidor onde o agente roda |
| Porta | `11112` |
| Filme | 14x17 ou A3, conforme o fluxo |

Use o botão **Verify / Echo** do aparelho para testar a conexão.

---

## 7. Impressoras e regras (no sistema)

1. **Impressoras → Buscar agora**: o agente varre a rede e lista o que encontrar. Clique em **Adicionar**.
2. **Regras de impressão → Nova regra**. Exemplos:
   - *Tomografia → OKI C911*, contingência Xerox 570, automática, todos os dias.
   - *Ressonância → Xerox 570*, contingência OKI, automática.
   - *Plantão noturno*: 19:00–07:00, impressão **manual** (fica aguardando liberação).
3. Use **Simular** para conferir para onde um exame iria.
4. Em **Trabalhos**, libere manualmente os que estiverem “Aguardando”.

A regra com **menor número de prioridade** que corresponder ao exame é a que vale. Se a impressora principal estiver fora do ar, o agente usa a contingência; se as duas estiverem fora, o trabalho fica aguardando.

---

### Impressoras que precisam de driver (Fila CUPS local)
Algumas impressoras não aceitam o arquivo direto pela rede (ex.: Xerox Phaser 3020, Xerox com Fiery). Nesses casos, a impressora deve estar instalada no Linux (CUPS) e o agente manda o trabalho para essa fila.

1. Veja as filas já instaladas no servidor:
```bash
lpstat -v
```
2. Se a impressora não estiver na lista, instale (funciona na maioria das impressoras de rede modernas):
```bash
lpadmin -p NOME_DA_FILA -E -v ipp://IP_DA_IMPRESSORA/ipp/print -m everywhere
```
3. Teste direto no Linux (deve sair uma folha):
```bash
echo "Teste AM2" > /tmp/teste.txt && lp -d NOME_DA_FILA /tmp/teste.txt
```
4. No sistema, em **Impressoras**, cadastre com **Protocolo: Fila CUPS local** e no campo **Nome da fila CUPS** coloque o nome exato (ex.: `AM2_OKI_C911`).

O `docker-compose.yml` já traz a linha `/var/run/cups:/var/run/cups:ro`, que permite ao agente usar as filas do Linux.

> Dica: se o status em Trabalhos fica "Impresso" mas nada sai no papel, a impressora provavelmente precisa de driver. Use a Fila CUPS.

Para corrigir nome, IP, protocolo ou papel de uma impressora, clique no **lápis** em **Impressoras**. Não precisa excluir.

---

## 8. Manutenção

```bash
docker compose ps                 # status
docker compose logs -f            # logs ao vivo
docker compose pull && docker compose up -d --build   # atualizar
docker compose restart            # reiniciar
```
Os arquivos recebidos ficam em `./data/spool` e são apagados após o **Tempo de guarda** (padrão 48 horas), ajustável em *Configurações DICOM*. As imagens “como chegou / como ficou” do botão **Visualizar** em *Trabalhos* seguem o mesmo prazo (agente v0.10.0+).

## 9. Problemas comuns

| Sintoma | O que verificar |
|---|---|
| Agente “offline” no sistema | Token no `.env`, saída HTTPS liberada, `docker compose logs`. |
| Modalidade não conecta | Firewall na porta 11112, AE Title igual dos dois lados. |
| Impressão não sai | IP/porta da impressora; teste `nc -vz IP 9100` no servidor. |
| Status "Impresso" mas nada sai | A impressora precisa de driver: use **Fila CUPS local** (seção 7). |
| Porta ocupada | Veja em **Configurações DICOM** as portas livres sugeridas pelo agente. |
| Busca não acha impressoras | Configure `SCAN_SUBNET`; algumas impressoras bloqueiam varredura. |

## Cabeçalho e rodapé das impressões

Na nuvem, em **Modelos de impressão**, monte o cabeçalho e o rodapé (logo, nome do paciente, exame, data, QR code para o laudo, avisos). Depois, em **Regras de impressão**, escolha o modelo de cada regra. O agente aplica o modelo em cada folha antes de imprimir.

Observação: a impressão DICOM vinda do aparelho normalmente não traz os dados do paciente; nesses casos os campos de paciente saem em branco até a consulta ao PACS estar ativa.

## Dados do paciente pelo PACS (C-FIND)

A impressão DICOM normalmente não traz o nome do paciente. Com o PACS ligado em **Configurações DICOM** e a opção **Consulta ao PACS** ativa, o agente pergunta ao PACS, a cada impressão recebida, qual exame é esse e preenche o cabeçalho (nome, ID, nascimento, idade, sexo, exame, accession, solicitante).

- Se o aparelho mandar o identificador do estudo, a busca é exata.
- Se não mandar, o agente pega o exame **de hoje, da mesma modalidade, iniciado mais recentemente**.
- Cadastre no PACS o AE Title do agente (campo "AE Title do agente") como cliente autorizado a consultar.
- Se o PACS não responder, a folha é impressa mesmo assim, sem os dados.

## Montar impressão (busca no PACS)

No menu **Montar impressão** você busca o exame no PACS (nome, ID, accession, data), abre a série, escolhe as imagens (uma a uma ou "pular de N em N") e imprime em grades 1x1 até 5x6, em A3 ou A4, retrato ou paisagem. Acima de 20 imagens numa 4x5, o sistema divide em várias folhas.

Na folha, clique nas imagens para selecionar quais receberão ajustes ou use **Selecionar todas** (inclui todas as folhas). Os pré-filtros **Mais escuro**, **Mais claro**, **Contraste forte** e **Original** ajustam brilho/contraste; os controles permitem brilho e contraste de 20% a 200%, zoom de 100% a 300%, giro de 90° e espelhamento. **Restaurar ajustes** desfaz todas as alterações da seleção. O zoom amplia com corte central, podendo ocultar bordas da imagem. Os ajustes são aplicados pelo agente nas imagens de resolução original antes de gerar o PDF; o DICOM de origem permanece intacto. A prévia usa miniaturas, não é um visualizador diagnóstico; valide o resultado na impressora usada pela clínica.

Requisitos no PACS: liberar o AE Title do agente (ex.: `AM2_PRINT_SCU`) para **C-FIND** e **C-GET**. As imagens baixadas ficam em cache no agente (`data/cache`). O primeiro pedido pode levar até 30 s; depois o agente responde a cada 2 s enquanto a montagem estiver em uso. Após esta atualização, baixe o pacote novamente e atualize o agente para aplicar os ajustes.


## Porta DICOM ocupada (Address already in use)

Se a porta escolhida já for usada por outro programa no mesmo servidor (PACS ou outro sistema DICOM), o agente **não cai mais**: ele continua ligado na porta do `.env` e mostra um **aviso vermelho** na tela Configurações DICOM. Basta escolher outra porta livre (ex.: 11115, 11116, 11120) e salvar. Não precisa reinstalar.

## Renovar token

Em Agentes locais, clique em **Renovar token**, copie o novo token, troque a linha `AGENT_TOKEN=` no `.env` e rode `docker compose down && docker compose up -d`.

## Busca no PACS por período

Em Montar impressão use **Data inicial / Data final** ou os atalhos Hoje, Ontem, Últimos 7 dias, Este mês e Qualquer data (esta exige nome, ID ou accession).

## Proteção da busca no PACS (v0.3.0)
- Sem nome, ID ou accession: é obrigatório informar data inicial e final, com no máximo 60 dias.
- Cada busca traz no máximo 100 exames; se houver mais, a tela avisa para refinar os filtros.
- O agente e a tela descartam exames fora do período/modalidade, mesmo que o PACS ignore o filtro.
- A versão do agente aparece em Agentes; se estiver em vermelho, baixe o pacote novo em Downloads e rode `docker compose down && docker compose up -d --build`.

## Leitura automática dos dados do paciente (OCR) — v0.5.0

Muitos aparelhos (ex.: GE Signa) enviam a impressão DICOM só com a imagem: nome, Accession e ID aparecem escritos no canto, mas não vêm como dados. A partir da v0.5.0 o agente:

1. Lê os cantos das primeiras imagens (Acc Num, nome do paciente, ID).
2. Consulta o PACS por Accession → ID → Nome, e só aceita se o nome do PACS bater com o lido na imagem.
3. Preenche o cabeçalho/rodapé com os dados completos do PACS. Sem resposta do PACS, usa o que foi lido.

Já vem ligado. Para desligar: `OCR_ENABLED=false` no `.env`. No log aparece `OCR leu: {...}`.
Para atualizar: baixe o novo pacote em Downloads e rode `docker compose down && docker compose up -d --build`.

## Novidades da v0.9.0

- **Nome das impressoras na busca:** o agente pergunta o modelo por SNMP (comunidade `public`) e pela página HTTPS, igual ao CUPS.
- **Bolinha verde/vermelha automática:** a cada minuto o agente testa todas as impressoras e o PACS e mostra Online/Offline no painel.
- **Atualizar pelo painel:** em Agentes locais, botão **Atualizar agente**. Não precisa mais de terminal.

**Última atualização pelo terminal (só uma vez, vindo da v0.8.0 ou anterior):**

```bash
cd /opt/am2print-edge
cp .env /tmp/env.bak
curl -L -o /tmp/agent.zip https://cloudside-bridge.lovable.app/downloads/am2-edge-agent.zip
unzip -o /tmp/agent.zip -d .
cp /tmp/env.bak .env
docker compose down && docker compose up -d --build
```

Depois disso, as próximas versões são instaladas pelo botão no painel.

## Novidades da v0.8.0

- **Testar comunicação**: em *Configurações DICOM* há o botão **Testar C-ECHO** para o PACS, e em *Impressoras* cada impressora tem o botão **Testar**. Bolinha **verde** = online (com tempo de resposta); **vermelha** = falha, com o motivo.
- Filas CUPS são testadas com `lpstat`; impressoras de rede (RAW/IPP/LPD) testam a porta; impressoras DICOM usam C-ECHO.
- *Montar impressão* agora tem filtro de **Modalidade** (Todas, CT, MR, CR, MG, US…).

## Novidades da v0.7.0

- Compatibilidade com aparelhos GE (e outros) que enviam a ordem de impressão sem identificador da sessão. Antes, o aparelho mostrava "impressora não encontrada" e o trabalho não chegava.
- Para atualizar: baixe o novo pacote em Downloads, substitua os arquivos (mantenha o `.env`) e rode `docker compose down && docker compose up -d --build`.

