feat: unifica pipeline de ingestao (S2-01/02/06/17), corrige bugs reais e adiciona observabilidade

.env.example

@@ -22,6 +22,12 @@ N8N_ENCRYPTION_KEY=sinapse-shared-dev-encryption-key-2026
 # ATENÇÃO: NUNCA comite a chave real no repositório!
 N8N_API_KEY=
 
+# Token compartilhado entre n8n e backend para o endpoint server-to-server
+# POST /api/v1/projects/:p/documents/:d/chunks (pipeline de ingestão de documentos).
+# No n8n: configure a credencial "Header Auth" com Name=Authorization,
+# Value="Bearer <este valor>". Em produção, troque por um segredo aleatório.
+N8N_INGEST_TOKEN=sinapse-dev-ingest-token
+
 # --- Runtime de IA e Embeddings Locais (Ollama) ---
 OLLAMA_PORT=11434
 OLLAMA_BASE_URL=http://localhost:11434
@@ -37,24 +43,50 @@ OLLAMA_EMBEDDING_MODEL=bge-m3
 OLLAMA_KEEP_ALIVE=24h
 # URL do serviço RepoAnalyzer quando o backend roda em Docker Compose.
 REPO_ANALYZER_URL=http://ai-service:8000
+# Segredo para o backend autorizar chamadas internas ao endpoint de ingestão de documentos.
+# Gere um segredo privado com: openssl rand -hex 32
+DOCUMENT_INGESTION_TOKEN=
+# Similaridade coseno mínima para aceitar candidatos encontrados somente pelo vetor; calibrar com a bateria S2-17.
+SEARCH_MIN_VECTOR_SIMILARITY=0.55
+# Ranking textual mínimo para retornar correspondências full-text; calibrar com S2-17.
+SEARCH_MIN_TEXT_RANK=0.05
 # Limite de arquivos priorizados nos perfis do RepoAnalyzer (Complete usa MAX_FILES).
 ANALYZER_QUICK_FILES=8
 ANALYZER_BALANCED_FILES=80
 # Limite rígido de arquivos elegíveis inventariados pelo RepoAnalyzer.
 MAX_FILES=1000
+ANALYZER_MAX_ACTIVE_RUNS=2
+ANALYZER_MAX_QUEUED_RUNS=6
+ANALYZER_WORKSPACE_QUOTA_MB=2048
+MAX_REPO_SIZE_MB=300
+ANALYZER_CLONE_MEMORY_MB=512
+ANALYZER_CLONE_TIMEOUT_SECONDS=300
 
 # --- Documentos enviados (S1-19/S1-22) ---
 # Limite de tamanho por arquivo, aplicado no backend e informado ao cliente
 DOCUMENT_MAX_SIZE_MB=20
-# Webhook do n8n que recebe o evento document.removed (vazio mantém o evento pendente)
-DOCUMENT_EVENTS_WEBHOOK_URL=
+# Webhooks dos workflows n8n versionados; ative ambos antes de processar documentos.
+DOCUMENT_EVENTS_WEBHOOK_URL=http://n8n:5678/webhook/sinapse-document-removed
+DOCUMENT_INGEST_WEBHOOK_URL=http://n8n:5678/webhook/sinapse-ingest
 
 # --- Aplicações e Microsserviços ---
 BACKEND_PORT=3001
 FRONTEND_PORT=5173
 AI_SERVICE_PORT=8000
+# Endereço de bind da porta do ai-service no host (Docker DNS continua interno)
+AI_SERVICE_BIND=127.0.0.1
 
 # --- Configurações Regionais ---
 GENERIC_TIMEZONE=America/Sao_Paulo
 TZ=America/Sao_Paulo
 
+
+# Token compartilhado entre o backend Node e o ai-service Python (header
+# X-Service-Token). O compose exige esta variavel preenchida; sem valor o
+# `docker compose up` falha com "Configure AI_SERVICE_TOKEN in .env".
+#
+# Em DEV, o valor abaixo basta para subir a stack localmente. Em PROD,
+# rotacione para um segredo aleatorio (ex.:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# ) e NUNCA versione o valor real.
+AI_SERVICE_TOKEN=sinapse-dev-ai-service-token

.github/workflows/ci.yml

