[_PSSR_drafts] Описание и ТЗ PSSR MVP.docx

Google Docs neutral 2026-04-11 10 чанков ~14 мин чтения

Сущности

AI PSSR API MVP UI ТЗ ИИ JSON docker-compose multi-repo Kernel AI Assist Ingest Kernel API Stack Orchestrator pssr-contracts pssr-kernel

PSSR MVP Итоговое описание и базовые ТЗ Часть 1. Архитектура, границы ответственности, репозитории 1. Назначение системы PSSR MVP это локальная прототипная система, которая принимает события из разнородных источников, детерминированно определяет режим и контур, применяет гейты L0 и L-Law как допуск, фиксирует аудитный след и возвращает результат в форме карточки решения. Система допускает использование ИИ в модулях, где это не критично для допуска, но ускоряет работу оператора, повышает качество разметки и помогает готовить тексты. На текущей фазе система работает на одном локальном компьютере, без требований к промышленной информационной безопасности и сертификации, но с сохранением архитектурной дисциплины, чтобы дальнейшее усиление безопасности не ломало модель. Ключевое требование MVP это воспроизводимость. При одинаковом входном событии и одинаковой версии реестра правил результат определения режима, гейтов и допустимых действий должен быть одинаковым. Это не означает “идеальную истинность”, но означает, что система не будет непредсказуемой. 2. Базовые принципы Принцип единственного исполнителя означает, что только Kernel формирует решения и допускает или блокирует дальнейшие действия. Ни UI, ни коннекторы, ни AI Assist не могут обходить Kernel и не могут производить “выходной текст” напрямую. Это защищает систему от деградации в “набор скриптов” и обеспечивает аудит. Принцип разделения данных означает, что сырьё и артефакты обработки не смешиваются. Сырьё это то, что пришло извне, с минимальными преобразованиями. Артефакты это то, что система вывела и зафиксировала как собственное действие, включая режим, контур, нарушения, протокол и черновики. Разделение нужно для дедупликации, расследований и доказуемости. Принцип “ИИ как ускоритель, не как допуск” означает, что ИИ может резюмировать, извлекать сущности, группировать события, переводить и готовить черновики. Но ИИ не имеет права определять режим, снимать ограничения L0 или L-Law и подтверждать факты как “verified” автоматически. Любой AI-draft, который потенциально может стать внешней формулировкой, обязан пройти повторную проверку через гейты Kernel. Принцип контрактов означает, что все компоненты системы общаются через зафиксированные схемы и OpenAPI, находящиеся в отдельном репозитории contracts. Контракты являются источником истины, а не “договорённостью на словах”. 3. Компонентная архитектура Система состоит из пяти независимых компонент. Kernel. Единственный исполнитель решения. Принимает события, записывает сырьё, связывает события, определяет режим и контур по реестру, применяет гейты, формирует решение, пишет журнал, отдаёт карточку решения и агрегаты для UI. AI Assist. Отдельный сервис помощника. Выполняет суммаризацию, извлечение сущностей, перевод, кластеризацию и генерацию черновиков. Работает только как advisory. Результаты сохраняются в Kernel через специальный API, чтобы у системы было одно хранилище истины. Ingest. Набор коннекторов источников. Каждый коннектор преобразует данные конкретного источника к единой Event Schema и отправляет в Kernel. Ingest хранит только checkpoint и технические состояния, но не хранит решения. UI. Отдельный фронтенд. Реализует три представления: Mobile Console, Desktop Operator, Sitcenter Wall. Работает только через Kernel API. Не содержит логики допуска. Stack Orchestrator. Отдельный репозиторий для сборки локального запуска, docker-compose, конфигурации окружения и тестовых сценариев. 4. Организация репозиториев и выпусков Мы фиксируем multi-repo как базовую организацию. Репозиторий pssr-contracts. Здесь лежат JSON Schema объектов и OpenAPI спецификация Kernel. Здесь же определены enum режимов, контуров, статусов и типы событий. В репозитории есть фиксированные примеры событий и решений для тестов, и генерация артефактов для Python и Node. Контракты имеют версионирование. Любое изменение контрактов идёт через повышение версии и проверку совместимости. Репозиторий pssr-kernel. Здесь только Kernel, его доменная логика, миграции SQLite, тесты воспроизводимости, и реализация OpenAPI. Kernel не содержит ни UI, ни конкретных парсеров YouScan, ни “бизнес-логики источников”. Kernel имеет один файловый каталог артефактов и одну БД. Это специально, чтобы не появилось “двух правд”. Репозиторий pssr-assist. Здесь AI Assist как отдельный HTTP сервис. Он читает данные через Kernel API, генерирует артефакты и возвращает их в Kernel через API сохранения. Assist может использовать Ollama локально. Он не имеет прямого доступа к БД Kernel. Репозитории pssr-ingest-youscan, pssr-ingest-rss, pssr-ingest-import. Каждый коннектор отдельно, чтобы не связывать циклы релизов. Все коннекторы используют общий Python пакет из contracts и отправляют события только в Kernel. В каждом коннекторе есть строгая логика checkpoint: checkpoint обновляется только при успешной обработке событий Kernel. Репозиторий pssr-ui. Отдельный фронтенд на стандартном стеке и Bootstrap 5. Фронт получает типы из contracts. Реализует три view-режима как отдельные маршруты и отдельные layout’ы. Обновление очереди и ситцентра делается через SSE или polling fallback. Репозиторий pssr-stack. В этом репозитории нет доменной логики. Здесь docker-compose, переменные окружения, локальные volume, и документация “как поднять всё локально”. Здесь же могут лежать таблицы тестовых сценариев tabletop, чтобы прогонять ядро на входных наборах. 5. Принципиальные границы ответственности между компонентами Kernel обязан обеспечить, чтобы любое решение существовало только как запись в его журнале. Если запись не сделана, решение не возвращается. Это фундаментальная гарантия. Kernel обязан фиксировать версию реестра в каждом решении. UI обязан отображать режим и контур как доминирующий сигнал, а hard_stop как явное ограничение. UI не может “скрывать” блокировки и не может предлагать действия, которых Kernel не разрешил через next_actions. Ingest обязан быть идемпотентным на уровне источника. Повторный запуск коннектора не должен создавать дублей. Для этого коннектор хранит checkpoint, а Kernel хранит fingerprint и индексы. AI Assist обязан маркировать все результаты как advisory и не должен производить “готовый текст” без повторного gate-check. Любой draft должен быть возвращён в Kernel и проверен, прежде чем UI получит его как “approved draft”. Contracts обязаны оставаться назад-совместимыми как минимум в пределах minor версии. Kernel обязан оставаться назад-совместимым по API хотя бы на период активной разработки MVP, иначе вы будете постоянно чинить UI и ingest вместо развития логики. 6. Выбор UI стека и роль Bootstrap Вы просили заранее заложить стандартные и обкатанные решения. В этой архитектуре Bootstrap 5 фиксируется как базовая дизайн-система. Это означает, что UI проектируется вокруг стандартных компонентов Bootstrap, а кастомные элементы допускаются только в части визуальной индикации режима и hard_stop. Это дисциплинирует интерфейс, ускоряет разработку и снижает риск “UI ради UI”. Так как UI отдельный, опыт показывает, что в дальнейшем sitcenter-экран почти всегда начинает жить по своим законам. Поэтому Sitcenter Wall фиксируется как отдельный маршрут и отдельный layout, а не как “responsive-верстка на тех же компонентах”. Адаптивность используется как техническая мера, но логика отображения различается. 7. Сводка ключевых требований MVP на уровне архитектуры Система должна работать локально, но уже в “правильной” компонентной архитектуре. Kernel должен быть единственным исполнителем решений, а гейты должны быть обязательными. Сырьё и решения разделены. Контракты вынесены отдельно. UI поддерживает телефон, desktop и ситцентр не через попытку “одним экраном”, а через три режима отображения. ИИ ускоряет работу, но не принимает решений и не снимает ограничения. Часть 2. Контракты, API, данные, Router/Gates, next_actions 8. Контракты и версии Репозиторий pssr-contracts является источником истины для объектов и интерфейсов. В MVP контракты включают как минимум: JSON Schema: Event, Decision, AIArtifact, RegistryRule, RegistryTrigger, RegistryProtocol OpenAPI: Kernel API и Assist API Enum: source_type, mode_code, contour_code, severity, decision_status, artifact_type Набор фикстур: примеры входных событий и ожидаемых решений для тестов Версионирование контрактов. Вводится semver. Изменения, которые ломают обратную совместимость, идут только через major. Kernel и UI обязаны проверять совместимость на CI: если контракт обновился, сборка должна упасть, если сервис не соответствует схеме. 9. Канонические перечисления 9.1. SourceType social_listening news internal manual 9.2. ModeCode N0 N1 N2 N3 N4 9.3. ContourCode A S C D 9.4. Severity CRITICAL HIGH MEDIUM LOW 9.5. DecisionStatus APPROVED BLOCKED 9.6. ArtifactType summary entities translation cluster draft sitcenter_brief test_case 10. Контракт Event Event является входным объектом для Kernel. Минимальный объект, который обязан быть принят системой, это source_type, source_name, text. Остальные поля либо заполняются ingest-коннектором, либо проставляются Kernel. Схема Event фиксируется так, чтобы она была стабильной для всех источников. { "type": "object", "required": ["source_type", "source_name", "text"], "properties": { "event_id": { "type": ["string", "null"] }, "source_type": { "type": "string", "enum": ["social_listening","news","internal","manual"] }, "source_name": { "type": "string" }, "source_item_id": { "type": ["string","null"] }, "observed_at": { "type": ["string","null"] }, "received_at": { "type": ["string","null"] }, "url": { "type": ["string","null"] }, "language": { "type": "string", "enum": ["ru","kk","en","unknown"], "default": "unknown" }, "title": { "type": ["string","null"] }, "text": { "type": "string", "minLength": 1 }, "author": { "type": ["string","null"] }, "reach_proxy": { "type": ["number","null"] }, "sentiment_proxy": { "type": ["number","null"] }, "tags": { "type": "array", "items": { "type": "string" } }, "raw_ref": { "type": ["string","null"] }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } Требование. Kernel обязан проставлять received_at. Если observed_at отсутствует, Kernel проставляет observed_at равным received_at и добавляет метку в meta. 11. Контракт Decision Decision является выходным объектом Kernel для любого обработанного Event. Decision обязателен даже если событие заблокировано. Decision является “атомом” обсуждения, аудита и привязки UI. { "type": "object", "required": ["decision_id","created_at","registry_version","mode_code","contour_code","hard_stop","status","violations","reasons","next_actions","links"], "properties": { "decision_id": { "type": "string" }, "created_at": { "type": "string" }, "registry_version": { "type": "integer" }, "mode_code": { "type": "string", "enum": ["N0","N1","N2","N3","N4"] }, "contour_code": { "type": "string", "enum": ["A","S","C","D"] }, "hard_stop": { "type": "boolean" }, "status": { "type": "string", "enum": ["APPROVED","BLOCKED"] }, "violations": { "type": "array", "items": { "type": "object", "required": ["rule_code","rule_type","severity","description"], "properties": { "rule_code": { "type": "string" }, "rule_type": { "type": "string", "enum": ["L0","LLAW"] }, "severity": { "type": "string", "enum": ["CRITICAL","HIGH","MEDIUM","LOW"] }, "description": { "type": "string" } } } }, "reasons": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "required": ["raw_item_id","canonical_event_id"], "properties": { "raw_item_id": { "type": "integer" }, "canonical_event_id": { "type": "integer" } } }, "debug": { "type": ["object","null"], "additionalProperties": true } }, "additionalProperties": false } Требование. decision_id возвращается только если запись решения успешно сохранена в БД. Если запись не сохранена, Kernel отвечает ошибкой. 12. Контракты Registry объектов Правила и триггеры должны быть внешними по отношению к коду, то есть храниться в реестре и версионироваться. RegistryRule: rule_code rule_type (L0 или LLAW) severity description patterns is_active RegistryTrigger: mode_code contour_code (опционально) priority patterns is_active RegistryProtocol: protocol_code name allowed_modes constraints (включая стиль и запреты) is_active В MVP допускается, что RegistryProtocol в начале будет содержать только next_actions по режимам и минимальные текстовые ограничения, а позже будет расширяться. 13. Kernel API (OpenAPI смысловые эндпойнты) 13.1. Обработка события POST /event Вход: Event Выход: Decision Гарантии: записывается raw_item создаётся или выбирается canonical_event вычисляется режим и контур применяются гейты записывается decision возвращается Decision 13.2. Получение решения GET /decision/{decision_id} Выход: Decision + расширенная карточка для UI, включая нормализацию и ссылки на связанные raw_items, если запрошено параметрами. Для MVP можно сделать два режима: краткий (по умолчанию) полный (include=details) 13.3. Очередь GET /queue?limit=50&mode=N2&status=BLOCKED Выход: массив элементов очереди. Каждый элемент содержит минимум: decision_id created_at mode_code contour_code status source_name короткий preview текста (первые N символов) hard_stop 13.4. Sitcenter агрегаты GET /sitcenter/summary Выход: текущий режим системы (как агрегат по последним решениям или как “последнее состояние”) количество событий по режимам за период количество blocked за период топ причин блокировок последние решения N3/N2 13.5. Sitcenter поток GET /sitcenter/stream (SSE) Выход: события обновления очереди и агрегатов, чтобы большой экран обновлялся без перезагрузки. 13.6. Реестр GET /registry/rules POST /registry/rules GET /registry/triggers POST /registry/triggers GET /registry/protocols POST /registry/protocols Требование. Любое изменение реестра увеличивает registry_version и фиксируется в журнале реестра (в MVP можно журналировать изменения как отдельную таблицу или через системные decisions типа “REGISTRY_UPDATE”). 14. Kernel: хранение и транзакционность Kernel использует SQLite и файловое хранилище артефактов. Требование. Обработка /event обязана быть транзакционной минимум на уровне: raw_item + canonical_event link + decision. Если что-либо не записалось, decision не возвращается. 15. Формальная спецификация нормализации и fingerprint Нормализация для fingerprint должна быть: воспроизводимой консервативной не зависящей от внешних библиотек, которые могут менять поведение между версиями без явного контроля MVP нормализация: lowercasing удаление двойных пробелов замена табов на пробелы удаление невидимых символов обрезка до разумного лимита (например 20 000 символов) с фиксацией в meta, если было обрезание Fingerprint: hash(normalized_text + “|” + source_name + “|” + (source_item_id or “-”) + “|” + (url or “-”)) Важное уточнение. fingerprint не является “истиной” дедупликации, это практическая эвристика. Поэтому система хранит и fingerprint, и source_item_id, и url. Это позволяет позже улучшать дедуп без потери данных. 16. Router: формальная спецификация Router использует registry_triggers. Алгоритм Router в MVP детерминированный и основан на pattern matching. Псевдокод: candidates = [] for t in active registry_triggers: if matches_any(t.patterns, normalized_text): candidates.append(t) if empty: mode = "N0" contour = default_contour("N0") else: max_pr = max(c.priority for c in candidates) top = [c for c in candidates if c.priority == max_pr] if len(top) == 1: chosen = top[0] else: chosen = tie_break(top) mode = chosen.mode_code contour = chosen.contour_code or default_contour(mode) Tie-break фиксируется в коде и тестируется. Tie-break правило: выбирается более жёсткий режим по порядку N4 > N3 > N2 > N1 > N0. Если режим одинаковый, выбирается тот, где contour указан явно. Если и это одинаково, выбирается первый по стабильной сортировке (например по id триггера). Default contour фиксируется в реестре или в коде, но должен быть единственным источником истины. Для MVP допустимо зафиксировать в коде. Позже лучше вынести в registry_protocols. 17. Gates: формальная спецификация Гейт L-Law имеет приоритет. Если срабатывает LLAW правило, то hard_stop устанавливается в true и статус решения становится BLOCKED независимо от L0. Псевдокод: violations = [] if matches_any(LLAW.patterns): violations += LLAW violations hard_stop = true status = BLOCKED next_actions = next_actions_for_hard_stop(mode) return if matches_any(L0.patterns): violations += L0 violations hard_stop = false status = BLOCKED next_actions = next_actions_for_l0_block(mode) return hard_stop = false status = APPROVED next_actions = next_actions_for_mode(mode) Важное уточнение. Даже при APPROVED next_actions ограничивают то, что UI имеет право предложить оператору. APPROVED не означает “публикация разрешена”, это означает “событие допускается к дальнейшим разрешённым операциям”. 18. Next_actions: спецификация Next_actions являются ключевым мостом между логикой Kernel и UX. Они должны быть достаточно грубыми, чтобы не зависеть от конкретного UI, но достаточно конкретными, чтобы UI мог ограничить сценарии. В MVP фиксируем минимальный набор действий как строковые коды. Базовые действия: ACTION_LOG_ONLY (зафиксировать и оставить в мониторинге) ACTION_REQUEST_VERIFICATION (пометить UNVERIFIED и запросить подтверждение) ACTION_ESCALATE (эскалация оператору/руководителю) ACTION_PREPARE_BRIEF (подготовить краткую сводку) ACTION_PREPARE_DRAFT (подготовить черновик формулировки) ACTION_USE_TEMPLATE (использовать шаблон, без свободного текста) ACTION_FREEZE_OUTPUT (запрет на любые внешние тексты) Правило по режимам в MVP: В N0 обычно доступны LOG_ONLY, REQUEST_VERIFICATION, PREPARE_DRAFT, PREPARE_BRIEF. В N2 обычно доступны REQUEST_VERIFICATION, ESCALATE, PREPARE_BRIEF, PREPARE_DRAFT с ограничениями. В N3 доступны ESCALATE, PREPARE_BRIEF, USE_TEMPLATE, FREEZE_OUTPUT. При hard_stop всегда доступен FREEZE_OUTPUT, и недоступен PREPARE_DRAFT. Детальные правила и связка с протоколами должны быть в registry_protocols. В MVP можно захардкодить матрицу next_actions в Kernel и позже вынести в реестр, но при этом необходимо зафиксировать её как часть версии Kernel и покрыть тестами. Часть 3. AI Assist, коннекторы, UI, CI/CD, критерии приёмки 19. AI Assist: архитектура и API AI Assist реализуется как отдельный сервис pssr-assist. Его назначение — ускорять и улучшать качество работы оператора без вмешательства в логику допуска. Assist не имеет прямого доступа к БД Kernel. Все операции сохранения происходят через API Kernel. 19.1. Поток взаимодействия Сценарий “AI summary”: UI запрашивает у Assist summary по canonical_event_id. Assist запрашивает через Kernel API все raw_items данного canonical_event. Assist генерирует summary. Assist отправляет в Kernel POST /ai/artifact. Kernel сохраняет ai_artifact. UI получает результат через Kernel. Сценарий “AI draft”: UI запрашивает draft по decision_id и protocol_code. Assist запрашивает через Kernel API: decision режим протокол Assist генерирует draft. Assist отправляет draft в Kernel POST /ai/draft-check. Kernel выполняет повторный gate-check. Kernel сохраняет draft как ai_artifact с gate_result. Kernel возвращает статус draft: APPROVED или BLOCKED. UI отображает draft только с указанием результата проверки. Assist не имеет права напрямую возвращать draft в UI без прохождения через Kernel. 19.2. Assist API (минимальный) POST /assist/summary Вход: canonical_event_id POST /assist/entities Вход: raw_item_id POST /assist/draft Вход: decision_id protocol_code Assist API является внутренним. В продакшене его может вызывать только UI или оркестратор. 19.3. Ограничения AI Assist Не может менять режим. Не может менять hard_stop. Не может менять registry_version. Не может напрямую писать в БД Kernel. Все результаты помечаются как advisory. 20. Коннекторы: формализация Коннектор — отдельный сервис, который: получает данные из источника, приводит к Event Schema, отправляет в Kernel. Коннектор обязан быть идемпотентным. 20.1. Общие требования к коннекторам Наличие checkpoint (last_processed_id или timestamp). Checkpoint обновляется только после успешного ответа Kernel. Повторный запуск не создаёт дублей. При ошибке Kernel коннектор логирует и повторяет попытку. Коннектор не хранит решений. 20.2. YouScan Connector Функция: получать mentions через API маппить в Event Schema отправлять в Kernel Дополнительные поля: reach_proxy sentiment_proxy platform engagement Checkpoint: хранится локально (файл или SQLite) обновляется после успешной обработки партии 20.3. RSS Connector Функция: регулярный polling RSS hash URL+title отправка в Kernel Дедупликация: если URL уже обработан, событие не отправляется повторно 20.4. Manual Import Connector Функция: загрузка файла (CSV/JSON) преобразование строк в Event отправка в Kernel Используется для tabletop-тестов. 21. UI: детальная спецификация UI реализуется как отдельное SPA или веб-приложение с Bootstrap 5. 21.1. Mobile Console Экран: список последних решений карточка выбранного события режим (крупно) статус (APPROVED/BLOCKED) кнопки next_actions Особенности: минимальное количество текста collapsible детали крупная индикация hard_stop 21.2. Desktop Operator Экран: очередь карточка решения блок violations блок next_actions блок AI artifacts ссылка на Decision Viewer 21.3. Sitcenter Wall Экран: текущий режим (очень крупно) индикатор hard_stop количество событий по режимам последние решения N2/N3 топ нарушений Особенности: read-only обновление через SSE минимальное взаимодействие 22. CI/CD и контроль качества Каждый репозиторий имеет свой CI: contracts: проверка схем kernel: unit-тесты Router и Gates assist: тест генерации и возврата draft ingest: тест идемпотентности ui: типизация и проверка контрактов Интеграционные тесты: запуск всего стека через docker-compose отправка тестовых событий проверка, что режимы совпадают с ожиданиями проверка, что blocked события не дают draft 23. Критерии приёмки MVP Kernel: Детерминированный режим. L-Law блокирует корректно. registry_version фиксируется. Нет решения без decision_id. Assist: Генерирует summary. Draft проходит повторную проверку. Заблокированный draft отображается как BLOCKED. Ingest: Нет дублей при повторном запуске. Checkpoint работает. UI: Отображает режим. Отображает hard_stop. Не предлагает запрещённых действий. Sitcenter: Обновляется автоматически. Показывает агрегаты корректно. 24. Итоговое состояние MVP В результате вы получаете: раздельные сервисы, воспроизводимое ядро, масштабируемую архитектуру, возможность расширять источники, возможность усиливать безопасность позже, возможность заменить фронтенд без переписывания Kernel.