# Task P.6.1 - Document Sequence Scope Refactor

## Objective

Refactor document sequence generation so document numbers are scoped by:

```text
Organization + Branch + Product Type + Document Type + Period
```

This task must be completed before P.7 Document Assembly, because generated/approved/merged documents depend on stable and correct document numbers.

---

# Background

Current document sequence behavior is not sufficient for CRM quotation numbering.

The required numbering examples are:

```text
ALLA
CRA2606-001
DKA2606-001

ONVALLA
CRO2606-001
DKO2606-001
SCO2606-001
```

Meaning:

* `CR` = Product Type code, e.g. Crane
* `DK` = Product Type code, e.g. Dock Door
* `SC` = Product Type code, e.g. Solar Cell
* `A` / `O` = Organization or company code
* `2606` = YYMM period
* `001` = running number within the sequence scope

---

# Required Sequence Scope

Document sequence must be unique per:

```text
organizationId
branchId
productType
documentType
period
```

The same period may have separate counters for different product types.

Example:

```text
ALLA + Branch A + Crane + Quotation + 2606 = CRA2606-001
ALLA + Branch A + Dock Door + Quotation + 2606 = DKA2606-001
ONVALLA + Branch O + Crane + Quotation + 2606 = CRO2606-001
ONVALLA + Branch O + Dock Door + Quotation + 2606 = DKO2606-001
ONVALLA + Branch O + Solar Cell + Quotation + 2606 = SCO2606-001
```

---

# Discovery Requirement

Before implementation, inspect the actual current implementation.

Review at minimum:

```text
src/features/foundation/document-sequence
src/db/schema.ts
drizzle migrations
foundation seed
CRM quotation create flow
CRM document sequence settings UI
/dashboard/crm/settings/document-sequences
```

Identify:

* current table structure
* current unique indexes
* current sequence service behavior
* current seed data
* current UI assumptions
* current document code format
* current quotation create integration

Do not assume the current implementation.

---

# Functional Requirements

## 1. Schema Refactor

Update `document_sequences` to support:

* organizationId
* branchId
* productType
* documentType
* period
* prefix
* currentNumber
* padding
* format
* resetPolicy
* isActive

Required uniqueness:

```text
organizationId + branchId + productType + documentType + period
```

If product type is optional for some future document types, represent this explicitly.

Do not collapse product type into prefix only.

---

## 2. Product Type Code Resolution

Resolve product type code from master data or mapping.

Examples:

| Product Type | Code |
| ------------ | ---- |
| Crane        | CR   |
| Dock Door    | DK   |
| Solar Cell   | SC   |
| Service      | SV   |
| Spare Part   | SP   |

The implementation must not hardcode business labels throughout the codebase.

Preferred source:

```text
ms_options / master options
```

or a centralized CRM product type code map.

---

## 3. Organization / Company Code Resolution

Resolve organization/company code for document number middle segment.

Examples:

| Organization | Code |
| ------------ | ---- |
| ALLA         | A    |
| ONVALLA      | O    |

The source should be centralized.

Do not infer by taking the first letter of the organization name unless explicitly configured.

---

## 4. Number Format

Required quotation number format:

```text
{productTypeCode}{organizationCode}{YYMM}-{running}
```

Examples:

```text
CRA2606-001
DKA2606-001
CRO2606-001
DKO2606-001
SCO2606-001
```

Document type should still be part of the sequence scope even if it does not appear visibly in the final code.

---

## 5. Period Handling

Use period format:

```text
YYMM
```

Example:

```text
2026-06 => 2606
```

Sequence resets per period.

---

## 6. Quotation Create Flow

Quotation creation must request the next sequence using:

* organizationId
* branchId
* productType
* documentType = quotation
* quotation date / created date period

The generated code must be stored on the quotation.

---

## 7. Settings UI

Update:

```text
/dashboard/crm/settings/document-sequences
```

The UI must show and filter by:

* Organization
* Branch
* Product Type
* Document Type
* Period
* Prefix / Format
* Current Number
* Next Number
* Active Status

It must be clear that Branch means internal company branch, not customer branch.

---

## 8. Seed Data

Update seed data to create realistic document sequence rows for:

```text
ALLA + Crane
ALLA + Dock Door
ONVALLA + Crane
ONVALLA + Dock Door
ONVALLA + Solar Cell
```

At minimum seed quotation sequence examples for the current period.

---

## 9. Backward Compatibility

Existing generated quotations must keep their current codes.

Do not retroactively change old quotation codes.

Only new generated codes use the new sequence logic.

If existing `document_sequences` rows lack product type, migration must either:

* backfill product type where determinable, or
* mark them as legacy/inactive, or
* keep them compatible without being used for new CRM quotation generation

---

# Concurrency Requirement

Sequence generation must be concurrency-safe.

When two users create quotations at the same time under the same scope, they must not receive duplicate codes.

Preferred approach:

* database transaction
* row-level lock
* atomic increment

Do not generate next number purely in client code.

---

# Error Handling

Handle:

* missing product type
* missing branch
* missing organization code
* missing product type code
* inactive sequence
* duplicate sequence row
* unsupported document type
* period mismatch

Errors should be business-readable.

---

# Audit Logging

Record audit logs for:

* sequence created
* sequence updated
* sequence activated/deactivated
* next number generated
* sequence generation failed

---

# Testing Requirements

Add tests for:

* separate counter per product type
* separate counter per organization
* separate counter per branch
* monthly reset
* concurrent generation safety if practical
* missing product type code
* missing organization code
* quotation create integration
* backward compatibility with existing quotation codes

Run:

```bash
npm run typecheck
npm run build
npm run audit:pdf
```

---

# Acceptance Criteria

* Document sequence scope includes Organization + Branch + Product Type + Document Type + Period.
* Quotation number format matches `{productTypeCode}{organizationCode}{YYMM}-{running}`.
* ALLA Crane can generate `CRA2606-001`.
* ALLA Dock Door can generate `DKA2606-001`.
* ONVALLA Crane can generate `CRO2606-001`.
* ONVALLA Dock Door can generate `DKO2606-001`.
* ONVALLA Solar Cell can generate `SCO2606-001`.
* Different product types do not share counters.
* Different organizations do not share counters.
* Different branches do not share counters.
* Existing quotation codes remain unchanged.
* Settings UI shows product type and branch clearly.
* Sequence generation is concurrency-safe.
* Runtime PDF audit still passes.

---

# Out of Scope

## P.7

* PDF merge
* Document Assembly
* SLA append rules
* Final merged artifact

## P.8

* Render configuration
* Optional sections
* User-selectable product table visibility

---

# Final Success Condition

Task P.6.1 is complete when new CRM quotations generate document numbers using the correct Organization + Branch + Product Type + Document Type + Period scope, while existing documents remain unchanged and the system is safe to proceed to P.7 Document Assembly.
