380 lines
6.2 KiB
Markdown
380 lines
6.2 KiB
Markdown
# 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`
|