docs/FLUXOGRAMA.md

# 📊 FLUXOGRAMA.md — Para.AI Assuntos Jurídicos
**Fluxo de dados nas pesquisas disponíveis**

---

## Fluxo 1 — GET /busca (full-text)

```
Cliente
  │  GET /busca?q=aposentadoria&ramo=DIREITO+PREVIDENCIÁRIO&size=10
  ▼
routes.busca_get()
  │  valida Query params via FastAPI/Pydantic
  ▼
es_client.buscar(q, ramo, nivel2, nivel3, lei, page, size, com_facets)
  │
  ├─ build_busca_query()
  │    multi_match:
  │      query: "aposentadoria"
  │      fields: [nome_assunto^4, titulo_curto^3, breve_sintese^2,
  │               glossario, classes_path^2, texto_completo]
  │      fuzziness: AUTO · prefix_length: 2
  │    filter: [term{ramo: "DIREITO PREVIDENCIÁRIO"}]
  │    highlight: [nome_assunto, titulo_curto, breve_sintese]
  │    _source.excludes: [texto_completo]
  │    aggs: {por_ramo, por_nivel2, por_nivel3, por_lei, profundidades}
  │    from: 0 · size: 10
  │
  ▼
Elasticsearch 8.12
  │  Analyzer juridico_pt: tokenize → lowercase → asciifolding → stem PT
  │  BM25 scoring com boosts
  │  Agregações bucket
  ▼
builders.build_busca_response(raw, took_ms, page, size)
  │  hits → AssuntoHit(score, Assunto(**src))
  │  highlight injetado em breve_sintese
  │  aggs → Facets(por_ramo, por_nivel2 …)
  ▼
BuscaResponse {total, pagina, tamanho, took_ms, resultados[], facets}
  │  ORJSONResponse
  ▼
Cliente recebe JSON
```

---

## Fluxo 2 — POST /busca-q (estruturada para LLMs)

```
LLM / Cliente
  │  POST /busca-q
  │  {q, campos:[{campo,valor}…], modo, topk, operador, retornar[]}
  ▼
routes.busca_q_post()
  │  valida BuscaQRequest (Pydantic)
  │  valida retornar[] ∈ FICHA_CAMPOS_VALIDOS
  ▼
es_client.busca_q(q, campos, modo, topk, operador, …, retornar)
  │
  ├─ _ficha_to_es_source(retornar, incluir_texto_completo)
  │    retornar=[]  → {"excludes":["texto_completo"]}
  │    retornar=[…] → {"includes":[campos_es mapeados]}
  │    "texto" em retornar OR incluir_texto_completo=True
  │              → inclui texto_completo
  │
  ├─ build_busca_q_query(q, campos, modo, topk, …)
  │    must:   multi_match(q) com pesos
  │    should: _clausula_campo(campo, valor, modo) × N
  │      fuzzy  → match com fuzziness AUTO
  │      exato  → term (keyword)
  │    minimum_should_match: 1 (or) | N (and)
  │    _source: ← _ficha_to_es_source()
  │    size: topk
  │
  ▼
Elasticsearch 8.12
  │  score combinado: must (q) + should (campos)
  │  retorna apenas campos _source solicitados
  ▼
builders.build_busca_q_response(raw, …, retornar)
  │  hits → FichaHit(score, campos_matched, _src_to_ficha())
  │
  │  _src_to_ficha():   ← FIX #1 aplicado aqui
  │    want = set(retornar)|{"id"} se retornar else None
  │    _want(campo) = True se want is None OR campo in want
  │    titulo      ← hl("titulo",       "nome_assunto")
  │    introducao  ← hl("introducao",   "breve_sintese")
  │    definicao   ← hl("definicao",    "glossario")
  │    normas      ← src["dispositivos_legais"]
  │    texto       ← src["texto_completo"]
  │                  SE (incluir_texto OR
  │                      (want is not None AND "texto" in want))
  │
  ▼
BuscaQResponse {total, retornados, took_ms, modo, operador, resultados[]}
  │  payload compacto (~2KB)  ← ideal para LLMs
  ▼
LLM recebe fichas estruturadas
```

