vault: update Smart Support project -- v0.6.0, API v1, auth, structlog, architecture patterns

2 - Projects/Smart Support.md

@@ -1,8 +1,8 @@
 ---
 created: 2026-03-29
-updated: 2026-04-06
+updated: 2026-04-07
 type: project
-status: completed
+status: active
 deadline: ""
 tags:
   - ai-agent
@@ -48,11 +48,14 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 |
 | MCP | langchain-mcp-adapters | MultiServerMCPClient |
 | 数据库 | PostgreSQL 16 | Docker Compose 部署 |
-| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Google 切换 |
+| DB 迁移 | Alembic | 自动运行 migrations |
+| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Azure/Google 切换 |
 | 前端 | React 19 + TypeScript + Vite 6 | React Router 7.x |
-| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516 测试 92%+ 覆盖率 |
+| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516+ 测试 94%+ 覆盖率 |
 | 部署 | Docker Compose | PostgreSQL + FastAPI + nginx |
+| 日志 | structlog | 结构化日志（console/json 模式） |
 | 代码质量 | ruff 0.9+ | Python linting + formatting |
+| 认证 | API Key | `X-API-Key` header / `?token=` for WS |
 
 ## 核心特性
 
@@ -76,14 +79,15 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | COMPLETED (2026-03-30) | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
 | Phase 4 | 第 6-7 周 | 分析 + 回放 | COMPLETED (2026-03-31) | [[Smart Support/Phase 4 - 分析 + 回放]] |
 | Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] |
+| Post | 2026-04 | 架构修复 + 工程改进 | 进行中 | API v1 版本化、structlog、Alembic、认证、GraphContext/WebSocketContext |
 
 ## 项目数据
 
-- 后端测试：516 个（单元 ~400 + 集成 ~7 + E2E ~3）
+- 后端测试：516+ 个（单元 ~439 + 集成 ~51 + E2E ~26）
 - 前端测试：~23 个（vitest + happy-dom）
-- 代码覆盖率：92.88%
-- 应用版本：v0.5.0
-- Git 最新提交：`af53111` refactor: fix architectural issues
+- 代码覆盖率：~94%
+- 应用版本：v0.6.0
+- Git 最新提交：`f069943` refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization
 
 ## 目标用户
 
@@ -99,28 +103,36 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 
 客户端 -> 服务器：
 - `{"type": "message", "thread_id": "...", "content": "..."}`
-- `{"type": "interrupt_response", "thread_id": "...", "interrupt_id": "...", "approved": true/false}`
+- `{"type": "interrupt_response", "thread_id": "...", "approved": true/false}`
 
-服务器 -> 客户端：
-- `{"type": "token", "thread_id": "...", "content": "..."}` -- 流式 token
-- `{"type": "interrupt", ...}` -- 人工确认提示（含 TTL）
-- `{"type": "tool_call", ...}` / `{"type": "tool_result", ...}` -- 工具调用
-- `{"type": "message_complete", ...}` -- 消息完成
-- `{"type": "error", ...}` -- 错误
+服务器 -> 客户端（8 种消息类型）：
+- `{"type": "token", "agent": "...", "content": "..."}` -- 流式 token
+- `{"type": "interrupt", "thread_id": "...", "action": "...", "params": {...}}` -- 人工确认提示
+- `{"type": "clarification", "thread_id": "...", "message": "..."}` -- 意图模糊，请求澄清
+- `{"type": "interrupt_expired", "thread_id": "...", "action": "...", "message": "..."}` -- 审批超时
+- `{"type": "tool_call", "agent": "...", "tool": "...", "args": {...}}` -- 工具调用
+- `{"type": "tool_result", "agent": "...", "tool": "...", "result": ...}` -- 工具返回
+- `{"type": "message_complete", "thread_id": "..."}` -- 消息完成
+- `{"type": "error", "message": "..."}` -- 错误
+
+WebSocket 连接需 `?token=<ADMIN_API_KEY>` 认证（未配置 key 时跳过）。
 
 ## REST API
 
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| WS | `/ws` | WebSocket 聊天 |
-| GET | `/api/health` | 健康检查 |
-| GET | `/api/conversations` | 对话列表（分页） |
-| GET | `/api/replay/{thread_id}` | 回放时间线（分页，默认 20 步） |
-| GET | `/api/analytics?range=7d` | 分析摘要（1d/7d/30d/90d） |
-| POST | `/api/openapi/import` | 开始 OpenAPI 导入 |
-| GET | `/api/openapi/jobs/{id}` | 导入任务状态 |
-| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | 修改端点分类 |
-| POST | `/api/openapi/jobs/{id}/approve` | 审核通过，生成工具 |
+所有端点使用 `/api/v1/` 前缀。管理端点需 `X-API-Key` header（`ADMIN_API_KEY` 未配置时跳过认证）。
+
+| 方法 | 路径 | 认证 | 说明 |
+|------|------|------|------|
+| WS | `/ws` | Token | WebSocket 聊天（`?token=<key>`） |
+| GET | `/api/v1/health` | 无 | 健康检查 |
+| GET | `/api/v1/conversations` | API Key | 对话列表（分页） |
+| GET | `/api/v1/replay/{thread_id}` | API Key | 回放时间线（分页） |
+| GET | `/api/v1/analytics?range=7d` | API Key | 分析摘要 |
+| POST | `/api/v1/openapi/import` | API Key | 开始 OpenAPI 导入 |
+| GET | `/api/v1/openapi/jobs/{id}` | API Key | 导入任务状态 |
+| GET | `/api/v1/openapi/jobs/{id}/classifications` | API Key | 获取端点分类 |
+| PUT | `/api/v1/openapi/jobs/{id}/classifications/{idx}` | API Key | 修改端点分类 |
+| POST | `/api/v1/openapi/jobs/{id}/approve` | API Key | 审核通过，生成工具代码 + Agent YAML |
 
 ## 数据库表
 
