390 lines
7.3 KiB
Markdown
390 lines
7.3 KiB
Markdown
# 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.
|