# @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

```ts
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:**
```html
<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
