alla-allaos-fullstack/plans/task-d.4.6.md

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:

{
  "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.

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

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