IAV-91/feat(customer-care): add main agent creation endpoint for merchant clients

🎯 Objective

Implement the ability to create main agents for the customer care agent family system, linked to merchant clients.

📋 Changes Overview

New Components

• Controller Layer: AgentController

  • Endpoint: POST /api/customer-care/agents/main-agent
  • Accepts MainAgentRequest with validation
  • Returns AgentResponseDTO with HTTP 201 status

• Service Layer: AgentService

  • Main agent creation business logic
  • Integration with UserService for merchant validation
  • Orchestration with N8nService and FileManagerService

• Domain Models:

  • Agent: Core agent entity with audit fields
  • AgentLanguage: Multi-language support for agents

• DTOs:

  • MainAgentRequest: Request payload with validation constraints
  • AgentResponseDTO: Response structure
  • AgentLanguageDTO: Language-specific agent data

• Data Access:

  • AgentRepository: JPA repository for agents
  • AgentLanguageRepository: JPA repository for agent languages

• Mapping: AgentMapper for entity-DTO conversions

Architecture

Controller → Service → Repository
              ↓
         External Services (N8n, FileManager, User)

🔍 Key Features

• ✅ RESTful API endpoint for agent creation
• ✅ Input validation using Jakarta Validation
• ✅ Multi-language agent support
• ✅ Merchant client validation
• ✅ External service integration readiness
• ✅ Proper error handling with custom exceptions
• ✅ Audit trail support (createdBy, createdDate, etc.)

🧪 Testing Checklist

• Unit tests for AgentService
• Integration tests for AgentController endpoint
• Validation tests for MainAgentRequest
• Repository tests for data persistence
• External service integration

📚 API Documentation

Endpoint: POST /api/customer-care/agents/main-agent Query Param: userUid (required) Request Body: MainAgentRequest Response: AgentResponseDTO (201 Created)

Closes IAV-91