251216:0946 Docunment Number: Update specs/ and backend/

2025-12-16 09:46:37 +07:00
parent 78370fb590
commit 9c1e175b76
17 changed files with 932 additions and 3259 deletions
--- a/specs/03-implementation/document-numbering.md
+++ b/specs/03-implementation/document-numbering.md
@@ -2,10 +2,10 @@

 ---
 title: 'Implementation Guide: Document Numbering System'
-version: 1.5.1
+version: 1.6.1
 status: draft
 owner: Development Team
-last_updated: 2025-12-02
+last_updated: 2025-12-16
 related:

 - specs/01-requirements/03.11-document-numbering.md
@@ -31,6 +31,21 @@ related:
 ### 1.1. Counter Table Schema

 ```sql
+CREATE TABLE document_number_formats (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  project_id INT NOT NULL,
+  correspondence_type_id INT NULL, -- NULL indicates default format for the project
+  format_template VARCHAR(100) NOT NULL,
+  reset_sequence_yearly TINYINT(1) DEFAULT 1,
+  description VARCHAR(255),
+  created_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6),
+  updated_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+
+  UNIQUE KEY idx_unique_project_type (project_id, correspondence_type_id),
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types(id) ON DELETE CASCADE
+);
+
 CREATE TABLE document_number_counters (
  project_id INT NOT NULL,
  originator_organization_id INT NOT NULL,
@@ -73,14 +88,15 @@ CREATE TABLE document_number_counters (
 ```sql
 CREATE TABLE document_number_audit (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
-  document_id INT NOT NULL,
+  document_id INT NULL COMMENT 'FK to documents (NULL initially, updated after doc creation)',
  generated_number VARCHAR(100) NOT NULL,
  counter_key JSON NOT NULL COMMENT 'Counter key used (JSON format)',
  template_used VARCHAR(200) NOT NULL,
-  user_id INT NOT NULL,
+  user_id INT NULL COMMENT 'FK to users (Allow NULL for system generation)',
  ip_address VARCHAR(45),
  user_agent TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  is_success BOOLEAN DEFAULT TRUE COMMENT 'Track success/failure status',

  -- Performance & Error Tracking
  retry_count INT DEFAULT 0,
@@ -152,7 +168,50 @@ src/modules/document-numbering/
    └── metrics.service.ts
 ```

-### 2.2. TypeORM Entity
+### 2.2. Number Generation Process
+
+#### 2.2.1. Resolve Format Template:
+  * Query document_number_formats by project_id + type_id.
+  * If no result, query by project_id + NULL (Default Project Format).
+  * If still no result, apply System Default Template: `{ORG}-{RECIPIENT}-{SEQ:4}-{YEAR:BE}`.
+  * Determine resetSequenceYearly flag from the found format (default: true)
+
+#### 2.2.2. Determine Counter Key:
+  * If resetSequenceYearly is True: Use Current Year (e.g., 2025).
+  * If resetSequenceYearly is False: Use 0 (Continuous).
+  * Use type_id from the resolved format (Specific ID or NULL).
+
+#### 2.2.3. Generate Number:
+  * Use format template to generate number.
+  * Replace tokens with actual values:
+    * {PROJECT} -> Project Code
+    * {ORG} -> Originator Organization Code
+    * {RECIPIENT} -> Recipient Organization Code
+    * {TYPE} -> Type Code
+    * {YEAR} -> Current Year
+    * {SEQ} -> Sequence Number
+    * {REV} -> Revision Number
+
+#### 2.2.4. Validate Number:
+  * Check if generated number is unique.
+  * If not unique, increment sequence and retry.
+
+#### 2.2.5. Update Counter:
+  * Update document_number_counters with new sequence.
+
+#### 2.2.6. Generate Audit Record:
+  * Create audit record with:
+    * Generated number
+    * Counter key used
+    * Template used
+    * User ID
+    * IP Address
+    * User Agent
+
+#### 2.2.7. Return Generated Number:
+  * Return generated number to caller.
+
+### 2.3. TypeORM Entity

 ```typescript
 // File: src/modules/document-numbering/entities/document-number-counter.entity.ts
@@ -192,7 +251,7 @@ export class DocumentNumberCounter {
 }
 ```

-### 2.3. Redis Lock Service
+### 2.4. Redis Lock Service

 ```typescript
 // File: src/modules/document-numbering/services/document-numbering-lock.service.ts
--- a/specs/05-decisions/ADR-002-document-numbering-strategy.md
+++ b/specs/05-decisions/ADR-002-document-numbering-strategy.md
@@ -122,20 +122,19 @@ LCBP3-DMS ต้องสร้างเลขที่เอกสารอั

 ```sql
 -- Format Templates
-CREATE TABLE document_number_configs (
+CREATE TABLE document_number_formats (
  id INT PRIMARY KEY AUTO_INCREMENT,
  project_id INT NOT NULL,
-  doc_type_id INT NOT NULL COMMENT 'Correspondence, RFA, Transmittal, Drawing',
-  sub_type_id INT DEFAULT 0 COMMENT 'ประเภทย่อย (nullable, use 0 for fallback)',
-  discipline_id INT DEFAULT 0 COMMENT 'สาขาวิชา (nullable, use 0 for fallback)',
-  template VARCHAR(255) NOT NULL COMMENT 'e.g. {PROJECT}-{ORG}-{TYPE}-{DISCIPLINE}-{SEQ:4}-{REV}',
+  correspondence_type_id INT NULL COMMENT 'Specific Type ID, or NULL for Project Default', -- CHANGED: Allow NULL
+  format_template VARCHAR(100) NOT NULL COMMENT 'e.g. {PROJECT}-{TYPE}-{YEAR}-{SEQ:4}',
  description TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  version INT DEFAULT 0 NOT NULL COMMENT 'For template versioning',
-  FOREIGN KEY (project_id) REFERENCES projects(id),
-  FOREIGN KEY (doc_type_id) REFERENCES document_types(id),
-  UNIQUE KEY unique_config (project_id, doc_type_id, sub_type_id, discipline_id)
+
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types(id) ON DELETE CASCADE,
+  -- Note: Application logic must enforce single default format per project
+  UNIQUE KEY unique_format (project_id, correspondence_type_id)
 ) ENGINE=InnoDB COMMENT='Template configurations for document numbering';

 -- Counter Table with Optimistic Locking
@@ -208,6 +207,19 @@ CREATE TABLE document_number_audit (
 >
 > **Always refer to**: [03.11-document-numbering.md](../01-requirements/03.11-document-numbering.md) as source of truth

+### Format Resolution Strategy (Fallback Logic)
+
+The system resolves the numbering format using the following priority:
+1.  **Specific Format:** Search for a record matching both `project_id` and `correspondence_type_id`.
+2.  **Default Format:** If not found, search for a record with matching `project_id` where `correspondence_type_id` is `NULL`.
+3.  **System Fallback:** If neither exists, use the hardcoded system default: `{ORG}-{RECIPIENT}-{SEQ:4}-{YEAR:BE}`.
+
+| Priority | Scenario | Template Source | Counter Scope (Key) | Reset Behavior |
+| --- | --- | --- | --- | --- |
+| 1 | Specific Format Found | Database (project_id, type_id) | Specific Type (type_id) | Based on reset_sequence_yearly flag |
+| 2 | Default Format Found | Database (project_id, type_id=NULL) | Shared Counter (type_id=NULL) | Based on reset_sequence_yearly flag |
+| 3 | Fallback (No Config) | System Default: {ORG}-{RECIPIENT}-{SEQ:4}-{YEAR:BE} | Shared Counter (type_id=NULL) | Reset Yearly (Default: True) |
+
 ### Format Examples by Document Type

 #### 1. Correspondence (หนังสือราชการ)
--- a/specs/05-decisions/ADR-005-technology-stack.md
+++ b/specs/05-decisions/ADR-005-technology-stack.md
@@ -107,7 +107,7 @@ LCBP3-DMS ต้องเลือก Technology Stack สำหรับพั
 | Component             | Technology          | Rationale                              |
 | :-------------------- | :------------------ | :------------------------------------- |
 | **Framework**         | Next.js 14+         | App Router, SSR/SSG, React integration |
-| **UI Library**        | React 18            | Industry standard, large ecosystem     |
+| **UI Library**        | React 19            | Industry standard, large ecosystem     |
 | **Language**          | TypeScript 5.x      | Consistency with backend               |
 | **Styling**           | Tailwind CSS        | Utility-first, fast development        |
 | **Component Library** | shadcn/ui           | Accessible, customizable, TypeScript   |
--- a/specs/07-database/lcbp3-v1.6.0-schema.sql
+++ b/specs/07-database/lcbp3-v1.6.0-schema.sql
@@ -963,9 +963,10 @@ CREATE TABLE contract_drawing_attachments (
 CREATE TABLE document_number_formats (
  id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ของตาราง',
  project_id INT NOT NULL COMMENT 'โครงการ',
-  correspondence_type_id INT NOT NULL COMMENT 'ประเภทเอกสาร',
+  correspondence_type_id INT NULL COMMENT 'ประเภทเอกสาร',
  discipline_id INT DEFAULT 0 COMMENT 'สาขางาน (0 = ทุกสาขา/ไม่ระบุ)',
-  format_template VARCHAR(255) NOT NULL COMMENT 'รูปแบบ Template (เช่น {ORG_CODE}-{TYPE_CODE}-{SEQ:4})',
+  format_template VARCHAR(255) NOT NULL COMMENT 'รูปแบบ Template (เช่น {ORG}-{RECIPIENT}-{SEQ:4}-{YEAR:BE})',
+  reset_sequence_yearly TINYINT(1) DEFAULT 1,
  example_number VARCHAR(100) COMMENT 'ตัวอย่างเลขที่ได้จาก Template',
  padding_length INT DEFAULT 4 COMMENT 'ความยาวของลำดับเลข (Padding)',
  reset_annually BOOLEAN DEFAULT TRUE COMMENT 'เริ่มนับใหม่ทุกปี',
@@ -975,10 +976,9 @@ CREATE TABLE document_number_formats (
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
  FOREIGN KEY (project_id) REFERENCES projects (id) ON DELETE CASCADE,
  FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types (id) ON DELETE CASCADE,
-  UNIQUE KEY uk_proj_type_disc (
+  UNIQUE KEY unique_format (
    project_id,
-    correspondence_type_id,
-    discipline_id
+    correspondence_type_id
  )
 ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตาราง Master เก็บ "รูปแบบ" Template ของเลขที่เอกสาร';