148 lines
7.6 KiB
Markdown
148 lines
7.6 KiB
Markdown
---
|
|
phase: 06-web-chat
|
|
plan: 01
|
|
subsystem: backend
|
|
tags: [web-chat, websocket, redis-pubsub, rbac, orm, migration]
|
|
dependency_graph:
|
|
requires: []
|
|
provides:
|
|
- WebSocket endpoint at /chat/ws/{conversation_id}
|
|
- REST API at /api/portal/chat/* for conversation CRUD
|
|
- web_conversations and web_conversation_messages tables with RLS
|
|
- Redis pub-sub response delivery for web channel
|
|
- ChannelType.WEB in shared message model
|
|
affects:
|
|
- packages/orchestrator/orchestrator/tasks.py (new web channel routing)
|
|
- packages/shared/shared/api/__init__.py (chat_router added)
|
|
- packages/gateway/gateway/main.py (Phase 6 routers mounted)
|
|
tech_stack:
|
|
added:
|
|
- gateway/channels/web.py (FastAPI WebSocket + normalize_web_event)
|
|
- shared/api/chat.py (conversation CRUD REST API)
|
|
- shared/models/chat.py (WebConversation + WebConversationMessage ORM)
|
|
- migrations/versions/008_web_chat.py (DB tables + RLS + CHECK constraint update)
|
|
patterns:
|
|
- WebSocket auth via first JSON message (browser cannot send custom headers)
|
|
- Redis pub-sub for async response delivery from Celery to WebSocket
|
|
- thread_id = conversation_id for agent memory scoping
|
|
- try/finally around all Redis connections to prevent leaks
|
|
- TEXT+CHECK for role column (not sa.Enum) per Phase 1 ADR
|
|
- SQLAlchemy 2.0 Mapped[]/mapped_column() style
|
|
- require_tenant_member RBAC guard on all REST endpoints
|
|
key_files:
|
|
created:
|
|
- packages/gateway/gateway/channels/web.py
|
|
- packages/shared/shared/api/chat.py
|
|
- packages/shared/shared/models/chat.py
|
|
- migrations/versions/008_web_chat.py
|
|
- tests/unit/test_web_channel.py
|
|
- tests/unit/test_chat_api.py
|
|
modified:
|
|
- packages/shared/shared/models/message.py (ChannelType.WEB added)
|
|
- packages/shared/shared/redis_keys.py (webchat_response_key added)
|
|
- packages/shared/shared/api/__init__.py (chat_router exported)
|
|
- packages/gateway/gateway/main.py (Phase 6 routers mounted)
|
|
- packages/orchestrator/orchestrator/tasks.py (web channel extras + routing)
|
|
decisions:
|
|
- "WebSocket auth via first JSON message after connection — browser WebSocket API cannot send custom HTTP headers"
|
|
- "thread_id = conversation_id in normalize_web_event — scopes agent memory to one web conversation (consistent with WhatsApp wa_id scoping)"
|
|
- "Redis pub-sub response delivery: orchestrator publishes to webchat_response_key, WebSocket handler subscribes with 60s timeout"
|
|
- "TEXT+CHECK for role column ('user'/'assistant') per Phase 1 ADR — not sa.Enum"
|
|
- "dependency_overrides used in tests instead of patching shared.db.get_session — FastAPI dependency injection doesn't follow module-level patches"
|
|
metrics:
|
|
duration: "~8 minutes"
|
|
completed_date: "2026-03-25"
|
|
tasks_completed: 2
|
|
files_created: 6
|
|
files_modified: 5
|
|
---
|
|
|
|
# Phase 6 Plan 01: Web Chat Backend Infrastructure Summary
|
|
|
|
**One-liner:** WebSocket endpoint + Redis pub-sub response bridge + RBAC REST API providing complete web chat plumbing from portal UI to the agent pipeline.
|
|
|
|
## What Was Built
|
|
|
|
This plan establishes the complete backend for web chat — the "web" channel that lets portal users talk to AI employees directly from the Konstruct portal UI without setting up Slack or WhatsApp.
|
|
|
|
### ChannelType.WEB and Redis key
|
|
`ChannelType.WEB = "web"` added to the shared message model. `webchat_response_key(tenant_id, conversation_id)` added to `redis_keys.py` following the established namespace pattern (`{tenant_id}:webchat:response:{conversation_id}`).
|
|
|
|
### DB Schema (migration 008)
|
|
Two new tables with FORCE ROW LEVEL SECURITY:
|
|
- `web_conversations` — one per (tenant_id, agent_id, user_id) triple with UniqueConstraint for get-or-create semantics
|
|
- `web_conversation_messages` — individual messages with TEXT+CHECK role column ('user'/'assistant') and CASCADE delete
|
|
- `channel_connections.channel_type` CHECK constraint replaced to include 'web'
|
|
|
|
### WebSocket Endpoint (`/chat/ws/{conversation_id}`)
|
|
Full message lifecycle in `gateway/channels/web.py`:
|
|
1. Accept connection
|
|
2. Auth handshake via first JSON message (browser limitation)
|
|
3. For each message: typing indicator → save to DB → Celery dispatch → Redis subscribe → save response → send to client
|
|
4. try/finally cleanup on all Redis connections
|
|
|
|
### REST API (`/api/portal/chat/*`)
|
|
Four endpoints in `shared/api/chat.py`:
|
|
- `GET /conversations` — list with RBAC (platform_admin sees all, others see own)
|
|
- `POST /conversations` — get-or-create with IntegrityError race condition handling
|
|
- `GET /conversations/{id}/messages` — paginated history with cursor support
|
|
- `DELETE /conversations/{id}` — message reset keeping conversation row
|
|
|
|
### Orchestrator Integration
|
|
`tasks.py` updated:
|
|
- `handle_message` pops `conversation_id` and `portal_user_id` before `model_validate`
|
|
- `_build_response_extras` handles "web" case returning `{conversation_id, tenant_id}`
|
|
- `_send_response` handles "web" case with Redis pub-sub publish and try/finally cleanup
|
|
- `webchat_response_key` imported at module level
|
|
|
|
## Test Coverage
|
|
|
|
19 unit tests written (TDD, all passing):
|
|
|
|
| Test | Covers |
|
|
|------|--------|
|
|
| `test_webchat_response_key_format` | Key format correct |
|
|
| `test_webchat_response_key_isolation` | Tenant isolation |
|
|
| `test_channel_type_web_exists` | ChannelType.WEB |
|
|
| `test_normalize_web_event_*` (5 tests) | Message normalization CHAT-01 |
|
|
| `test_send_response_web_publishes_to_redis` | Redis pub-sub publish CHAT-02 |
|
|
| `test_send_response_web_connection_cleanup` | try/finally Redis cleanup |
|
|
| `test_send_response_web_missing_conversation_id_logs_warning` | Error handling |
|
|
| `test_typing_indicator_sent_before_dispatch` | Typing indicator CHAT-05 |
|
|
| `test_chat_rbac_enforcement` | 403 for non-member CHAT-04 |
|
|
| `test_platform_admin_cross_tenant` | Admin bypass CHAT-04 |
|
|
| `test_list_conversation_history` | Paginated messages CHAT-03 |
|
|
| `test_create_conversation` | Get-or-create CHAT-03 |
|
|
| `test_create_conversation_rbac_forbidden` | 403 for non-member |
|
|
| `test_delete_conversation_resets_messages` | Message reset |
|
|
|
|
Full 313-test suite passes.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Test dependency injection: patch vs dependency_overrides**
|
|
- **Found during:** Task 1 test implementation
|
|
- **Issue:** `patch("shared.db.get_session")` doesn't work for FastAPI endpoint testing because FastAPI's dependency injection resolves `Depends(get_session)` at function definition time, not via module attribute lookup
|
|
- **Fix:** Used `app.dependency_overrides[get_session] = _override_get_session` pattern in test helper `_make_app_with_session_override()` — consistent with other test files in the project
|
|
- **Files modified:** `tests/unit/test_chat_api.py`
|
|
|
|
**2. [Rule 2 - Missing functionality] session.refresh mock populating server defaults**
|
|
- **Found during:** Task 1 create_conversation test
|
|
- **Issue:** Mocked `session.refresh()` was a no-op, leaving `created_at`/`updated_at` as `None` on new ORM objects (server_default not applied without real DB)
|
|
- **Fix:** Test uses an async side_effect function that populates datetime fields on the object passed to `refresh()`
|
|
- **Files modified:** `tests/unit/test_chat_api.py`
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All key artifacts verified:
|
|
- `ChannelType.WEB = "web"` — present in message.py
|
|
- `webchat_response_key()` — present in redis_keys.py
|
|
- `WebConversation` ORM class — present in models/chat.py
|
|
- `chat_websocket` WebSocket endpoint — present in gateway/channels/web.py
|
|
- `chat_router` — exported from shared/api/__init__.py
|
|
- `web_conversations` table — created in migration 008
|
|
- Commits `c72beb9` and `56c11a0` — verified in git log
|
|
- 313/313 unit tests pass
|