Upload backend-to-frontdoor-spec-v6.md

backend-to-frontdoor-spec-v6.md

@@ -0,0 +1,265 @@
+# Спецификация: ChatService ↔ L1 Router Agent
+
+**Создано**: 2026-04-01
+**Статус**: Draft
+**Базовые документы**:
+- «Базовая схема работы ChatService бэкенда и агента L1 Router Agent»
+- «Sequence flows ChatService» (2026-03-30)
+
+---
+
+## 1. Назначение
+
+Описывает взаимодействие между ChatService (бэкенд модуля ИИ-агентов) и L1 Router Agent (входная точка мультиагентной системы). Описаны: формат вызовов, жизненный цикл чата и сообщений, runtime-binding, retry, cleanup.
+
+---
+
+## 2. Участники
+
+| Участник | Описание |
+|----------|----------|
+| **API Gateway** | Вход в backend-контур Space. Валидация JWT, rate limiting. |
+| **ChatService** | Бэкенд модуля ИИ-агентов. Хранит чаты, сообщения, feedback. Вызывает L1 Router Agent. |
+| **FeedbackService** | Хранилище истории, feedback и runtime-binding. |
+| **L1 Router Agent** | Downstream агентный сервис. Stateful — поддерживает runtime-сессии через `agent_id`. |
+| **Observability** | Langfuse, Prometheus. Логирование, trace, метрики. |
+
+---
+
+## 3. Общая схема
+
+```
+API Gateway
+    │
+    ▼
+ChatService
+    │  • хранит сообщения, feedback
+    │  -- • формирует inline chat-context
+    │  -- • управляет retry и placeholder-ами
+    │
+    ▼
+L1 Router Agent (stateful)
+    │  • принимает POST /v1/chat/completions
+    │  • управляет session_id (создаёт, сменяет при смене темы)
+    │  • возвращает ответ + session_id
+    │
+    ▼
+Domain Agent → L3 Agent → Tools
+```
+
+---
+
+## 4. Формат вызова ChatService → L1 Router Agent
+
+ChatService вызывает L1 Router Agent через **Completions-совместимый формат** (`POST /v1/chat/completions`). L1 Router Agent внутри себя трансформирует в межагентный формат для Domain/L3.
+
+### 4.1. Request: ChatService → L1 Router Agent
+
+**`POST /v1/chat/completions`**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `message` | string | Текст последнего сообщения пользователя |
+| `history` | array\<Message\> | Inline chat-context — предыдущие сообщения из Chat Storage |
+| `request_id` | string (UUID) | Уникальный ID запроса. Используется для дедупликации retry. |
+| `trace_id` | string (UUID) | Сквозной ID трассировки |
+| `session_id` | string \| null | ID текущей сессии (темы). `null` — первое обращение, сессии ещё нет. |
+| `auth` | object | Данные пользователя (извлекаются из JWT) |
+| `auth.employee_id` | string | Табельный номер сотрудника |
+| `auth.login` | string | Корпоративный логин |
+| `stream` | boolean | Включить SSE-стриминг |
+
+**Структура Message (в history):**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `role` | string | `"user"` \| `"assistant"` |
+| `content` | string | Текст сообщения |
+
+**Пример (первое сообщение, сессии ещё нет):**
+```json
+{
+  "message": "Сколько дней отпуска мне положено?",
+  "history": [],
+  "request_id": "a1b2c3d4-0001-4000-8000-000000000001",
+  "trace_id": "f7e6d5c4-b3a2-4000-9000-000000000001",
+  "session_id": null,
+  "auth": {
+    "employee_id": "EMP-8834",
+    "login": "i.petrov"
+  },
+  "stream": false
+}
+```
+
+**Пример (follow-up, сессия есть):**
+```json
+{
+  "message": "А как его оформить?",
+  "history": [
+    {"role": "user", "content": "Сколько дней отпуска мне положено?"},
+    {"role": "assistant", "content": "Сотруднику положено 28 календарных дней..."}
+  ],
+  "request_id": "a1b2c3d4-0001-4000-8000-000000000003",
+  "trace_id": "f7e6d5c4-b3a2-4000-9000-000000000003",
+  "session_id": "ses-001",
+  "auth": {
+    "employee_id": "EMP-8834",
+    "login": "i.petrov"
+  },
+  "stream": false
+}
+```
+
+### 4.2. Response: L1 Router Agent → ChatService
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `status` | enum | `"completed"` \| `"needs_clarification"` \| `"no_result"` \| `"error"` |
+| `content` | string \| null | Текст ответа или уточняющий вопрос |
+| `session_id` | string | ID сессии. При первом запросе — новый. При смене темы — нов��й. Иначе — тот же. |
+| `request_id` | string (UUID) | Эхо request_id из запроса |
+| `trace_id` | string (UUID) | Эхо trace_id из запроса |
+| `sources` | array \| null | Источники ответа |
+| `sources[].title` | string | Название источника |
+| `sources[].url` | string | URL источника |
+| `sources[].type` | string | `"confluence_page"` \| `"sql_result"` |
+| `artifacts` | array \| null | Файлы, вложения, выгрузки от агентов |
+| `artifacts[].type` | string | `"file"` \| `"csv"` \| `"document"` \| `"link"` |
+| `artifacts[].ref` | string | URL для скачивания |
+| `artifacts[].title` | string \| null | Название файла |
+| `artifacts[].note` | string \| null | Описание |
+
+**Пример (успех, первый запрос — L1 Router Agent создал сессию):**
+```json
+{
+  "status": "completed",
+  "content": "Сотруднику положено 28 календарных дней ежегодного оплачиваемого отпуска.",
+  "session_id": "ses-001",
+  "request_id": "a1b2c3d4-0001-4000-8000-000000000001",
+  "trace_id": "f7e6d5c4-b3a2-4000-9000-000000000001",
+  "sources": [
+    {"title": "Политика отпусков", "url": "https://confluence.internal/pages/conf-hr-1452", "type": "confluence_page"}
+  ],
+  "artifacts": null,
+}
+```
+
+**Пример (с файловым вложением):**
+```json
+{
+  "status": "completed",
+  "content": "Шаблон авансового отчёта доступен для скачивания.",
+  "session_id": "ses-001",
+  "request_id": "...",
+  "trace_id": "...",
+  "sources": [
+    {"title": "Шаблоны командировочных документов", "url": "https://confluence.internal/pages/conf-hr-2200", "type": "confluence_page"}
+  ],
+  "artifacts": [
+    {
+      "type": "file",
+      "ref": "https://confluence.internal/download/conf-hr-2200/avansoviy_otchet.xlsx",
+      "title": "Шаблон авансового отчёта",
+      "note": "Excel-файл для заполнения"
+    }
+  ]
+}
+```
+
+
+**Пример (нет данных):**
+```json
+{
+  "status": "no_result",
+  "content": "В базе знаний отсутствует информация по данной теме.",
+  "session_id": "ses-001",
+  "request_id": "...",
+  "trace_id": "...",
+  "sources": null,
+  "artifacts": null
+}
+```
+
+**Пример (ошибка):**
+```json
+{
+  "status": "error",
+  "content": "Запрашиваемая информация недоступна.",
+  "session_id": "ses-001",
+  "request_id": "...",
+  "trace_id": "...",
+  "sources": null,
+  "artifacts": null
+}
+```
+
+### 4.3. SSE-стриминг (stream: true)
+
+При `stream: true` L1 Router Agent отправляет ответ по частям через SSE:
+
+```
+data: {"delta": {"content": "Сотруднику "}}
+data: {"delta": {"content": "положено "}}
+data: {"delta": {"content": "28 календарных дней."}}
+data: {"sources": [{"title": "Политика отпусков", "url": "https://..."}]}
+data: {"session_id": "ses-001"}
+data: [DONE]
+```
+
+`session_id` приходит в финальном событии.
+
+---
+
+## 5. Управление сессиями (session_id)
+
+L1 Router Agent — **stateful**. Он управляет сессиями: создаёт при первом обращении, сохраняет контекст темы, создаёт новую при смене темы.
+
+### Жизненный цикл session_id
+
+| Событие | Что происходит |
+|---------|---------------|
+| Первый запрос (`session_id: null`) | L1 Router Agent создаёт сессию, возвращает `session_id: "ses-001"`. Gateway сохраняет. |
+| Follow-up в той же теме (`session_id: "ses-001"`) | L1 Router Agent продолжает сессию, контекст сохранён. Возвращает тот же `session_id`. |
+| Смена темы | L1 Router Agent определяет смену темы (специальный тул), создаёт новую сессию. Возвращает `session_id: "ses-002"`. Gateway обновляет. |
+| L1 Router Agent перезапущен | L1 Router Agent не узнаёт `session_id`, работает по `history` (fallback). Возвращает новый `session_id`. Gateway обновляет. |
+
+### Важно
+
+- `session_id` управляется L1 Router Agent, не ChatService
+- ChatService просто хранит последний `session_id` и передаёт обратно в следующем запросе
+- `history` всегда передаётся как fallback — если `session_id` устарел, L1 Router Agent не теряет контекст
+- Один пользователь может иметь несколько `session_id` в рамках одного п��тока сообщений (каждая тема — отдельная сессия)
+
+---
+
+## 6. Жизненный цикл сообщения (assistant)
+
+Каждый ответ ассистента проходит через статусы:
+
+| Статус | Описание | Переход |
+|--------|----------|---------|
+| `pending` | Placeholder создан, запрос отправлен в L1 Router Agent | → `completed` / `needs_clarification` / `retryable` |
+| `completed` | Ответ получен от L1 Router Agent, сохранён | — |
+| `needs_clarification` | L1 Router Agent вернул уточняющий вопрос | → следующий completions-вызов |
+| `retryable` | L1 Router Agent вернул ошибку / timeout, retry возможен | → `completed` (после retry) / `failed` (по TTL) |
+| `failed` | Retry не произошёл в течение TTL | — |
+
+### Алгоритм
+
+1. Gateway получает запрос от фронтенда
+2. Создаёт assistant placeholder (`status=pending`)
+3. Отправляет запрос в L1 Router Agent
+4. Сохраняет user message в Chat Storagenj
+5. Результат:
+   - **Успех** → обновляет placeholder (`status=completed`, `content=answer`), сохраняет `session_id`
+   - **Ошибка/timeout** → обновляет placeholder (`status=retryable`)
+
+---
+
+## 7. Обработка ошибок
+
+| Ситуация | HTTP-код | Ответ |
+|----------|---------|-------|
+| L1 Router Agent | 200 | Response с `completed` |
+| L1 Router Agent | 500 | Bad Gateway - L1 Router Agent не доступен |