ISA-Frontend/libs/crm/feature/customer-bon-redemption/README.md

@isa/crm/feature/customer-bon-redemption

A feature library providing customer loyalty receipt (Bon) redemption functionality with validation and point allocation capabilities.

Overview

This library implements a complete workflow for redeeming customer receipts (Bons) for loyalty points. It provides a user interface that allows staff to enter a receipt number, validate it against the backend system, view receipt details, and process the redemption to add points to the customer's loyalty account.

The feature is designed for use in CRM contexts where customers need to receive loyalty points for receipts that were not automatically processed at the point of sale.

Installation

import { CrmFeatureCustomerBonRedemptionComponent } from '@isa/crm/feature/customer-bon-redemption';

Main Component

CrmFeatureCustomerBonRedemptionComponent

The main component orchestrating the entire Bon redemption workflow.

Selector: crm-customer-bon-redemption

Inputs:

• cardCode?: string - The customer's active loyalty card code (required for validation and redemption)

Outputs:

• redeemed: void - Emitted when a Bon has been successfully redeemed

Example Usage:

<crm-customer-bon-redemption
  [cardCode]="activeCardCode()"
  (redeemed)="onBonRedeemed()"
/>

Features:

1. Input field for entering Bon number with validation
2. Real-time Bon validation against backend API
3. Display of validated Bon details (date, total amount)
4. Redemption action with loading states and error handling
5. Automatic form reset after successful redemption
6. Integrated feedback dialogs for success/error states

Child Components

BonInputFieldComponent

Smart component managing the Bon number input field with validation controls.

Selector: crm-bon-input-field

Inputs:

• cardCode?: string - Customer's loyalty card code

Outputs:

• validate: void - Emitted when validation should be triggered
• clearForm: void - Emitted when form should be cleared

Features:

• Text input with required validation
• "Bon suchen" (Search) button with loading state
• Clear button when text is entered
• Success/error message display
• Enter key support for quick validation
• Auto-focus on reset

BonDetailsDisplayComponent

Displays validated Bon details including date and total amount.

Selector: crm-bon-details-display

Features:

• Formatted date display
• Total amount with currency formatting (German locale)
• Conditional rendering (only visible when Bon is validated)

BonRedemptionButtonComponent

Action button for processing the Bon redemption.

Selector: crm-bon-redemption-button

Inputs:

• disabled: boolean - Whether the button should be disabled

Outputs:

• redeem: void - Emitted when redemption is triggered

Features:

• Primary action button with "Für Kunden verbuchen" label
• Loading state during redemption process
• Disabled state management

State Management

The library uses BonRedemptionStore (from @isa/crm/data-access) for centralized state management:

State Properties:

• bonNumber: string - Current Bon number input
• validatedBon?: ValidatedBon - Validated Bon data (number, date, total)
• errorMessage?: string - Current error message
• isValidating: boolean - Validation loading state
• isRedeeming: boolean - Redemption loading state
• disableRedemption: boolean - Computed disable state

Store Methods:

• setBonNumber(value: string) - Update Bon number
• setValidatedBon(bon: ValidatedBon) - Store validated Bon data
• setError(message: string) - Set error state
• setValidating(loading: boolean) - Update validation loading state
• setRedeeming(loading: boolean) - Update redemption loading state
• reset() - Reset to initial state

API Integration

CustomerBonCheckResource

Uses Angular's Resource API for reactive Bon validation:

Parameters:

• cardCode: string - Customer's loyalty card code
• bonNr: string - Bon number to validate

Returns: Validated Bon data with date and total amount

CustomerBonRedemptionFacade

Handles the actual Bon redemption operation:

Method: addBon({ cardCode: string, bonNr: string })

Returns: Promise<boolean> - Success status

User Workflow

1. Enter Bon Number: User types the receipt number into the input field
2. Validate: Click "Bon suchen" or press Enter to validate
3. View Details: If valid, date and total amount are displayed
4. Redeem: Click "Für Kunden verbuchen" to process redemption
5. Confirmation: Success dialog appears with auto-close
6. Reset: Form automatically clears for next redemption

Error Handling

The component handles multiple error scenarios:

• Missing card code validation
• Missing or invalid Bon number
• Backend validation failures
• Redemption API errors
• Network errors

All errors are displayed inline with user-friendly German messages and logged via @isa/core/logging.

Accessibility Features

• ARIA labels on all interactive elements
• ARIA live regions for status messages
• ARIA invalid and describedby for error states
• Semantic HTML with proper roles
• Keyboard navigation support (Enter key for validation)

E2E Testing Attributes

All components include data-what and data-which attributes for automated testing:

• bon-redemption-container
• bon-number-input
• validate-bon-button
• bon-success-message
• bon-error-message
• bon-details
• bon-date
• bon-total
• redeem-bon-button

Dependencies

Internal Dependencies

• @isa/crm/data-access - BonRedemptionStore, CustomerBonCheckResource, CustomerBonRedemptionFacade
• @isa/ui/dialog - injectFeedbackDialog, injectFeedbackErrorDialog
• @isa/ui/buttons - ButtonComponent, TextButtonComponent
• @isa/ui/input-controls - TextFieldComponent, InputControlDirective, TextFieldClearComponent
• @isa/core/logging - logger factory for structured logging
• @isa/common/data-access - ResponseArgsError

External Dependencies

• @angular/core - Angular framework
• @angular/common - DecimalPipe for number formatting
• @angular/forms - FormsModule for ngModel

Styling

The component uses Tailwind CSS with ISA design system tokens:

• Background: bg-isa-neutral-200
• Text: isa-text-body-1-bold, isa-text-body-2-regular, etc.
• Colors: text-isa-accent-green, text-isa-accent-red, text-isa-neutral-600
• Spacing: Standard Tailwind spacing utilities

Configuration

Project: crm-feature-customer-bon-redemption

Prefix: crm

Tags: skip:ci

Testing: Vitest configuration with @nx/vite:test executor

Linting: ESLint configuration with @nx/eslint:lint executor