dtf-system/ESPECIFICACAO.md

# Módulo DTF no PCP — especificação de implementação

> Para o Wagner. Consolida o desenho depois das reuniões com os designers e com
> a sala de impressão em 02/09/2026.
> Complementa o `README.md` (arquitetura) e o código em `portal/`, `agente/` e
> `kanban/`.

---

## O que mudou depois das reuniões

Sete decisões vieram da equipe e **já estão refletidas no código**. Se algo no
código parecer estranho, provavelmente é uma delas.

| Item | Era | Ficou | Quem definiu |
|---|---|---|---|
| Reserva ao puxar | 15 min | **3 min** | sala |
| Puxar trabalho | até 30 min | **um pedido por vez** | sala |
| Marcadores de duração | seriam apagados | **viram campo `minutos_maquina`** | sala |
| Hot folder em rede | a confirmar | **aceita** | sala |
| Production Manager | a confirmar | **centraliza, mas o PC central precisa de mais capacidade** | sala |
| Licenças do Flexi | a confirmar | **por PC** | sala |
| Meta de retrabalho | 0,4% por causa | **rever: a sala prefere meta geral** | sala |

---

## Números que a equipe deu e que entram no cálculo

| Dado | Valor | De onde veio |
|---|---|---|
| Arquivos que chegam usáveis | **30%** | designers |
| Tempo para tratar arquivo bom | **3 minutos** | designers |
| Tempo para tratar arquivo ruim | **1h30** | designers |
| Formatos que mais chegam | **PNG e PDF** | designers |
| PDF que chega | **vetorial** | designers |
| SPOT | **sempre igual** | designers |
| Cores que sempre dão problema | azul, vermelho, castanho, laranja, verde — **secundárias** | sala |
| Prova de cor hoje | **não mandam para ninguém** | sala |
| Como o operador sabe o próximo | **notinha do pedido** | sala |
| Tempos de setup | **"não temos informação"** | sala |

**O de 30% é o mais consequente.** Sete de cada dez arquivos passam pelo
designer. Se o pré-flight barrar metade dos ruins na entrada, são ~3,5 arquivos
em 10 que deixam de consumir tempo de arte.

---

## Fases de implementação

Cada fase entrega valor sozinha. **Não espere a fase 4 para colocar algo no ar.**

### Fase 1 · Limpeza do Tiny — pode começar hoje

Não depende de nada nem de ninguém.

- [ ] Criar os marcadores `DTF-PRODUCAO`, `DTF-PRONTO` e `DTF-PROVA-COR`
- [ ] Tirar da **lista de sugestão** as variações digitadas à mão: `inicio 14:45`,
      `inicio13:34`, `1hrs`, `3h`, `+30min de correcao` e as demais
- [ ] **Não apagar do histórico dos pedidos** — só da lista de opções
- [ ] **Preservar** `30 min`, `1 hora` e `3 horas`: são estimativa de máquina e
      viram o campo `minutos_maquina`

### Fase 2 · Portal e robô — recebe 24h sozinho

Entrega valor sem o kanban existir.

- [ ] Contratar VPS, storage S3 e o subdomínio (ver README)
- [ ] Webhook do Tiny → cria token → dispara link no WhatsApp
- [ ] Página de upload com campo de repetição e prévia da montagem
- [ ] URL pré-assinada · upload em partes até **5 GB**
- [ ] Pré-flight (`preflight.py` pronto)
- [ ] Normalização: vetor → PDF, raster → TIF, CMYK → RGB
- [ ] Montagem empilhada · fatiamento em 20 m · carimbo com QR de 20 mm
- [ ] ClamAV em segundo plano
- [ ] Retenção de 30 dias · artes para recompra, 12 meses

### Fase 3 · Agente — o arquivo cai na pasta sozinho

- [ ] Serviço no servidor da fábrica (NSSM ou systemd)
- [ ] Webhook + polling de 60 s
- [ ] Download com verificação de hash
- [ ] Heartbeat a cada 5 min · alerta se sumir por 15

### Fase 4 · Kanban como aba do PCP

- [ ] Quadro com as 7 colunas e cronômetro por card
- [ ] Painel das 6 máquinas com **indicador vermelho de ocupada**
- [ ] `puxar próximo` — reserva de 3 min, um pedido por vez
- [ ] `devolver à fila` — volta ao topo
- [ ] Campo `minutos_maquina` no card, com sugestão automática
- [ ] Retrabalho: abertura, classificação de causa, autorização
- [ ] Painel com filtros de período
- [ ] Endpoints de relatório: etapas, impressão, aproveitamento, retrabalho

