Manual Técnico — Módulo Workflow

Documento de referência técnica exclusivo do módulo Workflow (Kanban/Gestão de Tarefas).

Sumário

1. Visão Geral
2. Modelo de Dados
3. Regras de Negócio
4. Requisitos Funcionais
5. Arquitetura e Estrutura de Código
6. Mapa de APIs
7. Schemas de Validação (Zod)
8. Notificações
9. Registro de Tempo (Timesheet)
10. Alçadas de Aprovação
11. Isolamento por Empresa
12. Testes

1. Visão Geral

O módulo Workflow é um sistema de gestão de tarefas estilo Kanban integrado à plataforma NotaNacional. Permite criar quadros (workspaces) com etapas configuráveis, cards (tarefas) com campos financeiros, prioridades, anexos, comentários, registro de tempo e alçadas de aprovação.

Funcionalidades Principais

2. Modelo de Dados

Diagrama ER (Mermaid)

Entidades

Workspace

Constraints: @@unique([prestadorId, nome])

WorkspaceMembro

Constraints: @@unique([workspaceId, usuarioAcessoId])

WorkspaceEtapa

Constraints: @@unique([workspaceId, nome])

WorkspacePrioridade

Constraints: @@unique([workspaceId, nome])

WorkspaceCard

WorkspaceCardAnexo

WorkspaceCardComentario

WorkspaceCardHistorico

WorkspaceRegistroTempo

WorkspaceCronometro

WorkspaceNotificacao

WorkspaceNotificacaoPreferencia

Constraints: @@unique([prestadorId, usuarioId, tipoEvento])

PrestadorVolumetria (Compartilhado)

3. Regras de Negócio

3.1 Multi-tenancy

• Toda query filtra por prestadorId.
• Toda mutação valida que o recurso pertence ao prestadorId do usuário.
• Nome de workspace é único por prestador.

3.2 Ciclo de Vida do Card

• Status FINALIZADO e CANCELADO são terminais (não podem ser revertidos).
• Status muda automaticamente ao mover card para etapa isFinal = true.

3.3 Etapas

• Cada workspace deve ter pelo menos 1 etapa com isInitial = true (obrigatório para encaminhamento).
• Podem existir etapas com isFinal = true (marcam cards como FINALIZADO ao entrar).
• Posição determina a ordem visual das colunas (pode ser reordenada via drag-and-drop).
• Nome de etapa é único dentro do workspace.
• Inativação de etapa: somente se não houver cards ativos nela (a validar no backend).

3.4 Membros

• Papéis: ADMIN (gerencia workspace, membros, etapas, prioridades) e MEMBRO (opera cards).
• Membro é vinculado via usuarioAcessoId (tabela UsuarioAcesso).
• Unique constraint: um usuário não pode ser adicionado duas vezes ao mesmo workspace.

3.5 Cards — Campos Financeiros

• Cards possuem campos financeiros opcionais: valor, centroCusto, fornecedor, vencimento, etc.
• Esses campos permitem usar o workflow como fluxo de contas a pagar/aprovação financeira.
• Valor usa Decimal(12,2) — máscara BRL R$ X.XXX,XX.
• Se valor > alçada, dispara solicitação de aprovação (ver seção 10).

3.6 Encaminhamento entre Workspaces

• Um card pode ser copiado para outro workspace via /cards/:id/encaminhar.
• O novo card é criado na etapa inicial (isInitial = true) do workspace destino.
• O card original permanece inalterado no workspace de origem.
• Campos copiados: titulo, descricao, valor, centroCusto, fornecedor, clienteId, etc.
• Anexos ativos são duplicados (copiados, não referenciados).
• Rastreabilidade: cardOrigemId e workspaceOrigemId no card novo.
• Pré-requisito: o usuário deve ser membro ativo do workspace destino.
• Pré-requisito: o workspace destino deve ter etapa com isInitial = true.

3.7 Posicionamento e Reordenação

