Ciclo de Vida do Processo & Tráfego de Dados

O frontend nunca fala com o banco direto: toda página chama a API FastAPI (prefixo /api/v2/...). Os workers populam o banco de forma assíncrona; a API só lê/escreve o que já está consolidado.

O dado percorre 5 etapas: Captura → Triagem → Catalogação → Controle de prazos → Arquivamento. Há dois portões de validação humana (losangos): um na triagem jurimétrica e outro na fila de tarefas automáticas.

flowchart TD
    %% ============ FONTES EXTERNAS ============
    subgraph EXT["🌐 Fontes externas"]
        direction LR
        CNJ["CNJ DataJud
(dumps CSV mensais)"]
        DJE["DJE
(Diários de Justiça)"]
        COM["PJe Comunica
(intimações)"]
        EDI["Editais de RJ"]
        ADV["Advise
(publicações + prazos)"]
    end

    %% ============ ETAPA 1: CAPTURA ============
    subgraph CAP["1 · CAPTURA / INGESTÃO  (workers Railway)"]
        direction TB
        BZ["baixar_zips.py
→ tb_datajud_dumps + Bunny"]
        EX["extrair_classes.py
filtra 108/128/129/12134-5
→ tb_datajud_consolidados"]
        CL["classificar.py
UPSERT → tb_datajud_processos
+ tb_datajud_partes"]
        TRG[("triggers →
tb_jurimetria_processos
(universo bruto)")]
        MIN["minerar_dje.py /
buscar_comunica.py /
localizar_interesse.py"]
        SYNC["advise/sync
(andamentos, capa,
publicações)"]
        BZ --> EX --> CL --> TRG
    end

    CNJ --> BZ
    DJE --> MIN
    COM --> MIN
    EDI --> MIN
    ADV --> SYNC

    %% ============ ETAPA 2: TRIAGEM ============
    subgraph TRI["2 · TRIAGEM  (curadoria humana)"]
        direction TB
        PEND[("tb_triagem_processos
fonte='jurimetria'
status='pendente'")]
        VAL{"Validação humana
/validacao_mineracao
POST /triagem/{cnj}/decidir"}
        PEND --> VAL
    end
    CL -->|cria pendentes| PEND
    MIN -.->|leads/escopo| PEND

    %% ============ ETAPA 3: CATALOGAÇÃO / ACERVO ============
    subgraph CAT["3 · CATALOGAÇÃO / ACERVO  (família radar = fonte de verdade)"]
        direction TB
        OM[("tb_radar_obs_metodol
INSTRUMENTO + contagem
(correcao_classe FAL/RJ/RE/TC)")]
        RP[("tb_radar_processos
+ tb_radar_cadastro
+ demais tb_radar_* (cadernos)")]
        DIST[("tb_distribuicao + tb_orgaos
atributos DataJud canônicos")]
        PROC[("tb_processos
(família operacional)")]
        OM --- RP
        RP --- PROC
        DIST --- RP
    end
    VAL -->|APROVA: grava instrumento| OM

    %% ============ CONSUMIDORES (leitura) ============
    subgraph CONS["📊 Consumo (somente leitura)"]
        direction LR
        RADAR["Radar da Crise /
Painéis / Indicadores"]
        CAD["Cadernos / Relatórios /
Sumários"]
        PESQ["Pesquisa temática /
Consulta de partes /
Acervo & vinculação"]
    end
    OM --> RADAR
    RP --> CAD
    DIST --> PESQ

    %% ============ ETAPA 4: CONTROLE DE PRAZOS / TAREFAS ============
    subgraph PRZ["4 · CONTROLE DE PRAZOS & TAREFAS  (Scrum)"]
        direction TB
        AUTO["criar_tarefas_radar / _nid_dje /
_nid_datajud (workers)"]
        FILA{"Fila de validação
/kanban/validacao
(status_validacao=pendente)"}
        PRAZOS[("tb prazos (Advise)
GET /api/v2/prazos
afazer→elaboracao→revisao→protocolado")]
        KB[("Kanban: tb_kanban_quadros /
tb_kanban_tarefas
backlog→afazer→andamento→revisao→concluido")]
        SPR[("Scrum: tb_sprints /
sprint_backlog (Fibonacci)")]
        AUTO --> FILA -->|aprova| KB
        KB --- SPR
    end
    OM -->|processo no radar| AUTO
    SYNC -->|prazo novo| PRAZOS
    PRAZOS -->|"auto-sync: tarefa vinculada (prazo_id)"| KB

    %% ============ ETAPA 5: ARQUIVAMENTO ============
    subgraph ARQ["5 · ARQUIVAMENTO / ENCERRAMENTO"]
        direction LR
        TA["Tarefa: coluna 'concluido'
→ arquivado = TRUE"]
        PA["Prazo: 'protocolado'
ou 'cancelado'"]
        PRA["Processo: situação
'baixado'/arquivado
(tb_processos)"]
    end
    KB --> TA
    PRAZOS --> PA
    PROC --> PRA

    classDef ext fill:#1a1816,stroke:#957c46,color:#f4f0ea
    classDef gate fill:#0e1b3a,stroke:#d2b878,color:#fff
    class CNJ,DJE,COM,EDI,ADV ext
    class VAL,FILA gate

O sistema não cadastra processo manualmente como regra: ele descobre os processos varrendo fontes públicas e integrações. Há vários canais de entrada, todos rodando como workers na Railway (configs railway.*.json).

3.1 Pipeline DataJud (canal principal — quinzenal)

Documentado em backend/apps/jurimetria/README.md. Roda encadeado pelo serviço cron (railway.cron.json, baixar → extrair → classificar, dia 1 e 16):

• O passo 2 filtra só as classes-alvo: 108 = Falência, 128 = RE, 129 = RJ, 12134/12135 = Tutela Cautelar.
• O passo 3 faz UPSERT no universo bruto e, via triggers, popula tb_jurimetria_processos. Ao final, cria as pendentes da triagem (ver §4).
• Cada rodada de cada passo grava uma linha em tb_datajud_pipeline_runs (helper pipeline_runs.py), visível no Monitor de Scripts.

3.2 Outros canais de captura

Tabelas geradas pelos demais canais:

• DJE — tb_dje_pesquisa_livre (hits por termo/data), tb_dje_processos, tb_dje_partes; CNJs novos entram em tb_jurimetria_processos (descoberto_via inclui 'dje') e geram pendente na triagem (fonte='dje').
• Advise — tb_advise_movimentacoes, tb_advise_prazos, tb_advise_capa, tb_advise_sync_state (todas idempotentes por hash_dedup).

Resumo do tráfego nesta etapa: fontes externas → workers → tabelas tb_datajud_* / tb_dje_* / tb_advise_* / tb_jurimetria_processos (universo bruto descoberto). Nada aqui ainda é "verdade curada": é matéria-prima para a triagem.

A triagem é o portão que separa o "universo bruto descoberto" do "universo curado do observatório". É a porta que alimenta a família radar (FAMILIA_RADAR.md).

1. O classificar.py insere os candidatos em tb_triagem_processos (fonte='jurimetria', status='pendente') — isto é o "mandado para validação". A mineração DJE alimenta a mesma fila com fonte='dje'. Apoiam a curadoria as tabelas tb_triagem_partes, tb_triagem_comunicacoes e tb_triagem_historico.
2. O curador trabalha na tela /validacao_mineracao (admin_jurimetria_validacao_humana.html). Endpoints em apps/jurimetria/routes.py:
   • GET /api/v2/triagem/listar — fila de pendentes
   • GET /api/v2/triagem/{cnj}/classe-sugerida e .../distribuicao-sugerida
   • POST /api/v2/triagem/{cnj}/decidir — decisão de aprovar/rejeitar
   • POST /api/v2/triagem/{cnj}/atribuir, .../status-workflow, GET /api/v2/triagem/{cnj}/historico, /api/v2/triagem/vocabularios
3. Ao aprovar, o curador define o envio ao radar e a(s) classe(s)/ instrumento(s) — isso grava em tb_radar_obs_metodol (correcao_classe), criando a ocorrência que conta como caso.

Aprovado na triagem, o processo passa a viver na família radar — as tabelas tb_radar_*, que são a fonte de verdade de toda a jurimetria (FAMILIA_RADAR.md).

Regra de ouro (FAMILIA_RADAR): contagem de ocorrências sempre via tb_radar_obs_metodol (nunca por flags is_FAL/... ou ultima_classe_codigo); atributos via tb_distribuicao. Os painéis de distribuição contam só os 4 instrumentos; classes acessórias (HAB/IMP/CCP) ficam fora do total.

Consumidores (somente leitura) dessa base: Radar da Crise, Painéis (apps/radar_paineis), catálogo de Indicadores (apps/indicadores), Cadernos (apps/cadernos), Relatórios (apps/relatorios), Sumários (apps/sumario), e as telas de exploração (pesquisa temática, consulta de partes, acervo & vinculação).

O escritório trabalha em Scrum: a unidade de trabalho é a atividade (gênero), com seis espécies: tarefa (sem prazo), prazo (tem data fatal), negociação (vinculada a credor/crédito) e os três compromissos com data e hora marcadas — audiência, reunião e mediação. Toda atividade tem link compartilhável e abre no modal único (frontend/tarefa-modal.js, objeto TM); a versão página inteira é tarefa.html.

6.1 De onde nascem as tarefas

Origens automáticas nascem com status_validacao='pendente' e param na fila de validação (/validacao_tarefas), com endpoints GET /api/v2/kanban/validacao, POST /api/v2/kanban/validacao/aprovar e .../rejeitar. Só após aprovação a tarefa aparece no board. Detecção idempotente por CNJ (ex.: tb_radar_tarefas); cada rodada grava safra em tb_tarefas_auto_runs.

6.2 Prazos (integração Advise)

Tela frontend/prazos.html, app apps/advise/routes.py:

• GET /api/v2/prazos — lista paginada com filtros
• GET /api/v2/prazos/resumo — contadores por status (colunas do board)
• POST /api/v2/prazos / PATCH /api/v2/prazos/{id} — cria / muda status

Fluxo da controladoria: afazer → elaboracao → revisao → protocolado. cancelado fecha o prazo; vencido é derivado (data fatal passada e ainda não protocolado), não armazenado. Cada prazo aberto tem uma tarefa de Kanban vinculada (resolvida por GET /api/v2/kanban/tarefas/by-prazo/{prazo_id}).

6.3 Kanban e Scrum

• Kanban — tb_kanban_quadros / tb_kanban_tarefas (apps/tarefas/routes.py, endpoints /api/v2/kanban/*). Colunas padrão: backlog → afazer → andamento → revisao → concluido. Mover card = PATCH /api/v2/kanban/tarefas/{id}/mover.
• Scrum — tb_sprints + baia sprint_backlog (endpoints /api/v2/scrum/*). Estimativa de esforço só em Fibonacci (1,2,3,5,8,13,21…), inclusive no Planning Poker.
• Cada tarefa tem checklist, comentários (bate-papo), observadores, processo vinculado, histórico e impedimentos (/api/v2/scrum/tarefas/{id}/impedimento).

O ciclo se fecha em três planos paralelos:

O histórico permanece: tarefas concluídas/arquivadas seguem consultáveis pelo link compartilhável e pelos logs (tb_kanban_log, tb_datajud_pipeline_runs, safras tb_tarefas_auto_runs, e a auditoria geral em tb_logs_usuario — um middleware registra toda requisição POST/PUT/PATCH/DELETE), e o processo continua na família radar para fins de indicadores e cadernos.