bugfixes

docs/BACKOFFICE_REST_AS_CHANNEL_ARCHITECTURE.md

@@ -0,0 +1,97 @@
+# Backoffice REST as a Framework Channel
+
+This project now treats the TIM/ANATEL Backoffice REST contracts as a corporate channel instead of letting the HTTP routes call a domain workflow executor directly.
+
+## Target execution model
+
+```text
+Legacy-compatible REST endpoint
+        ↓
+BackofficeRestChannelAdapter
+        ↓
+ChannelGateway normalization path
+        ↓
+BackofficeWorkflowDispatcher
+        ↓
+Backoffice workflow LangGraph
+        ↓
+Framework layers: guardrails, supervisor, judges, checkpoint, telemetry, MCP
+        ↓
+Legacy-compatible REST response adapter
+```
+
+## What changed
+
+### New files
+
+- `app/channels/backoffice_rest_adapter.py`
+  - Converts legacy Backoffice REST payloads into `BackofficeChannelEnvelope`.
+  - Preserves the original payload under `request_context`.
+  - Extracts canonical `business_context` such as `customer_key`, `contract_key`, `interaction_key` and `session_key`.
+  - Passes the request through `ChannelGateway.normalize(...)` using `channel = backoffice_rest`.
+  - Falls back to the web adapter shape when the installed framework does not yet have a dedicated `backoffice_rest` adapter.
+
+- `app/workflows/backoffice_workflow_dispatcher.py`
+  - Receives a normalized channel envelope.
+  - Emits framework telemetry events for channel normalization and workflow dispatch.
+  - Invokes the correct operational workflow:
+    - `backoffice_checklist`
+    - `backoffice_response_emulator`
+
+### Updated file
+
+- `app/main.py`
+  - The compatibility routes no longer call `BackofficeWorkflowExecutor.execute_workflow(...)` directly.
+  - They now call:
+
+```python
+BackofficeRestChannelAdapter
+        ↓
+BackofficeWorkflowDispatcher
+        ↓
+BackofficeWorkflowExecutor
+```
+
+The `BackofficeWorkflowExecutor` still owns the compiled LangGraph workflows, but it is now behind the channel/dispatcher boundary rather than being the direct REST entrypoint.
+
+## Why this is architecturally cleaner
+
+The REST routes are now only transport adapters. They preserve the old external contract, but the request enters the same conceptual pipeline used by other framework channels.
+
+This avoids the previous coupling:
+
+```text
+REST route → BackofficeWorkflowExecutor
+```
+
+and replaces it with:
+
+```text
+REST route → channel adapter → ChannelGateway → workflow dispatcher → LangGraph workflow
+```
+
+## Compatibility
+
+The existing routes remain available:
+
+- `POST /agent/process-ticket`
+- `POST /agent/execute`
+- `POST /agent/process-and-stream`
+- `POST /case/{transaction_id}/response-emulator/generate`
+- `POST /case/{transaction_id}/response-emulator/finalize`
+
+The response builders are preserved, so external clients should not need to change their payload or response handling.
+
+## Runtime notes
+
+The metadata added to workflow state now includes:
+
+```text
+framework_entrypoint = channel_gateway
+channel = backoffice_rest
+normalized_channel = backoffice_rest or web fallback
+business_context = canonical business keys
+channel_context = normalized gateway context
+```
+
+This makes Langfuse/telemetry easier to interpret because Backoffice REST is visible as a channel entrypoint, not as an ad-hoc executor call.