Акт сдачи-приёмки работ № 1

Акт №1 и приложения: архитектура, API-слой, индексы OpenSearch, RBAC, реестр критических данных, карточки агентов.

Акт сдачи-приёмки работ № 1

Этап 0 «Исследование и архитектура»

Приложение №1 к Договору №04-002 от 24.04.2026 об оказании услуг между ООО «Экобанкинг» и ООО «АйТек»

г. Москва «» _____ 2026 г.

ООО «Экобанкинг» (далее -- Исполнитель) в лице __, действующего на основании __, с одной стороны,

и

ООО «АйТек» (далее -- Заказчик) в лице __, действующего на основании __, с другой стороны,

совместно именуемые «Стороны», составили настоящий Акт о нижеследующем.

1. Предмет акта

В соответствии с Договором №04-002 от 24.04.2026 и Техническим заданием (Приложение №1) Исполнитель выполнил, а Заказчик принимает результаты работ по Этапу 0 «Исследование и архитектура» в рамках проекта «Разработка и внедрение мультиагентной AI-системы Grace CRM Assistant для отдела продаж ООО „АйТек"».

2. Состав выполненных работ

В рамках Этапа 0 Исполнителем выполнены следующие работы и подготовлены соответствующие документы.

2.1 Исследование API Grace CRM и схемы данных

Исполнителем проведено исследование REST API системы Grace CRM (grace.i-tech.su), включая:

Результат: зафиксирована модель данных Grace CRM, достаточная для проектирования агентов и схемы синхронизации.

2.2 Проектирование индексов OpenSearch

Спроектирована и развёрнута структура из 15 индексов OpenSearch, обеспечивающая поисковый и аналитический слой системы.

Документ: 01_opensearch_schema.md

Группа Индексы
Контур продаж (Sales AI) itech_projects, itech_accounts, itech_calculations, itech_orders, itech_order_items, itech_comments, itech_contacts, itech_properties, itech_expected_payments, itech_users
Продуктовый каталог itech_nomenclatures, itech_calc_nomenclatures, itech_bom_components, itech_purchase_items
Управление разработкой itech_digital_requests

Для каждого индекса определены: маппинг полей, типы данных, анализаторы (ru_standard, standard), правила фильтрации, связи между индексами.

Текущее состояние: OpenSearch развёрнут, все 15 индексов наполнены данными (~225 000 документов), OpenSearch Dashboards доступны по адресу http://localhost:5601.

2.3 Архитектура агентов обоих контуров

Спроектирована агентная архитектура системы с описанием каждого агента по продуктовому методу: продукт агента, внутренний клиент, механизм, триггер, входные данные, критерий выполнения.

Документ: 00_architecture.md

Контур 1 -- Sales AI (Grace CRM Assistant):

Агент Продукт
Sync Agent Актуальный поисковый образ данных CRM в OpenSearch
Quality Agent Ежедневный реестр проектов с критическими пробелами данных
Recommendation Agent Конкретный следующий шаг по каждому активному проекту
Notification Agent Адресное уведомление через Mattermost (осн.) / Telegram (резерв)
Orchestrator Бесперебойная работа агентной системы как единого целого

Контур 2 -- Knowledge AI (база знаний):

Агент Продукт
Ingest Agent Проиндексированный документ в RAGflow с метаданными
Query Agent Контекстный ответ с цитатой из источника за ≤ 5 секунд
Lint Agent Еженедельный отчёт о противоречиях и устаревших данных

Для каждого агента зафиксированы: входные данные, индексы OpenSearch, формат выходного продукта, критерии качества.

2.4 Схема интеграции Grace CRM -> OpenSearch

Спроектирована схема синхронизации данных из Grace CRM в OpenSearch через Sync Agent.

Документ: 02_integration_schema.md

Схема включает:

2.5 Спецификация API-слоя для внешних систем

Разработана спецификация API-слоя Grace CRM Assistant для интеграции с внешними системами (BI, ERP, 1С).

Документ: 03_api_spec.md

Спецификация включает:

2.6 Ролевая модель (RBAC)

Разработана ролевая модель системы для контуров Sales AI и Knowledge AI.

Документ: 04_rbac.md

Модель включает:

2.7 Выбор фреймворка и архитектура агентов базы знаний

Зафиксирован выбор технологического стека для реализации системы.

Зафиксировано в: 00_architecture.md, раздел 5

Компонент Технология Обоснование
Агентный фреймворк Agno Нативная поддержка Teams, on-premise, совместимость с RAGflow через tool API
LLM основной OpenAI GPT-4o / GPT-4o-mini Function calling, высокое качество рассуждения
LLM резервный GigaChat / YandexGPT Fallback без изменения логики агентов
База знаний RAGflow Self-hosted, гибридный поиск, граф знаний, on-premise
Поисковый слой OpenSearch 2.13 15 индексов CRM, развёрнут и наполнен
Коммуникации Mattermost (осн.) + Telegram (резерв) Adapter pattern, канал per-user
Деплой Docker Compose On-premise, инфраструктура I-TECH

2.8 Работающее окружение для разработки

Развёрнуто и передано Заказчику рабочее окружение для начала Этапа 1:

Компонент Статус Адрес
OpenSearch 2.13 ✅ Работает http://localhost:9200
OpenSearch Dashboards ✅ Работает http://localhost:5601
RAGflow ✅ Развёрнут http://localhost:9380
ETL-скрипт (Grace CRM -> OpenSearch) ✅ Готов scripts/mysql_to_opensearch.py
15 индексов OpenSearch ✅ Наполнены ~225 000 документов

3. Соответствие требованиям ТЗ

Требование Этапа 0 (ТЗ, раздел 6) Выполнено Документ
Исследование API Grace CRM и схемы MS SQL ✅ 00_architecture.md, раздел 3
Проектирование индексов OpenSearch ✅ 01_opensearch_schema.md
Архитектура агентов обоих контуров ✅ 00_architecture.md, раздел 4
Выбор фреймворка агентов базы знаний ✅ 00_architecture.md, раздел 5
Ролевая модель (агенты продаж + база знаний) ✅ 04_rbac.md
Схема интеграции (коннектор, периодичность, конфликты) ✅ 02_integration_schema.md
Спецификация API-слоя для внешних систем ✅ 03_api_spec.md
Работающее окружение для разработки ✅ Артефакт (п. 2.8 настоящего Акта)
Согласование Подписание настоящего Акта --

4. Открытые вопросы, перенесённые на Этап 1

Следующие вопросы выявлены в ходе Этапа 0 и требуют уточнения или реализации в рамках Этапа 1:

# Вопрос Ответственный
1 Поддержка webhooks в API Grace CRM -- уточнить у разработчика Grace Заказчик
2 Лимиты запросов (rate limit) API Grace CRM -- получить от разработчика Grace Заказчик
3 Финальная формула расчёта Кк и веса для каждой проверки -- утвердить у РОПа и Зам. ГД Заказчик
4 Конкретный сервер / инфраструктура для production-деплоя Заказчик
5 Список ответственных по ролям (knowledge_manager, admin) Заказчик

5. Стоимость и оплата

В соответствии с Договором №04-002 от 24.04.2026 стоимость работ по Этапу 0 составляет:

__ рублей __ копеек (__ руб. коп.), в том числе НДС %: ____________ рублей.

Оплата производится в порядке, предусмотренном Договором.

6. Заключение

Стороны подтверждают, что работы по Этапу 0 «Исследование и архитектура» выполнены Исполнителем в полном объёме, в соответствии с требованиями Технического задания и с надлежащим качеством.

Заказчик претензий по объёму, качеству и срокам выполненных работ не имеет.

Настоящий Акт составлен в двух экземплярах, имеющих равную юридическую силу, -- по одному для каждой из Сторон.

7. Подписи сторон
ИСПОЛНИТЕЛЬ ЗАКАЗЧИК
ООО «Экобанкинг» ООО «АйТек»
_____________ _____________
(подпись) (подпись)
_____________ _____________
(ФИО, должность) (ФИО, должность)
М.П. М.П.

Приложения к настоящему Акту

  1. 00_architecture.md -- Техническое описание архитектуры Grace CRM Assistant

  2. 01_opensearch_schema.md -- Схема индексов OpenSearch

  3. 02_integration_schema.md -- Схема интеграции Grace CRM -> OpenSearch

  4. 03_api_spec.md -- Спецификация API-слоя для внешних систем

  5. 04_rbac.md -- Ролевая модель (RBAC)

  6. 05_agent_cards.md -- Карточки агентов (продуктовый подход)

Техническое описание архитектуры — Grace CRM Assistant

Версия: 1.0 Дата: 4 мая 2026

Статус: Этап 0 -- согласование файл 00_architecture.md

Проект: Мультиагентная AI-система для отдела продаж I-TECH

1. Назначение системы

