Service Text Management¶

Overview¶

The Service Text Management feature provides a robust workflow for managing translatable, sanitized, and enhanced text for partner services (e.g., descriptions, short descriptions). It moves away from simple hardcoded text fields to a versioned, AI-augmented, and dual-approval system.

Key capabilities: - Multilingual Support: Pre-generation of translations for all supported locales. - AI Transformations: Integrated tools for sanitization (moderation), enhancement, and summarization. - Dual Approval Workflow: Requires both partner and admin approval before content is published. - Versioning & History: Full audit trail of changes, authorship, and notes. - Real-time Updates: WebSocket notifications for status changes and approval requests.

Implementation Status¶

Task	Status	Description
Data Modeling	✅ Completed	Created PostgreSQL tables for fields, revisions, variants, approvals, and catalog.
Backend Logic	✅ Completed	Implemented `ServiceTextsService` with revision lifecycle and AI integration.
AI Integration	✅ Completed	Updated `ai-service` to handle text transformation tasks and callback results.
Partner Console	✅ Completed	Added "Content" tab for partners to manage drafts and request publication.
Admin Console	✅ Completed	Created "Content Review" interface for admins to trigger AI and manage approvals.
Public Integration	✅ Completed	Added public endpoints and service to fetch published content in `public-fo`.

Data Model¶

The feature uses five main tables in the partner-service database:

partner_service_translatable_fields_catalog: Defines which fields (e.g., description) are eligible for this workflow.
partner_service_text_fields: Links a specific service and field key to an original language.
partner_service_text_revisions: Stores versions of the original text, status, and metadata.
partner_service_text_variants: Stores the transformed text (sanitized, enhanced, translated) for each locale.
partner_service_text_approvals: Tracks approval timestamps and publication status.

Workflows¶

1. Content Revision Lifecycle¶

The following diagram illustrates the states a text revision goes through from creation to publication:

stateDiagram-v2
    [*] --> DRAFT: Partner/Admin Creates
    DRAFT --> AWAITING_ADMIN_ACTIONS: Partner Requests Publication
    AWAITING_ADMIN_ACTIONS --> PROCESSING_AI: Admin Triggers AI
    PROCESSING_AI --> AWAITING_PARTNER_APPROVAL: AI Success (Automatic)
    PROCESSING_AI --> DRAFT: AI Failure
    AWAITING_PARTNER_APPROVAL --> AWAITING_ADMIN_APPROVAL: Partner Approves
    AWAITING_ADMIN_APPROVAL --> PUBLISHED: Admin Approves
    PUBLISHED --> [*]

    AWAITING_ADMIN_APPROVAL --> AWAITING_PARTNER_APPROVAL: Admin Rejects/Edits
    AWAITING_PARTNER_APPROVAL --> DRAFT: Partner Edits Original

2. AI Transformation Flow¶

Trigger: Admin clicks "Trigger AI" in the Admin Console.
Request: partner-service publishes a service_text.process.requested message to RabbitMQ.
Processing: ai-service consumes the message, applies requested tools (sanitize, enhance, summarize), and translates to all target locales.
Callback: ai-service calls the internal endpoint in partner-service with the results.
Update: partner-service saves variants and updates the revision status.

API Reference¶

Partner API (`partner-service`)¶

POST /api/partners/:partnerId/services/:serviceId/text-fields/:fieldKey/revisions

Endpoint	Method	Description
`/text-fields`	GET	List translatable fields for a service.
`/:fieldKey/revisions`	POST	Create a new draft revision.
`/revisions/:revisionId`	GET/PATCH	Get or update a specific revision.
`/revisions/:revisionId/request-approval`	POST	Move status to `AWAITING_ADMIN_ACTIONS`.
`/revisions/:revisionId/approve`	POST	Partner approval.
`/revisions/:revisionId/variants`	GET/PATCH	Manage translated versions.

Admin API (`partner-service`)¶

POST /api/admin/service-texts/...

Endpoint	Method	Description
`/catalog`	GET/POST/PUT	Manage the translatable fields catalog.
`/revisions/:revisionId/trigger-ai`	POST	Trigger AI processing for a revision.
`/revisions/:revisionId/approve`	POST	Admin approval (Final step to publish).
`/revisions/:revisionId/request-partner-approval`	POST	Request partner to review AI changes.

Public API (`partner-service`)¶

GET /api/public/services/:serviceId/text-fields/:fieldKey?locale=...

Returns the final_text of the most recently published revision for the specified locale.

Frontend Components¶

Partner Console¶

ServiceTextManagement: A comprehensive component found in the "Content" tab of the Service Edit page. It allows partners to edit original text, select desired AI actions, and track the approval progress.

Admin Console¶

ServiceTextsPage: Accessible via "Content Review" in the sidebar. Allows admins to see all pending revisions, review original text, trigger AI processing, and manually edit or approve variants.

Implemented Code & Files¶

Backend (`partner-service`)¶

src/modules/service-texts/: New module containing entities, DTOs, service, and controllers (Partner, Admin, Internal, Public).
src/common/database/database.service.ts: Updated with schema definitions for text management tables.
src/app.module.ts: Registered ServiceTextsModule.

Backend (`ai-service`)¶

app/services/rabbitmq_consumer.py: Implemented handler for service_text.process.requested events and logic to call AI tools and callback results.
app/core/config.py: Added PARTNER_SERVICE_URL.

Frontends¶

partner-console/src/components/organisms/ServiceManagement/ServiceTextManagement.tsx: New management component.
admin-console/src/pages/ServiceTextsPage/ServiceTextsPage.tsx: New review page.
public-fo/src/services/partner-service.service.ts: Service to fetch published transformed text.

Example: AI Processing Request¶

RabbitMQ Message Content:

{
  "payload": {
    "revisionId": "uuid-123",
    "serviceId": "uuid-service",
    "fieldKey": "description",
    "originalLanguage": "pt",
    "originalText": "Uma experiência incrível em Portugal.",
    "requestedActions": {
      "actions": ["sanitize", "enhance", "translate"]
    },
    "locales": ["en", "es", "pt"]
  }
}