# @isa/remission/shared/remission-start-dialog

Angular dialog component for initiating remission processes with two-step workflow: creating return receipts and assigning package numbers.

## Overview

The Remission Start Dialog library provides a critical workflow component for starting new remission processes ("Warenbegleitschein" - return receipt workflow). It implements a two-step process: first creating or inputting a return receipt number, then assigning a package number ("Wannennummer"). The component integrates with RemissionStore for state management and supports both automatic and manual input modes.

## Features

- **Two-Step Workflow** - Receipt creation → Package assignment
- **Receipt Number Options** - Auto-generate or manual input
- **Package Number Assignment** - Scan or manual entry (#5289)
- **Validation** - Server-side validation with error handling
- **Loading States** - Separate loading states for each step
- **Error Recovery** - Display validation errors inline
- **RemissionStore Integration** - Automatic state synchronization
- **Service Wrapper** - RemissionStartService for simplified usage

## Quick Start

```typescript
import { RemissionStartService } from '@isa/remission/shared/remission-start-dialog';

@Component({})
export class MyComponent {
  #remissionStartService = inject(RemissionStartService);

  async startNewRemission(returnGroup: string) {
    await this.#remissionStartService.startRemission(returnGroup);
    // RemissionStore is automatically updated
    // User is ready to add items
  }

  // #5289 - Package assignment only
  async assignPackageOnly(returnId: number, receiptId: number) {
    const result = await this.#remissionStartService.assignPackage({
      returnId,
      receiptId
    });
    if (result) {
      console.log('Package assigned:', result);
    }
  }
}
```

## Component API

### RemissionStartDialogComponent

Two-step dialog for creating return receipts and assigning packages.

**Selector**: `remi-remission-start-dialog`

**Dialog Data**:
```typescript
{
  returnGroup: string | undefined;
  assignPackage?: {
    returnId: number;
    receiptId: number;
  } | undefined; // #5289 - Package assignment only mode
}
```

**Dialog Result**:
```typescript
{
  returnId: number;
  receiptId: number;
} | undefined
```

### RemissionStartService

Injectable service for simplified dialog usage.

**Methods**:
- `startRemission(returnGroup: string | undefined): Promise<void>`
- `assignPackage({ returnId, receiptId }): Promise<RemissionStartDialogResult>`

## Two-Step Workflow

### Step 1: Create Return Receipt

**Options**:
1. **Generate** - Auto-generate receipt number
2. **Input** - Manual receipt number entry

**Component**: `CreateReturnReceiptComponent`

**API Call**: `RemissionReturnReceiptService.createRemission()`

**Validation**: Server-side validation via `invalidProperties` error response

### Step 2: Assign Package Number

**Input**: Scan or manually enter package number ("Wannennummer")

**Component**: `AssignPackageNumberComponent`

**API Call**: `RemissionReturnReceiptService.assignPackage()`

**Requirement**: #5289 - Package must be assigned before completing remission

## Usage Examples

### Start Remission from Card

```typescript
import { RemissionStartService } from '@isa/remission/shared/remission-start-dialog';

@Component({
  selector: 'app-remission-start-card',
  template: `
    <button (click)="startRemission()" uiButton>
      Neue Remission starten
    </button>
  `
})
export class RemissionStartCardComponent {
  #remissionStartService = inject(RemissionStartService);
  #router = inject(Router);
  #tabId = injectTabId();

  returnGroup = input<string | undefined>(undefined);

  async startRemission() {
    await this.#remissionStartService.startRemission(this.returnGroup());
    await this.#router.navigate(['/', this.#tabId(), 'remission']);
  }
}
```

### Assign Package Before Completion

```typescript
import { RemissionStartService } from '@isa/remission/shared/remission-start-dialog';

@Component({})
export class CompleteButtonComponent {
  #remissionStartService = inject(RemissionStartService);

  async completeRemission() {
    // #5289 - Ensure package is assigned
    if (!this.hasAssignedPackage()) {
      const result = await this.#remissionStartService.assignPackage({
        returnId: this.returnId(),
        receiptId: this.receiptId()
      });

      if (!result) {
        return; // User canceled
      }
    }

    // Proceed with completion
    await this.completeReturnReceipt();
  }
}
```

## Component Details

### Return Receipt Result Types

```typescript
enum ReturnReceiptResultType {
  Close = 'close',      // User closed dialog
  Generate = 'generate', // Auto-generate number
  Input = 'input'       // Manual input
}

type ReturnReceiptResult =
  | { type: ReturnReceiptResultType.Close }
  | { type: ReturnReceiptResultType.Generate }
  | { type: ReturnReceiptResultType.Input; value: string | undefined | null };
```

### Request Status Tracking

```typescript
type RequestStatus = {
  loading: boolean;
  invalidProperties?: Record<string, string>; // Server validation errors
};
```

## Testing

```bash
npx nx test remission-remission-start-dialog --skip-nx-cache
```

## Dependencies

- `@angular/core` - Angular framework
- `@isa/remission/data-access` - RemissionStore, RemissionReturnReceiptService
- `@isa/ui/dialog` - Dialog infrastructure
- `@isa/icons` - Icons (isaActionScanner)

## License

Internal ISA Frontend library - not for external distribution.