@@ -13,54 +13,6 @@ on:
       - develop
 
 jobs:
-  validate-seed:
-    name: Validate curated seed on PostgreSQL
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: pgvector/pgvector:pg16
-        env:
-          POSTGRES_USER: seed_test
-          POSTGRES_PASSWORD: seed_test_only
-          POSTGRES_DB: sinapse_seed_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U seed_test -d sinapse_seed_test"
-          --health-interval 5s --health-timeout 5s --health-retries 10
-    env:
-      NODE_ENV: test
-      POSTGRES_HOST: localhost
-      POSTGRES_PORT: 5432
-      POSTGRES_USER: seed_test
-      POSTGRES_PASSWORD: seed_test_only
-      POSTGRES_DB: sinapse_seed_test
-      SEED_TEST_DATABASE_URL: postgresql://seed_test:seed_test_only@localhost:5432/sinapse_seed_test
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-          cache-dependency-path: backend/package-lock.json
-      - run: npm ci
-        working-directory: backend
-      - name: Build backend scripts used by seed validation
-        run: npm run build
-        working-directory: backend
-      - run: npm run migrate
-        working-directory: backend
-      - run: npm run seed:validate
-        working-directory: backend
-      - run: npm run test:seed
-        working-directory: backend
-      - name: Test archive cascade on PostgreSQL
-        run: node --import tsx --test src/modules/projects/projects.archive.db.test.ts src/modules/projects/hierarchy-archive.db.test.ts src/modules/projects/projects.backlog-tree.db.test.ts src/database/migration-010.db.test.ts src/database/migration-011.db.test.ts src/database/migration-012.db.test.ts src/modules/documents/documents.repository.db.test.ts src/modules/chat/chat.repository.db.test.ts src/modules/backlog-search/backlog-search.db.test.ts src/modules/decisions/decisions.db.test.ts src/database/migration-013.db.test.ts
-        working-directory: backend
-        env:
-          ARCHIVE_TEST_DATABASE_URL: postgresql://seed_test:seed_test_only@localhost:5432/sinapse_seed_test
-          BACKLOG_TREE_TEST_DATABASE_URL: postgresql://seed_test:seed_test_only@localhost:5432/sinapse_seed_test
-
   validate-environment:
     name: Validate Workflows and Docker Setup
     runs-on: ubuntu-latest
@@ -86,7 +38,7 @@ jobs:
       - name: Validate Docker Compose configuration
         run: |
           cp .env.example .env
-          docker compose config --quiet
+          AI_SERVICE_TOKEN=ci-compose-validation-only DOCUMENT_INGESTION_TOKEN=ci-validation-placeholder-32-characters docker compose config --quiet
 
   validate-backend:
     name: Build & Typecheck Backend (Node.js)

.github/workflows/e2e.yml

@@ -45,6 +45,9 @@ jobs:
       POSTGRES_USER: e2e
       POSTGRES_PASSWORD: e2e_only
       POSTGRES_DB: sinapse_e2e_test
+      E2E_DATABASE_URL: postgresql://e2e:e2e_only@localhost:5432/sinapse_e2e_test
+      AI_SERVICE_URL: http://127.0.0.1:9
+      REPO_ANALYZER_URL: http://127.0.0.1:9
       E2E_API_URL: http://localhost:3001/api/v1
       E2E_APP_URL: http://localhost:5173
       E2E_CHROME_PATH: /usr/bin/google-chrome
@@ -65,7 +68,7 @@ jobs:
         run: |
           export DOCUMENT_STORAGE_DIR="$RUNNER_TEMP/documents"
           mkdir -p "$DOCUMENT_STORAGE_DIR"
-          (cd backend && nohup npx tsx src/index.ts > "$RUNNER_TEMP/backend.log" 2>&1 &)
+          (cd backend && nohup env NODE_ENV=test node --import tsx ../e2e/server.mts > "$RUNNER_TEMP/backend.log" 2>&1 &)
           (cd frontend && nohup npx vite --port 5173 --strictPort > "$RUNNER_TEMP/frontend.log" 2>&1 &)
           for i in $(seq 1 30); do
             curl -fs http://localhost:3001/health > /dev/null && curl -fs http://localhost:5173 > /dev/null && exit 0

