chore: remove the abandoned prototypes and archive what described them
portal/, kanban/ and agente/ were 2,034 lines implementing the original Tiny-first model: token upload links, a second SQLite Kanban, a factory agent. Nothing imported or started any of it, and several endpoints took the acting user from the request body with no authentication at all. Their real cost was that a reader arriving at this repository found two Kanbans and two portals and had to work out which one was real. The root schema.sql and .env.exemplo went with them: both code paths load local/schema.sql, and having .env.exemplo beside .env.example differing by one letter was a trap rather than a convenience. The documents describing that model are archived rather than deleted. They record decisions and reasoning the current documents do not repeat, so they are worth keeping as background, with a header saying plainly that they are not instructions. README.md keeps its business case — the capacity figures and the cost argument are still the reason this project exists — but now states where the prototype documentation begins and that the code it describes is gone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Cauê Faleiros
307
docs/historico/ESPECIFICACAO.md
Normal file
307
docs/historico/ESPECIFICACAO.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user