refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization, test coverage

- API versioning: all REST endpoints prefixed with /api/v1/
- Structured logging: replaced stdlib logging with structlog (console/JSON modes)
- Alembic migrations: versioned DB schema with initial migration
- Error standardization: global exception handlers for consistent envelope format
- Interrupt cleanup: asyncio background task for expired interrupt removal
- Integration tests: +30 tests (analytics, replay, openapi, error, session APIs)
- Frontend tests: +57 tests (all components, pages, useWebSocket hook)
- Backend: 557 tests, 89.75% coverage | Frontend: 80 tests, 16 test files

docs/ARCHITECTURE.md

@@ -99,7 +99,12 @@ smart-support/
 ├── backend/
 │   ├── app/
 │   │   ├── main.py              # FastAPI + WebSocket 入口
-│   │   ├── graph.py             # LangGraph Supervisor 配置
+│   │   ├── graph.py             # LangGraph Supervisor 构建
+│   │   ├── graph_context.py     # GraphContext: 图 + 分类器 + 注册表的类型化封装
+│   │   ├── ws_handler.py        # WebSocket 消息分发 + 速率限制
+│   │   ├── ws_context.py        # WebSocketContext: WS 依赖包
+│   │   ├── auth.py              # API Key 认证中间件
+│   │   ├── api_utils.py         # 共享 API 响应工具 (envelope)
 │   │   ├── agents/              # Agent 定义 + 工具绑定
 │   │   ├── registry.py          # YAML Agent 注册表加载器
 │   │   ├── openapi/             # OpenAPI 解析 + MCP 服务器生成
@@ -139,7 +144,11 @@ smart-support/
 | 模块 | 职责 |
 |------|------|
 | main.py | 应用入口, WebSocket 端点, 静态文件服务 |
-| WebSocket Handler | 双向通信: 接收用户消息, 流式返回 token, 处理 interrupt 响应 |
+| auth.py | API Key 认证: 管理端点通过 `X-API-Key` header, WebSocket 通过 `?token=` query param |
+| ws_handler.py | 双向通信: 接收用户消息, 流式返回 token, 处理 interrupt 响应 |
+| graph_context.py | 类型化封装: 将编译后的图与分类器、注册表绑定, 替代猴子补丁 |
+| ws_context.py | 依赖包: 将 WebSocket 处理所需的 9 个依赖打包为单一不可变对象 |
+| api_utils.py | 共享响应格式: 统一的 `envelope()` 函数 |
 
 ### 2.3 Agent 编排层 (LangGraph)
 
@@ -427,6 +436,19 @@ CREATE INDEX idx_interrupts_ttl ON interrupts(ttl_expires_at)
     WHERE status = 'pending';
 ```
 
+#### sessions (自定义 - 会话状态持久化)
+
+```sql
+-- 用于多 worker 部署的 PostgreSQL 会话状态管理
+-- PgSessionManager 使用此表替代内存中的 dict
+CREATE TABLE sessions (
+    thread_id               TEXT PRIMARY KEY,
+    last_activity           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    has_pending_interrupt   BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at              TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
 #### analytics_events (自定义 - 分析事件流)
 
 ```sql