alla-allaos-fullstack/docs/implementation/task-d.4.6-quotation-document-sequence-fix-2026-06-30.md

Task D.4.6 Implementation Report - 2026-06-30

Scope

• Fix POST /api/crm/quotations returning 400 during document-number generation.
• Preserve existing quotation, sequence, branch, organization, and approval rules.
• Improve frontend propagation of backend error messages.

Root Cause

• Quotation create sends payload.quotationType as a master-option id from category crm_quotation_type.
• Document-sequence resolution was looking up only crm_product_type options.
• Because crm_quotation_type.id and crm_product_type.id are different records, valid quotation-type ids never resolved to a product-type code even though the codes and document-sequence rows already existed.
• Result: document-sequence generation failed before quotation insert with message Missing product type code configuration for quotation type.

Implementation

• Added shared resolver product-type-resolver.ts to normalize and resolve:
  • product-type option ids
  • product-type codes
  • document-sequence aliases such as dock_door and solar
  • quotation-type ids/codes via reference-option translation into product-type codes
• Updated service.ts so quotation document-sequence generation now resolves:
  • crm_quotation_type option -> code
  • code -> matching crm_product_type
  • product type -> document sequence / prefix
• Added internal diagnostic details to failed document-sequence audit payloads:
  • requested product type
  • normalized requested value
  • available product-type ids/codes
  • available quotation-type ids/codes
• Updated api-client.ts to surface backend message/error payloads instead of always throwing generic API error: 400 Bad Request.

Tests

• Added product-type-resolver.test.ts covering:
  • quotation-type id resolution
  • direct code resolution
  • alias resolution
  • non-quotation fallback
  • unresolved input handling

Verification

• npm exec tsc --noEmit
• node --import tsx --test src/features/foundation/document-sequence/config.test.ts src/features/foundation/document-sequence/product-type-resolver.test.ts
• Live API verification against local app on http://localhost:3000 on 2026-06-30 with authenticated UAT admin session:
  • crane -> CRA2606-002
  • dockdoor -> DKA2606-001
  • solarcell -> SCA2606-001
  • service -> SVA2606-001

Regression Notes

• No schema changes
• No seed changes
• No duplicate ms_options
• No duplicate document_sequences
• Existing organization and branch scoping preserved
• Existing document prefix format preserved