# 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.