### Fase 5 · Duas semanas medindo

**Não pule.** É o que decide se vale o terceiro turno.

O que sai depois de duas semanas rodando:
- tempo real de cada etapa
- metros/hora reais por máquina
- quanto do tempo do designer é retrabalho de arquivo ruim
- retrabalho medido contra o que a sala achava que era

---

## Funcionalidades, uma a uma

### Portal do cliente

**Link com token.** Um por pedido, UUID v4, 7 dias de validade. O token já
carrega o número do pedido no Tiny — o cliente não digita nada.

**Upload direto para o storage.** URL pré-assinada, em partes, até 5 GB. O
arquivo nunca passa pelo VPS.

**Campo de repetição.** O cliente sobe uma arte e informa quantas vezes repetir.
O robô empilha. É o trabalho braçal que hoje o designer faz à mão.

**Prévia da montagem.** Mostra como a folha ficou antes de fechar o pedido.
Montagem **empilhada**, sem encaixe lado a lado — decisão do Marcus.

**Gabarito 57 × 97 cm** para download. Os 30 mm do rodapé são do carimbo.

**Resposta na hora.** Aprovado ou recusado com o motivo em português. **O relógio
do prazo só começa quando a arte é aprovada.**

### Robô de pré-flight

Ordem: **normalizar → validar → repetir → fatiar → carimbar.**

| Verificação | Limite | Ação |
|---|---|---|
| Canal de transparência | obrigatório | recusa |
| DPI efetivo na medida comprada | < 150 | recusa |
| Largura | > 57 cm | recusa |
| Formato | JPEG | recusa |
| DPI efetivo | 150 a 300 | aceita com aviso |
| Alfa parcial nas bordas | > 15% | aceita com aviso |
| CDR | — | **entra sem validar**, etiqueta "conferir" |

**DPI efetivo = pixels ÷ (cm comprados ÷ 2,54).** O metadado do arquivo mente.

**Normalização por natureza:** vetor sai PDF mantendo vetor, raster sai TIF com
alfa. CMYK vira RGB. **O original é sempre preservado** — pedido dos designers.

### Kanban

**Sete colunas:** arte recebida, arte tratada, aprovação de cor, fila,
imprimindo, correção, finalizado. **Não há coluna de aplicação** — a sala só
imprime o filme.

**Fila por ordem de chegada, sempre.**

**Puxar próximo.** Um botão por máquina. Reserva por 3 minutos; se não entrar em
Imprimindo nesse prazo, volta para a fila. **Um pedido por vez.**

**Indicador de máquina ocupada.** Círculo vermelho e botão desabilitado. Com seis
máquinas vendo o mesmo quadro, é o que evita dois operadores no mesmo arquivo.

**Devolver à fila.** Volta ao **topo**, não ao fim — o pedido já esperou uma vez.

**Cronômetro por card.** Tempo parado na coluna atual, em tempo real. Verde até
1h, amarelo até 3h, vermelho acima.

**Trilha por pedido.** Tempo em cada etapa e quanto do total foi só esperando.

### Estimativa de máquina

Campo `minutos_maquina` no card. **Herda os marcadores `30 min`, `1 hora` e
`3 horas` do Tiny**, que a sala confirmou serem estimativa.

- O sistema sugere pelo tamanho: `metros ÷ 20 × 60`
- Quem trata a arte ajusta **só quando foge do normal**
- É esse número que soma a fila contra a capacidade do dia

### Aprovação de cor

A sala confirmou que **hoje não manda prova para ninguém**, e que as cores
problemáticas são as secundárias: azul, vermelho, castanho, laranja e verde.
São cores fora do gamut CMYK — o monitor do cliente mostra o que a máquina não
reproduz.

Dispara sozinho em três casos: arquivo acima de 10 m, primeiro pedido do
cliente, ou cor detectada fora do gamut.

**Custo:** ~30 cm de filme, R$ 1,50. Uma reposição de 20 m custa R$ 99.

**Sugestão de implantação:** começar só com **cliente novo**. Os outros dois
gatilhos entram depois, senão metade dos pedidos vai esperar resposta e o prazo
morre.

### Retrabalho

SKU `CRRMP.TX.100CM`. **Mayana abre e classifica a causa; Thales ou Alexandre
autorizam** — eles confirmaram que acham justo, já que entra na meta deles.

