# 📝 **Documents Management System Version 1.4.2: แนวทางการพัฒนา FullStackJS** **สถานะ:** FINAL GUIDELINE **วันที่:** 2025-11-19 **อ้างอิง:** Requirements Specification v1.4.2 **Classification:** Internal Technical Documentation ## 🧠 **1. ปรัชญาทั่วไป (General Philosophy)** แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ **"Data Integrity First"** (ความถูกต้องของข้อมูลต้องมาก่อน) ตามด้วย Security และ UX * **ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก * **Strict Typing:** ใช้ TypeScript อย่างเคร่งครัด ห้าม `any` * **Consistency:** ใช้ภาษาอังกฤษใน Code / ภาษาไทยใน Comment * **Resilience:** ระบบต้องทนทานต่อ Network Failure และ Race Condition ## ⚙️ **2. แนวทางทั่วไปสำหรับ TypeScript** ### **2.1 หลักการพื้นฐาน** * ใช้ **ภาษาอังกฤษ** สำหรับโค้ด * ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด * กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด * หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง * ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public * ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์ * หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน * ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์ * ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก ### **2.2 Configuration & Secrets Management** * **Production/Staging:** ห้ามใส่ Secrets (Password, Keys) ใน `docker-compose.yml` หลัก * **Development:** ให้สร้างไฟล์ `docker-compose.override.yml` (เพิ่มใน `.gitignore`) เพื่อ Inject ตัวแปร Environment ที่เป็นความลับ * **Validation:** ใช้ `joi` หรือ `zod` ในการ Validate Environment Variables ตอน Start App หากขาดตัวแปรสำคัญให้ Throw Error ทันที ### **2.3 Idempotency (ความสามารถในการทำซ้ำได้)** * สำหรับการทำงานที่สำคัญ (Create Document, Approve, Transactional) **ต้อง** ออกแบบให้เป็น Idempotent * Client **ต้อง** ส่ง Header `Idempotency-Key` (UUID) มากับ Request * Server **ต้อง** ตรวจสอบว่า Key นี้เคยถูกประมวลผลสำเร็จไปแล้วหรือไม่ ถ้าใช่ ให้คืนค่าเดิมโดยไม่ทำซ้ำ ### **2.4 ข้อตกลงในการตั้งชื่อ (Naming Conventions)** | Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) | | :---- | :---- | :---- | | Classes | PascalCase | UserService | | Property | snake_case | user_id | | Variables & Functions | camelCase | getUserInfo | | Files & Folders | kebab-case | user-service.ts | | Environment Variables | UPPERCASE | DATABASE_URL | | Booleans | Verb + Noun | isActive, canDelete, hasPermission | ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx) ### 🧩**2.5 ฟังก์ชัน (Functions)** * เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด) * ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด * ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม * ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น * ใช้ **default parameters** แทนการตรวจสอบค่า null * จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern) * ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives) * รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน ### 🧱**2.6 การจัดการข้อมูล (Data Handling)** * ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types) * ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const * ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ * ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ ### 🧰**2.7 คลาส (Classes)** * ปฏิบัติตามหลักการ **SOLID** * ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance) * กำหนด **interfaces** สำหรับสัญญา (contracts) * ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties) ### 🚨**2.8 การจัดการข้อผิดพลาด (Error Handling)** * ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด * ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers * ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ ### 🧪**2.9 การทดสอบ (ทั่วไป) (Testing (General))** * ใช้รูปแบบ **Arrange–Act–Assert** * ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput) * เขียน **unit tests** สำหรับ public methods ทั้งหมด * จำลอง (Mock) การพึ่งพาภายนอก (external dependencies) * เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then ### **Testing Strategy โดยละเอียด** * **Test Pyramid Structure** /\ / \ E2E Tests (10%) /____\ Integration Tests (20%) / \ Unit Tests (70%) /________\ * **Testing Tools Stack** ```typescript // Backend Testing Stack const backendTesting = { unit: ['Jest', 'ts-jest', '@nestjs/testing'], integration: ['Supertest', 'Testcontainers', 'Jest'], e2e: ['Supertest', 'Jest', 'Database Seeds'], security: ['Jest', 'Custom Security Test Helpers'], performance: ['Jest', 'autocannon', 'artillery'] }; // Frontend Testing Stack const frontendTesting = { unit: ['Vitest', 'React Testing Library'], integration: ['React Testing Library', 'MSW'], e2e: ['Playwright', 'Jest'], visual: ['Playwright', 'Loki'] }; ``` * **Test Data Management** ```typescript // Test Data Factories interface TestDataFactory { createUser(overrides?: Partial): User; createCorrespondence(overrides?: Partial): Correspondence; createRoutingTemplate(overrides?: Partial): RoutingTemplate; } // Test Scenarios const testScenarios = { happyPath: 'Normal workflow execution', edgeCases: 'Boundary conditions and limits', errorConditions: 'Error handling and recovery', security: 'Authentication and authorization', performance: 'Load and stress conditions' }; ``` ## 🏗️ **3. แบ็กเอนด์ (NestJS) - Implementation Details** ### **3.1 หลักการ** * **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**: * หนึ่งโมดูลต่อหนึ่งโดเมน * โครงสร้างแบบ Controller → Service → Repository (Model) * API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team * DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator** * ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB * ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common): * Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators ### **3.2 Database & Data Modeling (MariaDB + TypeORM)** #### **3.2.1 Optimistic Locking & Versioning** เพื่อป้องกัน Race Condition ในการแก้ไขข้อมูลพร้อมกัน (โดยเฉพาะการรันเลขที่เอกสาร) ให้เพิ่ม Column `@VersionColumn()` ใน Entity ที่สำคัญ ```typescript @Entity() export class DocumentCounter { // ... fields @Column() last_number: number; @VersionColumn() // เพิ่ม Versioning version: number; } ``` #### **3.2.2 Virtual Columns for JSON Performance** เนื่องจากเราใช้ MariaDB 10.11 และมีการเก็บข้อมูล JSON (Details) ให้ใช้ **Generated Columns (Virtual)** สำหรับ Field ที่ต้อง Search/Sort บ่อยๆ และทำ Index บน Virtual Column นั้น ```sql -- ตัวอย่าง SQL Migration ALTER TABLE correspondence_revisions ADD COLUMN ref_project_id INT GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(details, '$.projectId'))) VIRTUAL; CREATE INDEX idx_ref_project_id ON correspondence_revisions(ref_project_id); ``` #### **3.2.3 Partitioning Strategy** สำหรับตาราง `audit_logs` และ `notifications` ให้เตรียมออกแบบ Entity ให้รองรับ Partitioning (เช่น แยกตามปี) โดยใช้ Raw SQL Migration ในการสร้างตาราง ### **3.3 File Storage Service (Two-Phase Storage)** ปรับปรุง Service จัดการไฟล์ให้รองรับ Transactional Integrity 1. **Upload (Phase 1):** * รับไฟล์ → Scan Virus (ClamAV) → Save ลงโฟลเดอร์ `temp/` * Return `temp_id` และ Metadata กลับไปให้ Client 2. **Commit (Phase 2):** * เมื่อ Business Logic (เช่น Create Correspondence) ทำงานสำเร็จ * Service จะย้ายไฟล์จาก `temp/` ไปยัง `permanent/{YYYY}/{MM}/` * Update path ใน Database * ทั้งหมดนี้ต้องอยู่ภายใต้ Database Transaction เดียวกัน (ถ้า DB Fail, ไฟล์จะค้างที่ Temp และถูกลบโดย Cron Job) ### **3.4 Document Numbering (Double-Lock Mechanism)** การออกเลขที่เอกสารต้องใช้กลไกความปลอดภัย 2 ชั้น: 1. **Layer 1 (Redis Lock):** ใช้ `redlock` เพื่อ Block ไม่ให้ Process อื่นเข้ามายุ่งกับ Counter ของ Project/Type นั้นๆ ชั่วคราว 2. **Layer 2 (Optimistic Lock):** ตอน Update Database ให้เช็ค `version` ถ้า version เปลี่ยน (แสดงว่า Redis Lock หลุดหรือมีคนแทรก) ให้ Throw Error และ Retry ใหม่ ### **3.5 Unified Workflow Engine** ห้ามแยก Logic ระหว่าง `CorrespondenceRouting` และ `RfaWorkflow` ออกจากกันเด็ดขาด ให้สร้าง `WorkflowEngineService` ที่เป็น Generic: * **Input:** `currentState`, `action`, `rules (Guard)` * **Output:** `nextState`, `assignee` * รองรับทั้ง Linear Flow (Routing) และ Complex Flow (RFA) ผ่าน Configuration ### **3.6 ฟังก์ชันหลัก (Core Functionalities)** * Global **filters** สำหรับการจัดการ exception * **Middlewares** สำหรับการจัดการ request * **Guards** สำหรับการอนุญาต (permissions) และ RBAC * **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log ### **3.7 ข้อจำกัดในการ Deploy (QNAP Container Station)** * **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1] * การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1] ### **3.8 ข้อจำกัดด้านความปลอดภัย (Security Constraints):** * **File Upload Security:** ต้องมี virus scanning (ClamAV), file type validation (white-list), และ file size limits (50MB) * **Input Validation:** ต้องป้องกัน OWASP Top 10 vulnerabilities (SQL Injection, XSS, CSRF) * **Rate Limiting:** ต้อง implement rate limiting ตาม strategy ที่กำหนด * **Secrets Management:** ต้องมี mechanism สำหรับจัดการ sensitive secrets อย่างปลอดภัย แม้จะใช้ docker-compose.yml ### **3.9 โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)** เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน: #### 3.9.1 **CommonModule:** * เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService * จัดการ audit_logs * NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7] #### 3.9.2 **AuthModule:** * จัดการะการยืนยันตัวตน (JWT, Guards) * **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **4 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับองกรณ์ (Organization Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ สิทธิ์ระดับสัญญา (Contract Role) * **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ: * สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3] * ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6] * ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10] #### 3.9.3 **UserModule:** * จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles * **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ: * สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3] #### 3.9.4 **ProjectModule:** * จัดการ projects, organizations, contracts, project_parties, contract_parties #### 3.9.5 **MasterModule:** * จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5] #### 3.9.6 **CorrespondenceModule (โมดูลศูนย์กลาง):** * จัดการ correspondences, correspondence_revisions, correspondence_tags * **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง * **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้ * จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ) * รับผิดชอบ Routing **Correspondence Routing** (correspondence_routings, correspondence_routing_template_steps, correspondence_routing_templates, correspondence_status_transitions) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร #### 3.9.7 **RfaModule:** * จัดการ rfas, rfa_revisions, rfa_items * รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค #### 3.9.8 **DrawingModule:** * จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs * จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ) #### 3.9.9 **CirculationModule:** * จัดการ circulations, circulation_templates, circulation_assignees * จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ) * รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร** #### 3.9.10 **TransmittalModule:** * จัดการ transmittals และ transmittal_items #### 3.9.11 **SearchModule:** * ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags * ระบบจะใช้ Elasticsearch Engine ในการจัดทำดัชนีเพื่อการค้นหาข้อมูลเชิงลึกจากเนื้อหาของเอกสาร โดยข้อมูลจะถูกส่งไปทำดัชนีจาก Backend (NestJS) ทุกครั้งที่มีการสร้างหรือแก้ไขเอกสาร #### 3.9.12 **DocumentNumberingModule:** * **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก * **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน * **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสารโดยใช้ **Redis distributed locking** แทน stored procedure * **Features:** * Application-level locking เพื่อป้องกัน race condition * Retry mechanism ด้วย exponential backoff * Fallback mechanism เมื่อการขอเลขล้มเหลว * Audit log ทุกครั้งที่มีการ generate เลขที่เอกสารใหม่ #### 3.9.13 **CorrespondenceRoutingModule:** * **สถานะ:** โมดูลหลักสำหรับจัดการการส่งต่อเอกสาร * **หน้าที่:** จัดการแม่แบบการส่งต่อและการส่งต่อจริง * **Entities:** * CorrespondenceRoutingTemplate * CorrespondenceRoutingTemplateStep * CorrespondenceRouting * **Features:** * สร้างและจัดการแม่แบบการส่งต่อ * ดำเนินการส่งต่อเอกสารตามแม่แบบ * ติดตามสถานะการส่งต่อ * คำนวณวันครบกำหนดอัตโนมัติ * ส่งการแจ้งเตือนเมื่อมีการส่งต่อใหม่ #### 3.9.14 **WorkflowEngineModule:** * **สถานะ:** Internal Module สำหรับจัดการ workflow logic * **หน้าที่:** ประมวลผล state transitions และ business rules * **Features:** * State machine สำหรับสถานะเอกสาร * Validation rules สำหรับการเปลี่ยนสถานะ * Automatic status updates * Deadline management และ escalation #### 3.9.15 **JsonSchemaModule:** * **สถานะ:** Internal Module สำหรับจัดการ JSON schemas * **หน้าที่:** Validate, transform, และ manage JSON data structures * **Features:** * JSON schema validation ด้วย AJV * Schema versioning และ migration * Dynamic schema generation * Data transformation และ sanitization #### 3.9.16 **DetailsService:** * **สถานะ:** Shared Service สำหรับจัดการ details fields * **หน้าที่:** Centralized service สำหรับ JSON details operations * **Methods:** * validateDetails(type: string, data: any): ValidationResult * transformDetails(input: any, targetVersion: string): any * sanitizeDetails(data: any): any * getDefaultDetails(type: string): any ### **3.10 สถาปัตยกรรมระบบ (System Architecture)** โครงสร้างโมดูล (Module Structure) ```bash 📁 src ├── 📄 app.module.ts ├── 📄 main.ts ├── 📁 common # @app/common (โมดูลส่วนกลาง) │ ├── 📁 auth # AuthModule (JWT, Guards) │ ├── 📁 config # Configuration │ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission) │ ├── 📁 entities # Shared Entities (User, Role, Permission) │ ├── 📁 exceptions # Global Exception Filters │ ├── 📁 file-storage # FileStorageService (Virus Scanning, Security) │ ├── 📁 guards # Custom Guards (RBAC Guard, RateLimitGuard) │ ├── 📁 interceptors # Interceptors (Audit Log, Transform, Performance) │ ├── 📁 resilience # Circuit Breaker, Retry Patterns │ └── 📁 services # Shared Services (NotificationService, CachingService) ├── 📁 modules │ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions) │ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts) │ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ) │ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ) │ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน) │ ├── 📁 circulation # CirculationModule (จัดการใบเวียน) │ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง) │ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch) │ ├── 📁 monitoring # MonitoringModule (Metrics, Health Checks) │ └── 📁 document-numbering # DocumentNumberingModule (Internal Module) └── 📁 database # Database Migration & Seeding Scripts ``` ### **3.11 กลยุทธ์ความทนทานและการจัดการข้อผิดพลาด (Resilience & Error Handling Strategy)** * **Circuit Breaker Pattern:** ใช้สำหรับ external service calls (Email, LINE, Elasticsearch) * **Retry Mechanism:** ด้วย exponential backoff สำหรับ transient failures * **Fallback Strategies:** Graceful degradation เมื่อบริการภายนอกล้มเหลว * **Error Handling:** Error messages ต้องไม่เปิดเผยข้อมูล sensitive * **Monitoring:** Centralized error monitoring และ alerting system ### **3.12 FileStorageService (ปรับปรุงใหม่):** * **Virus Scanning:** Integrate ClamAV สำหรับ scan ไฟล์ที่อัปโหลดทั้งหมด * **File Type Validation:** ใช้ white-list approach (PDF, DWG, DOCX, XLSX, ZIP) * **File Size Limits:** 50MB ต่อไฟล์ * **Security Measures:** * เก็บไฟล์นอก web root * Download ผ่าน authenticated endpoint เท่านั้น * Download links มี expiration time (24 ชั่วโมง) * File integrity checks (checksum) * Access control checks ก่อนดาวน์โหลด ### **3.13 เเทคโนโลยีที่ใช้ (Technology Stack)** | ส่วน | Library/Tool | หมายเหตุ | |---|---|---| | **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework | | **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ | | **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก | | **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล | | **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO | | **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT | |**Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC | | **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ | | **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง | | **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน | | **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) | | **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ | | **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E | | **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ | | **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API | | **Resilience** | `@nestjs/circuit-breaker` | 🔄 Circuit breaker pattern | | **Caching** | `@nestjs/cache-manager`, `cache-manager-redis-store` | 💾 Distributed caching | | **Security** | `helmet`, `csurf`, `rate-limiter-flexible` | 🛡️ Security enhancements | | **Validation** | `class-validator`, `class-transformer` | ✅ Input validation | | **Monitoring** | `@nestjs/monitoring`, `winston` | 📊 Application monitoring | | **File Processing** | `clamscan` | 🦠 Virus scanning | | **Cryptography** | `bcrypt`, `crypto` | 🔐 Password hashing และ checksums | | **JSON Validation** | `ajv`, `ajv-formats` | 🎯 JSON schema validation | | **JSON Processing** | `jsonpath`, `json-schema-ref-parser` | 🔧 JSON manipulation | | **Data Transformation** | `class-transformer` | 🔄 Object transformation | | **Compression** | `compression` | 📦 JSON compression | ### **3.14 Security Testing:** * **Penetration Testing:** ทดสอบ OWASP Top 10 vulnerabilities * **Security Audit:** Review code สำหรับ security flaws * **Virus Scanning Test:** ทดสอบ file upload security * **Rate Limiting Test:** ทดสอบ rate limiting functionality ### **3.15 Performance Testing:** * **Load Testing:** ทดสอบด้วย realistic workloads * **Stress Testing:** หา breaking points ของระบบ * **Endurance Testing:** ทดสอบการทำงานต่อเนื่องเป็นเวลานาน ### 🗄️**3.16 Backend State Management** Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB * **Request-Scoped State (สถานะภายใน Request เดียว):** * **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร? * **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้ * **Application-Scoped State (การ Caching):** * **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย * **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database ### **3.17 Caching Strategy (ตามข้อ 6.4.2):** * **Master Data Cache:** Roles, Permissions, Organizations (TTL: 1 hour) * **User Session Cache:** User permissions และ profile (TTL: 30 minutes) * **Search Result Cache:** Frequently searched queries (TTL: 15 minutes) * **File Metadata Cache:** Attachment metadata (TTL: 1 hour) * **Cache Invalidation:** Clear cache on update/delete operations ### **3.18 การไหลของข้อมูล (Data Flow)** #### **3.18.1 Main Flow:** 1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller 2. **Rate Limiting:** RateLimitGuard ตรวจสอบ request limits 3. **Input Validation:** Validation Pipe ตรวจสอบและ sanitize inputs 4. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User 5. Authorization: RBAC Guard ตรวจสอบสิทธิ์ 6. **Security Checks:** Virus scanning (สำหรับ file upload), XSS protection 7. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ 8. **Resilience:** Circuit breaker และ retry logic สำหรับ external calls 9. Data Access: Repository Layer ติดต่อกับฐานข้อมูล 10. **Caching:** Cache frequently accessed data 11. **Audit Log:** บันทึกการกระทำสำคัญ 12. Response: ส่งกลับไปยัง Frontend #### **3.18.2 Workflow Data Flow:** 1. User สร้างเอกสาร → เลือก routing template 2. System สร้าง routing instances ตาม template 3. สำหรับแต่ละ routing step: - กำหนด due date (จาก expected_days) - ส่ง notification ไปยังองค์กรผู้รับ - อัพเดทสถานะเป็น SENT 4. เมื่อองค์กรผู้รับดำเนินการ: - อัพเดทสถานะเป็น ACTIONED/FORWARDED/REPLIED - บันทึก processed_by และ processed_at - ส่ง notification ไปยังขั้นตอนต่อไป (ถ้ามี) 5. เมื่อครบทุกขั้นตอน → อัพเดทสถานะเอกสารเป็น COMPLETED #### **3.18.3 JSON Details Processing Flow:** 1. **Receive Request** → Get JSON data from client 2. **Schema Validation** → Validate against predefined schema 3. **Data Sanitization** → Sanitize and transform data 4. **Version Check** → Handle schema version compatibility 5. **Storage** → Store validated JSON in database 6. **Retrieval** → Retrieve and transform on demand ### 📊**3.19 Monitoring & Observability (ตามข้อ 6.8)** #### **Application Monitoring:** * **Health Checks:** `/health` endpoint สำหรับ load balancer * **Metrics Collection:** Response times, error rates, throughput * **Distributed Tracing:** สำหรับ request tracing across services * **Log Aggregation:** Structured logging ด้วย JSON format * **Alerting:** สำหรับ critical errors และ performance degradation #### **Business Metrics:** * จำนวน documents created ต่อวัน * Workflow completion rates * User activity metrics * System utilization rates * Search query performance #### **Performance Targets:** * API Response Time: < 200ms (90th percentile) * Search Query Performance: < 500ms * File Upload Performance: < 30 seconds สำหรับไฟล์ 50MB * Cache Hit Ratio: > 80% ## 🖥️ **4. ฟรอนต์เอนด์ (Next.js) - Implementation Details** **โปรไฟล์นักพัฒนา (Developer Profile:** วิศวกร TypeScript + React/NextJS ระดับ Senior เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI ### **4.1 State Management & Offline Support** #### **4.1.1 Auto-Save Drafts** ใช้ `zustand` ร่วมกับ middleware `persist` (ลง LocalStorage) สำหรับฟอร์มที่มีขนาดใหญ่ (RFA, Correspondence) เพื่อป้องกันข้อมูลหายเมื่อเน็ตหลุด ```typescript // lib/stores/draft-store.ts export const useDraftStore = create( persist( (set) => ({ drafts: {}, saveDraft: (key, data) => set((state) => ({ drafts: { ...state.drafts, [key]: data } })), clearDraft: (key) => set((state) => { const newDrafts = { ...state.drafts }; delete newDrafts[key]; return { drafts: newDrafts }; }), }), { name: 'form-drafts' } ) ); ``` ### **4.2 Dynamic Form Generator** เพื่อรองรับ JSON Schema หลากหลายรูปแบบ ให้สร้าง Component กลางที่รับ Schema แล้ว Gen Form ออกมา (ลดการแก้ Code บ่อยๆ) * **Libraries:** แนะนำ `react-jsonschema-form` หรือสร้าง Wrapper บน `react-hook-form` ที่ Recursively render field ตาม Type * **Validation:** ใช้ `ajv` ที่ฝั่ง Client เพื่อ Validate JSON ก่อน Submit ### **4.3 Mobile Responsiveness (Card View)** ตารางข้อมูล (`DataTable`) ต้องมีความฉลาดในการแสดงผล: * **Desktop:** แสดงเป็น Table ปกติ * **Mobile:** แปลงเป็น **Card View** โดยอัตโนมัติ (ซ่อน Header, แสดง Label คู่ Value ในแต่ละ Card) ```tsx // components/ui/responsive-table.tsx
{/* Desktop View */}
{data.map((item) => ( {/* Mobile View: Render cells as list items */} ))}
``` ### **4.4 Optimistic Updates** ใช้ความสามารถของ **TanStack Query** (`onMutate`) เพื่ออัปเดต UI ทันที (เช่น เปลี่ยนสถานะจาก "รออ่าน" เป็น "อ่านแล้ว") แล้วค่อยส่ง Request ไป Server ถ้า Failed ค่อย Rollback ### **4.5 แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)** * ใช้ **early returns** เพื่อความชัดเจน * ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ * ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings * ใช้ **const arrow functions** สำหรับ components และ handlers * Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit) * รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย: tabIndex="0", aria-label, onKeyDown, ฯลฯ * ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)** * ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ ### **4.6 UI/UX ด้วย React** * ใช้ **semantic HTML** * ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:) * รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing * ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน * ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง * ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ) * ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup ### **4.7 การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)** * ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form * แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline * ต้องมี labels, placeholders, และข้อความ feedback ### **🧪4.8 Frontend Testing** เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E: * **Unit Tests (การทดสอบหน่วยย่อย):** * **เครื่องมือ:** Vitest + RTL * **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions * **Integration Tests (การทดสอบการบูรณาการ):** * **เครื่องมือ:** RTL + **Mock Service Worker (MSW)** * **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง * **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks) * **E2E (End-to-End) Tests:** * **เครื่องมือ:** **Playwright** * **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6]) ### **🗄️4.9 Frontend State Management** สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ: 1. **Local UI State (สถานะ UI ชั่วคราว):** * **เครื่องมือ:** useState, useReducer * **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input) 2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):** * **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR * **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings) * **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ 3. **Global Client State (สถานะส่วนกลางฝั่ง Client):** * **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API * **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions) 4. **Form State (สถานะของฟอร์ม):** * **เครื่องมือ:** **React Hook Form** + **Zod** * **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7]) ## 🔐 **5. Security & Access Control (Full Stack Integration)** ### **5.1 CASL Integration (Shared Ability)** * **Backend:** ใช้ CASL กำหนด Permission Rule * **Frontend:** ให้ดึง Rule (JSON) จาก Backend มา Load ใส่ `@casl/react` เพื่อให้ Logic การ Show/Hide ปุ่ม ตรงกัน 100% ### **5.2 Maintenance Mode** เพิ่ม Middleware (ทั้ง NestJS และ Next.js) เพื่อตรวจสอบ Flag ใน Redis: * ถ้า `MAINTENANCE_MODE = true` * **API:** Return `503 Service Unavailable` (ยกเว้น Admin IP) * **Frontend:** Redirect ไปหน้า `/maintenance` ### **5.3 Idempotency Client** สร้าง Axios Interceptor เพื่อ Generate `Idempotency-Key` สำหรับ POST/PUT/DELETE requests ทุกครั้ง ```typescript // lib/api/client.ts import { v4 as uuidv4 } from 'uuid'; apiClient.interceptors.request.use((config) => { if (['post', 'put', 'delete'].includes(config.method)) { config.headers['Idempotency-Key'] = uuidv4(); } return config; }); ``` ### **5.4 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)** ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions ```typescript @RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code' @Put(':id') updateRFA(@Param('id') id: string) { return this.rfaService.update(id); } ``` #### **5.4.1 Roles (บทบาท)** * **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3] * **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3] * **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3] * **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3] * **Viewer**: สามารถดู เอกสาร [cite: 4.3] #### **5.4.2 ตัวอย่าง Permissions (จากตาราง permissions)** * rfas.view, rfas.create, rfas.respond, rfas.delete * drawings.view, drawings.upload, drawings.delete * corr.view, corr.manage * transmittals.manage * cirs.manage * project_parties.manage การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3] ## 📊 **6. Notification & Background Jobs** ### **6.1 Digest Notification** ห้ามส่ง Email ทันทีที่เกิด Event ให้: 1. Push Event ลง Queue (Redis/BullMQ) 2. มี Processor รอเวลา (เช่น 5 นาที) เพื่อ Group Events ที่คล้ายกัน (เช่น "คุณมีเอกสารรออนุมัติ 5 ฉบับ") 3. ส่ง Email เดียว (Digest) เพื่อลด Spam ## 🔗 **7. แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)** | Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) | | :---- | :---- | :---- | :---- | | API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล | | Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn | | Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) | | Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback | | Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression | | Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities | | Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML | ## 🗂️ **8. ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)** ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation) ### 🧾**8.1 มาตรฐาน AuditLog (AuditLog Standard)** บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs | Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) | | :---- | :---- | :---- | | audit_id | BIGINT | Primary Key | | user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) | | action | VARCHAR(100) | rfa.create, correspondence.update, login.success | | entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' | | entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ | | details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) | | ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ | | user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ | | created_at | TIMESTAMP | Timestamp (UTC) | ### 📂**8.2 การจัดการไฟล์ (File Handling)** #### **8.2.1 มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)** * **Security-First Approach:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService ที่มี security measures ครบถ้วน * ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น: * correspondence_attachments (เชื่อม Correspondence กับ Attachments) * circulation_attachments (เชื่อม Circulation กับ Attachments) * shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments) * contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments) * เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored_filename]) * ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip (ผ่าน white-list validation) * ขนาดสูงสุด: **50 MB** * จัดเก็บนอก webroot * ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download #### **8.2.2 Security Controls สำหรับ File Access:** การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง: 1. ค้นหาระเบียน attachment 2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม 3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่ 4. ตรวจสอบ download token expiration (24 ชั่วโมง) 5. บันทึก audit log การดาวน์โหลด ### 🔟**8.3 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]** * **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence_number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด * **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year** * **ตาราง SQL:** * document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5] * document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year) * **การทำงาน (Backend):** * DocumentNumberingModule จะให้บริการ DocumentNumberingService * เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...) * Service นี้จะใช้ **Redis distributed locking** แทน stored procedure ซึ่งจะจัดการ Database Transaction และ Row Locking ภายใน Application Layer เพื่อรับประกันการป้องกัน Race Condition * มี retry mechanism และ fallback strategies ### 📊**8.4 การรายงานและการส่งออก (Reporting & Exports)** #### **8.4.1 วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)** การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก: * v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA * v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master * v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization * v_user_tasks: สำหรับ Dashboard "งานของฉัน" * v_audit_log_details: สำหรับ Activity Feed Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล #### **8.4.2 กฎการส่งออก (Export Rules)** * Export formats: CSV, Excel, PDF. * จัดเตรียมมุมมองสำหรับพิมพ์ (Print view). * รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id). ## 🧮 **9. ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)** ### **9.1 DataTable (Server‑Side)** * Endpoint: /api/{module}?page=1&pageSize=20&sort=...&filter=... * ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters) * แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing) ### **9.2 มาตรฐานฟอร์ม (Form Standards)** * ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ): * Project → Contract Drawing Volumes * Contract Drawing Category → Sub-Category * RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้ * **File Upload Security:** ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7] พร้อม virus scanning feedback * **File Type Indicators:** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7] พร้อมแสดง file type icons * **Security Feedback:** แสดง security warnings สำหรับ file types ที่เสี่ยงหรือ files ที่ fail virus scan * ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast ### **9.3 ข้อกำหนด Component เฉพาะ (Specific UI Requirements)** * **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v_user_tasks [cite: 5.3] * **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6] * **Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])** * **Security Dashboard:** แสดง security metrics และ audit logs สำหรับ administrators ## 🧭 **10. แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)** ### **10.1 การ์ดบนแดชบอร์ด (Dashboard Cards)** * แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด * รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3] * รวมลิงก์ด่วนไปยังโมดูลต่างๆ * **Security Metrics:** แสดงจำนวน files scanned, security incidents, failed login attempts ### **10.2 ฟีดกิจกรรม (Activity Feed)** * แสดงรายการ v_audit_log_details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้ * รวม security-related activities (failed logins, permission changes) ```typescript // ตัวอย่าง API response [ { user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }, { user: 'system', action: 'Virus scan completed - 0 threats found', time: '2025-11-04T09:25Z' } ] ``` ## 🛡️ **11. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)** ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทาน * **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs * **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination * **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env) * **File Security [cite: 3.9.6]:** ต้องมี virus scanning, file type validation, access controls * **Resilience [cite: 6.5.3]:** ต้องมี circuit breaker, retry mechanisms, graceful degradation * **Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง * **Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด * **Monitoring [cite: 6.8]:** ต้องมี health checks, metrics collection, alerting ## ✅ **12. มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.4.0) (Implemented Standards (from SQL v1.4.0))** ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่ * ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL * ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ * ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว * ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว * ✅ **Application-level Locking:** ใช้ Redis distributed lock แทน stored procedure * ✅ **File Security:** Virus scanning, file type validation, access control * ✅ **Resilience Patterns:** Circuit breaker, retry, fallback mechanisms * ✅ **Security Measures:** Input validation, rate limiting, security headers * ✅ **Monitoring:** Health checks, metrics collection, distributed tracing ## 🧩 **13. การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))** * ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7]) * ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า) * 🔄 **AI-Powered Document Classification:** ใช้ machine learning สำหรับ automatic document categorization * 🔄 **Advanced Analytics:** Predictive analytics สำหรับ workflow optimization * 🔄 **Mobile App:** Native mobile application สำหรับ field workers * 🔄 **Blockchain Integration:** สำหรับ document integrity verification ที่ต้องการความปลอดภัยสูงสุด ## ✅ **14. Summary Checklist for Developers** ก่อนส่ง PR (Pull Request) นักพัฒนาต้องตรวจสอบหัวข้อต่อไปนี้: * [ ] **Security:** ไม่มี Secrets ใน Code, ใช้ `docker-compose.override.yml` แล้ว * [ ] **Concurrency:** ใช้ Optimistic Lock ใน Entity ที่เสี่ยง Race Condition แล้ว * [ ] **Idempotency:** API รองรับ Idempotency Key แล้ว * [ ] **File Upload:** ใช้ Flow Two-Phase (Temp -> Perm) แล้ว * [ ] **Mobile:** หน้าจอแสดงผลแบบ Card View บนมือถือได้ถูกต้อง * [ ] **Performance:** สร้าง Index สำหรับ JSON Virtual Columns แล้ว (ถ้ามี) --- ## 📋 **15. Summary of Key Changes from Previous Version** ### **Security Enhancements:** 1. **File Upload Security** - Virus scanning, file type validation, access controls 2. **Input Validation** - OWASP Top 10 protection, XSS/CSRF prevention 3. **Rate Limiting** - Comprehensive rate limiting strategy 4. **Secrets Management** - Secure handling of sensitive configuration ### **Architecture Improvements:** 1. **Document Numbering** - Changed from Stored Procedure to Application-level Locking 2. **Resilience Patterns** - Circuit breaker, retry mechanisms, fallback strategies 3. **Monitoring & Observability** - Health checks, metrics, distributed tracing 4. **Caching Strategy** - Comprehensive caching with proper invalidation ### **Performance Targets :** 1. **API Response Time** - < 200ms (90th percentile) 2. **Search Performance** - < 500ms 3. **File Upload** - < 30 seconds for 50MB files 4. **Cache Hit Ratio** - > 80% ### **Operational Excellence:** 1. **Disaster Recovery** - RTO < 4 hours, RPO < 1 hour 2. **Backup Procedures** - Comprehensive backup and restoration 3. **Security Testing** - Penetration testing and security audits 4. **Performance Testing** - Load testing with realistic workloads เอกสารนี้สะท้อนถึงความมุ่งมั่นในการสร้างระบบที่มีความปลอดภัย, มีความทนทาน, และมีประสิทธิภาพสูง พร้อมรองรับการเติบโตในอนาคตและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป **หมายเหตุ:** แนวทางนี้จะถูกทบทวนและปรับปรุงเป็นระยะตาม feedback จากทีมพัฒนาและความต้องการทางธุรกิจที่เปลี่ยนแปลงไป ## **Document Control:** * **Document:** FullStackJS v1.4.2 * **Version:** 1.4 * **Date:** 2025-11-19 * **Author:** NAP LCBP3-DMS & Gemini * **Status:** FINAL * **Classification:** Internal Technical Documentation * **Approved By:** Nattanin --- `End of FullStackJS Guidelines v1.4.2`