251218:1701 On going update to 1.7.0: Documnet Number rebuild

specs/09-history/2025-12-18-refactor-document-numbering.md

@@ -0,0 +1,55 @@
+# Document Numbering Refactoring - 2025-12-18
+
+## Overview
+Refactored the `DocumentNumberingService` in the backend to split responsibilities into dedicated services (`CounterService`, `ReservationService`) and updated the `DocumentNumberCounter` entity to match the v1.7.0 schema.
+
+## Changes
+
+### 1. Module Restructuring
+- **Services**: Created `CounterService` and `ReservationService`.
+- **DTOs**: Created `CounterKeyDto`, `ReserveNumberDto`, `ConfirmReservationDto`.
+- **Controllers**: Updated `DocumentNumberingController` and `DocumentNumberingAdminController`.
+
+### 2. Entity Updates
+- **`DocumentNumberCounter`**:
+    - Made `correspondenceTypeId`, `recipientOrganizationId`, etc., non-nullable primary keys (defaulting to 0).
+    - Added `resetScope` with length 20.
+- **`DocumentNumberReservation`**: Created for two-phase commit reservation logic.
+
+### 3. Service Logic
+- **`CounterService`**:
+    - Handles atomic counter increment.
+    - Implements optimistic locking with retry logic using `OptimisticLockVersionMismatchError`.
+- **`ReservationService`**:
+    - Manages `DocumentNumberReservation` entity (Reserve -> Confirm/Cancel).
+    - Removes unused `userId` from confirmation/cancellation logic.
+- **`DocumentNumberingService`**:
+    - Delegates counter logic to `CounterService`.
+    - Delegates reservation logic to `ReservationService`.
+    - Corrected property mapping (e.g., `originatorOrganizationId`).
+    - Fixed `resolveDisciplineCode` to use `disciplineCode` column.
+
+## Verification Results
+
+### Automated Tests
+Ran unit tests for `DocumentNumberingService`:
+```bash
+npm test modules/document-numbering/document-numbering.service.spec.ts
+```
+
+**Result:**
+```
+PASS src/modules/document-numbering/document-numbering.service.spec.ts
+  DocumentNumberingService
+    √ should be defined (13 ms)
+    generateNextNumber
+      √ should generate a new number successfully (6 ms)
+      √ should throw error when increment fails (12 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       3 passed, 3 total
+```
+
+### Manual Verification Steps
+1.  **Generate Number**: Call `POST /document-numbering/preview` (mapped to `previewNumber`).
+2.  **Admin Ops**: Verified `DocumentNumberingAdminController` structure updates.