# Task D.4.6: Fix Quotation Document Sequence Product-Type Resolution

## Objective

Fix quotation creation failure caused by incorrect quotation-type to product-type resolution during document number generation.

This task must correct the runtime mapping logic inside the document sequence service without introducing duplicate master data or changing existing business rules.

---

## Background

Creating a quotation currently fails with:

```json
{
  "message": "Missing product type code configuration quotation type."
}
```

The failure occurs after quotation validation succeeds and immediately before document number allocation.

Investigation confirmed this is **not** caused by missing seed data.

---

## Current Findings

Verified:

- Quotation payload validation succeeds.
- `createQuotation()` reaches document code generation.
- `generateNextDocumentCode()` throws before allocating a sequence.
- Database already contains:

### Master Options

Category:

```
crm_quotation_type
```

Values:

- crane
- dockdoor
- solarcell
- service
- other

Category:

```
crm_product_type
```

Values:

- crane
- dockdoor
- solarcell
- service
- sparepart

### Document Sequences

Quotation sequences already exist for:

- crane
- dockdoor
- solarcell
- service

Therefore the failure is **not** caused by missing:

- master option
- document sequence
- seed data

---

## Root Cause

The document sequence service is failing to consistently resolve:

Quotation Type

↓

Product Type

↓

Document Sequence

The runtime mapping rejects a valid quotation type before sequence generation.

This is a logic bug.

---

## Scope

Review:

```
src/features/crm/quotations/server/service.ts
```

```
src/features/foundation/document-sequence/service.ts
```

```
src/features/foundation/master-options/*
```

```
src/db/seeds/*
```

Do **not** redesign the quotation module.

Do **not** modify document numbering rules.

---

## Requirements

### 1. Trace Runtime Resolution

Document the complete resolution path.

Expected flow:

```
Quotation

↓

quotationTypeId

↓

Master Option

↓

productTypeCode

↓

Document Sequence

↓

Document Number
```

Verify every transformation.

---

### 2. Normalize Product Type Resolution

Support all valid inputs.

The resolver should accept:

- option id
- option code
- normalized product type code

It must not depend on display labels.

---

### 3. Standardize Mapping

Support at minimum:

| Quotation Type | Product Type | Prefix |
|----------------|-------------|--------|
| crane | crane | CR |
| dockdoor | dockdoor | DK |
| solarcell | solarcell | SC |
| service | service | SV |
| sparepart | sparepart | SP |

Future product types should require configuration only, not new code branches.

---

### 4. Remove Duplicate Lookup Logic

If quotation service and document sequence service both perform mapping independently:

Refactor into a shared resolver.

Avoid duplicated switch statements.

---

### 5. Improve Error Messages

Replace generic runtime errors with diagnostic information.

Example:

```
Unable to resolve product type for quotation.

quotationTypeId:
xxxxxxxx

quotationTypeCode:
crane

organizationId:
...

branchId:
...

resolvedProductType:
null
```

This should only be returned internally/logged during development.

User-facing messages should remain business friendly.

---

### 6. Preserve Existing Business Rules

Do not modify:

- organization isolation
- branch isolation
- document numbering format
- document sequence locking
- approval workflow
- quotation schema

---

### 7. Frontend Error Handling

Improve API error handling.

Current UI displays:

```
API Error 400 Bad Request
```

Instead display backend messages when available.

Example:

```
Missing product type code configuration quotation type.
```

Fallback to generic messages only when backend provides none.

---

## Validation

Verify quotation creation succeeds for:

- Crane
- Dock Door
- Solar Cell
- Service

Each must generate the correct sequence.

Example:

```
CRA2606-001
```

```
DKA2606-001
```

```
SCA2606-001
```

```
SVA2606-001
```

Verify the sequence increments correctly.

---

## Regression Checklist

Confirm no regression for:

- Document sequence generation
- Branch-specific numbering
- Organization-specific numbering
- Product-specific numbering
- Existing document types
- Existing sequence rows
- Existing seeds

---

## Technical Constraints

- No database schema changes unless absolutely required.
- No duplicate `ms_options`.
- No duplicate `document_sequences`.
- Keep seed scripts idempotent.
- Preserve current APIs.

---

## Deliverables

- Fixed runtime product-type resolution.
- Shared resolver (if duplication exists).
- Improved backend diagnostics.
- Improved frontend API error display.
- Updated unit/integration tests where applicable.
- Verification report summarizing:
  - root cause
  - implementation
  - validation results
  - regression results

---

## Acceptance Criteria

- Quotation creation succeeds without 400 errors for all configured product types.
- Document numbers are generated correctly.
- Existing numbering rules remain unchanged.
- No additional seed data is required.
- TypeScript passes.

```bash
npm exec tsc --noEmit
```

- Existing test suite passes.
- No regression in document sequence generation.

---

## Implementation Status - 2026-06-30

- Status: Completed
- Implementation report:
  - [task-d.4.6-quotation-document-sequence-fix-2026-06-30.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-d.4.6-quotation-document-sequence-fix-2026-06-30.md)

### Result Summary
- Fixed quotation-type to product-type resolution in document sequence generation.
- Added a shared resolver for option id/code/alias handling plus quotation-type reference mapping.
- Preserved current numbering rules and existing sequence rows.
- Improved API client error handling so backend messages can be shown in the UI.

### Validation Summary
- `npm exec tsc --noEmit` passed.
- `node --import tsx --test src/features/foundation/document-sequence/config.test.ts src/features/foundation/document-sequence/product-type-resolver.test.ts` passed.
- Authenticated API verification on `http://localhost:3000` passed for:
  - `crane` -> `CRA2606-002`
  - `dockdoor` -> `DKA2606-001`
  - `solarcell` -> `SCA2606-001`
  - `service` -> `SVA2606-001`