---

## Fluxo 3 — GET /autocomplete

```
Interface (digitação)
  │  GET /autocomplete?q=aposen&size=8
  ▼
routes.autocomplete()
  ▼
es_client.autocomplete(q, size)
  │
  ├─ build_autocomplete_query("aposen", 8)
  │    _source: [nome_assunto, titulo_curto, ramo, classes_nivel2]
  │    bool.should:
  │      match{nome_assunto.autocomplete: "aposen", boost:2}
  │      match{titulo_curto.autocomplete: "aposen",  boost:1}
  │
  ▼
Elasticsearch
  │  Tokenizer edge_ngram: min_gram=2, max_gram=20
  │  "aposentadoria" → ["ap","apo","apos","aposen","aposent",…]
  │  Match: docs cujo prefixo == "aposen"
  │  Rank: boost nome_assunto > titulo_curto
  ▼
Deduplicação (set) + prioriza nome_assunto
  ▼
AutocompleteResponse {sugestoes: ["Aposentadoria", "Aposentadoria Especial", …]}
```

---

## Fluxo 4 — GET /hierarquia

```
Cliente
  │  GET /hierarquia
  ▼
routes.hierarquia()
  ▼
es_client.get_hierarquia()
  │
  ├─ Query ES:
  │    size: 0  (sem hits, só agregações)
  │    aggs:
  │      ramos: terms{classes_nivel1, size:25}
  │        nivel2: terms{classes_nivel2, size:30}
  │          nivel3: terms{classes_nivel3, size:30}
  │
  ▼
Elasticsearch — aggregations aninhadas
  ▼
builders.build_hierarquia_response(raw)
  │  ramos_buckets → HierarquiaNo(nome, caminho, total, filhos[])
  │  Para cada ramo → para cada nivel2 → para cada nivel3
  │  Recursão: filhos aninhados
  ▼
HierarquiaResponse {ramos: [HierarquiaNo{nome, caminho, total, filhos[…]}]}
```

---

## Fluxo 5 — GET /grafo/filhos (drill-down)

```
Cliente
  │  GET /grafo/filhos?ancestor=Crimes+contra+o+Patrimônio&size=20
  ▼
routes.drill_down(ancestor, size)
  ▼
es_client.drill_down(ancestor, size)
  │
  ├─ Query ES:
  │    size: 20
  │    _source.excludes: [texto_completo, glossario]
  │    query: term{classes_ancestors: "Crimes contra o Patrimônio"}
  │
  ▼
Elasticsearch — filtra por campo classes_ancestors (keyword array)
  ▼
{ancestor, total, filhos:[_source dos hits]}
```

---

## Fluxo 6 — Inicialização do Sistema

```
docker-compose up
  ▼
Container app: entrypoint.sh
  │  1. Loop: curl http://elasticsearch:9200/_cluster/health
  │            Aguarda status ≠ red (retry até 60s)
  │  2. Download:
  │      curl -L https://github.com/…/bulk_assuntos.ndjson
  │           -o /app/data/bulk_assuntos.ndjson
  │  3. exec uvicorn app.main:app
  ▼
FastAPI lifespan (main.py)
  │  await es_client.setup_es()
  │    wait_for_es()  ← tenacity retry 10x
  │    Índice existe?
  │      NÃO → create_index() → bulk_index()
  │      SIM → count()
  │        count == 0 → bulk_index()
  │        count > 0  → skip (já indexado)
  ▼
bulk_index()
  │  _iter_bulk_docs(): lê NDJSON, 2 linhas por doc
  │  async_streaming_bulk(chunk_size=500)
  │  Log: "5.184 documentos indexados"
  ▼
API pronta — porta 8000
```

---

*Última atualização: 24/02/2026 · v1.0.0*