Skip to content

AI Agent Context: Service Text Management

This document provides high-density technical context for AI agents working on the Service Text Management feature. Use this to understand the internal machinery, state transitions, and integration points.

1. Core Logic & Intent

The system manages a versioned, multi-step workflow for transforming and approving service-related text (descriptions, etc.). It decouples "Original Text" from "Published Content" to allow for AI processing (Translate, Sanitize, Enhance) and human review.

2. Technical Data Model (PostgreSQL)

Tables & Relationships

  • partner_service_translatable_fields_catalog: Configuration table. Defines which JSON keys in partner_services are eligible for this workflow.
  • partner_service_text_fields: Anchor table. Links service_id and field_key (e.g., description).
  • partner_service_text_revisions: Versioning table. Each edit to the "Original Text" creates a new revision.
    • Critical Field: status (Enum: DRAFT, AWAITING_ADMIN_ACTIONS, PROCESSING_AI, AWAITING_PARTNER_APPROVAL, AWAITING_ADMIN_APPROVAL, PUBLISHED).
  • partner_service_text_variants: Multilingual storage. Linked to revision_id. Stores final_text plus intermediate AI outputs (sanitized_text, enhanced_text, summary_text).
  • partner_service_text_approvals: Workflow tracking. Stores partner_approved_at, admin_approved_at, and published_at.

3. State Machine & Transitions

Current Status Action Next Status Triggered By Side Effects
DRAFT request-approval AWAITING_ADMIN_ACTIONS Partner Notify Admin (WS)
AWAITING_ADMIN_ACTIONS trigger-ai PROCESSING_AI Admin Publish RMQ: service_text.process.requested
PROCESSING_AI callback-success AWAITING_PARTNER_APPROVAL System (AI) Save Variants, Notify Partner (WS)
PROCESSING_AI callback-failed DRAFT System (AI) Save error to admin_note, Notify Admin
AWAITING_PARTNER_APPROVAL approve AWAITING_ADMIN_APPROVAL Partner Update partner_approved_at, Notify Admin
AWAITING_ADMIN_APPROVAL approve PUBLISHED Admin Update admin_approved_at, published_at
Any edit-original DRAFT Partner/Admin Resets approvals for the revision

4. Communication Protocols

RabbitMQ (Exchange: partner.events)

  • Outgoing: service_text.process.requested
  • Payload: { revisionId, serviceId, fieldKey, originalLanguage, originalText, requestedActions: { actions: string[] }, locales: string[] }
  • Internal/Other: service_text.revision.created, service_text.approved, service_text.published.

WebSockets (Service: notification-service)

  • Channels: admin, partner:{serviceId}.
  • Events: service_text:revision:created, service_text:ai_processing:completed, service_text:published, etc.

HTTP Callbacks

  • AI to Partner: POST /api/internal/service-texts/revisions/:revisionId/results
  • Body: { revision_id, status: 'success'|'failed', variants: Array<{ locale, final_text, sanitized_text?, enhanced_text?, summary_text? }>, error_message? }

5. Critical Files & Entry Points

Backend (partner-service)

  • src/modules/service-texts/service-texts.service.ts: THE source of truth for business logic and DB transactions.
  • src/modules/service-texts/entities/service-text.entity.ts: TypeScript interfaces mirroring DB schema.
  • src/modules/service-texts/admin-service-texts.controller.ts: Admin-only actions (Catalog, AI trigger).
  • src/modules/service-texts/service-texts.controller.ts: Partner actions (Drafting, Approving).

Backend (ai-service)

  • app/services/rabbitmq_consumer.py: Logic for applying AI tools and performing the HTTP callback.

Frontend Integration

  • partner-console: src/components/organisms/ServiceManagement/ServiceTextManagement.tsx.
  • admin-console: src/pages/ServiceTextsPage/ServiceTextsPage.tsx.

6. Common Patterns & Troubleshooting

Adding a New Translatable Field

  1. Insert a record into partner_service_translatable_fields_catalog.
  2. The Frontend will automatically list it if enabled=true.

How to Write Tests

  • Unit: Mock DatabaseService and RabbitmqService in ServiceTextsService to test status transition logic.
  • Integration: POST to /revisions, then manually trigger the internal results endpoint to simulate AI completion.

Potential Bug Hotspots

  • SQL Parameter Indexing: Be careful with dynamic queries in ServiceTextsService (always check $1, $2 sequence).
  • Draft Resets: Any change to original_text MUST reset the status to DRAFT and clear approvals (implemented in updateRevision).
  • Locale Mismatches: Ensure locales requested match what the AI service produces.
  • Sanitization: All text inputs (original_text) and outputs (final_text, AI variants) are sanitized via sanitize-html in partner-service and bleach in ai-service to prevent XSS. The sanitization mode (plain/html/markdown) is derived from the catalog.

7. Future Extensions

  • HTML/Markdown Support: Catalog has input_kind, but currently treated as plain text.
  • AI Tool Configuration: Adding new tools (e.g., "Keyword Extraction") requires updating the ServiceTextAction enum and the AI consumer.
  • Batch Processing: Currently 1 revision = 1 message. Large services might need batching.