DLE/docs/system-messages-management.md

Техническое задание: управление системными сообщениями

1. Цель и контекст

• Обеспечить управляемое отображение системных сообщений на главной странице (/, компонент HomeView.vue) и добавить административный интерфейс для их создания и модерации в разделе контента (/content, компонент ContentListView.vue).
• Системные сообщения должны поддерживать статусы «черновик» и «опубликовано», храниться в базе данных и быть доступны через REST API.

2. Актуальное состояние

• Главная страница строится компонентом HomeView.vue и отображает чат ассистента (ChatInterface.vue), в котором выделены системные сообщения (Message.vue) по признаку message.role === 'system'.
• Раздел контента (ContentListView.vue) содержит карточки переходов: «Создать страницу», «Шаблоны», «Публичные», «Настройка», «Внутренние». Карточки ведут на существующие маршруты content-create, content-templates, content-published, content-settings, content-internal.
• В проекте отсутствуют сущности и API для системных сообщений; текущий pagesService.js работает только со страницами (/pages).

3. Новые пользовательские сценарии

• Просмотр системных сообщений (главная, /):
  • Опубликованные системные сообщения подгружаются в чат ассистента и отображаются в виде свернутых карточек с кликабельным заголовком.
  • При клике на заголовок сообщение раскрывается: в ленте чата отображается полный текст сообщения или отправляется предзаготовленный ответ от ИИ ассистента (контент «ответа» хранится вместе с сообщением и выбирается по флагу reply_type).
  • Сообщения должны явно маркироваться как системные (цвет, иконка). При повторном открытии пользователь видит последнее состояние раскрытия; возможно локальное запоминание «прочитано».
• Раздел «Системные сообщения» (/content):
  • На странице /content появляется новая карточка «Системные сообщения» с кнопкой «Подробнее». Переход ведёт на страницу с пользовательской таблицей (/content/system-messages/table), построенной на уже существующих компонентах таблиц (см. UserTablesList.vue), без отдельного дэшборда карточек.
  • Таблица отображает системные сообщения построчно, с возможностью множественного выбора через чекбоксы; доступные массовые действия: публикация, снятие с публикации, перевод в черновики, удаление.
  • Для каждого сообщения по клику «Подробнее» (внутри строки) открывается просмотр/редактирование с формой (см. ниже).
• Создание/редактирование (/content/system-messages/create, /content/system-messages/:id/edit):
  • Форма с полями: заголовок, краткое описание, основной текст (Markdown/HTML), тип ответа (inline — показывать контент, assistant_reply — отправлять подготовленный ответ от ассистента), поле «Ответ ассистента» (активно при assistant_reply), тег важности (info/warning/danger), дата начала публикации (опционально), дата окончания (опционально), флаг отображения гостям.
  • Кнопки: «Сохранить как черновик», «Опубликовать». При редактировании — «Обновить», «Снять с публикации», «Удалить».
  • Проверки: обязательность заголовка и основного текста (или ответа ассистента в соответствующем режиме); валидация дат (окончание ≥ начало).
• Работа с таблицей системных сообщений:
  • Колонки: чекбокс выбора, заголовок (кликабелен), статус, тип ответа, период действия, целевая аудитория (гости/авторизованные/все), дата создания, автор.
  • Массовые действия выполняются для выбранных строк; одиночные действия доступны через контекстное меню/кнопки в строке (редактировать, опубликовать, снять с публикации, удалить).

4. Требования к интерфейсу

• В ContentListView.vue в сетку management-blocks добавить карточку «Системные сообщения» с кнопкой Подробнее. По дизайну карточка должна соответствовать существующим блокам (заголовок, описание, кнопка).
• Страница с таблицей системных сообщений:
  • Использовать BaseLayout и локальные стили (scoped).
  • Таблица поддерживает сортировку, фильтрацию по статусам и поиск по заголовку.
  • Чекбоксы в шапке и строках для массового выбора; панель действий появляется при наличии выбора.
  • Кнопка «Создать сообщение» открывает форму создания.
• Форма создания/редактирования:
  • Rich-text (минимум Markdown) с предпросмотром и счётчиками символов/слов.
  • Переключатель режима показа (inline/assistant_reply) с условным отображением поля «Ответ ассистента» (можно использовать <transition>).
  • Поле для выбора иконки/цвета по severity (статические пресеты).
• Главная страница:
  • Системные сообщения отображаются в блоке чата как свернутые карточки (system-message-collapsed). При клике заголовок разворачивает карточку (system-message-expanded) или инициирует отправку ассистента (UI показывает «сообщение от ассистента»).
  • Для развёрнутых сообщений предусмотреть кнопку «Свернуть» и (опционально) «Отметить как прочитанное». Состояние хранить в localStorage.

5. Маршрутизация и компоненты

• Добавить маршруты в router/index.js:
• • /content/system-messages/table → SystemMessagesTableView.vue
• • /content/system-messages/create → SystemMessageCreateView.vue
• • /content/system-messages/:id → SystemMessageDetailsView.vue (просмотр)
• • /content/system-messages/:id/edit → SystemMessageEditView.vue
• При необходимости для модальных/вложенных маршрутов можно использовать дочерние маршруты или именованные вью.
• Создать соответствующие Vue-компоненты в src/views/content/system-messages/ и общий набор переиспользуемых элементов (таблица, форма, фильтры, массовые действия) в src/components/system-messages/.
• Создать сервис src/services/systemMessagesService.js с методами для нового API.