Grace CRM Assistant -- мультиагентная AI-система, развёртываемая поверх корпоративной CRM Grace (grace.i-tech.su). Система выполняет advisory-функцию: анализирует данные CRM, контролирует качество данных, формирует рекомендации менеджерам, обеспечивает управленческий контроль -- не нарушая принципа Grace CRM = source of truth.

Все изменения в CRM производятся только через API Grace. Система не имеет прямого доступа к базе данных MySQL.

2. Состав системы

Система включает два функциональных контура.

Контур 1 -- Sales AI (Grace CRM Assistant)

Агент Наименование Продукт агента
Sync Agent Агент синхронизации Актуальный поисковый образ данных CRM в OpenSearch
Quality Agent Агент контроля качества Реестр проектов с критическими пробелами данных
Recommendation Agent Агент рекомендаций Конкретный следующий шаг по каждому активному проекту
Notification Agent Агент уведомлений Доставленное уведомление с подтверждённой реакцией
Orchestrator Оркестратор Бесперебойная работа агентной системы как единого целого

Контур 2 -- Knowledge AI (база знаний)

Агент Наименование Продукт агента
Ingest Agent Агент загрузки знаний Проиндексированный документ в RAGflow с метаданными
Query Agent Агент поиска знаний Контекстный ответ с цитатой из источника
Lint Agent Агент аудита знаний Отчёт о противоречиях и устаревших данных в базе знаний

3. Архитектура решения

3.1 Общая схема

┌─────────────────────────────────────┐
│         Grace CRM (MySQL)           │
│         source of truth             │
└──────────────┬──────────────────────┘
               │ API (REST)
               │ CLI-синхронизация
               ▼
┌──────────────────────────────────────┐
│           Sync Agent                 │
│         (Agno framework)             │
└──────┬──────────────────┬────────────┘
       │                  │
       ▼                  ▼
┌─────────────┐    ┌──────────────────┐
│  OpenSearch │    │     RAGflow      │
│  (15 индек- │    │  (база знаний,   │
│   сов CRM)  │    │   векторный      │
└──────┬──────┘    │   поиск)         │
       │           └──────┬───────────┘
       └────────┬──────────┘
                ▼
┌───────────────────────────────────────┐
│          Orchestrator (Agno)          │
│     управление, приоритизация, SLA    │
└──────┬───────────────┬────────────────┘
       │               │
       ▼               ▼
┌────────────┐  ┌─────────────────┐
│  Quality   │  │ Recommendation  │
│   Agent    │  │     Agent       │
└─────┬──────┘  └───────┬─────────┘
      │                 │
      └────────┬─────────┘
               ▼
┌──────────────────────────────────────┐
│          Notification Agent          │
│  Mattermost (основной) / Telegram    │
│  adapter pattern, канал per-user     │
└──────────────────────────────────────┘

3.2 Слой данных

Слой Система Роль
Источник Grace CRM (MySQL) Source of truth для операционных данных
Поисковый OpenSearch (15 индексов) Быстрый доступ, аналитика, downstream для агентов
Семантический RAGflow База знаний, векторный поиск, RAG

3.3 Ключевые принципы архитектуры

4. Описание агентов -- продуктовый подход

Каждый агент описывается через продуктовую формулу:

Продукт × Внутренний клиент × Триггер × Критерий выполнения

4.1 Sync Agent -- Агент синхронизации

Продукт: Актуальный поисковый образ данных Grace CRM в OpenSearch -- гарантирующий, что любой запрос от downstream-агентов отражает реальное состояние CRM на момент последнего запуска.

Параметр Содержание
Внутренний клиент Quality Agent, Recommendation Agent
Механизм CLI -> API Grace CRM -> трансформация -> bulk index в OpenSearch
Триггер Cron по расписанию + ручной запуск администратором
Входные данные API Grace CRM: projects, activities, clients, tasks, comments, calculations, orders, users, objects
Выходной продукт Обновлённые индексы OpenSearch (15 индексов)
Критерий выполнения Все индексы обновлены без ошибок; расхождение Grace CRM / OpenSearch = 0 по завершении синхронизации

Режимы работы:

Режим Триггер Что синхронизируется
Инкрементальный Cron каждые N минут Изменения с последнего запуска (параметр updated_since)
Полный Ночной cron / ручной запуск администратором Все сущности, полная пересборка индексов

Входные данные (API endpoints):

GET /api/projects?updated_since=timestamp
GET /api/projects/{id}
GET /api/activities?updated_since=timestamp
GET /api/clients?updated_since=timestamp
GET /api/clients/{id}
GET /api/tasks?updated_since=timestamp
GET /api/comments?entity_type=&entity_id=
GET /api/calculations?updated_since=timestamp
GET /api/orders?updated_since=timestamp
GET /api/users
GET /api/objects?updated_since=timestamp

Красный флаг: ошибка синхронизации -> downstream-агенты работают на устаревших данных -> все рекомендации невалидны.

4.2 Quality Agent -- Агент контроля качества данных

Продукт: Ежедневный реестр проектов с критическими пробелами данных -- для менеджеров и РОПа -- с указанием конкретного поля, ответственного и срока устранения.

Параметр Содержание
Внутренний клиент 1 Менеджер -- задача на заполнение по своим проектам
Внутренний клиент 2 РОП -- сводка по команде, эскалация при просрочке
Триггер Ежедневно в 09:00 + при изменении статуса проекта
Входные данные OpenSearch: itech_projects, itech_calculations, itech_activities; правила проверки из конфига
Выходной продукт Структурированный реестр: проект -> пробел -> ответственный -> срок; сигнал в Notification Agent
Критерий выполнения Доля проектов с полными данными ≥ 85%; каждый пробел имеет назначенного ответственного

Правила проверки (настраиваются в конфиге):

Проверка Поле Условие
Обязательные поля account_id, property_id, project_status_id, probability_new, forecast_date Не пусто
Следующий шаг next_action, next_action_date Заполнено и дата не в прошлом
Логика статусов calculation_status При статусе «КП выставлено» -- существует расчёт
Активность last_activity_at Не более 30 дней назад для активных проектов

4.3 Recommendation Agent -- Агент рекомендаций

Продукт: Конкретный следующий шаг по каждому активному проекту -- для менеджера -- сформулированный на основе истории CRM и базы знаний RAGflow, доставляемый не позднее 2 часов после изменения статуса или по запросу.

Параметр Содержание
Внутренний клиент Менеджер (первично); РОП (при просрочке реакции)
Триггер Изменение статуса проекта / запрос менеджера / просрочка контакта
Входные данные OpenSearch (itech_projects, itech_calculations, itech_comments, itech_accounts); RAGflow (кейсы, скрипты, возражения)
Выходной продукт Рекомендация: действие + срок + обоснование + ссылка на кейс из базы знаний
Критерий выполнения Менеджер знает следующий шаг по каждому активному проекту; нет проектов без зафиксированного следующего действия

Формат рекомендации:

Проект: [название] | Клиент: [название] | Стадия: [статус]Последний контакт: N дней назад​Рекомендация: [конкретное действие]Срок: [дата]Обоснование: [краткое обоснование]Похожий кейс: [ссылка из базы знаний]

4.4 Notification Agent -- Агент уведомлений

Продукт: Адресное уведомление нужному человеку в нужный момент через нужный канал -- без информационного шума -- как условие того, что сигналы системы реально доходят и вызывают реакцию.

Параметр Содержание
Внутренний клиент Менеджер / РОП / Зам. ГД -- в зависимости от типа события
Триггер Сигнал от любого агента системы
Входные данные Сигнал от агента + профиль получателя (предпочтительный канал)
Выходной продукт Доставленное уведомление с подтверждённой реакцией
Механизм доставки Adapter pattern: Mattermost (основной) / Telegram (резерв), канал настраивается per-user
Критерий выполнения Реакция в течение N часов; при отсутствии реакции -- эскалация в Orchestrator

Матрица маршрутизации уведомлений:

Событие Получатель Приоритет
Пробел в данных по своему проекту Менеджер Нормальный
Просрочка реакции менеджера > SLA РОП Высокий
Рекомендация по проекту Менеджер Нормальный
Критическое событие (крупная сделка, риск ухода) РОП, Зам. ГД Высокий
Сводка по команде РОП Ежедневный

4.5 Orchestrator -- Оркестратор

Продукт: Бесперебойная работа агентной системы как единого целого -- обеспечивающая, что ни одно критическое событие не теряется и каждый сигнал доходит до нужного человека в нужное время.

Параметр Содержание
Внутренний клиент РОП, Зам. ГД
Триггер Постоянно -- реагирует на сигналы всех агентов
Входные данные Сигналы от всех агентов; SLA-параметры из конфига
Выходной продукт Гарантия непрерывности потока сигналов; каждое событие имеет назначенного ответственного
Критерий выполнения Отсутствие потерянных эскалаций; система работает без ручного вмешательства

