first commit

README_BACKOFFICE_FRAMEWORK_NATIVE_100.md

@@ -0,0 +1,77 @@
+# Backoffice TIM/ANATEL convertido 100% para o framework
+
+Esta versão substitui a execução direta dos grafos legados por workflows compilados pelo runtime do framework.
+
+## Princípio aplicado
+
+- O framework é dono do motor de workflow/LangGraph, checkpoint, telemetry, guardrails, judges, supervisor e persistência de execução.
+- O backend fornece apenas customizações de domínio: nós, services/clients, prompts, schemas e contratos REST.
+- Os contratos REST antigos continuam existindo, mas agora são adapters finos para `BackofficeNativeRuntime.execute_workflow(...)`.
+
+## O que foi removido do caminho ativo
+
+Os seguintes módulos do develop foram movidos para referência e não são mais importáveis pelo backend ativo:
+
+- `src/agent/graphs/*`
+- `src/api/executors/*`
+- `src/api/routes/*`
+- `src/api/main.py`
+
+Eles ficam em:
+
+```text
+legacy_reference_disabled/original_develop/
+```
+
+## Runtime ativo
+
+```text
+app/workflows/backoffice_native_runtime.py
+```
+
+Esse runtime monta dois workflows com o motor do framework:
+
+```text
+backoffice_checklist
+backoffice_response_emulator
+```
+
+Cada workflow inclui os nós de domínio do backoffice original, mas cercados por etapas do framework:
+
+```text
+framework_input_guardrails
+...
+framework_output_supervisor
+framework_output_guardrails
+framework_judges
+framework_supervisor_review
+framework_persist
+```
+
+## Rotas preservadas como adapters framework-native
+
+```text
+POST /agent/process-ticket
+POST /agent/execute
+POST /agent/process-and-stream
+POST /agent/search-tais-kb
+POST /case/{transaction_id}/response-emulator/generate
+POST /case/{transaction_id}/response-emulator/finalize
+GET  /case/{transaction_id}/response-emulator
+POST /emulator-rag/search
+GET  /health/live
+GET  /health/ready
+```
+
+## Validação estrutural
+
+Execute:
+
+```bash
+python tools/validate_parity.py
+python -m compileall -q app src tools
+```
+
+## Observação
+
+Esta entrega valida a estrutura e compilação Python. Teste funcional ponta-a-ponta ainda depende de serviços TIM/OCI/DB/VPN e variáveis reais.