docs/ROADMAP.md

# 🗺️ ROADMAP.md — Para.AI Assuntos Jurídicos
**Mapa de Desenvolvimento — Estado Atual e Plano Futuro**

---

## 📍 v1.0.0 — Fevereiro 2026 (ATUAL)

### Entregue

- [x] API REST completa (FastAPI 0.115)
- [x] Elasticsearch 8.12 — índice `assuntos_juridicos`
- [x] 5.184 assuntos jurídicos indexados (CNJ)
- [x] Analyzer customizado `juridico_pt` (stemmer PT + ASCII fold)
- [x] Edge n-gram tokenizer para autocomplete
- [x] 7 endpoints: `/busca`, `/busca-q`, `/autocomplete`,
      `/hierarquia`, `/grafo/filhos`, `/assuntos/{id}`, `/health`
- [x] Busca full-text com BM25 ponderado
- [x] Faceted search (agregações por ramo/nível/lei)
- [x] `/busca-q` com payload compacto para LLMs
- [x] Docker Compose (ES + API)
- [x] Entrypoint com auto-indexação
- [x] 13 testes HTTP (scripts/test_api.py)
- [x] **FIX #1**: `builders.py` — `retornar=['texto']` agora retorna
      `texto_completo` corretamente (**79/79 testes**)

### Métricas v1.0

| Métrica | Valor |
|---------|-------|
| Assuntos indexados | 5.184 |
| Ramos do Direito | 22 |
| Profundidade máxima | 5 níveis |
| Campos por documento | ~20 |
| Latência p50 `/busca` | ~800ms |
| Latência p50 `/busca-q` | ~74ms |
| Latência p50 `/autocomplete` | ~45ms |
| Testes passando | **79/79** |

---

## 🚀 v1.1 — Março 2026 — Otimização

### Prioridade Alta

- [ ] **Cache Redis** — query cache para `/busca` e `/busca-q`
  - TTL: 1h para queries, 24h para autocomplete
  - Target: p95 < 200ms
- [ ] **Rate limiting** — 1000 req/min por IP (sem auth)
- [ ] **Logs JSON estruturados** — request_id, latência por fase
- [ ] **Health check detalhado** — ES ping, contagem, latência

### Prioridade Média

- [ ] Export `/busca/export?fmt=csv` — CSV/JSON paginado
- [ ] Endpoint `/stats` — distribuição por ramo, top queries
- [ ] Testes de carga (Locust) — target 100 req/s estável
- [ ] CI/CD GitHub Actions — testes em PRs + deploy staging

### Prioridade Baixa

- [ ] Versionamento de API (`/v1/busca`)
- [ ] Changelog automático por commit
- [ ] Warm-up query no startup (eliminar cold start 2s)

**Meta v1.1:** p95 < 200ms · 99.5% uptime · 1.000 usuários/mês

---

## 🧠 v1.2 — Q2 2026 — Inteligência

- [ ] **Busca semântica** — embeddings + cosine similarity
  - Modelo: `neuralmind/bert-base-portuguese-cased` (candidato)
  - Hybrid search: BM25 + vector (RRF)
- [ ] **Dicionário de sinônimos jurídicos**
  - `BPC` ↔ `Benefício de Prestação Continuada`
  - `INSS` ↔ `Previdência Social`
  - `HC` ↔ `Habeas Corpus`
- [ ] **Endpoint `/classificar`**
  - Input: texto livre (petição, sentença)
  - Output: top-3 assuntos CNJ com score de confiança
- [ ] **Endpoint `/similar/{id}`** — "veja também"

**Meta v1.2:** 80% precisão na classificação automática · 5.000 usuários/mês

---

## 📈 v1.3 — Q3 2026 — Escala e Integração

- [ ] Cluster Elasticsearch 3 nós (HA)
- [ ] Integração com base de jurisprudência (acórdãos TJPR)
  - Endpoint `/jurisprudencia?assunto_id=...`
- [ ] Webhooks de atualização CNJ (quando taxonomia mudar)
- [ ] Admin endpoints com autenticação (JWT + API keys)
- [ ] Prometheus exporter + dashboard Grafana

**Meta v1.3:** 1.000 req/s · 10.000 usuários/mês · SLA 99.9%

---

## 🌍 v2.0 — 2027 — Expansão

- [ ] Multilíngue (EN, ES)
- [ ] Graph API — relações entre assuntos
- [ ] SDK oficial Python e TypeScript
- [ ] Mobile SDKs (React Native)
- [ ] Marketplace de integrações
- [ ] Plugin VS Code / Cursor

---

## 📋 Débitos Técnicos

| Item | Impacto | Sprint |
|------|---------|--------|
| Rate limiting ausente | ALTO (risco abuse) | v1.1 |
| Sem autenticação | ALTO (produção) | v1.1 |
| Logs não estruturados | MÉDIO | v1.1 |
| Sem métricas | MÉDIO | v1.1 |
| Cold start 2s | BAIXO | v1.1 |
| Sem testes unitários | MÉDIO | v1.2 |

---

## 📞 Feedback

Discussões: https://github.com/para-ai/discussions  
Email: roadmap@para-ai.com