4.6 Ingest Agent -- Агент загрузки знаний

Продукт: Проиндексированный документ в RAGflow с корректными метаданными -- готовый к поиску Query Agent.

Параметр Содержание
Внутренний клиент Query Agent, Recommendation Agent
Триггер Загрузка нового документа ответственным за базу знаний
Входные данные Документ (PDF, DOCX, MD) + метаданные: отрасль, тип клиента, стадия сделки, продукт, теги
Выходной продукт Проиндексированная запись в RAGflow; обновлённый граф связей
Критерий выполнения Документ доступен для поиска; метаданные заполнены полностью

4.7 Query Agent -- Агент поиска знаний

Продукт: Контекстный ответ с цитатой из источника -- для менеджера -- за ≤ 5 секунд.

Параметр Содержание
Внутренний клиент Менеджер, Recommendation Agent
Триггер Запрос менеджера / вызов от Recommendation Agent
Входные данные Текстовый запрос + контекст проекта
Выходной продукт Ответ + цитата + ссылка на источник
Критерий выполнения Релевантный ответ ≤ 5 сек; источник всегда указан

4.8 Lint Agent -- Агент аудита знаний

Продукт: Еженедельный отчёт о противоречиях, устаревших данных и логических разрывах в базе знаний.

Параметр Содержание
Внутренний клиент Ответственный за базу знаний
Триггер Еженедельно
Входные данные Все документы в RAGflow
Выходной продукт Отчёт: список противоречий, устаревших фактов, незаполненных разделов
Критерий выполнения Выявлены все документы старше 6 месяцев и документы с конфликтующими утверждениями

5. Технологический стек

Слой Технология Роль
Агентный фреймворк Agno Агенты, Teams, оркестрация
LLM (основной) OpenAI GPT-4o / GPT-4o-mini Рассуждение, генерация рекомендаций
LLM (резерв) GigaChat / YandexGPT Fallback при недоступности OpenAI
Поисковый слой OpenSearch 2.13 15 индексов CRM, аналитика
База знаний RAGflow Семантический поиск, RAG, граф знаний
Коммуникации Mattermost (основной) + Telegram (резерв) Доставка уведомлений, adapter pattern
Синхронизация CLI + Agno Agent Grace CRM API -> OpenSearch
Планировщик Cron / systemd timer Расписание синхронизации и агентов
Деплой Docker Compose On-premise, I-TECH инфраструктура

Выбор фреймворка агентов базы знаний

Для контура Knowledge AI выбран RAGflow как платформа базы знаний по следующим основаниям:

Критерий RAGflow
Развёртывание Self-hosted, on-premise -- соответствует требованиям I-TECH
Поиск Гибридный: semantic + full-text
Граф знаний Поддерживается нативно
Интеграция с Agno Через REST API -- Agno вызывает RAGflow как tool
Мультиформатность PDF, DOCX, MD, TXT

Агенты контура Knowledge AI реализованы на Agno и взаимодействуют с RAGflow через его REST API как с внешним инструментом (tool call). Прямой встройки RAGflow в агентный фреймворк не требуется.

6. Цепочка данных (основной сценарий)

Grace CRM (MySQL)    ↓  CLI → APISync Agent    ↓  bulk indexOpenSearch (15 индексов)    ↓  запрос агентовQuality Agent → реестр пробелов → Notification Agent → Mattermost/Telegram → МенеджерRecommendation Agent → рекомендация → Notification Agent → Mattermost/Telegram → Менеджер    ↑RAGflow (база знаний) — контекст для рекомендаций

7. Что остаётся за рамками Этапа 0

Тема Этап
Калькулятор премии (Кк) Этап 1
Telegram-бот (UI) Этап 2
Полная интеграция RAGflow + Ingest/Query/Lint агентов Этап 2
Интеграция с 1С ЕРП Этап 3

8. Программа и методика приёмо-сдаточных испытаний (ПМИ)

8.1 Общие принципы

ПМИ фиксирует проверку каждого функционального блока системы на соответствие требованиям Этапа 0.

Формат тест-кейса:

8.2 ПМИ -- Sync Agent

TC-SA-01 -- Инкрементальная синхронизация

TC-SA-02 -- Полная синхронизация

8.3 ПМИ -- Quality Agent

TC-QA-01 -- Обнаружение пробелов

TC-QA-02 -- SLA-эскалация

8.4 ПМИ -- Recommendation Agent

TC-RA-01 -- Генерация рекомендации

8.5 ПМИ -- Notification Agent

TC-NA-01 -- Доставка уведомления

8.6 ПМИ -- API

TC-API-01 -- Получение проектов

8.7 ПМИ -- Knowledge AI

TC-KB-01 -- Поиск

9. Прототипы дашбордов OpenSearch Dashboards

9.1 Общие требования

9.2 Дашборд «Менеджер»

Фильтры: период, стадия, тип клиента

Виджеты:

9.3 Дашборд «РОП»

Фильтры: менеджер, период, стадия, тип клиента

Виджеты:

9.4 Дашборд «Зам. ГД»

Виджеты:

Дополнительно:

10. Развёртывание и инфраструктура

10.1 Сервер

10.2 Размещение компонентов

Компонент Размещение
OpenSearch Docker container
RAGflow Docker container
Agno Agents Docker container
API Layer Docker container
Mattermost Внешний / контейнер

10.3 Требования к ресурсам

10.4 Сеть и доступ

10.5 Запуск (базовый)

docker-compose up -d

10.6 Резервное копирование

10.7 Мониторинг

Спецификация API-слоя — Grace CRM Assistant

Версия: 1.0 Дата: 4 мая 2026

Статус: Этап 0 -- согласование файл 03_api_spec.md

1. Назначение

API-слой Grace CRM Assistant предоставляет интерфейс для:

Все эндпоинты доступны только на внутренней сети. Публичного доступа нет.

2. Базовые параметры

Параметр Значение
Base URL http://grace-ai.i-tech.local/api/v1
Протокол HTTP/HTTPS (TLS 1.3 внутри периметра)
Формат JSON
Аутентификация Bearer Token (JWT)
Версионирование URI (/v1/, /v2/)

Заголовки запроса

Authorization: Bearer {token}Content-Type: application/jsonAccept: application/json

Стандартный формат ответа

{  "success": true,  "data": { ... },  "meta": {    "total": 100,    "page": 1,    "per_page": 20  }}

Стандартный формат ошибки

{  "success": false,  "error": {    "code": "UNAUTHORIZED",    "message": "Токен недействителен или истёк"  }}

3. Аутентификация и авторизация

3.1 Получение токена

POST /api/v1/auth/tokenContent-Type: application/json​{  "client_id": "erp-system",  "client_secret": "***"}

Ответ:

{  "access_token": "eyJ...",  "expires_in": 3600,  "token_type": "Bearer"}

3.2 Матрица доступа по ролям

