feat(sprint6c+sprint7): терминология, сверка примеров с кодом, мульти-RAG (часть A)

Спринт 6c — терминология и сверка документации с реальным кодом:
- Словарь терминов в static/docs.html: «маршрутизатор» вместо «роутер»,
  «защитное условие» вместо «guard», «пошаговая ветка» вместо «многошаговая».
  Разделены концепты «намерение» (intent) и «ветка» (branch) с пометкой,
  что в коде они хранятся как одна сущность 1:1.
- Песочница: «Решение маршрутизатора» виден всегда (зелёный/жёлтый),
  счётчик переключений «N из 3» отдельной плашкой, бейджи под словарь.
- Настройки: «Условия перехода» → «Защитные условия (guards, JSON)».
- GRAPH_ARCHITECTURE_v4.md: имена полей thread_state и слоты приведены
  к реальной БД (db/models/thread_state.py) и таксономии промптов шагов
  (prompts/intents/new_booking/steps/). Ссылки на *_v2 примеры. На v3
  поставлена шапка «устарело».
- 4 примера переписаны как *_v2: реальные current_intent_code/
  current_step_code/slots_json, реальные allowed_next без двойных переходов,
  реальная таксономия слотов name/reason/specialist/preferred_time/confirmed.
  Удалены вымышленные CRM tool calls и слоты, которых нет в коде.
- static/example.html — параметризованная страница с навигацией между
  4 примерами; роут GET /api/docs/examples/{name} в main.py отдаёт
  markdown без дублирования файлов.
- Редактирование документов в Отладке: GET/PUT /documents/{id}/raw,
  textarea с переразметкой и обновлением Chroma при сохранении.

Спринт 7, часть A — мульти-RAG через подписку ветка↔документы:
- Миграция: таблица intent_documents (M:N), модель IntentDocument,
  индекс по document_id для обратного поиска.
- API: GET/PUT /intents/{code}/documents и GET/PUT /documents/{id}/intents
  с PUT-семантикой «полный список», атомарно. Сервис
  services/intent_document_service.py.
- Retrieval-фильтр в chat_service: подтягивает document_ids активной
  ветки и передаёт в vectorstore.query(). Дефолт пустой подписки —
  document_ids=[] (= 0 чанков), не «вся коллекция»: пустая подписка
  означает «ветка не настроена», подмешивать случайное хуже, чем
  ничего. vectorstore.query() различает None (нет фильтра) и [] (0).
- UI Настроек: блок «Документы базы знаний» в правом сайдбаре,
  всегда видим независимо от вкладки, сортировка по имени, счётчик
  «N из M», PUT при сохранении.
- UI Отладки: третья кнопка «привязка» рядом с «удалить» —
  раскрывашка со списком веток (галочки), быстрая привязка прямо
  на странице загрузки.
- Песочница: блок «Срез RAG» с подпиской/найдено, ворнинг при пустой
  подписке. Поле rag_subscription в QueryResponse и ChatResponse.
- Системный промпт страницы Отладки переехал в обычную ветку _debug
  («Страница отладки»). Удалён prompts/system_prompt.md и логика
  DEFAULT_SYSTEM_PROMPT в llm_client. routers/query.py подтягивает
  активный конфиг ветки _debug и её подписки. Дефолт пустой подписки
  для _debug — None (вся коллекция), не [] как для пациентских — чтобы
  Отладка работала «из коробки». На странице Отладки info-bar показывает
  активную версию и счётчик подписок, ссылка → Настройки.
- Тест-блок «Тест-вопрос» в центре Настроек: расширил /query
  параметрами intent_code (default _debug), system_prompt (override
  для теста черновика из textarea), disable_rag (для _router).
  Редактор промпта обёрнут в <details open> — можно свернуть до
  одной строки. Под ним — три колонки результата (RAG / промпт /
  ответ). Для _router показывается подсказка про отсутствие RAG.

