alla-allaos-fullstack/plans/task-d.4.7.md

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