• Cards dentro de uma etapa têm campo posicao (1-based).
• Mover um card entre etapas: altera etapaId + recalcula posição na etapa destino.
• Reordenar dentro da mesma etapa: PATCH em batch com novo array de posições.
• Etapas e prioridades também possuem posicao reordenável.

3.8 Soft Delete

• Todas as entidades usam ativo = true/false.
• DELETE na API marca ativo = false (nunca remove fisicamente).
• Listagens padrão filtram ativo = true.

3.9 Volumetria de Storage

• Uploads de anexos contam contra PrestadorVolumetria.bytesUtilizados.
• Limite padrão: 1 GB (bytesLimite = 1073741824).
• Se ultrapassar, uploads são recusados.
• Ao deletar anexo (soft delete), bytes são devolvidos ao saldo.

3.10 Comentários com Notificação Seletiva

• Ao criar comentário, pode-se enviar notificarIds: string[] com IDs de membros.
• O sistema cria uma WorkspaceNotificacao do tipo NOVO_COMENTARIO para cada membro listado.
• Respeita as preferências de canal do destinatário (in-app e/ou email).

3.11 Severidade

• Cards podem ter campo severidadeId com valores: BAIXA, MEDIA, ALTA, CRITICA.
• É independente de prioridade (prioridade é customizável, severidade é fixa).

4. Requisitos Funcionais

4.1 Workspaces

4.2 Membros

4.3 Etapas (Colunas Kanban)

4.4 Prioridades

4.5 Cards (Tarefas)

4.6 Encaminhamento

4.7 Anexos

4.8 Comentários

4.9 Histórico

5. Arquitetura e Estrutura de Código

Páginas (Frontend)

src/app/(app)/workflow/
├── page.tsx                           # Lista de workspaces
└── [workspaceId]/
    ├── page.tsx                       # Kanban/tabela do workspace
    └── registro-tempo/
        └── page.tsx                   # Timesheet do workspace

API Routes (Backend)

src/app/api/workflow/
├── workspaces/
│   ├── route.ts                       # GET (list) + POST (create)
│   └── [id]/
│       ├── route.ts                   # GET (detail) + PATCH + DELETE
│       ├── membros/
│       │   ├── route.ts               # GET (list) + POST (add)
│       │   └── [membroId]/route.ts    # PATCH + DELETE
│       ├── etapas/
│       │   ├── route.ts               # GET + POST
│       │   ├── [etapaId]/route.ts     # PATCH + DELETE
│       │   └── reorder/route.ts       # PATCH (reordenar)
│       ├── prioridades/
│       │   ├── route.ts               # GET + POST
│       │   ├── [prioridadeId]/route.ts # PATCH + DELETE
│       │   └── reorder/route.ts       # PATCH (reordenar)
│       ├── cards/
│       │   ├── route.ts               # GET (kanban/tabela) + POST
│       │   ├── reorder/route.ts       # PATCH (reordenar)
│       │   └── [cardId]/
│       │       ├── route.ts           # GET + PATCH + DELETE
│       │       ├── mover/route.ts     # PATCH (mover entre etapas)
│       │       ├── status/route.ts    # PATCH (alterar status)
│       │       ├── encaminhar/route.ts # POST (encaminhar)
│       │       ├── pdf/route.ts       # GET (gerar PDF)
│       │       ├── anexos/route.ts    # GET + POST + DELETE
│       │       ├── comentarios/route.ts # GET + POST + DELETE
│       │       └── historico/route.ts # GET
│       ├── registro-tempo/
│       │   ├── route.ts               # GET + POST
│       │   ├── [registroId]/route.ts  # PATCH + DELETE
│       │   ├── relatorio/route.ts     # GET (relatório agrupado)
│       │   └── cronometro/
│       │       ├── iniciar/route.ts   # POST
│       │       ├── pausar/route.ts    # POST
│       │       ├── retomar/route.ts   # POST
│       │       ├── parar/route.ts     # POST
│       │       └── status/route.ts    # GET
│       ├── aprovacao/route.ts         # GET + POST (regra + decisão)
│       └── aprovadores/               # GET + POST + PATCH
└── notificacoes/
    ├── route.ts                       # GET (listar)
    ├── contagem/route.ts              # GET (count não-lidas)
    ├── marcar-todas-lidas/route.ts    # PATCH
    ├── preferencias/route.ts          # GET + PUT
    ├── [id]/route.ts                  # PATCH (marcar lida)
    └── cron/verificar-prazos/         # Cron: verificar prazos vencidos

