251218:1701 On going update to 1.7.0: Documnet Number rebuild

2025-12-18 17:01:42 +07:00
parent aaa5da3ec1
commit 83704377f4
102 changed files with 3385 additions and 1451 deletions
--- a/specs/03-implementation/03-01-fullftack-js-v1.7.0.md
+++ b/specs/03-implementation/03-01-fullftack-js-v1.7.0.md
--- a/specs/03-implementation/03-02-backend-guidelines.md
+++ b/specs/03-implementation/03-02-backend-guidelines.md
@@ -462,7 +462,7 @@ async approve(@Param('id') id: string, @CurrentUser() user: User) {

 ## 📚 เอกสารอ้างอิง

- [FullStack Guidelines](./fullftack-js-V1.5.0.md)
+- [FullStack Guidelines](03-01-fullftack-js-v1.7.0.md)
 - [Backend Plan v1.4.5](../../docs/2_Backend_Plan_V1_4_5.md)
 - [Data Dictionary](../../docs/4_Data_Dictionary_V1_4_5.md)
 - [Workflow Engine Plan](../../docs/2_Backend_Plan_V1_4_4.Phase6A.md)
--- a/specs/03-implementation/03-03-frontend-guidelines.md
+++ b/specs/03-implementation/03-03-frontend-guidelines.md
@@ -642,7 +642,7 @@ test.describe('Correspondence Workflow', () => {

 ## 📚 เอกสารอ้างอิง

- [FullStack Guidelines](./fullftack-js-V1.5.0.md)
+- [FullStack Guidelines](03-01-fullftack-js-v1.7.0.md)
 - [Frontend Plan v1.4.5](../../docs/3_Frontend_Plan_V1_4_5.md)
 - [Next.js Documentation](https://nextjs.org/docs)
 - [TanStack Query](https://tanstack.com/query)
--- a/specs/03-implementation/03-04-document-numbering.md
+++ b/specs/03-implementation/03-04-document-numbering.md
@@ -109,15 +109,17 @@ CREATE TABLE document_number_formats (
 ```sql
 CREATE TABLE document_number_counters (
  project_id INT NOT NULL,
+  correspondence_type_id INT NULL,
  originator_organization_id INT NOT NULL,
-  recipient_organization_id INT NULL,
-  correspondence_type_id INT NOT NULL,
+  recipient_organization_id INT NOT NULL DEFAULT 0, -- 0 = no recipient (RFA)
  sub_type_id INT DEFAULT 0,
  rfa_type_id INT DEFAULT 0,
  discipline_id INT DEFAULT 0,
-  current_year INT NOT NULL,
+  reset_scope VARCHAR(20) NOT NULL,
+  last_number INT DEFAULT 0 NOT NULL,,
  version INT DEFAULT 0 NOT NULL,
-  last_number INT DEFAULT 0,
+  created_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6),
+  updated_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),

  PRIMARY KEY (
    project_id,
@@ -127,19 +129,24 @@ CREATE TABLE document_number_counters (
    sub_type_id,
    rfa_type_id,
    discipline_id,
-    current_year
+    reset_scope
  ),

  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
  FOREIGN KEY (originator_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
-  FOREIGN KEY (recipient_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
  FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types(id) ON DELETE CASCADE,

-  INDEX idx_counter_lookup (project_id, correspondence_type_id, current_year),
-  INDEX idx_counter_org (originator_organization_id, current_year),
+  INDEX idx_counter_lookup (project_id, correspondence_type_id, reset_scope),
+  INDEX idx_counter_org (originator_organization_id, reset_scope),
+  INDEX idx_counter_updated (updated_at),

  CONSTRAINT chk_last_number_positive CHECK (last_number >= 0),
-  CONSTRAINT chk_current_year_valid CHECK (current_year BETWEEN 2020 AND 2100)
+  CONSTRAINT chk_reset_scope_format CHECK (
+    reset_scope IN ('NONE') OR
+    reset_scope LIKE 'YEAR_%' OR
+    reset_scope LIKE 'MONTH_%' OR
+    reset_scope LIKE 'CONTRACT_%'
+  )
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
  COMMENT='Running Number Counters';
 ```
@@ -149,18 +156,25 @@ CREATE TABLE document_number_counters (
 ```sql
 CREATE TABLE document_number_audit (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
-  operation ENUM('RESERVE', 'CONFIRM', 'CANCEL', 'MANUAL_OVERRIDE', 'VOID', 'GENERATE') NOT NULL,
  document_id INT NULL COMMENT 'FK to documents (NULL initially)',
  document_type VARCHAR(50),
-  generated_number VARCHAR(100) NOT NULL,
+  document_number VARCHAR(100) NOT NULL,
+  operation ENUM('RESERVE', 'CONFIRM', 'CANCEL', 'MANUAL_OVERRIDE', 'VOID', 'GENERATE') NOT NULL,
+  status ENUM('RESERVED', 'CONFIRMED', 'CANCELLED', 'VOID', 'MANUAL'),
  counter_key JSON NOT NULL COMMENT 'Counter key used (JSON format)',
+  reservation_token VARCHAR(36) NULL,
+  originator_organization_id INT NULL,
+  recipient_organization_id INT NULL,
+
  template_used VARCHAR(200) NOT NULL,
  old_value TEXT NULL,
  new_value TEXT NULL,
  user_id INT NULL COMMENT 'FK to users (Allow NULL for system generation)',
  ip_address VARCHAR(45),
+
  user_agent TEXT,
  is_success BOOLEAN DEFAULT TRUE,
+
  retry_count INT DEFAULT 0,
  lock_wait_ms INT COMMENT 'Lock acquisition time in milliseconds',
  total_duration_ms INT COMMENT 'Total generation time',
@@ -168,10 +182,11 @@ CREATE TABLE document_number_audit (
  metadata JSON NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

-  INDEX idx_operation (operation),
  INDEX idx_document_id (document_id),
-  INDEX idx_document_number (generated_number),
  INDEX idx_user_id (user_id),
+  INDEX idx_status (status),
+  INDEX idx_operation (operation),
+  INDEX idx_document_number (document_number),
  INDEX idx_created_at (created_at),
  FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE,
  FOREIGN KEY (user_id) REFERENCES users(id)
@@ -206,7 +221,55 @@ CREATE TABLE document_number_errors (
  INDEX idx_user_id (user_id)
 ) ENGINE=InnoDB COMMENT='Document Numbering Error Log';
 ```
+### 2.5 Reservation Table

+```sql
+CREATE TABLE document_number_reservations (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+
+  -- Reservation Details
+  token VARCHAR(36) NOT NULL UNIQUE COMMENT 'UUID v4',
+  document_number VARCHAR(100) NOT NULL UNIQUE,
+  status ENUM('RESERVED', 'CONFIRMED', 'CANCELLED', 'VOID') NOT NULL DEFAULT 'RESERVED',
+
+  -- Linkage
+  document_id INT NULL COMMENT 'FK to documents (NULL until confirmed)',
+
+  -- Context (for debugging)
+  project_id INT NOT NULL,
+  correspondence_type_id INT NOT NULL,
+  originator_organization_id INT NOT NULL,
+  recipient_organization_id INT DEFAULT 0,
+  user_id INT NOT NULL,
+
+  -- Timestamps
+  reserved_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6),
+  expires_at DATETIME(6) NOT NULL,
+  confirmed_at DATETIME(6) NULL,
+  cancelled_at DATETIME(6) NULL,
+
+  -- Audit
+  ip_address VARCHAR(45),
+  user_agent TEXT,
+  metadata JSON NULL COMMENT 'Additional context',
+
+  -- Indexes
+  INDEX idx_token (token),
+  INDEX idx_status (status),
+  INDEX idx_status_expires (status, expires_at),
+  INDEX idx_document_id (document_id),
+  INDEX idx_user_id (user_id),
+  INDEX idx_reserved_at (reserved_at),
+
+  -- Foreign Keys
+  FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE SET NULL,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types(id) ON DELETE CASCADE,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
+  COMMENT='Document Number Reservations - Two-Phase Commit';
+```
 ---

 ## 3. Core Services
@@ -748,10 +811,10 @@ GRAFANA_PORT=3000

 ## References

- [Requirements](file:///d:/nap-dms.lcbp3/specs/01-requirements/03.11-document-numbering.md)
- [Operations Guide](file:///d:/nap-dms.lcbp3/specs/04-operations/document-numbering-operations.md)
+- [Requirements](../01-requirements/01-03.11-document-numbering.md)
+- [Operations Guide](../04-operations/04-08-document-numbering-operations.md)
 - [ADR-018 Document Numbering](file:///d:/nap-dms.lcbp3/specs/05-decisions/adr-018-document-numbering.md)
- [Backend Guidelines](file:///d:/nap-dms.lcbp3/specs/03-implementation/backend-guidelines.md)
+- [Backend Guidelines](03-02-backend-guidelines.md)

 ---

--- a/specs/03-implementation/03-05-testing-strategy.md
+++ b/specs/03-implementation/03-05-testing-strategy.md
@@ -1229,10 +1229,10 @@ describe('[ClassName/FeatureName]', () => {

 ## 🔗 Related Documentation

- [Backend Guidelines](./backend-guidelines.md) - Backend development standards
- [Frontend Guidelines](./frontend-guidelines.md) - Frontend development standards
- [System Architecture](../02-architecture/system-architecture.md) - System overview
- [API Design](../02-architecture/api-design.md) - API specifications
+- [Backend Guidelines](03-02-backend-guidelines.md) - Backend development standards
+- [Frontend Guidelines](03-03-frontend-guidelines.md) - Frontend development standards
+- [System Architecture](../02-architecture/02-01-system-architecture.md) - System overview
+- [API Design](../02-architecture/02-02-api-design.md) - API specifications

 ---

--- a/specs/03-implementation/README.md
+++ b/specs/03-implementation/README.md
@@ -0,0 +1,119 @@
+# 🛠️ Implementation Specification
+
+> **แนวทางการพัฬนาและมาตรฐานทางเทคนิคของระบบ LCBP3-DMS**
+>
+> เอกสารชุดนี้รวบรวมมาตรฐานการเขียนโปรแกรม แนวทางการพัฒนา และรายละเอียดการนำสถาปัตยกรรมไปใช้งานจริง ทั้งในส่วนของ Backend และ Frontend
+
+---
+
+## 📊 Document Status
+
+| Attribute          | Value                            |
+| ------------------ | -------------------------------- |
+| **Version**        | 1.7.0                            |
+| **Status**         | Active                           |
+| **Last Updated**   | 2025-12-18                       |
+| **Owner**          | Nattanin Peancharoen             |
+| **Classification** | Internal Technical Documentation |
+
+---
+
+## 📚 Table of Contents
+
+- [หลักการพัฒนาหลัก (Core Principles)](#-หลักการพัฒนาหลัก-core-principles)
+- [คู่มือการพัฒนา (Implementation Guides)](#-คู่มือการพัฒนา-implementation-guides)
+- [มาตรฐานการเขียนโปรแกรม (Coding Standards)](#-มาตรฐานการเขียนโปรแกรม-coding-standards)
+- [Technology Stack Recap](#-technology-stack-recap)
+- [Testing Strategy](#-testing-strategy)
+- [Related Documents](#-related-documents)
+
+---
+
+## 🎯 หลักการพัฒนาหลัก (Core Principles)
+
+เพื่อให้ระบบมีความมั่นคง ยืดหยุ่น และดูแลรักษาง่าย การพัฒนาต้องยึดหลักการดังนี้:
+
+1.  **Type Safety Everywhere** - ใช้ TypeScript อย่างเข้มงวด ห้ามใช้ `any`
+2.  **Modular Dependency** - แยก Logic ตาม Module หลีกเลี่ยง Circular Dependency
+3.  **Idempotency** - การสร้างหรือแก้ไขข้อมูลต้องรองรับการกดซ้ำได้ (Idempotency-Key)
+4.  **Security by Default** - ตรวจสอบ Permission (RBAC) และ Validation ในทุก Endpoint
+5.  **Fail Fast & Log Everything** - ดักจับ Error ตั้งแต่เนิ่นๆ และบันทึก Audit Logs ที่สำคัญ
+
+---
+
+## 📖 คู่มือการพัฒนา (Implementation Guides)
+
+### 1. [FullStack JS Guidelines](./03-01-fullftack-js-v1.7.0.md)
+**แนวทางการพัฒนาภาพรวมทั้งระบบ (v1.7.0)**
+- โครงสร้างโปรเจกต์ (Monorepo-like focus)
+- Naming Conventions & Code Style
+- Secrets & Environment Management
+- Two-Phase File Storage Algorithm
+- Double-Lock Mechanism for Numbering
+
+### 2. [Backend Guidelines](./03-02-backend-guidelines.md)
+**แนวทางการพัฒนา NestJS Backend**
+- Modular Architecture Detail
+- DTO Validation & Transformer
+- TypeORM Best Practices & Optimistic Locking
+- JWT Authentication & CASL Authorization
+- BullMQ for Background Jobs
+
+### 3. [Frontend Guidelines](./03-03-frontend-guidelines.md)
+**แนวทางการพัฒนา Next.js Frontend**
+- App Router Patterns
+- Shadcn/UI & Tailwind Styling
+- TanStack Query for Data Fetching
+- React Hook Form + Zod for Client Validation
+- API Client Interceptors (Auth & Idempotency)
+
+### 4. [Document Numbering System](./03-04-document-numbering.md)
+**รายละเอียดการนำระบบออกเลขที่เอกสารไปใช้งาน**
+- Table Schema: Templates, Counters, Audit
+- Double-Lock Strategy (Redis Redlock + Database VersionColumn)
+- Reservation Flow (Phase 1: Reserve, Phase 2: Confirm)
+- API Specs for Numbering Management
+
+---
+
+## 🧪 Testing Strategy
+
+รายละเอียดอยู่ในเอกสาร: **[Testing Strategy](./03-05-testing-strategy.md)**
+
+- **Unit Testing:** NestJS (Jest), React (Vitest)
+- **Integration Testing:** API Endpoints (Supertest)
+- **E2E Testing:** Playwright สำหรับ Critical Flows
+- **Special Tests:** Concurrency Tests สำหรับ Document Numbering
+
+---
+
+## 🛠️ Technology Stack Recap
+
+| Layer        | Primary Technology | Secondary/Supporting |
+| ------------ | ------------------ | -------------------- |
+| **Backend**  | NestJS (Node.js)   | TypeORM, BullMQ      |
+| **Frontend** | Next.js 14+        | Shadcn/UI, Tailwind  |
+| **Database** | MariaDB 11.8       | Redis 7 (Cache/Lock) |
+| **Search**   | Elasticsearch      | -                    |
+| **Testing**  | Jest, Vitest       | Playwright           |
+
+---
+
+## 🔗 Related Documents
+
+- 📋 [Requirements Specification](../01-requirements/README.md)
+- 🏗️ [Architecture Specification](../02-architecture/README.md)
+- 🚀 [Operations Specification](../04-operations/README.md)
+- 🎯 [Active Tasks](../06-tasks/README.md)
+
+---
+
+<div align="center">
+
+**LCBP3-DMS Implementation Specification v1.7.0**
+
+[FullStack](./03-01-fullftack-js-v1.7.0.md) • [Backend](./03-02-backend-guidelines.md) • [Frontend](./03-03-frontend-guidelines.md) • [Testing](./03-05-testing-strategy.md)
+
+[Main README](../../README.md) • [Architecture](../02-architecture/README.md) • [Requirements](../01-requirements/README.md)
+
+</div>