**A causa fica travada depois de aberta.** Com o indicador atrelado a bônus,
haveria incentivo para reclassificar falha de máquina como culpa do cliente.
Quem discorda contesta, e a contestação fica registrada.

**⚠ A meta precisa ser redefinida.** A proposta era 0,4% por causa, somando 1,6%.
A sala respondeu que **"meta geral seria melhor"**. Antes de codificar, decidir
com o Marcus: meta única sobre o total da casa, ou por causa. O código tem
`META_POR_CAUSA` isolado justamente para isso.

### Integração com o Tiny

**Três marcadores, não sete.** O kanban é a fonte de verdade; o Tiny mostra o
estágio grosso para quem não abre o kanban.

| Movimento | Marcador |
|---|---|
| Imprimindo | `DTF-PRODUCAO` |
| Correção | `CORRECAO DTF` |
| Finalizado | `DTF-PRONTO` |

640 chamadas de API por dia em vez de 1.500.

### Mensagens ao cliente

| Quando | Mensagem |
|---|---|
| 1 hora sem arte | lembrete com o link · o pedido aparece como *faltando arquivo* |
| Arte recusada | motivo em português · o prazo não começou |
| Arte aprovada | qualidade em **% e DPI**, metragem, tempo estimado, horário previsto |
| Entrou em produção | aviso simples |
| Correção | motivo · **única que pede resposta** |
| Finalizado | pronto para retirada ou envio |

---

## O que ainda não pode ser codificado

### 1 · O SPOT automático

**Hipótese, não fato.** Os designers disseram que o SPOT é sempre igual; a sala
disse que "é possível criar um perfil só para isso". A documentação do Flexi 22
cita *transparency mask*, que gera o branco a partir da transparência de PNG e
TIF.

**Mas ninguém configurou ainda**, e a edição MiniTX é OEM.

O roteiro de teste está em `dtf-teste-branco-automatico.pdf`. Sete passos, uma
máquina, meia hora.

- **Se funcionar:** o arquivo vai do portal direto para a hot folder e o PC
  central atende só exceções. A madrugada roda sem ninguém.
- **Se não funcionar:** o SPOT segue manual e todo pedido passa pelo PC central.
  **A conta das 24 horas muda.**

### 2 · A capacidade do PC central

A sala confirmou que o Production Manager centraliza várias impressoras, **mas
que o PC central precisa de mais capacidade**. E as licenças do Flexi são **por
PC** — então centralizar o RIP exige licença lá.

Levantar antes de decidir: configuração atual do PC central, custo de uma
licença adicional, e quanto de memória o RIP consome num trabalho de 15 m.

### 3 · As regras de choke

Os designers **não responderam** os valores de choke nem a espessura mínima de
traço. Sem isso, a regra proposta — 2 px acima de 2 mm, 1 px de 1 a 2 mm,
nenhum abaixo de 1 mm — é chute informado.

**Só entra em código depois de validada com um arquivo real.**

### 4 · Metros/hora reais

Todo o cálculo de capacidade assume **20 m/h por máquina**. A sala não respondeu
o valor real, e disse que não tem informação sobre tempos.

Se o real for 14, a capacidade cai de 60.480 para 42.336 metros/mês e o plano
das 24 horas precisa ser refeito.

---

## Ressalvas honestas sobre o código

**`tiny.py` é chute informado.** Estrutura padrão de OAuth2 e endpoints v3, não
validado contra a documentação real. Está isolado de propósito: se o endpoint
for diferente, muda só ali.

**`carimbar()` precisa de teste visual.** A lógica está certa, mas posicionamento
de texto com pyvips sempre pede ajuste olhando o resultado impresso.

**O front do kanban usa dados fixos.** Precisa trocar por chamadas a
`/api/quadro` e `/api/mover`. O protótipo `dtf-kanban-treino.html` tem o layout e
o comportamento final.

**Nada instalado nos PCs da sala.** Decisão do Marcus. O navegador não abre
arquivo no FlexiPRINT — o desenho é miniatura no card mais botão que copia o
caminho, e File System Access API para mover arquivo pelo navegador.

---

## O que precisa de resposta antes da fase 4

1. Servidor da fábrica é Windows ou Linux?
2. A conta do Tiny já tem aplicação na API v3?
3. Confirmar na documentação do Tiny o endpoint de marcadores e o limite de
   requisições por minuto
4. O número do WhatsApp migra para a API oficial da Meta?
5. Qual a latência da integração VNDA → Tiny? Define quando o link sai
6. Meta de retrabalho: geral ou por causa?
7. Configuração e licença do PC central, se for virar servidor de RIP