DLE/docs-en/system-messages-management.md

Technical Specification: System Messages Management

1. Goal and Context

• Provide managed display of system messages on the main page (/, component HomeView.vue) and add an administrative interface for their creation and moderation in the content section (/content, component ContentListView.vue).
• System messages must support "draft" and "published" statuses, be stored in the database, and be accessible via REST API.

2. Current State

• The main page is built by component HomeView.vue and displays the assistant chat (ChatInterface.vue), in which system messages (Message.vue) are highlighted by the message.role === 'system' attribute.
• The content section (ContentListView.vue) contains navigation cards: "Create Page", "Templates", "Public", "Settings", "Internal". Cards lead to existing routes content-create, content-templates, content-published, content-settings, content-internal.
• The project lacks entities and API for system messages; current pagesService.js works only with pages (/pages).

3. New User Scenarios

• Viewing System Messages (main page, /):
  • Published system messages are loaded into the assistant chat and displayed as collapsed cards with clickable headers.
  • When clicking the header, the message expands: the chat feed displays the full message text or sends a pre-prepared response from the AI assistant (the "response" content is stored with the message and selected by the reply_type flag).
  • Messages must be explicitly marked as system (color, icon). When reopened, the user sees the last expansion state; local "read" memory is possible.
• "System Messages" Section (/content):
  • On the /content page, a new "System Messages" card appears with a "Details" button. Navigation leads to a page with a user table (/content/system-messages/table), built on existing table components (see UserTablesList.vue), without a separate dashboard of cards.
  • The table displays system messages row by row, with multiple selection via checkboxes; available bulk actions: publish, unpublish, move to drafts, delete.
  • For each message, clicking "Details" (within the row) opens view/edit with a form (see below).
• Create/Edit (/content/system-messages/create, /content/system-messages/:id/edit):
  • Form with fields: title, brief description, main text (Markdown/HTML), response type (inline — show content, assistant_reply — send prepared assistant response), "Assistant Reply" field (active when assistant_reply), importance tag (info/warning/danger), publication start date (optional), end date (optional), flag for guest display.
  • Buttons: "Save as Draft", "Publish". When editing — "Update", "Unpublish", "Delete".
  • Validations: title and main text required (or assistant reply in corresponding mode); date validation (end ≥ start).
• Working with System Messages Table:
  • Columns: selection checkbox, title (clickable), status, response type, active period, target audience (guests/authenticated/all), creation date, author.
  • Bulk actions are performed for selected rows; single actions available via context menu/buttons in row (edit, publish, unpublish, delete).

4. Interface Requirements

• In ContentListView.vue, add "System Messages" card to the management-blocks grid with a Details button. The card design should match existing blocks (header, description, button).
• System messages table page:
  • Use BaseLayout and local styles (scoped).
  • Table supports sorting, filtering by status, and search by title.
  • Checkboxes in header and rows for bulk selection; action panel appears when selection exists.
  • "Create Message" button opens creation form.
• Create/Edit Form:
  • Rich-text (minimum Markdown) with preview and character/word counters.
  • Display mode toggle (inline/assistant_reply) with conditional display of "Assistant Reply" field (can use <transition>).
  • Field for icon/color selection by severity (static presets).
• Main Page:
  • System messages are displayed in the chat block as collapsed cards (system-message-collapsed). Clicking the header expands the card (system-message-expanded) or initiates assistant sending (UI shows "message from assistant").
  • For expanded messages, provide "Collapse" button and (optionally) "Mark as Read". Store state in localStorage.

5. Routing and Components

• Add routes in router/index.js:
• • /content/system-messages/table → SystemMessagesTableView.vue
• • /content/system-messages/create → SystemMessageCreateView.vue
• • /content/system-messages/:id → SystemMessageDetailsView.vue (view)
• • /content/system-messages/:id/edit → SystemMessageEditView.vue
• If needed for modal/nested routes, child routes or named views can be used.
• Create corresponding Vue components in src/views/content/system-messages/ and a common set of reusable elements (table, form, filters, bulk actions) in src/components/system-messages/.
• Create service src/services/systemMessagesService.js with methods for the new API.

6. API and Data Requirements

• New Table 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; required when 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, unique, for addressing by link if needed)
• REST API (Express):
  • GET /system-messages (pagination, filters by status, search)
  • GET /system-messages/published (filtering by date/audience; public)
  • GET /system-messages/:id (access only for authorized editors)
  • POST /system-messages (creation; MANAGE_LEGAL_DOCS permission)
  • PATCH /system-messages/:id (editing; status checks)
  • DELETE /system-messages/:id (soft delete or physical)
  • POST /system-messages/:id/publish and POST /system-messages/:id/unpublish (optional, if not using PATCH)
• All protected endpoints must require authorization and permissions (see permissions.js, usePermissions).
• Add new migration (backend/scripts/run-migrations.js) and ORM/SQL files in the project's existing format.
• Update logging and error handling winston, add input validation (e.g., Joi or custom).

7. Frontend Display Logic

• HomeView.vue:
  • On initialization, request published system messages (considering current audience) via systemMessagesService.getPublished({ includeExpired: false }).
  • Cache response in store or local state; when subscribing to WebSocket, can provide system_message_updated event.
  • Add expansion handler: on header click, either substitute full message text (inline), or initiate sending assistant_reply_content to chat (without user participation).
  • Add message hiding handler, saving identifier in localStorage and filtering locally.
• ContentListView.vue:
  • Add new "System Messages" card to the management-blocks grid, without breaking the adaptive grid (update grid-template-columns if needed).
• List Pages:
  • Implement pagination (lazy loading or regular), sorting by date.
  • For statuses, use color badges (info/warning/danger).
• Creation Form:
  • Support submit via yarn lint-friendly code; client-side validation (e.g., using computed/watch).
  • On successful publication, redirect to published list; when saving draft — stay on page with notification.

8. Security and Access Requirements

• Creation/editing scenarios available only to roles with PERMISSIONS.MANAGE_LEGAL_DOCS.
• Public list (GET /system-messages/published) filters by:
  • status === 'published'.
  • publish_at <= now() (or null).
  • expire_at > now() (or null).
  • visible_for is checked based on context (guest/authenticated).
• When issuing through chat, hide fields created_by, updated_by, internal tags.
• Consider CSRF, CORS, rate-limit (adopt config from existing routes).

9. Testing

• Backend:
  • Unit tests for CRUD in tests/system-messages/*.test.js (Mocha).
  • Check publish/expire filters and role-based access.
  • Test migration (rollback/apply).
• Frontend:
  • Vue unit tests (if configured) for main components (form, list).
  • E2E (if available) — scenario: create draft → publish → display on main page.
• Regression Checks:
  • Ensure existing content list and assistant chat continue to work without errors (yarn lint, yarn test).

10. Integration and DevOps

• Update docker-compose.yml if needed (e.g., add migrations to startup process).
• Ensure new environment variables (if any, e.g., message count limits) are documented in README.md and setup-instruction.md.
• Add seeding script (optional) for test system messages.

11. Open Questions

• Is publication history (auditing) needed? If yes — provide system_messages_history table.
• Is multilingual support required? (If absent — limit to one language, EN).
• Is WebSocket notification needed when new messages appear? (If yes — add event to wsHub.js).

12. Final Artifacts

• Backend: new routes, controllers, service, migration.
• Frontend: new pages and service, updated routes and components HomeView, ContentListView.
• Documentation: update README.md (launch section), application-description.md or tables-system.md when schemas change, this specification.