Документы:
- data/datasets/*.md — наработки по 6 веткам (рабочие материалы оператора).
- docs/BRANCH_MAP_AND_PROMPTS_v1.md, docs/OPTIMIZATION_CONVERSION_v1.md,
  docs/guides/state_machine_and_slots.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

routers/chat.py

@@ -79,4 +79,5 @@ async def chat(req: ChatRequest, session: AsyncSession = Depends(get_session)):
         escalation_reason=result.get("escalation_reason"),
         operator_summary=result.get("operator_summary"),
         router_assembled_prompt=result.get("router_assembled_prompt", ""),
+        rag_subscription=result.get("rag_subscription"),
     )

routers/documents.py

@@ -5,16 +5,18 @@ from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from db.session import get_session
+from models.requests import DocumentIntentsUpdateRequest, DocumentRawUpdateRequest
 from models.responses import (
     ChunkDetail,
     ChunkPreview,
     DocumentChunksResponse,
     DocumentDeleteResponse,
     DocumentInfo,
+    DocumentIntentsResponse,
     DocumentListResponse,
     DocumentUploadResponse,
 )
-from services import document_service
+from services import document_service, intent_document_service
 from services.document_processor import process_document, rechunk_raw_text
 
 logger = logging.getLogger(__name__)
@@ -223,6 +225,95 @@ async def reindex_document(document_id: str, session: AsyncSession = Depends(get
     )
 
 
+@router.get("/{document_id}/raw")
+async def get_document_raw_text(document_id: str, session: AsyncSession = Depends(get_session)):
+    """Отдать исходный текст документа — для редактирования в UI."""
+    doc = await document_service.get_document_raw(session, document_id)
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Document not found")
+    return {
+        "document_id": doc.id,
+        "name": doc.name,
+        "file_type": doc.file_type,
+        "raw_text": doc.raw_text,
+    }
+
+
+@router.put("/{document_id}/raw", response_model=DocumentUploadResponse)
+async def update_document_raw_text(
+    document_id: str,
+    req: DocumentRawUpdateRequest,
+    session: AsyncSession = Depends(get_session),
+):
+    """Обновить raw_text + сразу переразметить и переиндексировать в Chroma.
+
+    Деструктивная операция: старые чанки удаляются, новые берут их место.
+    Имя и file_type не меняются.
+    """
+    from main import vectorstore_service
+
+    if vectorstore_service is None:
+        raise HTTPException(status_code=503, detail="Service not ready")
+
+    doc = await document_service.get_document_raw(session, document_id)
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Document not found")
+
+    new_raw = req.raw_text.strip()
+    if not new_raw:
+        raise HTTPException(status_code=400, detail="raw_text не может быть пустым")
+
+    chunks = rechunk_raw_text(new_raw)
+    if not chunks:
+        raise HTTPException(status_code=400, detail="После переразметки не осталось чанков")
+
+    # 1) обновляем raw_text в SQLite
+    await document_service.save_document_raw(
+        session=session,
+        document_id=document_id,
+        name=doc.name,
+        file_type=doc.file_type,
+        raw_text=new_raw,
+    )
+
+    # 2) переиндексация в Chroma — те же шаги, что в /reindex
+    vectorstore_service.delete_document(document_id)
+    chunks_count = vectorstore_service.add_document(
+        document_id=document_id,
+        document_name=doc.name,
+        file_type=doc.file_type,
+        chunks=[
+            {
+                "text": c.text,
+                "section": c.section,
+                "page_number": c.page_number,
+                "chunk_index": c.chunk_index,
+            }
+            for c in chunks
+        ],
+    )
+
+    chunks_prev = [
+        ChunkPreview(
+            index=c.chunk_index,
+            section=c.section,
+            page_number=c.page_number,
+            text_preview=c.text[:300],
+            char_length=len(c.text),
+        )
+        for c in chunks[:3]
+    ]
+
+    return DocumentUploadResponse(
+        document_id=document_id,
+        name=doc.name,
+        chunks_count=chunks_count,
+        status="updated",
+        created_at=datetime.now(timezone.utc).isoformat(),
+        chunks_preview=chunks_prev,
+    )
+
+
 @router.post("/reindex-all")
 async def reindex_all(session: AsyncSession = Depends(get_session)):
     """Переразметить все документы, у которых есть raw_text в SQLite."""
@@ -256,3 +347,27 @@ async def reindex_all(session: AsyncSession = Depends(get_session)):
         results.append({"document_id": doc.id, "name": doc.name, "status": "reindexed", "chunks_count": n})
 
     return {"total": len(results), "results": results}
+
+
+@router.get("/{document_id}/intents", response_model=DocumentIntentsResponse)
+async def list_document_intents(document_id: str, session: AsyncSession = Depends(get_session)):
+    doc = await document_service.get_document_raw(session, document_id)
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Document not found")
+    intent_codes = await intent_document_service.list_intents_for_document(session, document_id)
+    return DocumentIntentsResponse(document_id=document_id, intent_codes=intent_codes)
+
+
+@router.put("/{document_id}/intents", response_model=DocumentIntentsResponse)
+async def set_document_intents(
+    document_id: str,
+    req: DocumentIntentsUpdateRequest,
+    session: AsyncSession = Depends(get_session),
+):
+    doc = await document_service.get_document_raw(session, document_id)
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Document not found")
+    intent_codes = await intent_document_service.set_intents_for_document(
+        session, document_id, req.intent_codes,
+    )
+    return DocumentIntentsResponse(document_id=document_id, intent_codes=intent_codes)

routers/intents.py

@@ -5,14 +5,19 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from db.models import Intent, IntentStep
 from db.session import get_session
-from models.requests import IntentStepUpdateRequest, IntentToggleRequest
+from models.requests import (
+    IntentDocumentsUpdateRequest,
+    IntentStepUpdateRequest,
+    IntentToggleRequest,
+)
 from models.responses import (
+    IntentDocumentsResponse,
     IntentInfo,
     IntentListResponse,
     IntentStepInfo,
     IntentStepListResponse,
 )
-from services import config_service, intent_service, intent_step_service
+from services import config_service, intent_document_service, intent_service, intent_step_service
 
 logger = logging.getLogger(__name__)
 
@@ -109,3 +114,27 @@ async def update_intent_step(
         guards=req.guards,
     )
     return _step_to_info(updated, intent.code)
+
+
+@router.get("/{code}/documents", response_model=IntentDocumentsResponse)
+async def list_intent_documents(code: str, session: AsyncSession = Depends(get_session)):
+    intent = await intent_service.get_intent_by_code(session, code)
+    if intent is None:
+        raise HTTPException(status_code=404, detail="Intent not found")
+    document_ids = await intent_document_service.list_documents_for_intent(session, intent.id)
+    return IntentDocumentsResponse(intent_code=intent.code, document_ids=document_ids)
+
+
+@router.put("/{code}/documents", response_model=IntentDocumentsResponse)
+async def set_intent_documents(
+    code: str,
+    req: IntentDocumentsUpdateRequest,
+    session: AsyncSession = Depends(get_session),
+):
+    intent = await intent_service.get_intent_by_code(session, code)
+    if intent is None:
+        raise HTTPException(status_code=404, detail="Intent not found")
+    document_ids = await intent_document_service.set_documents_for_intent(
+        session, intent.id, req.document_ids,
+    )
+    return IntentDocumentsResponse(intent_code=intent.code, document_ids=document_ids)

routers/query.py

@@ -1,10 +1,13 @@
 import logging
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from config import settings
+from db.session import get_session
 from models.requests import QueryRequest
 from models.responses import QueryResponse, SourceInfo
+from services import config_service, intent_document_service, intent_service
 from services.llm_client import LLMClient
 from services.rag_pipeline import rag_query
 
@@ -12,9 +15,11 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(tags=["query"])
 
+DEBUG_INTENT_CODE = "_debug"
+
 
 @router.post("/query", response_model=QueryResponse)
-async def query_rag(request: QueryRequest):
+async def query_rag(request: QueryRequest, session: AsyncSession = Depends(get_session)):
     from main import vectorstore_service
 
     if vectorstore_service is None:
@@ -23,17 +28,64 @@ async def query_rag(request: QueryRequest):
     if not settings.deepseek_api_key:
         raise HTTPException(status_code=500, detail="DEEPSEEK_API_KEY not configured")
 
-    llm_client = LLMClient()
+    # Дефолт ветки — _debug (страница «Отладки»). При тесте из Настроек оператор передаёт
+    # код выбранной ветки, и используются её промпт и подписки.
+    intent_code = request.intent_code or DEBUG_INTENT_CODE
+    intent = await intent_service.get_intent_by_code(session, intent_code)
+    if intent is None:
+        raise HTTPException(status_code=404, detail=f"Ветка {intent_code!r} не найдена.")
 
+    # Системный промпт: если override задан — используем его (тест черновика из Настроек),
+    # иначе — активный конфиг ветки. Если конфига нет и override пустой — 503.
+    if request.system_prompt is not None:
+        effective_system_prompt = request.system_prompt
+        config_version = None
+    else:
+        active_cfg = await config_service.get_active_config_for_intent(session, intent.id)
+        if active_cfg is None:
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    f"У ветки {intent_code!r} нет активной версии промпта. "
+                    f"Зайдите в Настройки → выберите ветку → создайте и активируйте промпт."
+                ),
+            )
+        effective_system_prompt = active_cfg.system_prompt
+        config_version = active_cfg.version
+
+    # document_ids: приоритет — явный параметр запроса. Иначе берём подписки ветки.
+    # Для _debug дефолт пустой подписки — None (вся коллекция, удобство Отладки);
+    # для пациентских и системных веток дефолт пустой — [] (= 0 чанков).
+    if request.document_ids is not None:
+        effective_doc_ids = request.document_ids
+        subscribed_count = len(effective_doc_ids) if effective_doc_ids is not None else 0
+    else:
+        subscribed = await intent_document_service.list_documents_for_intent_code(
+            session, intent_code,
+        )
+        if subscribed:
+            effective_doc_ids = subscribed
+        elif intent_code == DEBUG_INTENT_CODE:
+            effective_doc_ids = None  # вся коллекция — только для _debug
+        else:
+            effective_doc_ids = []  # 0 чанков для остальных
+        subscribed_count = len(subscribed)
+
+    # disable_rag — пропускаем retrieval целиком (для веток без RAG, например _router).
+    if request.disable_rag:
+        effective_doc_ids = []  # пустой список → vectorstore.query вернёт []
+
+    llm_client = LLMClient()
     try:
         result = await rag_query(
             vectorstore=vectorstore_service,
             llm_client=llm_client,
             question=request.text,
             top_k=request.top_k,
-            document_ids=request.document_ids,
+            document_ids=effective_doc_ids,
             temperature=request.temperature,
             max_tokens=request.max_tokens,
+            system_prompt=effective_system_prompt,
         )
     except Exception as e:
         logger.exception("RAG query failed")
@@ -44,4 +96,10 @@ async def query_rag(request: QueryRequest):
         sources=[SourceInfo(**s) for s in result["sources"]],
         model_used=result["model_used"],
         assembled_prompt=result.get("assembled_prompt", ""),
+        intent_code=intent_code,
+        config_version=config_version,
+        rag_subscription={
+            "subscribed_count": subscribed_count,
+            "found_count": len(result["sources"]),
+        },
     )