task-p.7.1.1

plans/task-d.4.6.md

@@ -0,0 +1,379 @@
+# 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`