.gitignore

@@ -67,6 +67,10 @@ n8n/local-files/*
 htmlcov/
 .pytest_cache/
 
+# Resultados de avaliação local da busca
+ai-service/evaluation/results/
+ai-service/test_workspace/
+
 # armazenamento local de documentos enviados
 backend/storage/
 storage/

IMPLEMENTACAO_PIPELINE_INGESTAO.md

@@ -0,0 +1,125 @@
+# Pipeline de ingestão de documentos — implementação e correções (S2-01/02/06/17)
+
+Relatório técnico consolidado do trabalho feito na branch
+`feature/s2-02-n8n.embedding`: unificação de três implementações paralelas
+(S2-02/n8n, S2-01/worker do Giovanni, S2-06/S2-17 da branch `codex`),
+correção dos bugs reais que impediam o pipeline de funcionar ponta a ponta,
+e a tela local de observabilidade que substitui o editor do n8n.
+
+Para o passo a passo de **como rodar e testar**, ver [`TESTE_INGESTAO.md`](TESTE_INGESTAO.md).
+Este documento aqui é o **porquê** e o **o quê**.
+
+## Arquitetura final
+
+```
+Upload (frontend, multipart/form-data)
+  → backend grava documento (status_processamento = 'pendente')
+  → DocumentIngestionWorker (tick a cada 15s) reivindica com lease
+  → POST ai-service:8000/documents/process
+      headers: X-Service-Token + X-Document-Ingestion-Token
+      body: { document_id, project_id, filename, content_base64 }
+  → ai-service extrai texto (PDF/DOCX/MD/TXT), faz chunking,
+    gera embeddings via Ollama (bge-m3, 1024 dimensões)
+  → backend persiste os chunks em `chunk` (vector(1024) + pgvector)
+    e marca o documento como 'processado' — tudo numa transação
+  → /admin/ingestion mostra o estado da fila em tempo real
+  → /api/v1/search faz busca híbrida (full-text + similaridade vetorial)
+```
+
+O workflow do n8n (`n8n/workflows/*.json`) deixou de ser o canal oficial.
+Ele continua versionado e funcional como **ferramenta de debug manual**
+(dispara via `curl`, dá pra acompanhar nó a nó no editor), mas o caminho
+real que roda em produção é só o worker acima — sem n8n no meio.
+
+## O que foi implementado
+
+### Unificação de três branches paralelas
+- **S2-02** (esta branch): pipeline original via webhook do n8n.
+- **S2-01** (`origin/s2-01-pipeline-assincrono-documentos`, Giovanni): worker
+  assíncrono com estados `pendente/processando/processado/falha`, lease,
+  retry e diagnóstico de erro.
+- **codex/s2-17-ptbr-search-evaluation** (PR #44): reimplementação de
+  S2-01/02 do zero + busca híbrida real (S2-06) + bateria de avaliação de
+  busca em português (S2-17).
+
+Mesclados nessa ordem (S2-01 → codex), resolvendo conflitos de arquitetura
+(ver commits `875b276` e `cd689ad`). Decisão de design: adotada a
+arquitetura "worker como canal canônico" da codex — o backend chama o
+ai-service direto, sem depender do n8n estar no ar.
+
+### Endpoints novos no ai-service
+- `POST /documents/process` — endpoint oficial (fluxo S2-01): recebe o
+  arquivo em base64, extrai texto conforme a extensão, faz chunking e
+  gera embeddings, tudo numa chamada. Autenticado com
+  `X-Document-Ingestion-Token` (mínimo 32 caracteres).
+- `POST /chunk` e `POST /embed` — endpoints de debug para o workflow do
+  n8n chamar passo a passo (chunking separado de embedding). Não fazem
+  parte do fluxo oficial.
+
+### Endpoint novo no backend
+- `POST /api/v1/projects/:projectId/documents/:documentId/chunks` —
+  recebe chunks já processados (usado pelo workflow do n8n em modo debug).
+  Autenticado com `Authorization: Bearer <N8N_INGEST_TOKEN>`, separado da
+  sessão de usuário humano.
+
+### Tela de observabilidade (`/admin/ingestion`)
+Como o n8n saiu do caminho principal, perdemos a visibilidade visual que o
+editor dava. Reconstruída dentro da aplicação:
+- `GET /api/v1/admin/ingestion` (backend) — snapshot agregado: contagens
+  por status, documentos ativos, falhas recentes.
+- `IngestionObservabilityView.tsx` (frontend) — 4 contadores grandes,
+  pipeline visual animado por documento (Recebido → Processando →
+  Indexado), seção de falhas com botão de reprocessar. Polling a cada 5s.
+
+### Bootstrap do admin local
+`backend/scripts/bootstrap-admin.mts` (`npm run bootstrap:admin`) — cria
+ou promove o usuário admin de teste (`admin@sinapse.local` / `Admin@123`),
+reaproveitando o `hashPassword()` real do backend. Resolve o impasse de
+"cadastro público só cria dev, promover a admin exige sessão de admin" sem
+precisar de SQL manual.
+
+### Setup nativo sem Docker Desktop/WSL2
+`backend/scripts/apply-native-no-vector.mjs` + seção dedicada em
+`TESTE_INGESTAO.md`: todo o pipeline (Postgres, Ollama, backend, frontend,
+ai-service) validado rodando nativo no Windows, sem Docker — útil para
+quem não tem WSL2 disponível.
+
+## Bugs encontrados e corrigidos
+
+| # | Sintoma | Causa raiz | Correção | Commit |
+|---|---|---|---|---|
+| 1 | Upload pela UI nunca disparava o n8n | Frontend mandava o arquivo como `application/octet-stream` cru; backend (após mudar pra multer) exige `multipart/form-data` | `uploadDocument` monta `FormData`; `apiRequest` não força `Content-Type` quando o body é `FormData` | `f657380` |
+| 2 | n8n recebia `401` em `/chunk` e `/embed` do ai-service | Workflow usava uma única credencial "Header Auth" pra dois endpoints com headers diferentes (`X-Service-Token` vs `Authorization: Bearer`) | Workflow lê os dois tokens direto de `$env.AI_SERVICE_TOKEN` / `$env.N8N_INGEST_TOKEN`, expostos no container do n8n — sem credencial manual na UI | `12530e8` |
+| 3 | n8n caía no nó "Payload inválido" mesmo com tudo configurado certo | **Dupla ingestão**: o backend chamava o webhook do n8n (payload camelCase) *e* o worker da S2-01 chamava o mesmo webhook via `DOCUMENT_INGEST_WEBHOOK_URL` (payload snake_case + base64) — o n8n só entendia um dos dois formatos | Removida a chamada direta do `documents.service.ts` ao n8n; só o worker dispara, e por padrão vai direto pro ai-service (`DOCUMENT_INGEST_WEBHOOK_URL` vazio) | `2b6d9e8` |
+| 4 | `docker compose up` falhava com `Configure AI_SERVICE_TOKEN/DOCUMENT_INGESTION_TOKEN in .env` | `.env.example` definia essas variáveis como obrigatórias (`:?`) mas as deixava vazias | Defaults de dev preenchidos no `.env.example`, com instrução de rotacionar em produção | `f74d640` |
+| 5 | Arquivo gravado pelo backend ficava ilegível para o container do n8n | Backend salvava com `mode: 0o600` (só o dono lê); container roda como root, n8n roda como usuário `node` (não-root) — sem pgvector/Docker isso nem chega a ser testado, mas quebra o modo debug via n8n | `writeFile` com `mode: 0o644` | `64e6f0d` |
+| 6 | **Todo documento falhava com `401` no ai-service**, mesmo com tokens corretos no `.env` | `HttpDocumentIngestionClient.process()` (worker oficial da S2-01, veio da branch codex) só mandava `X-Document-Ingestion-Token`; esqueceu `X-Service-Token`, exigido pelo middleware global do ai-service em *toda* rota — bug real, afeta Docker também, não só ambiente local | Usa o mesmo helper `serviceHeaders()` que `chat.service.ts`/`repo-analyses.service.ts` já usavam corretamente | `b1c7a60` |
+| 7 | Geração de embedding falhava/travava de forma intermitente (`wsarecv: conexão forçada a cancelar`) | **Específico de ambiente local**: duas instâncias de `ollama serve` concorrendo pela porta 11434 (o instalador do Ollama já sobe uma via app de bandeja) | Matar todas as instâncias e subir uma única com `OLLAMA_KEEP_ALIVE=24h` | documentado em `TESTE_INGESTAO.md` |
+
+Os bugs #1, #2, #3, #4, #5 e #6 afetam **qualquer ambiente** (Docker
+inclusive) — não são específicos de rodar sem Docker. O #7 é específico de
+quem roda Ollama nativo no Windows.
+
+## Limitações conhecidas
+
+- **pgvector não tem pacote nativo pro Windows.** Quem roda sem Docker
+  precisa do shim documentado em `TESTE_INGESTAO.md` (`real[]` no lugar de
+  `vector`, não commitável) — e mesmo assim a busca híbrida vetorial
+  (`/api/v1/search`) não funciona nesse modo, só o full-text. Com o
+  Docker do time (imagem `pgvector/pgvector:pg16`), tudo funciona normal.
+- O workflow do n8n em `n8n/workflows/` não é mais testado automaticamente
+  (sem CI cobrindo o fluxo de debug) — validação é manual, via `curl`,
+  quando necessário.
+
+## Como validar
+
+Ver [`TESTE_INGESTAO.md`](TESTE_INGESTAO.md) — cobre os dois modos (Docker
+e nativo), checklist de troubleshooting, e os comandos de avaliação da
+busca (S2-17).
+
+Verificação automatizada:
+```bash
+cd backend && npx tsc --noEmit && npm test       # 313/313
+cd frontend && npx tsc -b && npm test             # 210/210
+cd backend && npm run audit:security              # 0 vulnerabilidades
+```

README.md

@@ -63,6 +63,10 @@ A primeira sprint teve como objetivo construir a **base funcional do Sinapse** e
 
 📌 [Planejamento completo da Sprint](docs/PLANEJAMENTO_SCRUM.md)
 
+### 📍 Estado atual do trabalho
+
+A Sprint 1 foi concluída em **27/09/2026**. A Sprint 2 está planejada para **05/10 a 25/10/2026**. A implementação candidata de ingestão, busca e avaliação está em [PR de revisão](https://github.com/Galaticos-API/API-4/pull/44) e ainda não foi aceita: o baseline encontrou latência acima de 2 s e pendências de relevância (Q008 e Q022). Veja o [registro QA](docs/STATUS_REVISAO_2026-10-02.md) para evidências, limites e próximos passos.
+
 ---
 
 ## 🖥️ Conheça o Sinapse
@@ -229,6 +233,8 @@ Permite registrar decisões relacionadas aos elementos do projeto, mantendo o co
 
 Documentos podem ser associados aos projetos e posteriormente consultados ou removidos.
 
+📖 [Guia completo de upload de documentos](docs/DOCUMENT_UPLOAD.md)
+
 ---
 
 ### 👥 Usuários e permissões
@@ -289,6 +295,8 @@ cp .env.example .env
 
 ```powershell
 Copy-Item .env.example .env
+# Gere com: python -c "import secrets; print(secrets.token_hex(32))"
+# Cole o resultado na variável DOCUMENT_INGESTION_TOKEN dentro do arquivo .env
 ```
 
 ---
@@ -299,6 +307,8 @@ Copy-Item .env.example .env
 docker compose up --build -d
 ```
 
+O Compose exige esse segredo compartilhado pelo backend e pelo serviço local de IA; não há mais token padrão no código.
+
 Verifique os containers:
 
 ```bash
@@ -426,3 +436,8 @@ O **Sinapse** é um **Projeto de Aprendizagem Interdisciplinar (API)** desenvolv
 **Grupo Galáticos · Fatec São José dos Campos · 2026**
 
 </div>
+
+
+### Segredo da comunicação interna
+
+Antes de iniciar o Compose, configure `AI_SERVICE_TOKEN` em `.env` com um segredo aleatório (por exemplo, 32 bytes gerados com `crypto.randomBytes` do Node). Não versione o valor. O mesmo segredo é usado pelo backend e pelo serviço Python. A porta 8000 não é publicada; acessos ao Python passam pelo backend e pelo workflow autenticado descrito em [n8n/README.md](n8n/README.md).