5.6 KiB
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:
switch(productType){
case "crane":
return "CRA";
}
or
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.
npm exec tsc --noEmit
- All document-sequence tests pass.