openapi: 3.0.3
info:
  title: Centron Enterprise Application REST API
  description: |
    Comprehensive REST API specification for the Centron Enterprise Application.
    This API provides access to all core business functionality including CRM,
    financial management, helpdesk, project management, and administrative functions.

    The API implements a dual-architecture pattern supporting both direct database
    and web service access through the ILogic interface pattern.
  version: 1.0.0
  contact:
    name: Centron Development Team
    email: support@c-entron.de
  license:
    name: Proprietary
    url: https://c-entron.de/license

servers:
  - url: https://api.centron.local/v1
    description: Production Server
  - url: https://api-dev.centron.local/v1
    description: Development Server
  - url: https://api-test.centron.local/v1
    description: Testing Server

security:
  - BearerAuth: []
  - ApiKeyAuth: []

paths:
  # Authentication and User Management
  /login:
    post:
      tags:
        - Authentication
      summary: User Authentication
      description: Authenticate user credentials and obtain access token
      operationId: authenticateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /logout:
    post:
      tags:
        - Authentication
      summary: User Logout
      description: Invalidate current session and access token
      operationId: logoutUser
      security:
        - BearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  # Customer Management
  /GetCustomers:
    post:
      tags:
        - Customer Management
      summary: Get Customer List
      description: Retrieve customers based on filter criteria
      operationId: getCustomers
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerFilterRequest'
      responses:
        '200':
          description: Customer list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /SaveCustomer:
    post:
      tags:
        - Customer Management
      summary: Save Customer
      description: Create or update customer information
      operationId: saveCustomer
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveCustomerRequest'
      responses:
        '200':
          description: Customer saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /DeleteCustomer:
    post:
      tags:
        - Customer Management
      summary: Delete Customer
      description: Delete customer by ID with validation
      operationId: deleteCustomer
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCustomerRequest'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  # Financial Management
  /GetAccountNavInfo:
    post:
      tags:
        - Financial Management
      summary: Get Account Navigation Information
      description: Retrieve account overview for the logged-in user
      operationId: getAccountNavInfo
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountNavRequest'
      responses:
        '200':
          description: Account navigation information retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNavResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /GetIncomingPayments:
    post:
      tags:
        - Financial Management
      summary: Get Incoming Payments
      description: Retrieve incoming payments based on filter criteria
      operationId: getIncomingPayments
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingPaymentsFilterRequest'
      responses:
        '200':
          description: Incoming payments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPaymentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /SaveIncomingPayment:
    post:
      tags:
        - Financial Management
      summary: Save Incoming Payment
      description: Create or update incoming payment record
      operationId: saveIncomingPayment
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveIncomingPaymentRequest'
      responses:
        '200':
          description: Incoming payment saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /GetOutgoingPayments:
    post:
      tags:
        - Financial Management
      summary: Get Outgoing Payments
      description: Retrieve outgoing payments based on filter criteria
      operationId: getOutgoingPayments
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutgoingPaymentsFilterRequest'
      responses:
        '200':
          description: Outgoing payments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutgoingPaymentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  # Helpdesk Management
  /GetTickets:
    post:
      tags:
        - Helpdesk Management
      summary: Get Tickets
      description: Retrieve helpdesk tickets based on filter criteria
      operationId: getTickets
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketFilterRequest'
      responses:
        '200':
          description: Tickets retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /SaveTicket:
    post:
      tags:
        - Helpdesk Management
      summary: Save Ticket
      description: Create or update helpdesk ticket
      operationId: saveTicket
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveTicketRequest'
      responses:
        '200':
          description: Ticket saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /UpdateTicketStatus:
    post:
      tags:
        - Helpdesk Management
      summary: Update Ticket Status
      description: Update ticket status with audit trail
      operationId: updateTicketStatus
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTicketStatusRequest'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  # Article Management
  /GetArticles:
    post:
      tags:
        - Article Management
      summary: Get Articles
      description: Retrieve articles/products based on filter criteria
      operationId: getArticles
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleFilterRequest'
      responses:
        '200':
          description: Articles retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /SaveArticle:
    post:
      tags:
        - Article Management
      summary: Save Article
      description: Create or update article/product information
      operationId: saveArticle
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveArticleRequest'
      responses:
        '200':
          description: Article saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  # Administration
  /GetUserRights:
    post:
      tags:
        - Administration
      summary: Get User Rights
      description: Retrieve user rights and permissions
      operationId: getUserRights
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRightsRequest'
      responses:
        '200':
          description: User rights retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRightsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /UpdateUserRights:
    post:
      tags:
        - Administration
      summary: Update User Rights
      description: Update user permissions and access rights
      operationId: updateUserRights
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRightsRequest'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /GetSystemSettings:
    post:
      tags:
        - Administration
      summary: Get System Settings
      description: Retrieve system configuration settings
      operationId: getSystemSettings
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemSettingsRequest'
      responses:
        '200':
          description: System settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemSettingsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token authentication

    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for system integration

  schemas:
    # Base Request/Response Models
    BaseRequest:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique request identifier for tracing
        timestamp:
          type: string
          format: date-time
          description: Request timestamp
        clientVersion:
          type: string
          description: Client application version
      required:
        - requestId
        - timestamp

    BaseResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message or error description
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
        requestId:
          type: string
          format: uuid
          description: Original request identifier
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
      required:
        - success
        - timestamp

    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
        message:
          type: string
          description: Human-readable error message
        field:
          type: string
          description: Field name for validation errors
        severity:
          type: string
          enum: [info, warning, error, critical]
          description: Error severity level

    # Authentication Models
    LoginRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            username:
              type: string
              description: User login name
            password:
              type: string
              format: password
              description: User password
            domain:
              type: string
              description: Optional domain for Active Directory authentication
            mfaToken:
              type: string
              description: Multi-factor authentication token
          required:
            - username
            - password

    LoginResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            accessToken:
              type: string
              description: JWT access token
            refreshToken:
              type: string
              description: JWT refresh token
            expiresIn:
              type: integer
              description: Token expiration time in seconds
            userInfo:
              $ref: '#/components/schemas/UserInfo'
            permissions:
              type: array
              items:
                type: string
              description: User permissions and rights

    UserInfo:
      type: object
      properties:
        userId:
          type: integer
          description: Unique user identifier (I3D)
        username:
          type: string
          description: User login name
        displayName:
          type: string
          description: User display name
        email:
          type: string
          format: email
          description: User email address
        department:
          type: string
          description: User department
        roles:
          type: array
          items:
            type: string
          description: User roles and groups
        lastLogin:
          type: string
          format: date-time
          description: Last login timestamp

    # Customer Management Models
    CustomerFilterRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            searchText:
              type: string
              description: Full-text search across customer data
            customerNumber:
              type: string
              description: Specific customer number filter
            companyName:
              type: string
              description: Company name filter
            city:
              type: string
              description: City filter
            country:
              type: string
              description: Country filter
            status:
              type: string
              enum: [active, inactive, all]
              description: Customer status filter
            pageSize:
              type: integer
              minimum: 1
              maximum: 1000
              default: 100
              description: Number of records per page
            pageNumber:
              type: integer
              minimum: 1
              default: 1
              description: Page number for pagination

    CustomerListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            customers:
              type: array
              items:
                $ref: '#/components/schemas/CustomerSummary'
            totalCount:
              type: integer
              description: Total number of matching customers
            pageSize:
              type: integer
              description: Requested page size
            pageNumber:
              type: integer
              description: Current page number

    CustomerSummary:
      type: object
      properties:
        customerId:
          type: integer
          description: Unique customer identifier (I3D)
        customerNumber:
          type: string
          description: Customer number
        companyName:
          type: string
          description: Company name
        contactName:
          type: string
          description: Primary contact name
        email:
          type: string
          format: email
          description: Primary email address
        phone:
          type: string
          description: Primary phone number
        city:
          type: string
          description: Customer city
        country:
          type: string
          description: Customer country
        status:
          type: string
          enum: [active, inactive]
          description: Customer status
        createdDate:
          type: string
          format: date-time
          description: Customer creation date
        lastModified:
          type: string
          format: date-time
          description: Last modification date

    SaveCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            customer:
              $ref: '#/components/schemas/CustomerDetail'

    CustomerDetail:
      type: object
      properties:
        customerId:
          type: integer
          description: Customer ID for updates, null for new customers
        customerNumber:
          type: string
          description: Customer number (auto-generated if not provided)
        companyName:
          type: string
          maxLength: 255
          description: Company name
        contactName:
          type: string
          maxLength: 255
          description: Primary contact name
        email:
          type: string
          format: email
          maxLength: 255
          description: Primary email address
        phone:
          type: string
          maxLength: 50
          description: Primary phone number
        address:
          $ref: '#/components/schemas/Address'
        paymentTerms:
          type: integer
          description: Payment terms in days
        creditLimit:
          type: number
          format: decimal
          description: Customer credit limit
        taxId:
          type: string
          maxLength: 50
          description: Tax identification number
        notes:
          type: string
          description: Additional customer notes
        status:
          type: string
          enum: [active, inactive]
          description: Customer status
      required:
        - companyName

    Address:
      type: object
      properties:
        street:
          type: string
          maxLength: 255
          description: Street address
        city:
          type: string
          maxLength: 100
          description: City
        postalCode:
          type: string
          maxLength: 20
          description: Postal/ZIP code
        country:
          type: string
          maxLength: 100
          description: Country
        region:
          type: string
          maxLength: 100
          description: State/Province/Region

    CustomerResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            customer:
              $ref: '#/components/schemas/CustomerDetail'

    DeleteCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            customerId:
              type: integer
              description: Customer ID to delete
            reason:
              type: string
              description: Reason for deletion
          required:
            - customerId

    # Financial Management Models
    AccountNavRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            accountId:
              type: integer
              description: Account ID for navigation info

    AccountNavResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            accountInfo:
              $ref: '#/components/schemas/AccountNavInfo'

    AccountNavInfo:
      type: object
      properties:
        accountId:
          type: integer
          description: Account identifier
        accountName:
          type: string
          description: Account name
        balance:
          type: number
          format: decimal
          description: Current account balance
        currency:
          type: string
          description: Account currency code
        lastTransaction:
          type: string
          format: date-time
          description: Last transaction date
        status:
          type: string
          enum: [active, inactive, suspended]
          description: Account status

    IncomingPaymentsFilterRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            dateFrom:
              type: string
              format: date
              description: Start date for payment filter
            dateTo:
              type: string
              format: date
              description: End date for payment filter
            customerId:
              type: integer
              description: Filter by specific customer
            status:
              type: string
              enum: [pending, processed, cancelled]
              description: Payment status filter
            amountFrom:
              type: number
              format: decimal
              description: Minimum payment amount
            amountTo:
              type: number
              format: decimal
              description: Maximum payment amount
            pageSize:
              type: integer
              minimum: 1
              maximum: 1000
              default: 100
            pageNumber:
              type: integer
              minimum: 1
              default: 1

    IncomingPaymentsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            payments:
              type: array
              items:
                $ref: '#/components/schemas/IncomingPayment'
            totalCount:
              type: integer
            pageSize:
              type: integer
            pageNumber:
              type: integer

    IncomingPayment:
      type: object
      properties:
        paymentId:
          type: integer
          description: Payment identifier (I3D)
        customerId:
          type: integer
          description: Customer identifier
        customerName:
          type: string
          description: Customer name
        amount:
          type: number
          format: decimal
          description: Payment amount
        currency:
          type: string
          description: Payment currency
        paymentDate:
          type: string
          format: date
          description: Payment date
        reference:
          type: string
          description: Payment reference
        bankAccount:
          type: string
          description: Bank account information
        status:
          type: string
          enum: [pending, processed, cancelled]
          description: Payment status
        notes:
          type: string
          description: Payment notes

    SaveIncomingPaymentRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            payment:
              $ref: '#/components/schemas/IncomingPayment'

    IncomingPaymentResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            payment:
              $ref: '#/components/schemas/IncomingPayment'

    OutgoingPaymentsFilterRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            dateFrom:
              type: string
              format: date
            dateTo:
              type: string
              format: date
            supplierId:
              type: integer
            status:
              type: string
              enum: [pending, processed, cancelled]
            amountFrom:
              type: number
              format: decimal
            amountTo:
              type: number
              format: decimal
            pageSize:
              type: integer
              minimum: 1
              maximum: 1000
              default: 100
            pageNumber:
              type: integer
              minimum: 1
              default: 1

    OutgoingPaymentsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            payments:
              type: array
              items:
                $ref: '#/components/schemas/OutgoingPayment'
            totalCount:
              type: integer
            pageSize:
              type: integer
            pageNumber:
              type: integer

    OutgoingPayment:
      type: object
      properties:
        paymentId:
          type: integer
          description: Payment identifier (I3D)
        supplierId:
          type: integer
          description: Supplier identifier
        supplierName:
          type: string
          description: Supplier name
        amount:
          type: number
          format: decimal
          description: Payment amount
        currency:
          type: string
          description: Payment currency
        paymentDate:
          type: string
          format: date
          description: Payment date
        reference:
          type: string
          description: Payment reference
        bankAccount:
          type: string
          description: Bank account information
        status:
          type: string
          enum: [pending, processed, cancelled]
          description: Payment status
        notes:
          type: string
          description: Payment notes

    # Helpdesk Management Models
    TicketFilterRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            searchText:
              type: string
              description: Search in ticket title, description, and comments
            status:
              type: string
              enum: [open, in_progress, resolved, closed, cancelled]
              description: Ticket status filter
            priority:
              type: string
              enum: [low, normal, high, urgent, critical]
              description: Ticket priority filter
            assignedTo:
              type: integer
              description: Filter by assigned user ID
            customerId:
              type: integer
              description: Filter by customer ID
            categoryId:
              type: integer
              description: Filter by ticket category
            createdFrom:
              type: string
              format: date-time
              description: Tickets created after this date
            createdTo:
              type: string
              format: date-time
              description: Tickets created before this date
            pageSize:
              type: integer
              minimum: 1
              maximum: 1000
              default: 100
            pageNumber:
              type: integer
              minimum: 1
              default: 1

    TicketListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            tickets:
              type: array
              items:
                $ref: '#/components/schemas/TicketSummary'
            totalCount:
              type: integer
            pageSize:
              type: integer
            pageNumber:
              type: integer

    TicketSummary:
      type: object
      properties:
        ticketId:
          type: integer
          description: Ticket identifier (I3D)
        ticketNumber:
          type: string
          description: Human-readable ticket number
        title:
          type: string
          description: Ticket title/subject
        description:
          type: string
          description: Ticket description (truncated)
        status:
          type: string
          enum: [open, in_progress, resolved, closed, cancelled]
          description: Current ticket status
        priority:
          type: string
          enum: [low, normal, high, urgent, critical]
          description: Ticket priority
        customerId:
          type: integer
          description: Associated customer ID
        customerName:
          type: string
          description: Customer name
        assignedTo:
          type: integer
          description: Assigned user ID
        assignedToName:
          type: string
          description: Assigned user name
        createdBy:
          type: integer
          description: Creator user ID
        createdByName:
          type: string
          description: Creator user name
        createdDate:
          type: string
          format: date-time
          description: Ticket creation date
        lastModified:
          type: string
          format: date-time
          description: Last modification date
        dueDate:
          type: string
          format: date-time
          description: Ticket due date

    SaveTicketRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            ticket:
              $ref: '#/components/schemas/TicketDetail'

    TicketDetail:
      type: object
      properties:
        ticketId:
          type: integer
          description: Ticket ID for updates, null for new tickets
        title:
          type: string
          maxLength: 255
          description: Ticket title/subject
        description:
          type: string
          description: Detailed ticket description
        status:
          type: string
          enum: [open, in_progress, resolved, closed, cancelled]
          description: Ticket status
        priority:
          type: string
          enum: [low, normal, high, urgent, critical]
          description: Ticket priority
        customerId:
          type: integer
          description: Associated customer ID
        assignedTo:
          type: integer
          description: Assigned user ID
        categoryId:
          type: integer
          description: Ticket category ID
        dueDate:
          type: string
          format: date-time
          description: Ticket due date
        estimatedHours:
          type: number
          format: decimal
          description: Estimated work hours
        actualHours:
          type: number
          format: decimal
          description: Actual work hours spent
        tags:
          type: array
          items:
            type: string
          description: Ticket tags for categorization
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: File attachments
      required:
        - title
        - description
        - customerId

    Attachment:
      type: object
      properties:
        attachmentId:
          type: integer
          description: Attachment identifier
        fileName:
          type: string
          description: Original file name
        fileSize:
          type: integer
          description: File size in bytes
        contentType:
          type: string
          description: MIME content type
        uploadDate:
          type: string
          format: date-time
          description: Upload timestamp
        uploadedBy:
          type: integer
          description: User who uploaded the file

    TicketResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            ticket:
              $ref: '#/components/schemas/TicketDetail'

    UpdateTicketStatusRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            ticketId:
              type: integer
              description: Ticket ID to update
            newStatus:
              type: string
              enum: [open, in_progress, resolved, closed, cancelled]
              description: New ticket status
            comment:
              type: string
              description: Status change comment
            assignedTo:
              type: integer
              description: New assigned user (optional)
          required:
            - ticketId
            - newStatus

    # Article Management Models
    ArticleFilterRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            searchText:
              type: string
              description: Search in article number, name, and description
            categoryId:
              type: integer
              description: Filter by article category
            supplierIds:
              type: array
              items:
                type: integer
              description: Filter by supplier IDs
            priceFrom:
              type: number
              format: decimal
              description: Minimum price filter
            priceTo:
              type: number
              format: decimal
              description: Maximum price filter
            inStock:
              type: boolean
              description: Filter by stock availability
            active:
              type: boolean
              description: Filter by active status
            pageSize:
              type: integer
              minimum: 1
              maximum: 1000
              default: 100
            pageNumber:
              type: integer
              minimum: 1
              default: 1

    ArticleListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            articles:
              type: array
              items:
                $ref: '#/components/schemas/ArticleSummary'
            totalCount:
              type: integer
            pageSize:
              type: integer
            pageNumber:
              type: integer

    ArticleSummary:
      type: object
      properties:
        articleId:
          type: integer
          description: Article identifier (I3D)
        articleNumber:
          type: string
          description: Article number/SKU
        name:
          type: string
          description: Article name
        description:
          type: string
          description: Short description
        price:
          type: number
          format: decimal
          description: Current price
        currency:
          type: string
          description: Price currency
        stockQuantity:
          type: integer
          description: Available stock quantity
        categoryName:
          type: string
          description: Category name
        supplierName:
          type: string
          description: Primary supplier name
        active:
          type: boolean
          description: Whether article is active
        createdDate:
          type: string
          format: date-time
          description: Article creation date
        lastModified:
          type: string
          format: date-time
          description: Last modification date

    SaveArticleRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            article:
              $ref: '#/components/schemas/ArticleDetail'

    ArticleDetail:
      type: object
      properties:
        articleId:
          type: integer
          description: Article ID for updates, null for new articles
        articleNumber:
          type: string
          maxLength: 100
          description: Article number/SKU
        name:
          type: string
          maxLength: 255
          description: Article name
        description:
          type: string
          description: Detailed description
        shortDescription:
          type: string
          maxLength: 500
          description: Short description for listings
        categoryId:
          type: integer
          description: Article category ID
        price:
          type: number
          format: decimal
          description: Base price
        currency:
          type: string
          description: Price currency
        costPrice:
          type: number
          format: decimal
          description: Cost price
        stockQuantity:
          type: integer
          description: Current stock quantity
        minStockQuantity:
          type: integer
          description: Minimum stock level
        weight:
          type: number
          format: decimal
          description: Article weight
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        active:
          type: boolean
          description: Whether article is active
        taxRate:
          type: number
          format: decimal
          description: Tax rate percentage
        suppliers:
          type: array
          items:
            $ref: '#/components/schemas/ArticleSupplier'
          description: Supplier information
      required:
        - articleNumber
        - name
        - categoryId
        - price

    Dimensions:
      type: object
      properties:
        length:
          type: number
          format: decimal
          description: Length in cm
        width:
          type: number
          format: decimal
          description: Width in cm
        height:
          type: number
          format: decimal
          description: Height in cm

    ArticleSupplier:
      type: object
      properties:
        supplierId:
          type: integer
          description: Supplier identifier
        supplierArticleNumber:
          type: string
          description: Supplier's article number
        supplierPrice:
          type: number
          format: decimal
          description: Supplier's price
        leadTimeDays:
          type: integer
          description: Lead time in days
        minimumOrderQuantity:
          type: integer
          description: Minimum order quantity
        isPrimary:
          type: boolean
          description: Whether this is the primary supplier

    ArticleResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            article:
              $ref: '#/components/schemas/ArticleDetail'

    # Administration Models
    UserRightsRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            userId:
              type: integer
              description: User ID to get rights for

    UserRightsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            userRights:
              $ref: '#/components/schemas/UserRights'

    UserRights:
      type: object
      properties:
        userId:
          type: integer
          description: User identifier
        rights:
          type: array
          items:
            $ref: '#/components/schemas/UserRight'
          description: List of user rights
        groups:
          type: array
          items:
            type: string
          description: User groups
        effectiveRights:
          type: array
          items:
            type: string
          description: All effective rights (including inherited)

    UserRight:
      type: object
      properties:
        rightId:
          type: integer
          description: Right identifier from UserRightsConst
        rightName:
          type: string
          description: Right name/identifier
        description:
          type: string
          description: Right description
        category:
          type: string
          description: Right category
        granted:
          type: boolean
          description: Whether right is granted
        inherited:
          type: boolean
          description: Whether right is inherited from group

    UpdateUserRightsRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            userId:
              type: integer
              description: User ID to update rights for
            rightsUpdates:
              type: array
              items:
                $ref: '#/components/schemas/RightUpdate'
              description: Rights to update
          required:
            - userId
            - rightsUpdates

    RightUpdate:
      type: object
      properties:
        rightId:
          type: integer
          description: Right identifier
        granted:
          type: boolean
          description: Grant or revoke the right
        reason:
          type: string
          description: Reason for the change
      required:
        - rightId
        - granted

    SystemSettingsRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            category:
              type: string
              description: Settings category filter
            settingNames:
              type: array
              items:
                type: string
              description: Specific setting names to retrieve

    SystemSettingsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            settings:
              type: array
              items:
                $ref: '#/components/schemas/SystemSetting'
              description: System settings

    SystemSetting:
      type: object
      properties:
        settingId:
          type: integer
          description: Setting identifier from ApplicationSettingID
        name:
          type: string
          description: Setting name
        value:
          type: string
          description: Setting value
        category:
          type: string
          description: Setting category
        dataType:
          type: string
          enum: [string, integer, decimal, boolean, date]
          description: Setting data type
        description:
          type: string
          description: Setting description
        isReadOnly:
          type: boolean
          description: Whether setting is read-only
        lastModified:
          type: string
          format: date-time
          description: Last modification date

  responses:
    SuccessResponse:
      description: Operation completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'

    BadRequestError:
      description: Invalid request data
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseResponse'
              - type: object
                properties:
                  success:
                    example: false
                  message:
                    example: "Invalid request data"

    UnauthorizedError:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseResponse'
              - type: object
                properties:
                  success:
                    example: false
                  message:
                    example: "Authentication required"

    ForbiddenError:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseResponse'
              - type: object
                properties:
                  success:
                    example: false
                  message:
                    example: "Insufficient permissions"

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseResponse'
              - type: object
                properties:
                  success:
                    example: false
                  message:
                    example: "Resource not found"

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseResponse'
              - type: object
                properties:
                  success:
                    example: false
                  message:
                    example: "Internal server error"

tags:
  - name: Authentication
    description: User authentication and session management
  - name: Customer Management
    description: Customer data and relationship management
  - name: Financial Management
    description: Payment processing and financial operations
  - name: Helpdesk Management
    description: Ticket and support management
  - name: Article Management
    description: Product and article management
  - name: Administration
    description: System administration and configuration

externalDocs:
  description: Centron API Documentation
  url: https://docs.centron.local/api