np-dms/lcbp3
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Main: revise specs to 1.5.0 (completed)

Browse Source
This commit is contained in:
admin
2025-12-01 01:28:32 +07:00
parent 241022ada6
commit 71c091055a
69 changed files with 28252 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
specs/00-overview/README.md
View File

@@ -1 +1,402 @@
# Project overview
# LCBP3-DMS - Project Overview
**Project Name:** Laem Chabang Port Phase 3 - Document Management System (LCBP3-DMS)
**Version:** 1.5.0
**Status:** Planning & Specification Phase
**Last Updated:** 2025-12-01
---
## 📋 Table of Contents
- [Project Introduction](#-project-introduction)
- [Key Features](#-key-features)
- [Technology Stack](#-technology-stack)
- [Project Structure](#-project-structure)
- [Quick Links](#-quick-links)
- [Getting Started](#-getting-started)
- [Team & Stakeholders](#-team--stakeholders)
---
## 🎯 Project Introduction
LCBP3-DMS is a comprehensive Document Management System (DMS) designed specifically for the Laem Chabang Port Phase 3 construction project. The system manages construction documents, workflows, approvals, and communications between multiple organizations including port authority, consultants, contractors, and third parties.
### Project Objectives
1. **Centralize Document Management** - Single source of truth for all project documents
2. **Streamline Workflows** - Automated routing and approval processes
3. **Improve Collaboration** - Real-time access for all stakeholders
4. **Ensure Compliance** - Audit trails and document version control
5. **Enhance Efficiency** - Reduce paper-based processes and manual routing
### Project Scope
**In Scope:**
- Correspondence Management (Letters & Communications)
- RFA (Request for Approval) Management
- Drawing Management (Contract & Shop Drawings)
- Workflow Engine (Approvals & Routing)
- Document Numbering System
- File Storage & Management
- Search & Reporting
- User & Access Management
- Audit Logs & Notifications
**Out of Scope:**
- Financial Management & Billing
- Procurement & Material Management
- Project Scheduling (Gantt Charts)
- HR & Payroll Systems
- Mobile App (Phase 1 only)
---
## ✨ Key Features
### 📨 Correspondence Management
- Create, review, and track official letters
- Master-Revision pattern for version control
- Multi-level approval workflows
- Attachment management
- Automatic document numbering
### 📋 RFA Management
- Submit requests for approval
- Item-based RFA structure
- Response tracking (Approved/Approved with Comments/Rejected)
- Revision management
- Integration with workflow engine
### 📐 Drawing Management
- Contract Drawings (แบบคู่สัญญา)
- Shop Drawings (แบบก่อสร้าง) with revisions
- Version control & comparison
- Drawing linking and references
### ⚙️ Workflow Engine
- DSL-based workflow configuration
- Dynamic routing based on rules
- Parallel & sequential approvals
- Escalation & timeout handling
- Workflow history & audit trail
### 🗄️ Document Numbering
- Automatic number generation
- Template-based formatting
- Discipline-specific numbering
- Concurrent request handling (Double-lock mechanism)
- Annual reset support
### 🔍 Search & Discovery
- Full-text search (Elasticsearch)
- Advanced filtering
- Document metadata search
- Quick access to recent documents
### 🔐 Security & Access Control
- 4-Level Hierarchical RBAC (Global/Organization/Project/Contract)
- JWT-based authentication
- Permission-based access control
- Audit logging
- Session management
### 📧 Notifications
- Multi-channel (Email, LINE Notify, In-app)
- Workflow event notifications
- Customizable user preferences
- Async delivery (Queue-based)
---
## 🛠️ Technology Stack
### Backend
- **Framework:** NestJS (TypeScript)
- **Database:** MariaDB 10.11
- **Cache & Queue:** Redis 7.2
- **Search:** Elasticsearch 8.11
- **ORM:** TypeORM
- **Authentication:** JWT (JSON Web Tokens)
- **Authorization:** CASL (4-Level RBAC)
- **File Processing:** ClamAV (Virus Scanning)
- **Queue:** BullMQ
### Frontend
- **Framework:** Next.js 14+ (App Router)
- **Language:** TypeScript
- **Styling:** Tailwind CSS
- **UI Components:** Shadcn/UI
- **State Management:** React Context / Zustand
- **Forms:** React Hook Form + Zod
- **API Client:** Axios
### Infrastructure
- **Deployment:** Docker & Docker Compose
- **Platform:** QNAP Container Station
- **Reverse Proxy:** NGINX
- **Logging:** Winston
- **Monitoring:** Health Checks + Log Aggregation
---
## 📁 Project Structure
```
lcbp3/
├── backend/ # NestJS Backend Application
│ ├── src/
│ │ ├── modules/ # Feature modules
│ │ ├── common/ # Shared utilities
│ │ ├── config/ # Configuration
│ │ └── migrations/ # Database migrations
│ ├── test/ # Tests
│ └── package.json
│
├── frontend/ # Next.js Frontend Application
│ ├── app/ # App router pages
│ ├── components/ # React components
│ ├── lib/ # Utilities
│ └── package.json
│
├── docs/ # Source documentation
│ ├── 0_Requirements_V1_4_5.md
│ ├── 1_FullStackJS_V1_4_5.md
│ ├── 2_Backend_Plan_V1_4_4.md
│ ├── 3_Frontend_Plan_V1_4_4.md
│ └── 4_Data_Dictionary_V1_4_5.md
│
├── specs/ # Technical Specifications
│ ├── 00-overview/ # Project overview & glossary
│ ├── 01-requirements/ # Functional requirements
│ ├── 02-architecture/ # System architecture
│ ├── 03-implementation/ # Implementation guidelines
│ ├── 04-operations/ # Deployment & operations
│ ├── 05-decisions/ # Architecture Decision Records (ADRs)
│ └── 06-tasks/ # Development tasks
│
├── docker-compose.yml # Docker services configuration
└── README.md # Project README
```
---
## 🔗 Quick Links
### Documentation
| Category | Document | Description |
| ------------------ | --------------------------------------------------------------------------- | ------------------------------------- |
| **Overview** | [Glossary](./glossary.md) | Technical terminology & abbreviations |
| **Overview** | [Quick Start](./quick-start.md) | 5-minute getting started guide |
| **Requirements** | [Functional Requirements](../01-requirements/03-functional-requirements.md) | Feature specifications |
| **Architecture** | [System Architecture](../02-architecture/system-architecture.md) | Overall system design |
| **Architecture** | [Data Model](../02-architecture/data-model.md) | Database schema |
| **Architecture** | [API Design](../02-architecture/api-design.md) | REST API specifications |
| **Implementation** | [Backend Guidelines](../03-implementation/backend-guidelines.md) | Backend coding standards |
| **Implementation** | [Frontend Guidelines](../03-implementation/frontend-guidelines.md) | Frontend coding standards |
| **Implementation** | [Testing Strategy](../03-implementation/testing-strategy.md) | Testing approach |
| **Operations** | [Deployment Guide](../04-operations/deployment-guide.md) | How to deploy |
| **Operations** | [Monitoring](../04-operations/monitoring-alerting.md) | Monitoring & alerts |
| **Decisions** | [ADR Index](../05-decisions/README.md) | Architecture decisions |
| **Tasks** | [Backend Tasks](../06-tasks/README.md) | Development tasks |
### Key ADRs
1. [ADR-001: Unified Workflow Engine](../05-decisions/ADR-001-unified-workflow-engine.md)
2. [ADR-002: Document Numbering Strategy](../05-decisions/ADR-002-document-numbering-strategy.md)
3. [ADR-003: Two-Phase File Storage](../05-decisions/ADR-003-file-storage-approach.md)
4. [ADR-004: RBAC Implementation](../05-decisions/ADR-004-rbac-implementation.md)
5. [ADR-005: Technology Stack](../05-decisions/ADR-005-technology-stack.md)
---
## 🚀 Getting Started
### For Developers
1. **Read Documentation**
- Start with [Quick Start Guide](./quick-start.md)
- Review [System Architecture](../02-architecture/system-architecture.md)
- Study [Backend](../03-implementation/backend-guidelines.md) / [Frontend](../03-implementation/frontend-guidelines.md) guidelines
2. **Setup Development Environment**
- Clone repository
- Install Docker & Docker Compose
- Run `docker-compose up`
- Access backend: `http://localhost:3000`
- Access frontend: `http://localhost:3001`
3. **Start Coding**
- Pick a task from [Backend Tasks](../06-tasks/README.md)
- Follow coding guidelines
- Write tests
- Submit PR for review
### For Operations Team
1. **Infrastructure Setup**
- Review [Environment Setup](../04-operations/environment-setup.md)
- Configure QNAP Container Station
- Setup Docker Compose
2. **Deployment**
- Follow [Deployment Guide](../04-operations/deployment-guide.md)
- Configure [Backup & Recovery](../04-operations/backup-recovery.md)
- Setup [Monitoring](../04-operations/monitoring-alerting.md)
3. **Maintenance**
- Review [Maintenance Procedures](../04-operations/maintenance-procedures.md)
- Setup [Incident Response](../04-operations/incident-response.md)
- Configure [Security Operations](../04-operations/security-operations.md)
---
## 👥 Team & Stakeholders
### Project Team
- **System Architect:** Nattanin Peancharoen
- **Backend Team Lead:** [Name]
- **Frontend Team Lead:** [Name]
- **DevOps Engineer:** [Name]
- **QA Lead:** [Name]
- **Database Administrator:** [Name]
### Stakeholders
- **Port Authority of Thailand (กทท.)** - Owner
- **Project Supervisors (สค©.)** - Consultants
- **Design Consultants (TEAM)** - Designers
- **Construction Supervisors (คคง.)** - Supervision
- **Contractors (ผรม.1-4)** - Construction
---
## 📊 Project Timeline
### Phase 1: Foundation (Weeks 1-4)
- Database setup & migrations
- Authentication & RBAC
- **Milestone:** User can login
### Phase 2: Core Infrastructure (Weeks 5-10)
- User Management & Master Data
- File Storage & Document Numbering
- Workflow Engine
- **Milestone:** Core services ready
### Phase 3: Business Modules (Weeks 11-17)
- Correspondence Management
- RFA Management
- **Milestone:** Core documents manageable
### Phase 4: Supporting Modules (Weeks 18-21)
- Drawing Management
- Circulation & Transmittal
- Search & Elasticsearch
- **Milestone:** Document ecosystem complete
### Phase 5: Services (Week 22)
- Notifications & Audit Logs
- **Milestone:** MVP ready for UAT
### Phase 6: Testing & Deployment (Weeks 23-24)
- User Acceptance Testing (UAT)
- Production deployment
- **Milestone:** Go-Live
---
## 📈 Success Metrics
### Technical Metrics
- **Uptime:** > 99.5%
- **API Response Time (P95):** < 500ms
- **Error Rate:** < 1%
- **Database Query Time (P95):** < 100ms
### Business Metrics
- **User Adoption:** > 90% of stakeholders using system
- **Document Processing Time:** 50% reduction vs manual
- **Search Success Rate:** > 95%
- **User Satisfaction:** > 4.0/5.0
---
## 🔐 Security & Compliance
- **Data Encryption:** At rest & in transit
- **Access Control:** 4-level RBAC
- **Audit Logging:** All user actions logged
- **Backup:** Daily automated backups
- **Disaster Recovery:** RTO 4h, RPO 24h
- **Security Scanning:** Automated vulnerability scans
---
## 📞 Support & Contact
### Development Support
- **Repository:** [Internal Git Repository]
- **Issue Tracker:** [Internal Issue Tracker]
- **Documentation:** This repository `/specs`
### Operations Support
- **Email:** ops-team@example.com
- **Phone:** [Phone Number]
- **On-Call:** [On-Call Schedule]
---
## 📝 Document Control
- **Version:** 1.5.0
- **Status:** Active
- **Last Updated:** 2025-12-01
- **Next Review:** 2026-01-01
- **Owner:** System Architect
- **Classification:** Internal Use Only
---
## 🔄 Version History
| Version | Date | Description |
| ------- | ---------- | ------------------------------------------ |
| 1.5.0 | 2025-12-01 | Complete specification with ADRs and tasks |
| 1.4.5 | 2025-11-30 | Updated architecture documents |
| 1.4.4 | 2025-11-29 | Initial backend/frontend plans |
| 1.0.0 | 2025-11-01 | Initial requirements |
---
**Welcome to LCBP3-DMS Project! 🚀**

497
specs/00-overview/glossary.md
View File

@@ -1 +1,496 @@
# คำศัพท์เทคนิค
# Glossary - คำศัพท์และคำย่อทางเทคนิค
**Project:** LCBP3-DMS
**Version:** 1.5.0
**Last Updated:** 2025-12-01
---
## 📋 General Terms (คำศัพท์ทั่วไป)
### A
**ADR (Architecture Decision Record)**
เอกสารบันทึกการตัดสินใจทางสถาปัตยกรรมที่สำคัญ พร้อมบริบท ทางเลือก และเหตุผล
**API (Application Programming Interface)**
ชุดคำสั่งและโปรโตคอลที่ใช้สำหรับการสื่อสารระหว่างระบบ
**APM (Application Performance Monitoring)**
การติดตามประสิทธิภาพของแอปพลิเคชัน
**Async (Asynchronous)**
การทำงานแบบไม่ต้องรอให้งานก่อนหน้าเสร็จก่อน
**Attachment**
ไฟล์แนบที่อยู่กับเอกสาร เช่น PDF, Word, Drawing files
**Audit Log**
บันทึกการกระทำของผู้ใช้ในระบบเพื่อการตรวจสอบ
**Authentication**
การยืนยันตัวตนผู้ใช้ (Login)
**Authorization**
การกำหนดสิทธิ์การเข้าถึง
---
### B
**Backend**
ส่วนของระบบที่ทำงานฝั่งเซิร์ฟเวอร์ จัดการข้อมูลและ Business Logic
**Backup**
การสำรองข้อมูล
**Blue-Green Deployment**
กลยุทธ์การ Deploy โดยมี 2 สภาพแวดล้อม (Blue และ Green) สลับกันใช้งาน
**BullMQ**
Message Queue library สำหรับ Node.js ที่ใช้ Redis
---
### C
**Cache**
ที่เก็บข้อมูลชั่วคราวเพื่อเพิ่มความเร็วในการเข้าถึง
**CASL (Component Ability Serialization Language)**
Library สำหรับจัดการ Authorization และ Permissions
**CI/CD (Continuous Integration / Continuous Deployment)**
กระบวนการอัตโนมัติในการ Build, Test และ Deploy code
**ClamAV**
Antivirus software แบบ Open-source สำหรับสแกนไวรัส
**Container**
หน่วยของ Software ที่รวม Application และ Dependencies ทั้งหมด
**CORS (Cross-Origin Resource Sharing)**
กลไกที่อนุญาตให้เว็บคุยข้ามโดเมน
**CRUD (Create, Read, Update, Delete)**
การดำเนินการพื้นฐานกับข้อมูล
---
### D
**Database Migration**
การเปลี่ยนแปลง Schema ของฐานข้อมูลอย่างเป็นระบบ
**DBA (Database Administrator)**
ผู้ดูแลระบบฐานข้อมูล
**DevOps**
แนวทางที่รวม Development และ Operations เข้าด้วยกัน
**Discipline**
สาขาวิชาชีพ เช่น GEN (General), STR (Structure), ARC (Architecture)
**DMS (Document Management System)**
ระบบจัดการเอกสาร
**Docker**
Platform สำหรับพัฒนาและรัน Application ใน Container
**DTO (Data Transfer Object)**
Object ที่ใช้สำหรับส่งข้อมูลระหว่าง Layer ต่างๆ
**DSL (Domain-Specific Language)**
ภาษาที่ออกแบบมาสำหรับโดเมนเฉพาะ
---
### E
**Elasticsearch**
Search Engine แบบ Distributed สำหรับ Full-text Search
**Entity**
Object ที่แทนตารางในฐานข้อมูล (TypeORM)
**ENV (Environment)**
สภาพแวดล้อมการทำงาน เช่น Development, Staging, Production
**Escalation**
การส่งต่อเรื่องไปยังผู้มีอำนาจสูงขึ้น
---
### F
**Foreign Key (FK)**
คีย์ที่เชื่อมโยงระหว่างตาราง
**Frontend**
ส่วนของระบบที่ผู้ใช้โต้ตอบได้ (User Interface)
---
### G
**Guard**
Middleware ใน NestJS ที่ใช้ตรวจสอบ Authorization
**GUI (Graphical User Interface)**
ส่วนติดต่อผู้ใช้แบบกราฟิก
---
### H
**Health Check**
การตรวจสอบสถานะของ Service ว่าทำงานปกติหรือไม่
**Hot Reload**
การ Reload code โดยไม่ต้อง Restart server
---
### I
**Idempotency**
การดำเนินการที่ให้ผลลัพธ์เดียวกันไม่ว่าจะทำกี่ครั้ง
**Incident**
เหตุการณ์ที่ทำให้ระบบไม่สามารถทำงานได้ตามปกติ
**Index**
โครงสร้างข้อมูลที่ช่วยเพิ่มความเร็วในการค้นหา (Database)
**Interceptor**
Middleware ใน NestJS ที่ดัก Request/Response
---
### J
**JWT (JSON Web Token)**
มาตรฐานสำหรับ Token-based Authentication
---
### K
**Key-Value Store**
ฐานข้อมูลที่เก็บข้อมูลในรูปแบบ Key และ Value (เช่น Redis)
---
### L
**LCBP3 (Laem Chabang Port Phase 3)**
โครงการท่าเรือแหลมฉบังระยะที่ 3
**Load Balancer**
ตัวกระจายโหลดไปยัง Server หลายตัว
**Lock**
กลไกป้องกันการเข้าถึงข้อมูลพร้อมกัน
**Log**
บันทึกเหตุการณ์ที่เกิดขึ้นในระบบ
---
### M
**MariaDB**
ฐานข้อมูล Relational แบบ Open-source
**Master Data**
ข้อมูลหลักของระบบ เช่น Organizations, Projects
**Master-Revision Pattern**
รูปแบบการจัดเก็บข้อมูลที่มี Master record และ Revision records
**Microservices**
สถาปัตยกรรมที่แบ่งระบบเป็น Service เล็กๆ หลายตัว
**Migration**
การย้ายหรือเปลี่ยนแปลง Schema ของฐานข้อมูล
**Modular Monolith**
Monolithic application ที่แบ่งโมดูลชัดเจน
**MTBF (Mean Time Between Failures)**
เวลาเฉลี่ยระหว่างความล้มเหลว
**MTTR (Mean Time To Resolution/Repair)**
เวลาเฉลี่ยในการแก้ไขปัญหา
**MVP (Minimum Viable Product)**
ผลิตภัณฑ์ขั้นต่ำที่ใช้งานได้
---
### N
**NestJS**
Framework สำหรับสร้าง Backend Node.js application
**Next.js**
Framework สำหรับสร้าง React application
**NGINX**
Web Server และ Reverse Proxy
---
### O
**ORM (Object-Relational Mapping)**
เทคนิคแปลง Object เป็น Relational Database
**Optimistic Locking**
กลไกป้องกัน Concurrent update โดยใช้ Version
---
### P
**Pessimistic Locking**
กลไกป้องกัน Concurrent access โดย Lock ทันที
**PIR (Post-Incident Review)**
การทบทวนหลังเกิดปัญหา
**Primary Key (PK)**
คีย์หลักของตาราง
**Production**
สภาพแวดล้อมที่ผู้ใช้จริงใช้งาน
---
### Q
**QNAP**
ยี่ห้อ NAS (Network Attached Storage)
**Queue**
แถวลำดับงานที่รอการประมวลผล
---
### R
**Race Condition**
สถานการณ์ที่ผลลัพธ์ขึ้นกับลำดับเวลาการทำงาน
**RBAC (Role-Based Access Control)**
การควบคุมการเข้าถึงตามบทบาท
**Redis**
In-memory Key-Value store สำหรับ Cache และ Queue
**Repository Pattern**
รูปแบบการออกแบบสำหรับการเข้าถึงข้อมูล
**REST (Representational State Transfer)**
สถาปัตยกรรม API ที่ใช้ HTTP
**Rollback**
การย้อนกลับไปสถานะก่อนหน้า
**RPO (Recovery Point Objective)**
จุดเวลาที่ยอมรับได้สำหรับการกู้คืนข้อมูล
**RTO (Recovery Time Objective)**
เวลาที่ยอมรับได้สำหรับการกู้คืนระบบ
---
### S
**Seed Data**
ข้อมูลเริ่มต้นที่ใส่ในฐานข้อมูล
**Session**
ช่วงเวลาที่ผู้ใช้ Login อยู่
**Soft Delete**
การลบข้อมูลโดยทำ Mark แทนการลบจริง
**SQL (Structured Query Language)**
ภาษาสำหรับจัดการฐานข้อมูล
**SSL/TLS (Secure Sockets Layer / Transport Layer Security)**
โปรโตคอลสำหรับการเข้ารหัสข้อมูล
**Staging**
สภาพแวดล้อมสำหรับทดสอบก่อน Production
**State Machine**
โมเดลที่มีหลาย State และ Transition
---
### T
**Temp (Temporary)**
ชั่วคราว
**Transaction**
ชุดการดำเนินการที่ต้องสำเร็จทั้งหมดหรือไม่ทำเลย
**Two-Phase Storage**
การจัดเก็บไฟล์แบบ 2 ขั้นตอน (Temp → Permanent)
**TypeORM**
ORM สำหรับ TypeScript/JavaScript
**TypeScript**
ภาษาโปรแกรมที่เป็น Superset ของ JavaScript พร้อม Static Typing
---
### U
**UAT (User Acceptance Testing)**
การทดสอบโดยผู้ใช้จริง
**UUID (Universally Unique Identifier)**
รหัสไม่ซ้ำกัน 128-bit
---
### V
**Validation**
การตรวจสอบความถูกต้องของข้อมูล
**Version Control**
การควบคุมเวอร์ชันของ Code (เช่น Git)
**Volume**
พื้นที่เก็บข้อมูลถาวรใน Docker
---
### W
**Webhook**
HTTP Callback ที่เรียกเมื่อเกิด Event
**Winston**
Logging library สำหรับ Node.js
**Workflow**
ลำดับขั้นตอนการทำงาน
---
## 🏗️ Project-Specific Terms (คำศัพท์เฉพาะโครงการ)
### Organizations (องค์กร)
**กทท. (Port Authority of Thailand)**
การท่าเรือแห่งประเทศไทย - เจ้าของโครงการ
**สค©. (Supervision Consultant)**
ที่ปรึกษาควบคุมงาน
**TEAM (Design Consultant)**
ที่ปรึกษาออกแบบ
**คคง. (Construction Supervision)**
ผู้ควบคุมงานก่อสร้าง
**ผรม. (Contractor)**
ผู้รับเหมาก่อสร้าง
---
### Document Types
**Correspondence**
เอกสารโต้ตอบ / หนังสือราชการ
**RFA (Request for Approval)**
เอกสารขออนุมัติ
**Contract Drawing**
แบบคู่สัญญา
**Shop Drawing**
แบบก่อสร้าง / แบบการผลิต
**Transmittal**
เอกสารนำส่ง
**Circulation Sheet**
ใบเวียนเอกสารภายใน
---
### Workflow States
**Draft**
ร่างเอกสาร
**Pending**
รอดำเนินการ
**In Review**
อยู่ระหว่างตรวจสอบ
**Approved**
อนุมัติ
**Rejected**
ไม่อนุมัติ
**Closed**
ปิดเรื่อง
---
### Disciplines (สาขาวิชาชีพ)
**GEN - General**
ทั่วไป
**STR - Structure**
โครงสร้าง
**ARC - Architecture**
สถาปัตยกรรม
**MEP - Mechanical, Electrical & Plumbing**
ระบบเครื่องกล ไฟฟ้า และสุขาภิบาล
**CIV - Civil**
โยธา
---
## 📚 Acronyms Reference (อ้างอิงตัวย่อ)
| Acronym | Full Form | Thai |
| ------- | --------------------------------- | ------------------------------- |
| ADR | Architecture Decision Record | บันทึกการตัดสินใจทางสถาปัตยกรรม |
| API | Application Programming Interface | ส่วนต่อประสานโปรแกรม |
| CRUD | Create, Read, Update, Delete | สร้าง อ่าน แก้ไข ลบ |
| DMS | Document Management System | ระบบจัดการเอกสาร |
| DTO | Data Transfer Object | วัตถุถ่ายโอนข้อมูล |
| JWT | JSON Web Token | โทเคนเว็บ JSON |
| LCBP3 | Laem Chabang Port Phase 3 | ท่าเรือแหลมฉบังระยะที่ 3 |
| MVP | Minimum Viable Product | ผลิตภัณฑ์ขั้นต่ำที่ใช้งานได้ |
| ORM | Object-Relational Mapping | การแมปวัตถุกับฐานข้อมูล |
| RBAC | Role-Based Access Control | การควบคุมการเข้าถึงตามบทบาท |
| REST | Representational State Transfer | การถ่ายโอนสถานะแบบนำเสนอ |
| RFA | Request for Approval | เอกสารขออนุมัติ |
| RTO | Recovery Time Objective | เวลาเป้าหมายในการกู้คืน |
| RPO | Recovery Point Objective | จุดเป้าหมายในการกู้คืน |
| UAT | User Acceptance Testing | การทดสอบการยอมรับของผู้ใช้ |
---
**Version:** 1.5.0
**Last Updated:** 2025-12-01
**Next Review:** 2026-03-01

389
specs/00-overview/quick-start.md Normal file
View File

@@ -0,0 +1,389 @@
# Quick Start Guide
**Project:** LCBP3-DMS
**Version:** 1.5.0
**Last Updated:** 2025-12-01
---
## ⚡ 5-Minute Quick Start
This guide will get you up and running with LCBP3-DMS in 5 minutes.
---
## 👨‍💻 For Developers
### Prerequisites
```bash
# Required
- Docker 20.10+
- Docker Compose 2.0+
- Git
- Node.js 18+ (for local development)
# Recommended
- VS Code
- Postman or similar API testing tool
```
### Step 1: Clone Repository
```bash
git clone <repository-url>
cd lcbp3
```
### Step 2: Setup Environment
```bash
# Backend
cp backend/.env.example backend/.env
# Edit backend/.env and set required values
# Frontend
cp frontend/.env.example frontend/.env.local
# Edit frontend/.env.local
```
### Step 3: Start Services
```bash
# Start all services with Docker Compose
docker-compose up -d
# Check status
docker-compose ps
```
### Step 4: Initialize Database
```bash
# Run migrations
docker exec lcbp3-backend npm run migration:run
# (Optional) Seed sample data
docker exec lcbp3-backend npm run seed
```
### Step 5: Access Application
```bash
# Backend API
http://localhost:3000
# Health check
curl http://localhost:3000/health
# Frontend
http://localhost:3001
# API Documentation (Swagger)
http://localhost:3000/api/docs
```
### Step 6: Login
**Default Admin Account:**
- Username: `admin`
- Password: `Admin@123` (Change immediately!)
---
## 🧪 For QA/Testers
### Running Tests
```bash
# Backend unit tests
docker exec lcbp3-backend npm test
# Backend e2e tests
docker exec lcbp3-backend npm run test:e2e
# Frontend tests
docker exec lcbp3-frontend npm test
```
### Test Data
```bash
# Reset database to clean state
docker exec lcbp3-backend npm run migration:revert
docker exec lcbp3-backend npm run migration:run
# Load test data
docker exec lcbp3-backend npm run seed
```
---
## 🚀 For DevOps
### Deploy to Staging
```bash
# Build images
docker-compose build
# Push to registry
docker-compose push
# Deploy to staging server
ssh staging-server
cd /app/lcbp3
git pull
docker-compose pull
docker-compose up -d
# Run migrations
docker exec lcbp3-backend npm run migration:run
```
### Deploy to Production
```bash
# Backup database first!
./scripts/backup-database.sh
# Deploy with zero-downtime
./scripts/zero-downtime-deploy.sh
# Verify deployment
curl -f https://lcbp3-dms.example.com/health
```
---
## 📊 For Project Managers
### View Project Status
**Documentation:**
- Requirements: [specs/01-requirements](../01-requirements/)
- Architecture: [specs/02-architecture](../02-architecture/)
- Tasks: [specs/06-tasks](../06-tasks/)
**Metrics:**
- Check [Monitoring Dashboard](http://localhost:9200) (if setup)
- Review [Task Board](../06-tasks/README.md)
---
## 🔍 Common Tasks
### Create New Module
```bash
# Backend
cd backend
nest g module modules/my-module
nest g controller modules/my-module
nest g service modules/my-module
# Follow backend guidelines
# See: specs/03-implementation/backend-guidelines.md
```
### Create New Migration
```bash
# Generate migration from entity changes
docker exec lcbp3-backend npm run migration:generate -- -n MigrationName
# Create empty migration
docker exec lcbp3-backend npm run migration:create -- -n MigrationName
# Run migrations
docker exec lcbp3-backend npm run migration:run
# Revert last migration
docker exec lcbp3-backend npm run migration:revert
```
### View Logs
```bash
# All services
docker-compose logs -f
# Specific service
docker logs lcbp3-backend -f --tail=100
# Search logs
docker logs lcbp3-backend 2>&1 | grep "ERROR"
```
### Database Access
```bash
# MySQL CLI
docker exec -it lcbp3-mariadb mysql -u root -p
# Run SQL file
docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms < script.sql
```
### Redis Access
```bash
# Redis CLI
docker exec -it lcbp3-redis redis-cli -a <password>
# Check keys
docker exec lcbp3-redis redis-cli -a <password> KEYS "*"
# Clear cache
docker exec lcbp3-redis redis-cli -a <password> FLUSHDB
```
---
## 🐛 Troubleshooting
### Backend not starting
```bash
# Check logs
docker logs lcbp3-backend
# Common issues:
# 1. Database connection - check DB_HOST in .env
# 2. Redis connection - check REDIS_HOST in .env
# 3. Port conflict - check if port 3000 is free
```
### Database connection failed
```bash
# Check if MariaDB is running
docker ps | grep mariadb
# Test connection
docker exec lcbp3-mariadb mysqladmin ping -h localhost
# Check credentials
docker exec lcbp3-backend env | grep DB_
```
### Frontend build failed
```bash
# Clear cache and rebuild
docker exec lcbp3-frontend rm -rf .next node_modules
docker exec lcbp3-frontend npm install
docker exec lcbp3-frontend npm run build
```
### Port already in use
```bash
# Find process using port
lsof -i :3000
# Kill process
kill -9 <PID>
# Or change port in docker-compose.yml
```
---
## 📚 Next Steps
### Learn More
1. **Architecture** - [System Architecture](../02-architecture/system-architecture.md)
2. **Development** - [Backend Guidelines](../03-implementation/backend-guidelines.md)
3. **Deployment** - [Deployment Guide](../04-operations/deployment-guide.md)
4. **Decisions** - [ADR Index](../05-decisions/README.md)
### Join the Team
1. Read [Contributing Guidelines](../../CONTRIBUTING.md)
2. Pick a task from [Backend Tasks](../06-tasks/README.md)
3. Create a branch: `git checkout -b feature/my-feature`
4. Make changes and write tests
5. Submit Pull Request
---
## 💡 Tips & Best Practices
### Development
- ✅ Always write tests for new features
- ✅ Follow coding guidelines
- ✅ Use TypeScript strict mode
- ✅ Add JSDoc for public APIs
- ✅ Keep Pull Requests small
### Git Workflow
```bash
# Update main branch
git checkout main
git pull
# Create feature branch
git checkout -b feature/my-feature
# Make commits
git add .
git commit -m "feat: add new feature"
# Push and create PR
git push origin feature/my-feature
```
### Code Review
- Review [Backend Guidelines](../03-implementation/backend-guidelines.md)
- Check test coverage
- Verify documentation updated
- Run linter: `npm run lint`
- Run tests: `npm test`
---
## 🆘 Getting Help
### Resources
- **Documentation:** `/specs` directory
- **API Docs:** http://localhost:3000/api/docs
- **Issue Tracker:** [Link to issue tracker]
### Contact
- **Tech Lead:** [Email]
- **DevOps:** [Email]
- **Slack:** #lcbp3-dms
---
## ✅ Checklist for First Day
- [ ] Clone repository
- [ ] Install prerequisites
- [ ] Setup environment variables
- [ ] Start Docker services
- [ ] Run migrations
- [ ] Access backend (http://localhost:3000/health)
- [ ] Access frontend (http://localhost:3001)
- [ ] Login with default credentials
- [ ] Run tests
- [ ] Read [System Architecture](../02-architecture/system-architecture.md)
- [ ] Read [Backend Guidelines](../03-implementation/backend-guidelines.md)
- [ ] Pick first task from [Tasks](../06-tasks/README.md)
---
**Welcome aboard! 🎉**
**Version:** 1.5.0
**Last Updated:** 2025-12-01