6. Требования к API и данным

• Новая таблица system_messages (PostgreSQL):
  • id (uuid, pk)
  • title (text, not null)
  • summary (text, nullable)
  • content (text, not null)
  • reply_type (enum: inline, assistant_reply; default inline)
  • assistant_reply_content (text, nullable; требуется при reply_type = assistant_reply)
  • severity (enum: info, warning, danger; default info)
  • status (enum: draft, published; not null)
  • visible_for (enum: all, authenticated, guests; default all)
  • publish_at (timestamp, nullable)
  • expire_at (timestamp, nullable)
  • created_at, updated_at
  • created_by, updated_by (references users/identities, nullable)
  • slug (text, уникальный, для адресации по ссылке при необходимости)
• REST API (Express):
  • GET /system-messages (пагинация, фильтры по статусу, поиску)
  • GET /system-messages/published (фильтрация по дате/аудитории; публичная)
  • GET /system-messages/:id (доступ только авторизованным редакторам)
  • POST /system-messages (создание; права MANAGE_LEGAL_DOCS)
  • PATCH /system-messages/:id (редактирование; проверка статусов)
  • DELETE /system-messages/:id (мягкое удаление или физическое)
  • POST /system-messages/:id/publish и POST /system-messages/:id/unpublish (опционально, если не использовать PATCH)
• Все защищённые эндпоинты должны требовать авторизацию и права (см. permissions.js, usePermissions).
• Добавить новую миграцию (backend/scripts/run-migrations.js) и ORM/SQL-файлы в существующем формате проекта.
• Обновить логирование и обработку ошибок winston, добавить валидацию входных данных (например, Joi или кастомную).

7. Логика отображения на фронтенде

• HomeView.vue:
  • При инициализации запрашивать опубликованные системные сообщения (учитывая текущую аудиторию) через systemMessagesService.getPublished({ includeExpired: false }).
  • Кэшировать ответ в сторе или локальном состоянии; при подписке на WebSocket можно предусмотреть system_message_updated событие.
  • Добавить обработчик раскрытия: по клику на заголовок либо подставлять полный текст сообщения (inline), либо инициировать цепочку отправки assistant_reply_content в чат (без участия пользователя).
  • Добавить обработчик скрытия сообщения, сохраняющий идентификатор в localStorage и фильтрующий локально.
• ContentListView.vue:
  • Добавить новую карточку «Системные сообщения» в сетку management-blocks, не нарушая адаптивную сетку (обновить grid-template-columns при необходимости).
• Страницы списков:
  • Реализовать пагинацию (lazy loading или обычная), сортировку по дате.
  • Для статусов использовать цветовые бейджи (info/warning/danger).
• Форма создания:
  • Поддерживать сабмит через yarn lint-friendly код; валидация на клиенте (например, с использованием computed/watch).
  • При успешной публикации перенаправлять на список опубликованных; при сохранении черновика — оставаться на странице с уведомлением.

8. Требования к безопасности и доступу

• Сценарии создания/изменения доступны только ролям с PERMISSIONS.MANAGE_LEGAL_DOCS.
• Публичный список (GET /system-messages/published) фильтрует по:
  • status === 'published'.
  • publish_at <= now() (или null).
  • expire_at > now() (или null).
  • visible_for проверяется на основе контекста (гость/авторизованный).
• При выдаче через чат скрывать поля created_by, updated_by, внутренние метки.
• Учитывать CSRF, CORS, rate-limit (перенять конфиг из существующих роутов).

9. Тестирование

• Backend:
  • Юнит-тесты для CRUD в tests/system-messages/*.test.js (Mocha).
  • Проверка фильтров publish/expire и доступа по ролям.
  • Тест миграции (откат/применение).
• Frontend:
  • Юнит-тесты Vue (если настроены) для основных компонентов (форма, список).
  • E2E (при наличии) — сценарий: создание черновика → публикация → отображение на главной.
• Регрессионные проверки:
  • Убедиться, что существующий список контента и чат ассистента продолжают работать без ошибок (yarn lint, yarn test).

10. Интеграция и DevOps

• Обновить docker-compose.yml при необходимости (например, добавить миграции в стартовый процесс).
• Убедиться, что новые переменные окружения (если будут, например, лимиты количества сообщений) документированы в README.md и setup-instruction.md.
• Добавить скрипт seeding (опционально) для тестовых системных сообщений.

11. Открытые вопросы

• Нужно ли хранить историю публикаций (auditing)? Если да — предусмотреть таблицу system_messages_history.
• Требуется ли поддержка многоязычности? (При отсутствии — ограничение на один язык, RU).
• Нужно ли уведомление по WebSocket при появлении новых сообщений? (Если да — добавить событие в wsHub.js).

12. Итоговые артефакты

• Backend: новые маршруты, контроллеры, сервис, миграция.
• Frontend: новые страницы и сервис, обновлённые маршруты и компоненты HomeView, ContentListView.
• Документация: обновление README.md (раздел запуск), application-description.md или tables-system.md при изменении схем, настоящая спецификация.