260222:1053 20260222 refactor specs/ #1 03-Data-and-Storage

2026-02-22 10:53:23 +07:00
parent fd9be92b9d
commit c90a664f53
105 changed files with 2561 additions and 0 deletions
--- a/specs/99-archives/tasks/TASK-BE-017-document-numbering-refactor.md
+++ b/specs/99-archives/tasks/TASK-BE-017-document-numbering-refactor.md
@@ -0,0 +1,159 @@
+# 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](../01-requirements/01-03.11-document-numbering.md)
+- [Implementation Guide v1.6.2](../03-implementation/03-04-document-numbering.md)
+- [ADR-002](../05-decisions/ADR-002-document-numbering-strategy.md)