260322:1648 Correct Coresspondence / Doing RFA / Correct CI

specs/99-archives/tasks/TASK-BE-017-document-numbering-refactor.md

@@ -1,18 +1,22 @@
 # TASK-BE-017: Document Numbering Backend Refactor
 
 ---
+
 status: TODO
 priority: HIGH
 estimated_effort: 3-5 days
 dependencies:
-  - specs/01-requirements/01-03.11-document-numbering.md (v1.6.2)
-  - specs/03-implementation/03-04-document-numbering.md (v1.6.2)
-related_task: TASK-FE-017-document-numbering-refactor.md
+
+- specs/01-requirements/01-03.11-document-numbering.md (v1.6.2)
+- specs/03-implementation/03-04-document-numbering.md (v1.6.2)
+  related_task: TASK-FE-017-document-numbering-refactor.md
+
 ---
 
 ## Objective
 
 Refactor Document Numbering module ตาม specification v1.6.2 และ Implementation Guide โดยเน้น:
+
 - Single Numbering System (Option A)
 - Number State Machine (RESERVED → CONFIRMED → VOID → CANCELLED)
 - Two-Phase Commit implementation
@@ -27,6 +31,7 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 ### 1. Entity Updates
 
 #### 1.1 DocumentNumberCounter Entity
+
 - [ ] Rename `current_year` → ใช้ `reset_scope` pattern (`YEAR_2025`, `NONE`)
 - [ ] Ensure FK columns match: `correspondence_type_id`, `originator_organization_id`, `recipient_organization_id`
 - [ ] Add `rfa_type_id`, `sub_type_id`, `discipline_id` columns
@@ -34,6 +39,7 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 - [ ] Add `version` column for optimistic locking
 
 #### 1.2 New Entities (Create)
+
 - [ ] **DocumentNumberFormat**: Store templates per project/type (`document_number_formats` table)
 - [ ] **DocumentNumberReservation**: Store active reservations (`document_number_reservations` table)
 - [ ] **DocumentNumberAudit**: Store complete audit trail (`document_number_audit` table)
@@ -44,18 +50,21 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 ### 2. Service Updates
 
 #### 2.1 Core Services
+
 - [ ] **DocumentNumberingService**: Main orchestration (Reserve, Confirm, Cancel, Preview)
 - [ ] **CounterService**: Handle `incrementCounter` with DB optimistic lock & retry logic
 - [ ] **DocumentNumberingLockService**: Implement Redis Redlock (`acquireLock`, `releaseLock`)
 - [ ] **ReservationService**: Handle Two-Phase Commit logic (TTL, cleanup)
 
 #### 2.2 Helper Services
+
 - [ ] **FormatService**: Format number string based on template & tokens
 - [ ] **TemplateService**: CRUD operations for `DocumentNumberFormat` and validation
 - [ ] **AuditService**: Async logging to `DocumentNumberAudit`
 - [ ] **MetricsService**: Prometheus counters/gauges (utilization, lock wait time)
 
 #### 2.3 Feature Services
+
 - [ ] **ManualOverrideService**: Handle manual number assignment & sequence adjustment
 - [ ] **MigrationService**: Handle bulk import / legacy data migration
 
@@ -64,6 +73,7 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 ### 3. Controller Updates
 
 #### 3.1 DocumentNumberingController
+
 - [ ] `POST /reserve`: Reserve number (Phase 1)
 - [ ] `POST /confirm`: Confirm number (Phase 2)
 - [ ] `POST /cancel`: Cancel reservation
@@ -72,12 +82,14 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 - [ ] Add `Idempotency-Key` header validation
 
 #### 3.2 DocumentNumberingAdminController
+
 - [ ] `POST /manual-override`
 - [ ] `POST /void-and-replace`
 - [ ] `POST /bulk-import`
 - [ ] `POST /templates`: Manage templates
 
 #### 3.3 NumberingMetricsController
+
 - [ ] `GET /metrics`: Expose utilization & health metrics for dashboard
 
 ---
@@ -85,6 +97,7 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 ### 4. Logic & Algorithms
 
 #### 4.1 Counter Key Builder
+
 - Implement logic to build unique key tuple:
   - Global: `(proj, orig, recip, type, 0, 0, 0, YEAR_XXXX)`
   - Transmittal: `(proj, orig, recip, type, subType, 0, 0, YEAR_XXXX)`
@@ -92,11 +105,13 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
   - Drawing: `(proj, TYPE, main, sub)` (separate namespace)
 
 #### 4.2 State Machine
+
 - [ ] Validate transitions: RESERVED -> CONFIRMED
 - [ ] Auto-expire RESERVED -> CANCELLED (via Cron/TTL)
 - [ ] CONFIRMED -> VOID
 
 #### 4.3 Lock Strategy
+
 - [ ] Try Redis Lock -> if valid -> Increment -> Release
 - [ ] Fallback to DB Lock if Redis unavailable (optional/advanced)
 
@@ -105,11 +120,13 @@ Refactor Document Numbering module ตาม specification v1.6.2 และ Impl
 ### 5. Testing
 
 #### 5.1 Unit Tests
+
 - [ ] `CounterService` optimistic locking
 - [ ] `TemplateValidator` grammar check
 - [ ] `ReservationService` expiry logic
 
 #### 5.2 Integration Tests
+
 - [ ] Full Two-Phase Commit flow
 - [ ] Concurrent requests (check for duplicates)
 - [ ] Idempotency-Key behavior