@@ -129,9 +141,12 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | checkpoints | LangGraph 状态快照（自动管理） |
 | checkpoint_writes | 检查点写入记录 |
 | conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） |
-| interrupts | 人工确认记录（pending/approved/rejected/expired） |
+| active_interrupts | 人工确认记录（interrupt_id, action, params, resolved_at） |
+| sessions | 会话状态持久化（last_activity, has_pending_interrupt），供 PgSessionManager 使用 |
 | analytics_events | 分析事件流（事件类型、Agent、工具、Token、成本、耗时） |
 
+数据库迁移通过 Alembic 管理，应用启动时自动执行 `run_alembic_migrations()`。
+
 ## 架构决策（ADR）
 
 | ADR | 决策 | 理由 |
@@ -166,26 +181,39 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 
 ```
 backend/app/
-  main.py              -- FastAPI 入口 (v0.5.0)
-  config.py            -- Pydantic Settings
-  db.py                -- AsyncPostgreSQL + AsyncPostgresSaver
-  llm.py               -- LLM 提供商工厂（Anthropic/OpenAI/Google）
-  graph.py             -- LangGraph Supervisor 构建
+  main.py              -- FastAPI 入口 (v0.6.0), 全局异常处理, 中断清理循环
+  config.py            -- Pydantic Settings（含 admin_api_key, log_format）
+  db.py                -- AsyncPostgreSQL + AsyncPostgresSaver + Alembic runner
+  llm.py               -- LLM 提供商工厂（Anthropic/OpenAI/Azure/Google）
+  graph.py             -- LangGraph Supervisor 构建，返回 GraphContext
+  graph_context.py     -- GraphContext: 图 + 分类器 + 注册表的类型化封装
   ws_handler.py        -- WebSocket 消息分发 + 流式 + 速率限制
+  ws_context.py        -- WebSocketContext: WS 处理依赖打包
+  auth.py              -- API Key 认证中间件（X-API-Key / ?token= for WS）
+  api_utils.py         -- 共享 envelope() 响应格式
+  logging_config.py    -- structlog 配置（console/json）
   registry.py          -- YAML Agent 注册表 + 模板支持
   intent.py            -- LLM 意图分类器
-  session_manager.py   -- Session TTL（30m 滑动窗口）
-  interrupt_manager.py -- 中断 TTL 追踪 + 自动取消
+  session_manager.py   -- Session TTL（30m 滑动窗口）+ PgSessionManager
+  interrupt_manager.py -- 中断 TTL 追踪 + 自动取消 + PgInterruptManager
   escalation.py        -- Webhook 升级（指数退避）
   conversation_tracker.py -- 对话生命周期追踪
   callbacks.py         -- Token 用量回调
+  safety.py            -- 确认策略规则 + MCP 错误分类
   agents/              -- Agent 定义（order_lookup, order_actions, discount, fallback）
-  openapi/             -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator）
+  openapi/             -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator, review_api）
   replay/              -- 回放模型 + 转换器 + API
   analytics/           -- 分析模型 + 事件记录 + 查询 + API
-  tools/               -- 错误处理（ErrorCategory, classify_error, with_retry）
 ```
 
+### 架构模式
+
+- **Protocol 接口**：所有跨模块边界使用 Protocol（SessionManagerProtocol, InterruptManagerProtocol 等）
+- **Frozen dataclasses**：GraphContext, WebSocketContext, SessionState, InterruptRecord 等全部不可变
+- **Composition Root**：main.py lifespan() 统一组装所有依赖
+- **Envelope 响应**：`{"success": bool, "data": T, "error": str | null}` 统一格式
+- **双实现状态管理**：内存版（开发）+ PostgreSQL 版（生产多 Worker）
+
 ## 计划文档
 
 项目根目录下：
@@ -235,12 +263,18 @@ cd ../frontend && npm test
 
 ## 已知技术债务
 
-- [ ] 认证/授权系统（生产部署前）
+- [x] ~~认证/授权系统~~ -- 已实现 API Key 认证（`auth.py`，`ADMIN_API_KEY`）
+- [x] ~~中断清理未定时调度~~ -- 已实现 `_interrupt_cleanup_loop` 后台任务（60s 间隔）
+- [x] ~~猴子补丁~~ -- 已替换为 GraphContext 类型化封装
+- [x] ~~dispatch_message 参数膨胀~~ -- 已替换为 WebSocketContext
+- [x] ~~_envelope 重复定义~~ -- 已提取到 api_utils.py
+- [x] ~~前端缺失消息类型~~ -- 已添加 clarification/interrupt_expired/tool_result 处理
 - [ ] 多租户架构（第一个付费客户后）
 - [ ] CI/CD 流水线（原型阶段手动部署）
 - [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis
-- [ ] 中断清理未定时调度（cleanup_expired 存在但未触发）
-- [ ] NoOpAnalyticsRecorder 已注册 -- PostgresAnalyticsRecorder 集成待完善
+- [ ] 生产环境切换到 PgSessionManager/PgInterruptManager
+- [ ] OpenAPI approve 后的工具尚未运行时注入到 _TOOL_MAP（仅生成代码 + YAML）
+- [ ] SSRF DNS 重绑定 TOCTOU 窗口（实践中利用难度大）
 - [ ] SaaS/Fintech 模板工具仅为桩（无实现）
 - [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST