lcbp3/specs/06-tasks/TASK-BE-017-document-numbering-refactor.md

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

---

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
• Redis Distributed Lock
• Idempotency-Key support
• Complete Audit & Metrics

---

Implementation Checklist

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
• Update Primary Key & Indices
• 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)
• DocumentNumberError: Store error logs (document_number_errors table)

---

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

---

3. Controller Updates

3.1 DocumentNumberingController

• POST /reserve: Reserve number (Phase 1)
• POST /confirm: Confirm number (Phase 2)
• POST /cancel: Cancel reservation
• POST /preview: Preview next number
• GET /sequences: Get current sequence status
• 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

---

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)
  • RFA: (proj, orig, 0, type, 0, rfaType, discipline, NONE)
  • 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)

---

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

---

Files to Create/Modify

Action	Path
MODIFY	backend/src/modules/document-numbering/document-numbering.module.ts
MODIFY	backend/src/modules/document-numbering/entities/document-number-counter.entity.ts
CREATE	backend/src/modules/document-numbering/entities/document-number-format.entity.ts
CREATE	backend/src/modules/document-numbering/entities/document-number-reservation.entity.ts
MODIFY	backend/src/modules/document-numbering/entities/document-number-audit.entity.ts
CREATE	backend/src/modules/document-numbering/entities/document-number-error.entity.ts
MODIFY	backend/src/modules/document-numbering/controllers/document-numbering.controller.ts
MODIFY	backend/src/modules/document-numbering/controllers/document-numbering-admin.controller.ts
CREATE	backend/src/modules/document-numbering/controllers/numbering-metrics.controller.ts
MODIFY	backend/src/modules/document-numbering/services/document-numbering.service.ts
CREATE	backend/src/modules/document-numbering/services/counter.service.ts
CREATE	backend/src/modules/document-numbering/services/document-numbering-lock.service.ts
CREATE	backend/src/modules/document-numbering/services/reservation.service.ts
CREATE	backend/src/modules/document-numbering/services/manual-override.service.ts
CREATE	backend/src/modules/document-numbering/services/format.service.ts
CREATE	backend/src/modules/document-numbering/services/template.service.ts
CREATE	backend/src/modules/document-numbering/services/audit.service.ts
CREATE	backend/src/modules/document-numbering/services/metrics.service.ts
CREATE	backend/src/modules/document-numbering/validators/template.validator.ts
CREATE	backend/src/modules/document-numbering/guards/idempotency.guard.ts

---

Acceptance Criteria

• Schema matches specs/03-implementation/03-04-document-numbering.md
• All 3 levels of locking (Redis, DB Optimistic, Unique Constraints) implemented
• Zero duplicates in load test
• Full audit trail visible

---

References

• Requirements v1.6.2
• Implementation Guide v1.6.2
• ADR-002