Services (Client-side)

src/services/
├── workflow.ts                  # Workspaces, membros, etapas, prioridades
├── workflow-cards.ts            # Cards, anexos, comentários, encaminhamento, histórico
├── workflow-registro-tempo.ts   # Registros de tempo + cronômetro
├── workflow-notificacoes.ts     # Notificações + preferências
└── alcadas-aprovacao.ts         # Regras, aprovadores, solicitações

Validators (Zod)

src/lib/validators/
├── workflow.ts                  # Workspace, membros, etapas, prioridades
├── workflow-cards.ts            # Cards, status, encaminhamento, anexos, comentários, reorder
├── workflow-registro-tempo.ts   # Registros, cronômetro, relatório
├── workflow-notificacoes.ts     # Preferências, listagem
└── alcadas-aprovacao.ts         # Regras, aprovadores, decisão

6. Mapa de APIs

6.1 Workspaces

6.2 Membros

6.3 Etapas

6.4 Prioridades

6.5 Cards

6.6 Anexos

6.7 Comentários

6.8 Histórico

6.9 Registro de Tempo

6.10 Notificações

6.11 Aprovação

7. Schemas de Validação (Zod)

7.1 Workspace

createWorkspaceSchema: { nome: string(2-100), descricao?: string(max 500), cor: #RRGGBB }
updateWorkspaceSchema: { nome?, descricao?, cor?, ativo? }

7.2 Membros

addMembroSchema: { usuarioAcessoId: UUID, papel: "ADMIN" | "MEMBRO" }
updateMembroSchema: { papel: "ADMIN" | "MEMBRO" }

7.3 Etapas

createEtapaSchema: { nome: string(2-50), cor: #RRGGBB, isInitial?: boolean, isFinal?: boolean }
updateEtapaSchema: { nome?, cor?, isInitial?, isFinal?, ativo? }
reorderEtapasSchema: { etapas: [{id: UUID, posicao: int ≥ 1}] }

7.4 Prioridades

createPrioridadeSchema: { nome: string(2-50), cor: #RRGGBB, icone: string(1-50) }
updatePrioridadeSchema: { nome?, cor?, icone?, ativo? }
reorderPrioridadesSchema: { prioridades: [{id: UUID, posicao: int ≥ 1}] }

7.5 Cards

createCardSchema: {
  titulo: string(2-200) REQUIRED,
  descricao?: string | null,
  responsavelId?: UUID | null,
  dataEntrega?: datetime (ISO offset) | null,
  prioridadeId?: UUID | null,
  etapaId?: UUID | null,
  empresaId?: UUID | null
}

updateCardSchemaExtended: {
  ...updateCardSchema,                    // titulo?, descricao?, responsavelId?, dataEntrega?, prioridadeId?, etapaId?, ativo?
  empresaId?: UUID | null,
  valor?: number(0 - 999999999999.99) | null,
  centroCusto?: string(max 100) | null,
  centroCustoId?: UUID | null,
  entidadeCategoria?: string(max 100) | null,
  vencimento?: datetime | null,
  fornecedor?: string(max 200) | null,
  fornecedorId?: UUID | null,
  numeroDocumento?: string(max 50) | null,
  dataEmissaoNf?: datetime | null,
  clienteId?: UUID | null,
  severidadeId?: "BAIXA" | "MEDIA" | "ALTA" | "CRITICA" | null,
  cardOrigemId?: UUID | null
}

updateStatusSchema: { status: "FINALIZADO" | "CANCELADO" }
moverCardSchema: { etapaDestinoId: UUID, posicao: int ≥ 1 }
reorderCardsSchema: { etapaId: UUID, cards: [{id: UUID, posicao: int ≥ 1}] }
encaminharCardSchema: { workspaceDestinoId: UUID }

7.6 Anexos

createAnexoSchema: { url: URL(max 500), nomeArquivo: string(1-255), mimeType: string(1-100), tamanhoBytes: int > 0 }
uploadArquivoSchema: { mimeType: PDF|JPEG|PNG|DOC|DOCX|XLS|XLSX, tamanhoBytes: int(max 10MB) }
// Constantes: MAX_FILE_SIZE_BYTES = 10485760 (10MB), MAX_LOGO_SIZE_BYTES = 2097152 (2MB)

7.7 Comentários

createComentarioSchema: { conteudo: string(1-5000) }
createComentarioComNotificacaoSchema: { conteudo: string(1-5000), notificarIds: UUID[] (default []) }

7.8 Registro de Tempo

createRegistroTempoSchema: {
  cardId: UUID,
  descricao: string(3-500),
  dataRegistro: "YYYY-MM-DD",
  horaInicio: "HH:MM",
  horaFim: "HH:MM"
}
updateRegistroTempoSchema: { descricao?, dataRegistro?, horaInicio?, horaFim?, ativo? }
iniciarCronometroSchema: { cardId: UUID, descricao?: string(max 500) }
pararCronometroSchema: { descricao?: string(3-500) }
relatorioQuerySchema: { dataInicio: "YYYY-MM-DD", dataFim: "YYYY-MM-DD", usuarioId?, cardId?, agrupamento: "diario"|"semanal"|"mensal" }

7.9 Notificações

// Tipos de evento: ATRIBUICAO, PRAZO_VENCIMENTO, NOVO_COMENTARIO, MUDANCA_ETAPA, EDICAO_CARD, CRIACAO_CARD
updatePreferenciasSchema: { preferencias: [{ tipoEvento, canalInApp: bool, canalEmail: bool }] (1-6 items) }
listNotificacoesQuerySchema: { page: int ≥ 1, limit: int(1-50), tipo?: TipoEvento, lida: "true"|"false"|"all" }

7.10 Aprovação

createRegraAprovacaoSchema: { valorMinimo: number(0.01 - 9999999999.99) }
createAprovadorSchema: { membroId: UUID, valorAlcada: number(0.01 - 999999999.99) }
decisaoSchema: { decisao: "APROVADO" | "REJEITADO", observacao?: string(max 500) }
listPendentesSchema: { page, perPage, workspaceId?, status, de?, ate?, orderBy, orderDir }

8. Notificações

Tipos de Evento

Canais

Preferências

• Cada usuário pode configurar por tipo de evento quais canais deseja receber.
• Padrão: ambos ativos (canalInApp: true, canalEmail: true).
• Unique: [prestadorId, usuarioId, tipoEvento].

Contagem

• Endpoint /api/workflow/notificacoes/contagem retorna total de não-lidas.
• Usado para exibir badge numérico no header.

Cron — Verificar Prazos

• Rota /api/workflow/notificacoes/cron/verificar-prazos verifica cards com dataEntrega próxima/vencida.
• Dispara notificação PRAZO_VENCIMENTO para o responsável.

9. Registro de Tempo (Timesheet)

Lançamento Manual

• Campos: cardId, descrição, dataRegistro, horaInício (HH:MM), horaFim (HH:MM).
• Duração calculada automaticamente em minutos (duracaoMin).
• Origem marcada como MANUAL.
• Um registro por vez — sem overlap checking.

Cronômetro

• 1 cronômetro ativo por usuário (usuarioId é UNIQUE em WorkspaceCronometro).
• Estados: EM_ANDAMENTO → PAUSADO → EM_ANDAMENTO (loop) → PARADO (gera registro).

• Ao pausar: salva pausadoEm e soma tempo ao acumuladoMs.
• Ao retomar: limpa pausadoEm e recomeça contagem.
• Ao parar: calcula tempo total, cria WorkspaceRegistroTempo com origem CRONOMETRO, deleta o cronômetro.

Relatório

• Endpoint: GET .../registro-tempo/relatorio?dataInicio&dataFim&agrupamento
• Retorna:
  • totalMinutos e totalFormatado (ex: "12h 30min")
  • mediaDiariaMin e mediaDiariaFormatada
  • porPeriodo[] — agrupado por dia/semana/mês
  • porResponsavel[] — agrupado por usuário
  • porCard[] — agrupado por card

10. Alçadas de Aprovação

Conceito

Quando um card com campo valor excede o valor mínimo configurado na regra de aprovação do workspace, o sistema bloqueia a movimentação até que um aprovador com alçada suficiente aprove.

Entidades

Fluxo

Regras

• Uma regra ativa por tipo (WORKSPACE/FINANCEIRO) por prestador.
• Aprovador deve ser membro do workspace.
• valorAlcada define até quanto o aprovador pode aprovar.
• Se valor do card > alçada do aprovador, outro aprovador com alçada maior deve decidir.
• Decisão: APROVADO ou REJEITADO com observação opcional (max 500 chars).
• Listagem de pendentes com filtros: status, workspace, período, ordenação.

11. Isolamento por Empresa

Conceito

Dentro de um mesmo tenant (prestadorId), cards podem ser isolados por empresa. Isso permite que prestadores com múltiplas empresas/CNPJs gerenciem workflows separados.

Implementação

• WorkspaceCard.empresaId: FK para Empresa.
• Filtro no GET cards: ?empresaId=UUID retorna apenas cards daquela empresa.
• Modelo Empresa: { id, prestadorId, nome, cnpj } com unique [prestadorId, cnpj].
• Modelo EmpresaUsuario: vincula usuários a empresas (ou acessoGlobal: true).
• Cards sem empresaId são visíveis a todos.

12. Testes

Cobertura Existente

src/app/api/workflow/workspaces/__tests__/
├── route.test.ts                                    # CRUD workspaces
├── workspace-access-control.exploration.test.ts     # Access control exploratório
└── workspace-access-control.preservation.test.ts    # Access control preservação

src/app/api/workflow/workspaces/[id]/cards/__tests__/
└── route.test.ts                                    # CRUD cards

src/app/api/workflow/workspaces/[id]/etapas/__tests__/
└── route.test.ts                                    # CRUD etapas

src/app/api/workflow/workspaces/[id]/etapas/reorder/__tests__/
└── route.test.ts                                    # Reordenação

src/app/api/workflow/workspaces/[id]/prioridades/__tests__/
└── route.test.ts                                    # CRUD prioridades

src/app/api/workflow/workspaces/[id]/prioridades/reorder/__tests__/
└── route.test.ts                                    # Reordenação

src/app/api/workflow/workspaces/[id]/registro-tempo/__tests__/
└── route.test.ts                                    # Registro de tempo

src/app/api/workflow/workspaces/[id]/registro-tempo/cronometro/__tests__/
└── ...                                              # Cronômetro

src/app/api/workflow/workspaces/[id]/aprovacao/__tests__/
└── route.test.ts                                    # Alçadas

src/app/api/workflow/workspaces/[id]/membros/[membroId]/__tests__/
└── ...                                              # Membros

src/app/api/workflow/workspaces/[id]/prioridades/[prioridadeId]/__tests__/
└── ...                                              # Prioridade individual

src/app/api/workflow/workspaces/[id]/etapas/[etapaId]/__tests__/
└── ...                                              # Etapa individual

src/app/api/workflow/workspaces/[id]/__tests__/
└── ...                                              # Workspace individual

Executar Testes do Módulo

# Todos os testes do módulo workflow
npx vitest run --testPathPattern=workflow

# Testes específicos de cards
npx vitest run --testPathPattern=workflow.*cards

# Testes de aprovação
npx vitest run --testPathPattern=workflow.*aprovacao

Documento atualizado em Junho/2026. Manter sincronizado com evolução do módulo.