mirror of
https://github.com/hoshikawa2/compass_backoffice.git
synced 2026-07-09 22:04:20 +00:00
98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
# 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.
|