251223:1649 On going update to 1.7.0: Refoctory drawing Module & document number Module
This commit is contained in:
admin
@@ -5,17 +5,20 @@ status: TODO
|
||||
priority: HIGH
|
||||
estimated_effort: 3-5 days
|
||||
dependencies:
|
||||
- specs/01-requirements/03.11-document-numbering.md (v1.6.2)
|
||||
- specs/03-implementation/document-numbering.md (v1.6.2)
|
||||
- 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 โดยเน้น:
|
||||
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
|
||||
- Counter Key alignment ตาม requirements
|
||||
- Complete Audit & Metrics
|
||||
|
||||
---
|
||||
|
||||
@@ -24,138 +27,128 @@ Refactor Document Numbering module ตาม specification v1.6.2 โดยเ
|
||||
### 1. Entity Updates
|
||||
|
||||
#### 1.1 DocumentNumberCounter Entity
|
||||
- [ ] Rename `current_year` → ใช้ `reset_scope` pattern (YEAR_2025, NONE)
|
||||
- [ ] 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 if missing
|
||||
- [ ] Update Primary Key ให้ตรงกับ requirements spec
|
||||
- [ ] Add `rfa_type_id`, `sub_type_id`, `discipline_id` columns
|
||||
- [ ] Update Primary Key & Indices
|
||||
- [ ] Add `version` column for optimistic locking
|
||||
|
||||
```typescript
|
||||
// Expected Counter Key structure
|
||||
interface CounterKey {
|
||||
projectId: number;
|
||||
originatorOrganizationId: number;
|
||||
recipientOrganizationId: number; // 0 for RFA
|
||||
correspondenceTypeId: number;
|
||||
subTypeId: number; // 0 if not applicable
|
||||
rfaTypeId: number; // 0 if not applicable
|
||||
disciplineId: number; // 0 if not applicable
|
||||
resetScope: string; // 'YEAR_2025', 'NONE'
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.2 DocumentNumberAudit Entity
|
||||
- [ ] Add `operation` enum: `RESERVE`, `CONFIRM`, `CANCEL`, `MANUAL_OVERRIDE`, `VOID`, `GENERATE`
|
||||
- [ ] Ensure `counter_key` is stored as JSON
|
||||
- [ ] Add `idempotency_key` column
|
||||
|
||||
#### 1.3 DocumentNumberReservation Entity (NEW if not exists)
|
||||
- [ ] Create entity for Two-Phase Commit reservations
|
||||
- [ ] Fields: `token`, `document_number`, `status`, `expires_at`, `metadata`
|
||||
#### 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 DocumentNumberingService
|
||||
- [ ] Implement `reserveNumber()` - Phase 1 of Two-Phase Commit
|
||||
- [ ] Implement `confirmNumber()` - Phase 2 of Two-Phase Commit
|
||||
- [ ] Implement `cancelNumber()` - Explicit cancel reservation
|
||||
- [ ] Add Idempotency-Key checking logic
|
||||
- [ ] Update `generateNextNumber()` to use new CounterKey structure
|
||||
#### 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 Counter Key Builder
|
||||
- [ ] Create helper to build counter key based on document type:
|
||||
- Global (LETTER, MEMO, RFI): `(project, orig, recip, type, 0, 0, 0, YEAR_XXXX)`
|
||||
- TRANSMITTAL: `(project, orig, recip, type, subType, 0, 0, YEAR_XXXX)`
|
||||
- RFA: `(project, orig, 0, type, 0, rfaType, discipline, NONE)`
|
||||
#### 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 ManualOverrideService
|
||||
- [ ] Implement `manualOverride()` with validation
|
||||
- [ ] Auto-update counter if manual number > current
|
||||
|
||||
#### 2.4 VoidReplaceService
|
||||
- [ ] Implement `voidAndReplace()` workflow
|
||||
- [ ] Link new document to voided document
|
||||
#### 2.3 Feature Services
|
||||
- [ ] **ManualOverrideService**: Handle manual number assignment & sequence adjustment
|
||||
- [ ] **MigrationService**: Handle bulk import / legacy data migration
|
||||
|
||||
---
|
||||
|
||||
### 3. Controller Updates
|
||||
|
||||
#### 3.1 DocumentNumberingController
|
||||
- [ ] Add `POST /reserve` endpoint
|
||||
- [ ] Add `POST /confirm` endpoint
|
||||
- [ ] Add `POST /cancel` endpoint
|
||||
- [ ] Add `Idempotency-Key` header validation middleware
|
||||
- [ ] `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
|
||||
- [ ] Add `POST /manual-override` endpoint
|
||||
- [ ] Add `POST /void-and-replace` endpoint
|
||||
- [ ] Add `POST /bulk-import` endpoint
|
||||
- [ ] Add `GET /metrics` endpoint for monitoring dashboard
|
||||
- [ ] `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. Number State Machine
|
||||
### 4. Logic & Algorithms
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> RESERVED: reserve()
|
||||
RESERVED --> CONFIRMED: confirm()
|
||||
RESERVED --> CANCELLED: cancel() or TTL expired
|
||||
CONFIRMED --> VOID: void()
|
||||
CANCELLED --> [*]
|
||||
VOID --> [*]
|
||||
```
|
||||
#### 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.1 State Transitions
|
||||
- [ ] Implement state validation before transitions
|
||||
- [ ] Log all transitions to audit table
|
||||
- [ ] TTL 5 minutes for RESERVED state
|
||||
#### 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.incrementCounter()
|
||||
- [ ] ReservationService.reserve/confirm/cancel()
|
||||
- [ ] TemplateValidator.validate()
|
||||
- [ ] CounterKeyBuilder
|
||||
- [ ] `CounterService` optimistic locking
|
||||
- [ ] `TemplateValidator` grammar check
|
||||
- [ ] `ReservationService` expiry logic
|
||||
|
||||
#### 5.2 Integration Tests
|
||||
- [ ] Two-Phase Commit flow
|
||||
- [ ] Idempotency-Key duplicate prevention
|
||||
- [ ] Redis lock + DB optimistic lock
|
||||
|
||||
#### 5.3 Load Tests
|
||||
- [ ] Concurrent number generation (1000 req/s)
|
||||
- [ ] Zero duplicates verification
|
||||
- [ ] 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` |
|
||||
| MODIFY | `backend/src/modules/document-numbering/entities/document-number-audit.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/services/document-numbering.service.ts` |
|
||||
| CREATE | `backend/src/modules/document-numbering/services/reservation.service.ts` |
|
||||
| CREATE | `backend/src/modules/document-numbering/services/manual-override.service.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
|
||||
|
||||
- [ ] All Counter Key ตรงกับ requirements v1.6.2
|
||||
- [ ] Number State Machine ทำงานถูกต้อง
|
||||
- [ ] Idempotency-Key ป้องกัน duplicate requests
|
||||
- [ ] Zero duplicate numbers ใน concurrent load test
|
||||
- [ ] Audit logs บันทึกทุก operation
|
||||
- [ ] 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
|
||||
|
||||
---
|
||||
|
||||
|
||||
37
specs/06-tasks/TASK-BE-018-v170-refactor.md
Normal file
37
specs/06-tasks/TASK-BE-018-v170-refactor.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: 'Task: Backend Refactoring for Schema v1.7.0'
|
||||
status: DONE
|
||||
owner: Backend Team
|
||||
created_at: 2025-12-23
|
||||
related:
|
||||
- specs/01-requirements/01-03.11-document-numbering.md
|
||||
- specs/07-database/lcbp3-v1.7.0-schema.sql
|
||||
- specs/07-database/data-dictionary-v1.7.0.md
|
||||
---
|
||||
|
||||
## Objective
|
||||
Update backend entities and logic to align with schema v1.7.0 and revised document numbering specifications.
|
||||
|
||||
## Scope of Work
|
||||
|
||||
### 1. Drawing Module
|
||||
- **Contract Drawings:**
|
||||
- Update `ContractDrawing` entity (map_cat_id, volume_page)
|
||||
- Create `ContractDrawingSubcatCatMap` entity
|
||||
- **Shop Drawings:**
|
||||
- Update `ShopDrawingMainCategory` (add project_id)
|
||||
- Update `ShopDrawingSubCategory` (add project_id, remove main_cat_id)
|
||||
- Update `ShopDrawing` (remove title)
|
||||
- Update `ShopDrawingRevision` (add title, legacy_number)
|
||||
- **As Built Drawings (New):**
|
||||
- Create entities for `asbuilt_drawings` and related tables.
|
||||
|
||||
### 2. Document Numbering Module
|
||||
- **Counters:**
|
||||
- Update `DocumentNumberCounter` entity to match 8-part Composite Key.
|
||||
- Ensure strict typing for `reset_scope`.
|
||||
|
||||
## Definition of Done
|
||||
- [x] All entities match v1.7.0 schema
|
||||
- [x] Application compiles without type errors
|
||||
- [x] Document Numbering service supports new key structure
|
||||
@@ -5,9 +5,9 @@ status: TODO
|
||||
priority: HIGH
|
||||
estimated_effort: 2-3 days
|
||||
dependencies:
|
||||
- TASK-BE-017-document-numbering-refactor.md
|
||||
- specs/01-requirements/03.11-document-numbering.md (v1.6.2)
|
||||
- specs/03-implementation/document-numbering.md (v1.6.2)
|
||||
- specs/06-tasks/TASK-BE-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)
|
||||
---
|
||||
|
||||
## Objective
|
||||
@@ -136,13 +136,13 @@ interface AuditQueryParams {
|
||||
|
||||
### 4. Components to Create
|
||||
|
||||
| Component | Path | Description |
|
||||
| ------------------ | ----------------------------------------------- | --------------------------- |
|
||||
| MetricsDashboard | `components/numbering/metrics-dashboard.tsx` | Metrics charts and gauges |
|
||||
| AuditLogsTable | `components/numbering/audit-logs-table.tsx` | Filterable audit log viewer |
|
||||
| ManualOverrideForm | `components/numbering/manual-override-form.tsx` | Admin tool form |
|
||||
| VoidReplaceForm | `components/numbering/void-replace-form.tsx` | Admin tool form |
|
||||
| BulkImportForm | `components/numbering/bulk-import-form.tsx` | CSV/Excel uploader |
|
||||
| Component | Path | Description |
|
||||
| ------------------ | -------------------------------------------------------- | --------------------------- |
|
||||
| MetricsDashboard | `frontend/components/numbering/metrics-dashboard.tsx` | Metrics charts and gauges |
|
||||
| AuditLogsTable | `frontend/components/numbering/audit-logs-table.tsx` | Filterable audit log viewer |
|
||||
| ManualOverrideForm | `frontend/components/numbering/manual-override-form.tsx` | Admin tool form |
|
||||
| VoidReplaceForm | `frontend/components/numbering/void-replace-form.tsx` | Admin tool form |
|
||||
| BulkImportForm | `frontend/components/numbering/bulk-import-form.tsx` | CSV/Excel uploader |
|
||||
|
||||
---
|
||||
|
||||
|
||||
53
specs/06-tasks/TASK-FE-019-v170-refactor.md
Normal file
53
specs/06-tasks/TASK-FE-019-v170-refactor.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: 'Task: Frontend Refactoring for Schema v1.7.0'
|
||||
status: IN_PROGRESS
|
||||
owner: Frontend Team
|
||||
created_at: 2025-12-23
|
||||
related:
|
||||
- specs/06-tasks/TASK-BE-018-v170-refactor.md
|
||||
- specs/07-database/data-dictionary-v1.7.0.md
|
||||
---
|
||||
|
||||
## Objective
|
||||
Update frontend application to align with the refactored backend (v1.7.0 schema). This includes supporting new field mappings, new As Built drawing type, and updated document numbering logic.
|
||||
|
||||
## Scope of Work
|
||||
|
||||
### 1. Type Definitions & API Client
|
||||
- **Types**: Update `Drawing`, `ContractDrawing`, `ShopDrawing` interfaces to match new backend entities (e.g. `mapCatId`, `projectId` in categories).
|
||||
- **API**: Update `drawing.service.ts` to support new filter parameters (`mapCatId`) and new endpoints for As Built drawings.
|
||||
|
||||
### 2. Drawing Upload Form (`DrawingUploadForm`)
|
||||
- **General**: Refactor to support dynamic fields based on Drawing Type.
|
||||
- **Contract Drawings**:
|
||||
- Replace `subCategoryId` with `mapCatId` (fetch from `contract-drawing-categories`?).
|
||||
- Add `volumePage` input.
|
||||
- **Shop Drawings**:
|
||||
- Remove `sheetNumber` (if not applicable) or map to `legacyDrawingNumber`.
|
||||
- Add `legacyDrawingNumber` input.
|
||||
- Handle `title` input (sent as revision title).
|
||||
- Use Project-specific categories.
|
||||
- **As Built Drawings (New)**:
|
||||
- Add "AS_BUILT" option.
|
||||
- Implement form fields similar to Shop Drawings (or Contract depending on spec).
|
||||
|
||||
### 3. Drawing List & Views (`DrawingList`)
|
||||
- **Contract Drawings**: Show `volumePage`.
|
||||
- **Shop Drawings**:
|
||||
- Display `legacyDrawingNumber`.
|
||||
- Display Title from *Current Revision*.
|
||||
- Remove direct title column from sort/filter if backend doesn't support it anymore on master.
|
||||
- **As Built Drawings**:
|
||||
- Add new Tab/Page for As Built.
|
||||
- Implement List View.
|
||||
|
||||
### 4. Logic & Hooks
|
||||
- Update `useDrawings`, `useCreateDrawing` hooks to handle new types.
|
||||
- Ensure validation schemas (`zod`) match backend constraints.
|
||||
|
||||
## Definition of Done
|
||||
- [x] Contract Drawing Upload works with `mapCatId` and `volumePage`
|
||||
- [x] Shop Drawing Upload works with `legacyDrawingNumber` and Revision Title
|
||||
- [x] As Built Drawing Upload and List implemented
|
||||
- [x] Drawing List displays correct columns for all types
|
||||
- [x] No TypeScript errors
|
||||
Reference in New Issue
Block a user