# @isa/crm/feature/customer-booking

A standalone Angular component that enables customer loyalty card point booking and reversal with configurable booking reasons.

## Overview

This feature library provides a self-contained booking interface for managing customer loyalty card points. It allows staff members to add or subtract points from customer cards based on configurable booking reasons (e.g., purchase bonuses, corrections, refunds). The component handles point calculation, validation, and provides real-time feedback through dialog notifications.

The booking operation automatically associates the transaction with the current booking partner store and supports both positive (credit) and negative (debit) point adjustments with multiplier factors.

## Architecture

- **Type**: Feature library (smart component with data access integration)
- **Prefix**: `crm`
- **Tags**: `skip:ci`
- **Testing**: Vitest

## Components

### CrmFeatureCustomerBookingComponent

A standalone component that provides a complete booking interface for customer loyalty card points.

**Selector**: `crm-customer-booking`

**Inputs**:
- `cardCode: string | undefined` - The customer loyalty card code to book points against

**Outputs**:
- `booked: void` - Emitted when a booking operation completes successfully

**Features**:
- **Dynamic booking reasons**: Loads available booking reasons from backend with automatic caching
- **Point calculation**: Supports multiplier factors per booking reason (e.g., 1€ = 10 points)
- **Real-time validation**: Disables booking when inputs are invalid or incomplete
- **Loading states**: Shows pending states during API operations
- **Error handling**: Displays user-friendly error messages via dialog
- **Auto-reset**: Clears form inputs after successful booking

**State Management**:
- `points: Signal<number | undefined>` - User-entered point value
- `selectedReasonKey: Signal<string | undefined>` - Currently selected booking reason
- `isBooking: Signal<boolean>` - Tracks ongoing booking operation
- `bookingReasons: Signal<BookingReason[]>` - Available booking reason options
- `calculatedPoints: Computed<number>` - Final point value after applying multiplier
- `disableBooking: Computed<boolean>` - Whether booking button should be disabled

**Template Features**:
- Positive integer input directive for point entry
- Dropdown selector for booking reasons with visual feedback (+/-)
- Tooltip with point conversion explanation (1€ = 10 points)
- Primary action button with loading state
- E2E test attributes (`data-what`, `data-which`) on all interactive elements

## Usage

### Basic Integration

```typescript
import { CrmFeatureCustomerBookingComponent } from '@isa/crm/feature/customer-booking';

@Component({
  selector: 'app-customer-detail',
  imports: [CrmFeatureCustomerBookingComponent],
  template: `
    <crm-customer-booking
      [cardCode]="customerCardCode()"
      (booked)="onPointsBooked()"
    />
  `,
})
export class CustomerDetailComponent {
  customerCardCode = signal<string>('CARD123456');

  onPointsBooked() {
    console.log('Points successfully booked');
    // Refresh customer data, close dialog, etc.
  }
}
```

### Integration Notes

1. **Card code requirement**: The component only renders when a valid `cardCode` is provided
2. **Booking partner context**: Automatically fetches and uses the current booking partner store
3. **Dialog dependencies**: Requires `@isa/ui/dialog` feedback dialogs to be configured in the app
4. **Resource management**: `CustomerBookingReasonsResource` is provided at component level for automatic cleanup

## Dependencies

### Internal Libraries

- **`@isa/crm/data-access`** - Core data access layer
  - `CustomerBookingReasonsResource` - Loads available booking reasons
  - `CustomerCardBookingFacade` - Handles booking API operations
- **`@isa/ui/buttons`** - Button component
- **`@isa/ui/input-controls`** - Dropdown components
- **`@isa/ui/dialog`** - Feedback dialog utilities
- **`@isa/ui/tooltip`** - Tooltip component
- **`@isa/utils/positive-integer-input`** - Input validation directive
- **`@isa/core/logging`** - Logging infrastructure

### Angular Dependencies

- `@angular/core` - Component framework
- `@angular/forms` - FormsModule for ngModel bindings

## API Integration

### Booking Request

```typescript
interface BookingRequest {
  cardCode: string;
  booking: {
    points: number;        // Calculated points (input × multiplier)
    reason: string;        // Selected booking reason key
    storeId: string | undefined;  // Current booking partner store
  };
}
```

### Booking Reasons

```typescript
interface BookingReason {
  key: string;      // Unique identifier
  label: string;    // Display label (e.g., "Gutschrift", "Storno")
  value: number;    // Multiplier factor (positive or negative)
}
```

## Styling

The component uses Tailwind CSS utility classes with the ISA design system:

- **Container**: `h-[15.5rem]` fixed height, rounded card with neutral background
- **Layout**: Flexbox column with 4-unit gap spacing
- **Typography**: ISA text classes (`isa-text-body-1-bold`, `isa-text-body-2-regular`)
- **Colors**: ISA neutral palette (`isa-neutral-200`, `isa-neutral-900`)
- **Input styling**: Custom number input with hidden spin buttons for clean appearance

## Error Handling

The component handles several error scenarios:

1. **Missing card code**: "Kein Karten-Code vorhanden"
2. **No booking reason selected**: "Kein Buchungsgrund ausgewählt"
3. **Zero points**: "Punktezahl muss größer als 0 sein"
4. **API failures**: Generic error message with fallback to error object message

All errors are logged via `@isa/core/logging` with context and displayed to users via error feedback dialog.

## Accessibility

- **ARIA attributes**: E2E test attributes on all interactive elements
- **Semantic HTML**: Proper input types and labels
- **Keyboard navigation**: Full keyboard support via native controls
- **Focus management**: Standard Angular focus behavior

## Testing

### Test Setup

The library uses Vitest for testing. Test files follow the pattern:
- Component tests: `*.component.spec.ts`
- Test setup: `test-setup.ts`

### Test Coverage Areas

- Component rendering with/without card code
- Point calculation with different multipliers
- Booking reason selection and validation
- Successful booking flow with dialog feedback
- Error scenarios and error dialog display
- Input validation and form state management

## Development

### Build

```bash
nx build crm-feature-customer-booking
```

### Test

```bash
nx test crm-feature-customer-booking
```

### Lint

```bash
nx lint crm-feature-customer-booking
```

## Related Libraries

- **`@isa/crm/feature/customer-card`** - Customer card overview and management
- **`@isa/crm/data-access`** - Shared CRM data access services
- **`@isa/checkout/feature/reward`** - Checkout reward redemption feature
