task-p.7.1.1

plans/task-d.4.7.md

@@ -0,0 +1,421 @@
+# Task D.4.7 – Organization-aware Document Sequence & Prefix Strategy
+
+## Objective
+
+Redesign the document-sequence strategy so document prefixes are configuration-driven and organization-aware, eliminating hardcoded prefix logic from the application.
+
+The new design must support multiple companies, branches, product types, and document types without requiring source code changes.
+
+---
+
+# Background
+
+Current document numbering works correctly after Task D.4.6 but still assumes product prefixes are fixed inside the application.
+
+Example:
+
+```
+CRA2606-001
+DKA2606-001
+SCA2606-001
+```
+
+However, the business requires different companies (organizations) to use different prefixes while keeping the same product types.
+
+Example:
+
+## ALLA
+
+```
+CRA2606-001
+DKA2606-001
+SCA2606-001
+SVA2606-001
+```
+
+## ONVALLA
+
+```
+CRO2606-001
+DKO2606-001
+SCO2606-001
+SVO2606-001
+```
+
+The application should support additional organizations in the future without code modifications.
+
+---
+
+# Business Requirements
+
+Document numbers must be isolated by:
+
+```
+Organization
+    ↓
+Branch
+    ↓
+Document Type
+    ↓
+Product Type
+    ↓
+Running Number
+```
+
+Running numbers must never overlap across organizations.
+
+Example
+
+ALLA
+
+```
+CRA2606-001
+CRA2606-002
+```
+
+ONVALLA
+
+```
+CRO2606-001
+CRO2606-002
+```
+
+Both organizations maintain independent counters.
+
+---
+
+# Scope
+
+Review:
+
+```
+src/features/foundation/document-sequence/*
+```
+
+```
+src/features/foundation/master-options/*
+```
+
+```
+src/db/schema.ts
+```
+
+```
+src/db/seeds/*
+```
+
+Review existing document sequence configuration before introducing new structures.
+
+Avoid duplicate concepts.
+
+---
+
+# Requirements
+
+## 1. Remove Hardcoded Prefix Logic
+
+No document prefix may be hardcoded.
+
+Avoid patterns such as:
+
+```ts
+switch(productType){
+ case "crane":
+   return "CRA";
+}
+```
+
+or
+
+```ts
+if(productType==="crane")
+```
+
+Prefix generation must be configuration-driven.
+
+---
+
+## 2. Introduce Organization-aware Prefix Configuration
+
+Design a configuration that determines:
+
+```
+Organization
+
+↓
+
+Document Type
+
+↓
+
+Product Type
+
+↓
+
+Prefix
+```
+
+Example
+
+| Organization | Document | Product | Prefix |
+|--------------|----------|----------|--------|
+| ALLA | quotation | crane | CRA |
+| ALLA | quotation | dockdoor | DKA |
+| ALLA | quotation | solarcell | SCA |
+| ALLA | quotation | service | SVA |
+| ONVALLA | quotation | crane | CRO |
+| ONVALLA | quotation | dockdoor | DKO |
+| ONVALLA | quotation | solarcell | SCO |
+| ONVALLA | quotation | service | SVO |
+
+Future organizations must be configurable without code changes.
+
+---
+
+## 3. Preserve Existing Sequence Strategy
+
+Current uniqueness must remain:
+
+```
+Organization
+
++
+
+Branch
+
++
+
+Document Type
+
++
+
+Product Type
+
++
+
+Period
+```
+
+Running numbers remain independent.
+
+---
+
+## 4. Keep Product Resolver Generic
+
+Task D.4.6 introduced a shared product-type resolver.
+
+Do not move organization logic into the resolver.
+
+Responsibilities should become:
+
+### Product Resolver
+
+Responsible only for
+
+```
+Quotation Type
+
+↓
+
+Product Type
+```
+
+### Document Sequence
+
+Responsible only for
+
+```
+Organization
+
+↓
+
+Prefix
+
+↓
+
+Running Number
+```
+
+Keep these responsibilities separated.
+
+---
+
+## 5. Centralize Prefix Configuration
+
+Avoid scattered constants.
+
+Design a single source of truth.
+
+Example
+
+```
+Document Prefix Configuration
+
+↓
+
+Resolver
+
+↓
+
+Document Sequence
+```
+
+No module should define its own prefixes.
+
+---
+
+## 6. Support Future Document Types
+
+The strategy must support future modules.
+
+Examples
+
+```
+Quotation
+
+Delivery Note
+
+Sales Contract
+
+Purchase Order
+
+Invoice
+
+Service Report
+
+Work Order
+```
+
+Each document type may define its own prefixes.
+
+---
+
+## 7. Preserve Backward Compatibility
+
+Existing document numbers remain valid.
+
+Do not change
+
+- existing quotations
+- revisions
+- approved PDFs
+- audit logs
+
+Only affect newly generated numbers.
+
+---
+
+## 8. Improve Configuration Validation
+
+During startup or seed validation verify:
+
+- duplicate prefixes
+- missing prefix
+- missing organization mapping
+- invalid product type
+- invalid document type
+
+Configuration errors should fail early with clear messages.
+
+---
+
+# Database Considerations
+
+Review whether existing `document_sequences` already contains sufficient information.
+
+If additional configuration is required:
+
+- prefer extending existing structures
+- avoid introducing duplicate master tables
+- justify any schema change
+
+Migration must remain backward compatible.
+
+---
+
+# Tests
+
+Add coverage for:
+
+- ALLA quotation
+- ONVALLA quotation
+- branch isolation
+- organization isolation
+- period rollover
+- configuration validation
+- missing prefix
+- duplicate configuration
+
+---
+
+# Verification
+
+Verify:
+
+ALLA
+
+```
+CRA2606-001
+CRA2606-002
+```
+
+```
+DKA2606-001
+```
+
+ONVALLA
+
+```
+CRO2606-001
+CRO2606-002
+```
+
+```
+DKO2606-001
+```
+
+Ensure counters remain independent.
+
+---
+
+# Regression Checklist
+
+Confirm no regression for:
+
+- Quotation creation
+- Revision creation
+- Approval workflow
+- PDF generation
+- Document preview
+- Audit log
+- Existing APIs
+- Existing seed data
+
+---
+
+# Deliverables
+
+- Organization-aware prefix strategy
+- Configuration-driven prefix resolution
+- Removal of hardcoded prefix logic
+- Updated seed/configuration (if required)
+- Updated unit tests
+- Verification report
+- Architecture notes describing the new numbering strategy
+
+---
+
+# Acceptance Criteria
+
+- No hardcoded document prefixes remain.
+- Prefixes are configurable per organization.
+- Running numbers remain isolated by organization, branch, document type, product type, and period.
+- Existing document numbers remain valid.
+- Future organizations can be added through configuration without modifying application logic.
+- TypeScript passes.
+
+```bash
+npm exec tsc --noEmit
+```
+
+- All document-sequence tests pass.