Группа эндпоинтов manager rop deputy_gd admin system
/projects -- свои проекты ✅ ✅ ✅ ✅ ✅
/projects -- все проекты ❌ ✅ ✅ ✅ ✅
/recommendations ✅ ✅ ❌ ✅ ✅
/analytics/team ❌ ✅ ✅ ✅ ✅
/analytics/aggregate ❌ ❌ ✅ ✅ ✅
/sync/* ❌ ❌ ❌ ✅ ✅
/admin/* ❌ ❌ ❌ ✅ ❌

4. Эндпоинты -- данные CRM

4.1 Проекты / Сделки

GET /api/v1/projects

Параметры фильтрации:

Параметр Тип Описание
manager_id integer Фильтр по менеджеру
status string Статус проекта
probability_min integer Минимальная вероятность, %
updated_since ISO8601 Изменено после даты
page integer Страница (default: 1)
per_page integer Записей на странице (max: 100)

Ответ:

{  "success": true,  "data": [    {      "id": 15714,      "name": "ЖК Дмитровское небо",      "account_name": "КР ЭНЕРГО ООО",      "manager_name": "Пересунько Павел",      "project_status": "Отправлено КП",      "probability_percent": 65,      "amount": 91769410,      "forecast_date": "2026-06-30"    }  ],  "meta": { "total": 247, "page": 1, "per_page": 20 }}

GET /api/v1/projects/{id}

Возвращает полную карточку проекта включая историю комментариев и список расчётов.

4.2 Рекомендации

GET /api/v1/recommendations

Параметры:

Параметр Тип Описание
manager_id integer Рекомендации для менеджера
project_id integer Рекомендации по проекту
status string pending / acknowledged / done

Ответ:

{  "success": true,  "data": [    {      "id": "rec_001",      "project_id": 15714,      "project_name": "ЖК Дмитровское небо",      "account_name": "КР ЭНЕРГО ООО",      "action": "Позвонить клиенту и уточнить статус решения по КП",      "deadline": "2026-05-07",      "rationale": "Последний контакт 18 дней назад, КП на согласовании",      "knowledge_ref": "kb://cases/energo-jk-pattern",      "created_at": "2026-05-04T09:00:00",      "status": "pending"    }  ]}

POST /api/v1/recommendations/{id}/acknowledge

Менеджер подтверждает получение рекомендации.

POST /api/v1/recommendations/{id}/done

Менеджер отмечает рекомендацию выполненной.

4.3 Аналитика

GET /api/v1/analytics/funnel

Воронка продаж с разбивкой по статусам и менеджерам.

Параметры: manager_id, date_from, date_to, group_by (manager / status / month)

GET /api/v1/analytics/data-quality

Коэффициент качества данных (Кк) по менеджерам и отделу.

Ответ:

{  "success": true,  "data": {    "team_kk": 0.82,    "managers": [      {        "manager_id": 12,        "manager_name": "Стегнина Мария",        "kk": 0.91,        "projects_total": 249,        "projects_with_gaps": 22      }    ]  }}

GET /api/v1/analytics/backlog

Сводка по backlog-позициям (незавершённые отгрузки).

5. Эндпоинты -- управление системой

5.1 Синхронизация (только role: admin, system)

POST /api/v1/sync/runContent-Type: application/json​{  "mode": "incremental",  "entities": ["projects", "orders"]}

Ответ:

{  "success": true,  "data": {    "run_id": "sync_2026_05_04_090000",    "status": "started",    "estimated_duration_sec": 25  }}

GET /api/v1/sync/status/{run_id}

Статус текущего или последнего запуска синхронизации.

GET /api/v1/sync/history

История запусков синхронизации (последние 30).

5.2 Состояние системы

GET /api/v1/health

Доступен без авторизации. Возвращает статус всех компонентов.

{  "status": "healthy",  "components": {    "opensearch": "healthy",    "ragflow": "healthy",    "grace_api": "healthy",    "sync_agent": "healthy",    "last_sync": "2026-05-04T08:45:00"  }}

GET /api/v1/metrics

Метрики системы для мониторинга (только admin).

6. Эндпоинты -- база знаний

GET /api/v1/knowledge/search

Поиск по базе знаний (через RAGflow).

Параметры: q (текст запроса), industry, deal_stage, product_type

Ответ:

{  "success": true,  "data": {    "answer": "По данному типу клиента рекомендуется...",    "sources": [      {        "id": "kb_case_001",        "title": "Кейс: ЦОД-проект, застройщик",        "excerpt": "...",        "relevance": 0.92      }    ]  }}

POST /api/v1/knowledge/documents

Загрузка нового документа в базу знаний (только role: knowledge_manager, admin).

7. Коды ошибок

Код HTTP Описание
UNAUTHORIZED 401 Токен отсутствует или недействителен
FORBIDDEN 403 Недостаточно прав для операции
NOT_FOUND 404 Ресурс не найден
VALIDATION_ERROR 422 Ошибка валидации параметров
RATE_LIMITED 429 Превышен лимит запросов
INTERNAL_ERROR 500 Внутренняя ошибка сервера
SERVICE_UNAVAILABLE 503 Компонент системы недоступен

8. Лимиты

Параметр Значение
Rate limit 100 запросов / минуту на токен
Максимум записей в ответе 100 (per_page)
Максимальный размер тела запроса 10 МБ
Таймаут 30 секунд

Схема индексов OpenSearch — Grace CRM Assistant

Версия: 2.0 Дата: 22 июля 2026 (актуализация по проду)

Источник: OpenSearch http://localhost:9200 файл 01_opensearch_schema.md

Всего индексов: 31

1. Назначение слоя OpenSearch

OpenSearch является поисковым и аналитическим слоем системы. Данные поступают из Grace CRM через Sync Agent и хранятся в виде денормализованных витрин, оптимизированных под сценарии работы AI-агентов.

Ключевые принципы:

2. Индексы контура Sales AI

2.1 itech_projects -- Сделки (Opportunities)

Центральный индекс воронки продаж. Используется Quality Agent и Recommendation Agent.

Поле Тип Описание
id integer PK
number keyword Номер сделки
name text + .keyword ru_standard
account_id integer -> itech_accounts.id
account_name text + .keyword ru_standard
manager_id integer
manager_name text + .keyword standard
engineer_user_id integer
engineer_name text + .keyword standard
property_id integer -> itech_properties.id
property_name text + .keyword ru_standard
project_status_id integer
project_status text + .keyword standard
probability_new keyword Вероятность (категория)
probability_percent integer Вероятность, %
amount double Сумма сделки
type_of_calculation keyword Тип тендера
forecast_date date Прогнозная дата закрытия
refusal_reason text Причина отказа, ru_standard
created_at date
created_year integer

Правила фильтрации для агентов:

2.2 itech_accounts -- Контрагенты

Поле Тип Описание
id integer PK
name text + .keyword ru_standard
inn keyword ИНН
reliability keyword red / yellow / green / black / blue
manager_id integer
manager_name text + .keyword standard
assistant_user_id integer
is_prepayment_only boolean Только предоплата
order_count integer Кол-во заказов
project_count integer Кол-во сделок
revenue_mln float Выручка, млн руб.
paid_mln float Оплачено, млн руб.
debt_mln float Долг, млн руб.
last_order_at date Дата последнего заказа
sectors keyword Отраслевые сектора
top_properties keyword Топ объекты
created_at date

2.3 itech_calculations -- КП / Расчёты

Поле Тип Описание
id integer PK
project_id integer -> itech_projects.id
project_name text + .keyword ru_standard
account_id integer
account_name text + .keyword ru_standard
manager_id integer
manager_name text + .keyword standard
engineer_user_id integer
engineer_name text + .keyword standard
calculation_status_id integer
calculation_status text + .keyword standard
amount double Сумма КП
type keyword Тип расчёта
quality keyword Точный / Бюджетная оценка
is_urgent boolean Срочный
due_date date Срок выполнения
kp_exposed_at date Дата выставления КП
completed_at date
created_at date

2.4 itech_orders -- Заказы (шапки)

Поле Тип Описание
id integer PK
order_number keyword Номер заказа
account_id integer
account_name text + .keyword ru_standard
manager_id integer
manager_name text + .keyword standard
project_id integer -> itech_projects.id
total_cost double Итоговая стоимость
general_purchase double Себестоимость
is_shipped boolean Отгружен
bill_type keyword Тип счёта
run_date date Дата запуска в производство
shipping_date_plan date Плановая дата отгрузки
shipping_date_fact date Фактическая дата отгрузки
created_at date

2.5 itech_order_items -- Позиции заказов

Поле Тип Описание
id integer PK
order_id integer -> itech_orders.id
order_number keyword
name text + .keyword standard
article keyword Артикул
amount double Сумма с НДС
amount_wo_vat double Сумма без НДС
purchase_plan double Плановая себестоимость
profit_amount double Прибыль
hours_plan double Плановые часы
is_shipped boolean
shipping_date_plan date
shipping_date_fact date NULL = позиция в backlog
created_at date

2.6 itech_comments -- Комментарии

Поле Тип Описание
id long PK
commentable_type keyword Тип объекта (Project / Calculation / ...)
commentable_id integer ID объекта
author_id integer
author_name text + .keyword standard
project_id integer -> itech_projects.id
project_name text + .keyword ru_standard
project_status keyword Статус на момент комментария
account_name text + .keyword standard
manager_name text + .keyword standard
comment text + .keyword Текст, ru_standard
created_at date

2.7 itech_contacts -- Контактные лица

Поле Тип Описание
id integer PK
full_name text + .keyword ru_standard
job_title text + .keyword Должность
phones keyword Массив телефонов
emails keyword Массив email
is_priority boolean
accounts nested Связанные контрагенты
└ account_id integer
└ account_name text + .keyword
created_at date

⚠️ accounts -- nested-тип. Обязательно использовать nested query при фильтрации.

2.8 itech_properties -- Строительные объекты

Поле Тип Описание
id integer PK
name text + .keyword ru_standard
address_full text + .keyword ru_standard
city keyword
region keyword
property_type keyword Тип объекта
sector keyword Отрасль
account_count integer Кол-во контрагентов
project_count integer Кол-во сделок
top_account keyword Основной контрагент
created_at date

2.9 itech_expected_payments -- Ожидаемые платежи

Поле Тип Описание
id text + .keyword PK
order_id integer -> itech_orders.id
order_number keyword
exp_payment_status keyword Статус платежа
pay_amount double Ожидаемая сумма
paid_amount double Оплаченная сумма
pay_date date Ожидаемая дата
paid_date date Фактическая дата
created_at date

2.10 itech_users -- Пользователи системы

Поле Тип Описание
id integer PK
full_name text + .keyword ru_standard
email keyword
title keyword Должность
department text + .keyword standard
roles keyword Массив ролей
is_active boolean
created_at date

3. Индексы продуктового каталога

3.1 itech_nomenclatures -- Мастер-каталог

Поле Тип Описание
id integer PK
name text + .keyword ru_standard
article keyword Артикул
brand text + .keyword Бренд
created_at date

3.2 itech_calc_nomenclatures -- Расчётная номенклатура

Поле Тип Описание
article keyword PK
name text + .keyword ru_standard
price float Нормативная цена
assembly_time float Норма времени сборки, ч
weight float Масса, кг
body_type keyword Тип корпуса
body_width / body_height / body_depth integer Габариты, мм
body_ip integer Степень защиты IP
rated_in float Номинальный ток, А
icu float Ток отключения, кА

3.3 itech_bom_components -- BOM-спецификации

Поле Тип Описание
id integer PK
calculation_id integer -> itech_calculations.id
project_id integer -> itech_projects.id
article keyword Артикул компонента
quantity double Количество
cost double Стоимость
currency keyword Валюта

3.4 itech_purchase_items -- Позиции закупок

Поле Тип Описание
id integer PK
nomenclature_id integer -> itech_nomenclatures.id
nomenclature_name text + .keyword ru_standard
article keyword
quantity integer Запрошено
received_quantity integer Получено
desired_delivery_date date
created_at date

3.5 itech_digital_requests -- ИТ-задачи

Поле Тип Описание
id integer PK
name text + .keyword ru_standard
status keyword Статус
importance keyword Важность
department_name text + .keyword Отдел-заказчик
plan_date_end_development date Плановая дата завершения
fact_date_end_development date Фактическая дата
created_at date

4. Схема связей между индексами

itech_projects ──── account_id ────► itech_accountsitech_projects ──── property_id ───► itech_propertiesitech_projects ──── manager_id ────► itech_users​itech_calculations ── project_id ──► itech_projectsitech_orders ──────── project_id ──► itech_projectsitech_order_items ─── order_id ────► itech_ordersitech_expected_payments ─ order_id ► itech_orders​itech_comments ──── project_id ────► itech_projectsitech_contacts ──── accounts[] ────► itech_accounts (nested)​itech_bom_components ── calculation_id ► itech_calculationsitech_purchase_items ─── nomenclature_id ► itech_nomenclatures

5. Правила использования агентами

Агент Индексы Операции
Sync Agent Все 15 Запись (bulk index)
Quality Agent itech_projects, itech_calculations, itech_accounts Чтение, агрегации
Recommendation Agent itech_projects, itech_accounts, itech_comments, itech_calculations, itech_contacts Чтение, fulltext
Orchestrator itech_projects, itech_users Чтение

6. Индексы, добавленные после v1.0

Снято с живого OpenSearch (прод, сервер 147) 22 июля 2026. Схемы полей — из фактического _mapping индексов. Служебные поля _sync_source / _synced_at в таблицах опущены.

6.1 Операционный контур — новые itech_* (синк из Grace)

itech_contracts — Договоры с контрагентами (шапки)

Документов: 1 980

Поле Тип
account_id integer
approval_status keyword
approval_status_id integer
assistant_name keyword
assistant_user_id integer
contact_id integer
contract_end_date date
contract_start_date date
deadline date
id integer
manager_name keyword
manager_user_id integer
number keyword
project_id integer
signing_date date
status_id integer
type keyword

itech_contract_annexes — Приложения/спецификации к договорам

Документов: 2 986

Поле Тип
amount double
approval_status keyword
contract_id integer
currency_code keyword
id integer
number keyword
order_number keyword
project_id integer
signing_date date
start_date date
status_id integer
type keyword

itech_calculation_requests — Заявки на расчёт — входящая очередь инженерам

Документов: 22 745

Поле Тип
account_id integer
calculation_complexity integer
created_at date
description text + .keyword
end_desired date
end_plan date
engineer_name keyword
engineer_user_id integer
estimated_time float
id integer
is_priority integer
is_question integer
manager_id integer
manager_name keyword
probability_percent float
project_id integer
project_path keyword
property_id integer
start_plan date
status_id integer
type_of_calc_id integer
updated_at date

itech_calculation_remarks — Замечания к расчётам

Документов: 41

Поле Тип
author_name keyword
author_user_id integer
calculation_engineer_user_id integer
calculation_id integer
created_at date
engineer_name keyword
id integer
project_id integer
remark text + .keyword

itech_services_requests — Сервисные заявки (внутренние закупки/услуги)

Документов: 4 503

Поле Тип
account_id integer
approval_status_id integer
category text + .keyword
cost long
created_at date
department_id integer
department_name text + .keyword
executor_name text + .keyword
expenditure_item_id integer
id integer
order_number keyword
purpose text + .keyword
recipient_name text + .keyword
status_id integer

itech_object_registrations — Регистрации объектов за контрагентом (защита проекта)

Документов: 467

Поле Тип
account_id integer
contact_id integer
controller_name keyword
controller_user_id integer
created_at date
id integer
property_id integer

itech_quality_managers — Снимки коэффициента качества Кк по менеджерам (витрина Quality Agent)

Документов: 41

Поле Тип
clean integer
gap_count integer
kk float
manager keyword
snapshot_date date
stale_count long
total integer
with_gaps integer

itech_activity_log — Журнал изменений сущностей (аудит воронки)

Документов: 15 868

Поле Тип
account_id integer
account_name text + .keyword
action keyword
amount double
causer_name text + .keyword
causer_user_id integer
changed_fields keyword
changes_text text
created_at date
created_year integer
engineer_name text + .keyword
engineer_user_id integer
entity_id integer
entity_type keyword
forecast_date date
id long
manager_name text + .keyword
manager_user_id integer
probability_percent float
project_id integer
status_id integer
status_name keyword

itech_reminders — Напоминания менеджерам (индекс создан, данных пока нет)

Документов: 0

Поле Тип
by_email boolean
by_grace boolean
by_telegram boolean
created_at date
entity_id integer
entity_type keyword
id integer
is_expired boolean
manager_id integer
manager_name text + .keyword
pre_notifications keyword
remind_date date
result text + .keyword
status keyword
text text + .keyword

6.2 Продуктовый каталог — itech_vendor_price_lists

Прайс-листы вендоров по артикулам — крупнейший индекс каталога.
Документов: 658 642

Поле Тип
article keyword
brand_id keyword
currency keyword
effective_date date
family text + .keyword
name text
price double
price_list_id keyword
source keyword
unit keyword
vendor keyword

6.3 Аналитический слой — витрины *_v1 (в v1.0 отсутствовал)

Считаются у нас (не синк из Grace): модель конверсии сделок (агент Quality) и поиск похожих проектов (агент Recommendation).

deal_conversion_training_v1 — Обучающая выборка модели конверсии сделок (признаки + метка converted)

Документов: 8 648

Поле Тип
account_id keyword
amount double
comment_avg_gap_days double
comment_count double
comment_distinct_authors double
comment_max_gap_days double
comment_span_days double
comments_before_forecast double
comments_per_week double
company_id keyword
complexity double
converted boolean
created_at date
created_year double
days_created_to_forecast double
days_forecast_to_first_order double
days_since_last_comment double
first_order_created_at date
first_order_id long
forecast_date date
important keyword
is_sales_plan keyword
label integer
manager_id keyword
manager_name keyword
probability_source keyword
probability_value double
project_age_days double
project_id long
project_name keyword
project_status keyword
project_status_id keyword
property_id keyword
sector keyword
type_of_calculation keyword

deal_conversion_predictions_v1 — Предсказания вероятности конверсии (модель против оценки менеджера)

Документов: 1 255

Поле Тип
as_of_date date
created_at date
features object
forecast_date date
manager_id keyword
manager_name keyword
manager_probability double
model_name keyword
predicted_probability double
probability_delta double
project_id long
project_name keyword
project_status keyword

project_similarity_embeddings_v1 — Эмбеддинги проектов (knn_vector: content + structured) для поиска похожих

Документов: 20 371

Поле Тип
account_id keyword
account_name text + .keyword
amount double
amount_log float
comment_count integer
comment_count_log float
comment_span_days float
comments_per_week double
content_embedding knn_vector
content_hash keyword
content_text text
created_at date
created_year integer
days_since_last_comment float
embedding_dimensions integer
embedding_model keyword
embedding_provider keyword
execution_days double
first_order_created_at date
first_order_id long
forecast_date date
forecast_horizon_days double
has_order boolean
has_order_value double
manager_id keyword
manager_name keyword
order_item_count integer
order_item_count_log float
probability double
project_age_days double
project_id long
project_name text + .keyword
project_status keyword
project_status_id keyword
property_id keyword
property_name text + .keyword
sector keyword
structured_vector knn_vector
type_of_calculation keyword

project_similarity_vectors_v1 — Векторы сходства проектов (knn_vector)

Документов: 20 356

Поле Тип
account_id keyword
account_name text + .keyword
amount double
amount_log float
comment_count integer
comment_count_log float
comment_span_days float
comments_per_week double
content_hash keyword
content_text text
content_vector knn_vector
created_at date
created_year integer
days_since_last_comment float
execution_days double
first_order_created_at date
first_order_id long
forecast_date date
forecast_horizon_days double
has_order boolean
has_order_value double
manager_id keyword
manager_name keyword
order_item_count integer
order_item_count_log float
probability double
project_age_days double
project_id long
project_name text + .keyword
project_status keyword
project_status_id keyword
property_id keyword
property_name text + .keyword
sector keyword
structured_vector knn_vector
type_of_calculation keyword

project_similarity_cards_v1 — Карточки проектов для выдачи похожих (токенизированные)

Документов: 20 353

Поле Тип
account_id keyword
account_name text + .keyword
amount double
amount_log double
created_at date
created_year integer
execution_days double
first_order_created_at date
first_order_id long
forecast_date date
forecast_horizon_days double
has_order boolean
manager_id keyword
manager_name keyword
order_item_count integer
probability double
project_age_days double
project_id long
project_name text + .keyword
project_status keyword
project_status_id keyword
property_id keyword
property_name text + .keyword
sector keyword
token_text text
tokens keyword
type_of_calculation keyword

project_similarity_comment_drafts_v1 — Черновики рекомендательных комментариев (nested similar_projects)

Документов: 426

Поле Тип
comment_text text
created_at date
draft_id keyword
send_result object
sent_at date
similar_projects nested
source keyword
status keyword
target_project_id long
target_project_name keyword

Схема интеграции Grace CRM → OpenSearch

Версия: 1.0 Дата: 4 мая 2026

Статус: Этап 0 -- согласование файл 02_integration_schema.md

1. Архитектура интеграции

Grace CRM (MySQL) не подключается к OpenSearch напрямую. Синхронизация осуществляется через Sync Agent -- Agno-агент, запускаемый по расписанию или вручную.

Grace CRM (MySQL)    │    │  REST API (GET-запросы)    ▼CLI-команда → Sync Agent (Agno)    │    │  Трансформация данных    │  (нормализация, денормализация, обогащение)    ▼OpenSearch (bulk index)    │    ├── itech_projects    ├── itech_accounts    ├── itech_calculations    ├── itech_orders    ├── itech_order_items    ├── itech_comments    ├── itech_contacts    ├── itech_properties    ├── itech_expected_payments    └── ... (15 индексов)

Важно: прямого доступа к MySQL Grace CRM у Sync Agent нет. Все данные получаются только через REST API Grace CRM.

2. Механизм запуска

2.1 CLI-команда

# Инкрементальная синхронизация (основной режим)grace-sync run --mode incremental​# Полная синхронизация (ночная / восстановление)grace-sync run --mode full​# Синхронизация конкретной сущностиgrace-sync run --entity projects --mode incremental​# Ручной запуск с указанием временного окнаgrace-sync run --mode incremental --since 2026-05-01T00:00:00

2.2 Расписание (cron)

Режим Расписание Описание
Инкрементальный Каждые 15 минут Основной рабочий режим
Полный Ежедневно в 02:00 Восстановление консистентности
Ручной По требованию администратора После миграций, исправлений

3. Сущности и endpoints API

Сущность Endpoint Индекс OpenSearch Частота
Сделки GET /api/projects?updated_since= itech_projects 15 мин
Контрагенты GET /api/clients?updated_since= itech_accounts 15 мин
Расчёты (КП) GET /api/calculations?updated_since= itech_calculations 15 мин
Заказы GET /api/orders?updated_since= itech_orders 15 мин
Позиции заказов GET /api/order_items?updated_since= itech_order_items 15 мин
Активности GET /api/activities?updated_since= itech_comments 15 мин
Задачи GET /api/tasks?updated_since= (в itech_projects) 15 мин
Контактные лица GET /api/contacts?updated_since= itech_contacts 1 час
Объекты GET /api/objects?updated_since= itech_properties 1 час
Платежи GET /api/expected_payments?updated_since= itech_expected_payments 1 час
Пользователи GET /api/users itech_users 1 раз/день

4. Режимы синхронизации

4.1 Инкрементальный режим

Принцип: запрашиваются только записи, изменённые с момента последней синхронизации.

1. Читаем last_sync_timestamp из хранилища состояния2. GET /api/{entity}?updated_since={last_sync_timestamp}3. Трансформируем полученные записи4. Bulk upsert в OpenSearch (upsert по id)5. Обновляем last_sync_timestamp = текущее время

Хранение состояния: файл sync_state.json или переменная окружения. Формат:

{  "projects": "2026-05-04T08:45:00",  "clients": "2026-05-04T08:45:00",  "orders": "2026-05-04T08:45:00"}

4.2 Полный режим

Принцип: полная выгрузка всех сущностей с пагинацией, полная пересборка индексов.

1. Создаём новый индекс с суффиксом _tmp2. Загружаем все данные через API с пагинацией (batch по 500 записей)3. После успешной загрузки — переключаем алиас4. Удаляем старый индекс

Применяется при: первоначальном развёртывании, восстановлении после сбоя, изменении маппинга.

5. Трансформация данных

5.1 Денормализация

При индексации данные обогащаются связанными сущностями во избежание JOIN-запросов в OpenSearch:

projects → добавляем account_name, manager_name, property_name, project_status (название)orders   → добавляем account_name, manager_name, company_namecomments → добавляем project_name, project_status, account_name, manager_name

5.2 Вычисляемые поля

Поле Индекс Формула
is_shipped itech_orders, itech_order_items shipping_date_fact IS NOT NULL
revenue_mln itech_accounts SUM(order_items.amount) / 1 000 000
debt_mln itech_accounts SUM(expected_payments где paid_amount < pay_amount) / 1 000 000
order_count itech_accounts COUNT(orders.id)
top_account itech_properties Контрагент с наибольшим числом проектов на объекте

5.3 Нормализация данных

6. Обработка конфликтов и ошибок

6.1 Стратегия при конфликте версий

Правило: последнее изменение по updated_at побеждает.

# При upsert в OpenSearch{  "doc": { ...новые поля... },  "doc_as_upsert": True}

Если updated_at в новой записи меньше, чем в существующей -- запись не обновляется (idempotent операция).

6.2 Обработка ошибок API

Ситуация Поведение
HTTP 429 (rate limit) Пауза 60 сек, повтор
HTTP 5xx (ошибка сервера) Retry 3 раза с экспоненциальной задержкой
HTTP 404 (запись удалена) Удаление из OpenSearch
Таймаут соединения Retry 3 раза, затем запись в лог ошибок
Частичный сбой батча Повтор только ошибочных записей

6.3 Логирование

Каждый запуск синхронизации фиксирует:

{  "run_id": "uuid",  "mode": "incremental",  "started_at": "2026-05-04T09:00:00",  "finished_at": "2026-05-04T09:00:23",  "entities": {    "projects": { "fetched": 42, "indexed": 42, "errors": 0 },    "orders": { "fetched": 7, "indexed": 7, "errors": 0 }  },  "status": "success"}

7. Мониторинг и алерты

Метрика Пороговое значение Действие
Время последней синхронизации > 30 минут назад Алерт администратору
Количество ошибок за запуск > 5% от batch Алерт + запись в лог
Расхождение счётчиков Индекс < 90% от MySQL Запуск полной синхронизации
Недоступность API Grace > 3 неудачных попытки Алерт + пауза 10 минут

8. Требования к API Grace CRM

Для корректной работы интеграции API Grace CRM должен поддерживать:

Требование Параметр Обязательно
Фильтрация по дате изменения ?updated_since=ISO8601 Да
Пагинация ?page=N&per_page=500 Да
Получение записи по ID GET /{entity}/{id} Да
Аутентификация API-ключ в заголовке Да
Rate limit Информация о лимитах Да (для настройки задержек)

Открытый вопрос: наличие webhooks в API Grace CRM уточняется на Этапе 0. При наличии webhooks -- добавить режим event-driven синхронизации в дополнение к cron-polling.

Ролевая модель (RBAC) — Grace CRM Assistant

Версия: 1.0 Дата: 4 мая 2026

Статус: Этап 0 -- согласование файл 04_rbac.md

1. Принципы ролевой модели

2. Роли системы

2.1 Контур Sales AI

Роль ID Назначение
Менеджер по продажам manager Работа со своими проектами, рекомендации, уведомления
Руководитель отдела продаж rop Мониторинг команды, эскалации, аналитика по отделу
Заместитель ГД deputy_gd Стратегическая аналитика, агрегированные данные
Администратор системы admin Управление системой, конфиг, синхронизация

2.2 Контур Knowledge AI

Роль ID Назначение
Ответственный за базу знаний knowledge_manager Загрузка документов, управление базой знаний
Читатель базы знаний knowledge_reader Поиск и просмотр документов

2.3 Системные роли

Роль ID Назначение
Системный интегратор system Межсистемное взаимодействие (API-to-API)

3. Матрица прав доступа

3.1 Данные CRM

Объект manager rop deputy_gd admin
Свои проекты (просмотр) ✅ ✅ ✅ ✅
Все проекты команды (просмотр) ❌ ✅ ✅ ✅
Все проекты компании (просмотр) ❌ ❌ ✅ ✅
Свои клиенты (просмотр) ✅ ✅ ✅ ✅
Все клиенты (просмотр) ❌ ✅ ✅ ✅
Комментарии по своим проектам ✅ ✅ ✅ ✅
Комментарии по всем проектам ❌ ✅ ✅ ✅

3.2 Рекомендации

Действие manager rop deputy_gd admin
Получать рекомендации по своим проектам ✅ ✅ ❌ ✅
Просматривать рекомендации по команде ❌ ✅ ❌ ✅
Подтверждать выполнение рекомендации ✅ ✅ ❌ ✅
Запрашивать рекомендацию вручную ✅ ✅ ❌ ✅

3.3 Аналитика

Объект manager rop deputy_gd admin
Своя воронка продаж ✅ ✅ ✅ ✅
Воронка по команде ❌ ✅ ✅ ✅
Агрегированная аналитика компании ❌ ❌ ✅ ✅
Свой коэффициент качества (Кк) ✅ ✅ ❌ ✅
Кк по команде ❌ ✅ ❌ ✅
Кк агрегированно по отделу ❌ ❌ ✅ ✅
Свой прогноз премии ✅ ✅ ❌ ✅
Прогноз премии по команде ❌ ✅ ❌ ✅
Прогноз премии по всему отделу ❌ ❌ ❌ ✅

Примечание: Зам. ГД видит только агрегированные данные по отделу, без персональных показателей менеджеров.

3.4 База знаний

Действие manager rop deputy_gd knowledge_manager admin
Поиск по базе знаний ✅ ✅ ✅ ✅ ✅
Просмотр документов ✅ ✅ ✅ ✅ ✅
Загрузка документов ❌ ❌ ❌ ✅ ✅
Редактирование документов ❌ ❌ ❌ ✅ ✅
Удаление документов ❌ ❌ ❌ ✅ ✅
Запуск Lint Agent (аудит) ❌ ❌ ❌ ✅ ✅

3.5 Управление системой

Действие manager rop deputy_gd knowledge_manager admin
Запуск синхронизации ❌ ❌ ❌ ❌ ✅
Просмотр статуса синхронизации ❌ ❌ ❌ ❌ ✅
Изменение правил проверки Quality Agent ❌ ❌ ❌ ❌ ✅
Изменение SLA-параметров ❌ ❌ ❌ ❌ ✅
Просмотр audit log ❌ ❌ ❌ ❌ ✅
Управление пользователями и ролями ❌ ❌ ❌ ❌ ✅

3.6 Уведомления

Действие manager rop deputy_gd admin
Получать уведомления о своих проектах ✅ ✅ ❌ ✅
Получать сводку по команде ❌ ✅ ✅ ✅
Получать эскалации ❌ ✅ ✅ ✅
Настраивать предпочтительный канал (Mattermost/Telegram) ✅ ✅ ✅ ✅

4. Изоляция данных: правила фильтрации

Менеджер (role: manager)

projects WHERE manager_id = {current_user_id}
accounts WHERE manager_id = {current_user_id}
  OR assistant_user_id = {current_user_id}
recommendations WHERE manager_id = {current_user_id}
kk_score WHERE manager_id = {current_user_id}
bonus_forecast WHERE manager_id = {current_user_id}

РОП (role: rop)

projects WHERE manager_id IN (
  SELECT id FROM users WHERE department_id = {rop_department_id}
)
-- или конфигурируемый список подчинённых менеджеров

Зам. ГД (role: deputy_gd)

-- Только агрегированные данные, без персональных показателей
SELECT COUNT(*), SUM(amount), AVG(probability_percent)
FROM projects
-- без разбивки по конкретным менеджерам в разделе премий

5. Назначение ролей

5.1 Текущее назначение (I-TECH)

Пользователь Роль в Grace CRM Роль в AI-системе
Менеджеры отдела продаж Продажи manager
Руководитель отдела продаж РОП rop
Заместитель ГД по развитию Зам. ГД deputy_gd
Дмитрий Калдарбеков Руководитель отдела цифровизации admin
Ответственный за базу знаний -- knowledge_manager

5.2 Правила назначения

6. Аутентификация

6.1 Режимы

Режим Применение
SSO через Grace CRM Основной режим для сотрудников I-TECH
JWT Bearer Token Межсистемные интеграции (1С, BI, ERP)
API Key Системные интеграторы (role: system)

6.2 Параметры JWT

Параметр Значение
Алгоритм RS256
Срок действия 8 часов (рабочая смена)
Refresh token 30 дней
Payload user_id, roles[], department_id, exp

7. Audit Log

Все действия пользователей фиксируются со следующими полями:

Поле Описание
timestamp Дата и время события
user_id ID пользователя
user_role Роль на момент действия
action Тип действия (READ / WRITE / DELETE / SYNC / LOGIN)
resource_type Тип объекта (project / recommendation / document / ...)
resource_id ID объекта
ip_address IP-адрес запроса
result success / forbidden / error

Обязательно логируются:

Хранение: audit log хранится 12 месяцев, доступен только admin.

Реестр критических данных и правила контроля качества

файл 05_critical_data.md

1. Назначение

Данный документ определяет перечень критических данных в Grace CRM, подлежащих обязательной проверке Quality Agent, а также правила контроля качества:

Цель: обеспечить достоверность аналитики и корректную работу Recommendation Agent.

2. Принципы контроля качества

3. Реестр объектов и полей

3.1 Проекты (itech_projects)

Поле Тип Обязательность Формат Правило проверки Критичность
account_id integer Обязательно >0 Не NULL Critical
project_status_id integer Обязательно >0 Не NULL Critical
probability_percent integer Обязательно 0–100 Не NULL Critical
forecast_date date Обязательно YYYY-MM-DD Не NULL, ≥ today Critical
next_action text Обязательно строка Не пусто Critical
next_action_date date Обязательно YYYY-MM-DD ≥ today Critical
last_activity_at date Обязательно дата ≤ 30 дней Warning

3.2 Контрагенты (itech_accounts)

Поле Тип Обязательность Формат Правило проверки Критичность
name text Обязательно строка Не пусто Critical
inn keyword Обязательно 10/12 цифр regex Critical
manager_id integer Обязательно >0 Не NULL Critical
reliability keyword Желательно enum red/yellow/green Warning

3.3 Активности / комментарии (itech_comments)

Поле Тип Обязательность Формат Правило проверки Критичность
comment text Обязательно строка длина > 10 Warning
created_at date Обязательно дата не NULL Critical

3.4 Расчёты (itech_calculations)

Поле Тип Обязательность Формат Правило проверки Критичность
project_id integer Обязательно >0 Не NULL Critical
calculation_status keyword Обязательно enum Не NULL Critical
amount double Обязательно >0 >0 Warning

4. Логика выявления пробелов

4.1 Отсутствие обязательных полей

IF field IS NULL → ошибка

4.2 Нарушение бизнес-логики

Примеры:

IF status = "КП отправлено" AND calculations = 0 → ошибка

4.3 Просроченные действия

IF next_action_date < today → ошибка

4.4 Отсутствие активности

IF last_activity_at > 30 дней → warning

5. Расчёт Кк (коэффициента качества данных)

Кк=1−(проектысошибками/общееколичествопроектов)

Где:

6. Выход Quality Agent

Формируется реестр:

Проект

Поле

Ошибка

Ответственный

Срок

7. Эскалации

Условие Действие
Ошибка Critical уведомление менеджеру
Нет реакции > SLA эскалация РОП
Повторная ошибка эскалация Зам. ГД

8. Расширение реестра

Карточки агентов — продуктовый подход

Приложение 6. Карточки агентов -- продуктовый подход

к Акту сдачи-приёмки работ по Этапу 0

Проект: Grace CRM Assistant Договор: №04-002 от 24.04.2026 Исполнитель: ООО «Экобанкинг» Заказчик: ООО «АйТек»

О методе описания

Каждый агент описан через продуктовую формулу:

Продукт -- что конкретно производит агент Внутренний клиент -- кто получает этот продукт (роль или другой агент) Триггер -- при каком условии агент запускается Критерий выполнения -- как проверить, что агент выполнил свою функцию

Такой подход позволяет однозначно определить границы каждого агента, порядок их взаимодействия и критерии приёмки на каждом этапе разработки.

Контур 1 -- Sales AI (Grace CRM Assistant)

Агент 1. Sync Agent -- Агент синхронизации

Продукт:

Актуальный поисковый образ данных Grace CRM в OpenSearch -- гарантирующий, что любой запрос от downstream-агентов отражает реальное состояние CRM на момент последнего запуска.

Элемент Содержание
Внутренний клиент Quality Agent, Recommendation Agent
Механизм CLI -> API Grace CRM -> трансформация -> bulk index в OpenSearch
Триггер Cron по расписанию + ручной запуск администратором
Входные данные API Grace CRM: projects, activities, clients, tasks, comments, calculations, orders, users, objects
Выходной продукт Обновлённые индексы OpenSearch (15 индексов)
Критерий выполнения Все индексы обновлены без ошибок; расхождение Grace CRM / OpenSearch = 0 по завершении синхронизации
Красный флаг Ошибка синхронизации -> downstream-агенты работают на устаревших данных -> все рекомендации невалидны

Режимы работы:

Режим Триггер Что синхронизируется
Инкрементальный Cron каждые 15 минут Изменения с последнего запуска (updated_since)
Полный Ежедневно в 02:00 / ручной запуск Все сущности, полная пересборка индексов

Цепочка ответственности:

Grace CRM (source of truth)    ↓ APISync Agent    ↓ bulk indexOpenSearch (15 индексов) → Quality Agent, Recommendation Agent

Агент 2. Quality Agent -- Агент контроля качества данных

Продукт:

Ежедневный реестр проектов с критическими пробелами данных -- для менеджеров и РОПа -- с указанием конкретного поля, ответственного и срока устранения.

Элемент Содержание
Внутренний клиент 1 Менеджер -- получает задачу на заполнение по своим проектам
Внутренний клиент 2 РОП -- получает сводку по команде и эскалацию при просрочке
Триггер Ежедневно в 09:00 + при изменении статуса проекта
Входные данные OpenSearch: itech_projects, itech_calculations; правила проверки из конфига
Выходной продукт Структурированный реестр: проект -> пробел -> ответственный -> срок; сигнал в Notification Agent
Критерий выполнения Доля проектов с полными данными ≥ 85% (вектор роста); каждый пробел имеет назначенного ответственного

Правила проверки (настраиваются в конфиге без релиза):

Проверка Поле Условие нарушения
Обязательные поля account_id, property_id, project_status_id, probability_new, forecast_date Пусто
Следующий шаг next_action_date Пусто или дата в прошлом
Логика статусов calculation_status При статусе «КП выставлено» -- расчёт отсутствует
Активность last_activity_at Более 30 дней назад для активного проекта

Агент 3. Recommendation Agent -- Агент рекомендаций

Продукт:

Конкретный следующий шаг по каждому активному проекту -- для менеджера -- сформулированный на основе истории CRM и базы знаний RAGflow, доставляемый не позднее 2 часов после изменения статуса или по запросу.

Элемент Содержание
Внутренний клиент Менеджер (первично); РОП (при просрочке реакции менеджера)
Триггер Изменение статуса проекта / запрос менеджера / просрочка контакта
Входные данные OpenSearch: история проекта, активности, комментарии; RAGflow: кейсы, скрипты, возражения
Выходной продукт Рекомендация: действие + срок + обоснование + ссылка на кейс из базы знаний
Критерий выполнения Менеджер знает следующий шаг по каждому активному проекту; нет проектов без зафиксированного следующего действия
Вектор роста Снижение доли проектов без следующего шага; рост конверсии КП -> заказ

Формат рекомендации:

Проект: [название] | Клиент: [название] | Стадия: [статус]
Последний контакт: N дней назад

Рекомендация: [конкретное действие]
Срок: [дата]
Обоснование: [краткое обоснование на основе истории]
Похожий кейс: [ссылка из базы знаний RAGflow]

Агент 4. Notification Agent -- Агент уведомлений

Продукт:

Адресное уведомление нужному человеку в нужный момент через нужный канал -- без информационного шума -- как условие того, что сигналы системы реально доходят и вызывают реакцию.

Элемент Содержание
Внутренний клиент Менеджер / РОП / Зам. ГД -- в зависимости от типа события
Триггер Сигнал от любого агента системы
Входные данные Сигнал от агента + профиль получателя (предпочтительный канал)
Выходной продукт Доставленное уведомление с подтверждённой реакцией
Механизм доставки Adapter pattern: Mattermost (основной) / Telegram (резерв), канал настраивается per-user
Критерий выполнения Реакция (действие или подтверждение) в течение N часов; при отсутствии реакции -- эскалация в Orchestrator
Красный флаг Уведомление без реакции сверх SLA -> передаётся Orchestrator для эскалации

Матрица маршрутизации:

Событие Получатель Приоритет
Пробел в данных по своему проекту Менеджер Нормальный
Рекомендация по проекту Менеджер Нормальный
Просрочка реакции менеджера > SLA РОП Высокий
Критическое событие (крупная сделка, риск ухода клиента) РОП, Зам. ГД Высокий
Ежедневная сводка по команде РОП Плановый

Агент 5. Orchestrator -- Оркестратор

Продукт:

Бесперебойная работа агентной системы как единого целого -- для РОПа и Зам. ГД -- обеспечивающая, что ни одно критическое событие не теряется и каждый сигнал доходит до нужного человека в нужное время.

Элемент Содержание
Внутренний клиент РОП, Зам. ГД
Триггер Постоянно -- реагирует на сигналы всех агентов
Входные данные Сигналы от всех агентов; SLA-параметры из конфига
Выходной продукт Гарантия непрерывности потока сигналов и эскалаций; каждое событие имеет назначенного ответственного
Критерий выполнения Отсутствие потерянных эскалаций; система работает без ручного вмешательства

Примечание: Orchestrator не имеет одного артефактного продукта -- его продукт это состояние системы. Это принципиальное отличие от остальных агентов.

Контур 2 -- Knowledge AI (база знаний)

Агент 6. Ingest Agent -- Агент загрузки знаний

Продукт:

Проиндексированный документ в RAGflow с корректными метаданными -- готовый к поиску Query Agent и использованию Recommendation Agent.

Элемент Содержание
Внутренний клиент Query Agent, Recommendation Agent
Триггер Загрузка нового документа ответственным за базу знаний
Входные данные Документ (PDF, DOCX, MD) + метаданные: отрасль, тип клиента, стадия сделки, продукт, теги
Выходной продукт Проиндексированная запись в RAGflow; обновлённый граф связей
Критерий выполнения Документ доступен для поиска Query Agent; все метаданные заполнены

Обязательные метаданные документа:

Поле Описание Пример
industry Отрасль клиента Энергетика, Строительство
client_type Тип клиента Генподрядчик, Интегратор
deal_stage Стадия сделки Расчёт КП, Переговоры
product Продукт НКУ, ВРУ, БКТП
doc_type Тип документа Кейс, Скрипт, Возражение, Регламент
tags Теги конкуренция, срок, цена

Агент 7. Query Agent -- Агент поиска знаний

Продукт:

Контекстный ответ с цитатой и ссылкой на источник -- для менеджера или Recommendation Agent -- за ≤ 5 секунд.

Элемент Содержание
Внутренний клиент Менеджер (прямой запрос); Recommendation Agent (инструментальный вызов)
Триггер Текстовый запрос менеджера / вызов от Recommendation Agent
Входные данные Текстовый запрос + контекст проекта (отрасль, стадия, тип клиента)
Выходной продукт Ответ + цитата из источника + ссылка на документ
Критерий выполнения Релевантный ответ ≤ 5 секунд; источник указан всегда

Агент 8. Lint Agent -- Агент аудита знаний

Продукт:

Еженедельный отчёт о противоречиях, устаревших данных и логических разрывах в базе знаний -- для ответственного за базу знаний.

Элемент Содержание
Внутренний клиент Ответственный за базу знаний (роль knowledge_manager)
Триггер Еженедельно
Входные данные Все документы в RAGflow
Выходной продукт Отчёт: противоречия, документы старше 6 месяцев, незаполненные разделы
Критерий выполнения Выявлены все документы старше 6 месяцев и документы с конфликтующими утверждениями

Схема взаимодействия агентов

Grace CRM
    ↓ API
[1] Sync Agent ──────────────────────────────────────────────►  OpenSearch
                                                                     │
                                     ┌───────────────────────────────┘
                                     │
                              [5] Orchestrator
                             (управление, SLA)
                                     │
                    ┌────────────────┴────────────────┐
                    ▼                                 ▼
             [2] Quality Agent              [3] Recommendation Agent
             (пробелы в данных)             (следующий шаг) ◄── RAGflow
                    │                                 │        [6] Ingest Agent
                    └────────────────┬────────────────┘        [7] Query Agent
                                     ▼                         [8] Lint Agent
                             [4] Notification Agent
                              (Mattermost / Telegram)
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                 ▼
                Менеджер            РОП            Зам. ГД