260518:1640 204 and 302 refactor #11
This commit is contained in:
admin
+560
-23
@@ -1,29 +1,566 @@
|
||||
# Architecture
|
||||
# LCBP3-DMS Architecture Documentation
|
||||
|
||||
## Current Structure
|
||||
---
|
||||
|
||||
- `backend/`: NestJS application with shared `CommonModule`, TypeORM entities, BullMQ queue integration, and feature modules such as `rfa`, `review-team`, `response-code`, `delegation`, `reminder`, and `distribution`.
|
||||
- `frontend/`: Next.js dashboard application with route groups under `app`, shared components under `components`, and feature hooks under `hooks`.
|
||||
- `specs/`: Core specifications plus categorized feature work. The active RFA approval refactor lives in `specs/200-fullstacks/204-rfa-approval-refactor`.
|
||||
**title:** 'LCBP3-DMS Architecture Documentation'
|
||||
**version:** 1.9.2
|
||||
**status:** active
|
||||
**owner:** Nattanin Peancharoen
|
||||
**last_updated:** 2026-05-18
|
||||
**related:**
|
||||
|
||||
## Unified AI Architecture
|
||||
- specs/02-Architecture/02-01-system-context.md
|
||||
- specs/02-Architecture/02-02-software-architecture.md
|
||||
- specs/02-Architecture/02-03-network-design.md
|
||||
- specs/02-Architecture/02-04-api-design.md
|
||||
- specs/06-Decision-Records/
|
||||
|
||||
- `backend/src/modules/ai`: ADR-023 gateway module for AI boundaries. It now owns AI queue registration, n8n service-account validation, the AI-scoped Qdrant gateway, and `MigrationReviewRecord` mapping for `migration_review_queue`.
|
||||
- `backend/src/modules/ai/ai-ingest.service.ts`: publicId-based legacy migration staging service. It accepts n8n/API batches, stores files through `FileStorageService`, creates `migration_review_queue` records, and delegates final import to `MigrationService` after human review.
|
||||
- `backend/src/modules/ai/workflows/folder-watcher.json`: n8n workflow template for watched-folder ingestion into `/api/ai/legacy-migration/ingest`.
|
||||
- AI BullMQ queues are centralized in `backend/src/modules/common/constants/queue.constants.ts`: `ai-ingest`, `ai-rag-query`, and `ai-vector-deletion`.
|
||||
- `frontend/app/(dashboard)/ai-staging`: dashboard route for reviewing AI staging records with constrained project/category/organization dropdowns before approval.
|
||||
- `frontend/lib/api/ai.ts` and `frontend/components/ai/AiStatusBanner.tsx`: frontend ADR-023 hooks and graceful-degradation banner for AI staging.
|
||||
- Schema changes for the AI staging queue and AI development feedback log are tracked as SQL delta `specs/03-Data-and-Storage/deltas/12-unified-ai-architecture.sql` per ADR-009.
|
||||
- Existing RAG ingestion code still lives under `backend/src/modules/rag`; US2 will migrate query orchestration to the ADR-023 AI queue path without replacing the existing ingestion processors in this foundation slice.
|
||||
- ADR-023A Phase 1 removed the cloud LLM client from `backend/src/modules/rag`; RAG generation now uses `LocalLlmService` with Ollama only, and SQL deltas `14-add-migration-review-queue.sql` plus `15-add-ai-processing-status.sql` track the AI model revision schema changes.
|
||||
- ADR-023A Phase 2 adds `ai-realtime` and `ai-batch` queue constants, processors, and module registration. `AiRealtimeProcessor` pauses `ai-batch` while interactive work is active, `AiModule.onModuleInit()` auto-resumes stale paused batch queues, and `OllamaService`/`OcrService` provide the local 2-model/OCR foundation for later user stories.
|
||||
- ADR-023A Phase 3 adds AI Suggest queueing through `/api/ai/suggest`, `/api/ai/jobs/:jobId/status`, `CreateAiJobDto`, and best-effort central commit hooks in `FileStorageService.commit()` when project-scoped metadata is available. `attachments.ai_processing_status` is the current schema-aligned progress field for queued AI work.
|
||||
---
|
||||
|
||||
## RFA Approval Refactor
|
||||
## 📋 Table of Contents
|
||||
|
||||
- `review-team`: review team CRUD, member assignment, review task creation, aggregate status, consensus, and veto override.
|
||||
- `response-code`: response code lookup, matrix rules, implications, and notification triggering.
|
||||
- `delegation`, `reminder`, `distribution`: supporting modules for proxy assignment, scheduled reminders, and post-approval distribution. Delegation resolution is applied during parallel review task creation while preserving `delegatedFromUserId` for audit/display.
|
||||
- `distribution`: schema-aligned Distribution Matrix CRUD, BullMQ queueing, approval listener integration, draft Transmittal creation, and `/distribution-matrices` admin UI.
|
||||
- Queue names are centralized in `backend/src/modules/common/constants/queue.constants.ts`.
|
||||
1. [System Context & Architecture](#1-system-context--architecture)
|
||||
2. [Software Architecture & Design](#2-software-architecture--design)
|
||||
3. [Network Design & Security](#3-network-design--security)
|
||||
4. [API Design & Error Handling](#4-api-design--error-handling)
|
||||
5. [AI Architecture (ADR-023/023A)](#5-ai-architecture-adr-023023a)
|
||||
6. [Architecture Decision Records (ADRs)](#6-architecture-decision-records-adrs)
|
||||
|
||||
---
|
||||
|
||||
## 1. System Context & Architecture
|
||||
|
||||
### 1.1 System Overview
|
||||
|
||||
ระบบ LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) ถูกออกแบบด้วยสถาปัตยกรรมแบบ **Headless/API-First Architecture** โดยทำงานแบบ **On-Premise 100%** บนเครื่องเซอร์ฟเวอร์ QNAP และ ASUSTOR
|
||||
|
||||
### 1.2 Architecture Principles
|
||||
|
||||
1. **Data Integrity First:** ความถูกต้องของข้อมูลต้องมาก่อนทุกอย่าง
|
||||
2. **Security by Design & Container Isolation:** รักษาความปลอดภัยที่ทุกชั้น และแยกส่วนการทำงานของแต่ละระบบอย่างชัดเจน
|
||||
3. **On-Premise First:** ข้อมูลและระบบงานทั้งหมดต้องอยู่ภายในเครือข่ายของโครงการเท่านั้น
|
||||
4. **Resilience:** ทนทานต่อ Failure และ Recovery ได้รวดเร็ว
|
||||
5. **Observability:** ติดตามและวิเคราะห์สถานะระบบได้ง่าย
|
||||
|
||||
### 1.3 Hardware Infrastructure
|
||||
|
||||
| Component | Specification | Role | IP Address |
|
||||
| --------------------- | ----------------------------------------- | ----------------------------------- | ------------ |
|
||||
| **Primary Server** | QNAP TS-473A (AMD Ryzen V1500B, 32GB RAM) | Primary NAS for DMS, Container Host | 192.168.10.8 |
|
||||
| **Backup Server** | ASUSTOR AS5304T | Backup / Secondary NAS | 192.168.10.9 |
|
||||
| **Network Interface** | LACP bonding (IEEE 802.3ad) | High availability & bandwidth | - |
|
||||
|
||||
### 1.4 Container Isolation & Environment
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph PublicZone["🌐 PUBLIC ZONE"]
|
||||
NPM["NPM (Reverse Proxy)<br/>Ports: 80, 443"]
|
||||
end
|
||||
|
||||
subgraph AppZone["📱 APPLICATION ZONE (Docker Network 'lcbp3')"]
|
||||
Frontend["Next.js"]
|
||||
Backend["NestJS"]
|
||||
N8N["n8n"]
|
||||
Gitea["Gitea"]
|
||||
end
|
||||
|
||||
subgraph DataZone["💾 DATA ZONE (Internal Only)"]
|
||||
MariaDB["MariaDB"]
|
||||
Redis["Redis"]
|
||||
ES["Elasticsearch"]
|
||||
end
|
||||
|
||||
PublicZone -->|HTTPS Only| AppZone
|
||||
AppZone -->|Internal API| DataZone
|
||||
```
|
||||
|
||||
### 1.5 Core Services Architecture
|
||||
|
||||
| Service | Application Name | Domain | Technology | Purpose |
|
||||
| ------------ | ---------------- | ------------------- | ------------------- | ------------------ |
|
||||
| **Frontend** | lcbp3-frontend | lcbp3.np-dms.work | Next.js 16.2.0 | Web UI |
|
||||
| **Backend** | lcbp3-backend | backend.np-dms.work | NestJS 11 | API Server & Logic |
|
||||
| **Database** | lcbp3-db | db.np-dms.work | MariaDB 11.8 | Primary Data |
|
||||
| **Proxy** | lcbp3-npm | npm.np-dms.work | Nginx Proxy Mgr | Gateway & SSL |
|
||||
| **Workflow** | lcbp3-n8n | n8n.np-dms.work | n8n | Process Automation |
|
||||
| **Git** | git | git.np-dms.work | Gitea | Code Repository |
|
||||
| **Cache** | - | - | Redis | Caching, Locking |
|
||||
| **Search** | - | - | Elasticsearch 9.3.4 | Full-text Indexing |
|
||||
|
||||
### 1.6 Data Flow & Interactions
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as Client
|
||||
participant NPM as Nginx Proxy
|
||||
participant BE as Backend (NestJS)
|
||||
participant Redis as Redis Cache
|
||||
participant DB as MariaDB
|
||||
|
||||
Client->>NPM: HTTP Request + JWT
|
||||
NPM->>BE: Forward Request
|
||||
|
||||
BE->>BE: Rate Limit Check & Validate Input
|
||||
BE->>Redis: Get User Permissions (RBAC Cache)
|
||||
Redis-->>BE: Permission Data
|
||||
BE->>BE: Verify Permission
|
||||
|
||||
BE->>DB: Process Logic & Save
|
||||
BE->>Redis: Invalidate affected Cache
|
||||
|
||||
BE-->>Client: JSON Response
|
||||
```
|
||||
|
||||
### 1.7 Backup & Disaster Recovery
|
||||
|
||||
- **Database Backup:** ทำ Automated Backup รายวันด้วย QNAP HBS 3
|
||||
- **File Backup:** ทำ Snapshot จาก `/share/dms-data` บน QNAP ไปยัง ASUSTOR
|
||||
- **Recovery Standard:** หาก NAS พัง สามารถ Restore Config และรัน `docker-compose up` ขึ้นใหม่ได้ทันที
|
||||
|
||||
---
|
||||
|
||||
## 2. Software Architecture & Design
|
||||
|
||||
### 2.1 Backend Module Architecture (NestJS)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Core Modules"
|
||||
Common[CommonModule<br/>Shared Services]
|
||||
Auth[AuthModule<br/>JWT & Guards]
|
||||
User[UserModule<br/>User Management]
|
||||
end
|
||||
|
||||
subgraph "Business Modules"
|
||||
Project[ProjectModule<br/>Projects & Contracts]
|
||||
Corr[CorrespondenceModule<br/>Correspondences]
|
||||
RFA[RfaModule<br/>RFA Management]
|
||||
Drawing[DrawingModule<br/>Shop & Contract Drawings]
|
||||
Circ[CirculationModule<br/>Circulation Sheets]
|
||||
end
|
||||
|
||||
subgraph "Supporting Modules"
|
||||
Workflow[WorkflowEngineModule<br/>Unified Workflow]
|
||||
Numbering[DocumentNumberingModule<br/>Auto Numbering]
|
||||
Search[SearchModule<br/>Elasticsearch]
|
||||
end
|
||||
|
||||
Corr --> Workflow
|
||||
RFA --> Workflow
|
||||
Circ --> Workflow
|
||||
|
||||
Corr --> Numbering
|
||||
RFA --> Numbering
|
||||
|
||||
Search --> Corr
|
||||
Search --> RFA
|
||||
Search --> Drawing
|
||||
```
|
||||
|
||||
### 2.2 Key Architectural Patterns
|
||||
|
||||
#### Unified Workflow Engine (DSL-Based)
|
||||
|
||||
ระบบการเดินเอกสารใช้ Engine กลางเดียวกัน ผ่าน **Workflow DSL (JSON Configuration)**
|
||||
|
||||
- **Separation of Concerns:** Modules เก็บเฉพาะข้อมูล (Data) ส่วน Flow/State ถูกจัดการโดย Engine
|
||||
- **Versioning:** อาศัย Workflow Definition Version ป้องกันความขัดแย้งของ State
|
||||
|
||||
#### Double-Locking Mechanism (Auto Numbering)
|
||||
|
||||
เพื่อป้องกัน Race Condition ในการขอเลขเอกสารพร้อมกัน:
|
||||
|
||||
- **Layer 1:** Redis Distributed Lock (ล็อคการเข้าถึงในระดับ Server/Network)
|
||||
- **Layer 2:** Optimistic Database Lock ผ่าน `@VersionColumn()` (ป้องกันระดับ Data Record)
|
||||
|
||||
#### Idempotency
|
||||
|
||||
ทุก API ที่แก้ไขสถานะจะต้องส่ง `Idempotency-Key` ป้องกันผู้ใช้กดยืนยันซ้ำสองรอบ
|
||||
|
||||
### 2.3 File Upload Flow (Two-Phase Storage)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as Client
|
||||
participant BE as Backend
|
||||
participant Temp as Temp Storage
|
||||
participant Virus as ClamAV
|
||||
participant Perm as Permanent Storage
|
||||
|
||||
Client->>BE: Upload File
|
||||
BE->>Virus: Scan File
|
||||
Virus-->>BE: Clean
|
||||
BE->>Temp: Save to temp/
|
||||
BE-->>Client: Return temp_id
|
||||
|
||||
Client->>BE: Create Document (with temp_id)
|
||||
BE->>BE: Validate & Save to DB
|
||||
BE->>Perm: Move temp/ → permanent/
|
||||
BE->>Temp: Cleanup temp file
|
||||
BE-->>Client: Success
|
||||
```
|
||||
|
||||
### 2.4 Security Architecture
|
||||
|
||||
#### Rate Limiting (Redis-backed)
|
||||
|
||||
| Endpoint Type | Limit | Scope |
|
||||
| ---------------- | ------------- | ----- |
|
||||
| Anonymous | 100 req/hour | IP |
|
||||
| File Upload | 50 req/hour | User |
|
||||
| Document Control | 2000 req/hour | User |
|
||||
| Admin | 5000 req/hour | User |
|
||||
|
||||
#### Authorization checking flow (CASL)
|
||||
|
||||
1. ดึง JWT Token ตรวจสอบความถูกต้อง
|
||||
2. โหลด User Permissions จาก Redis
|
||||
3. ตรวจสอบเงื่อนไขตาม Context (Global, Organization, Project, Contract)
|
||||
4. พิจารณาอนุญาตหากระดับใดระดับหนึ่งอนุญาต
|
||||
|
||||
### 2.5 Resilience & Error Handling
|
||||
|
||||
- **Circuit Breaker:** ใช้งานครอบ API ภายนอก (Email, LINE Notify)
|
||||
- **Retry Mechanism:** สำหรับกระบวนการสำคัญชั่วคราว
|
||||
- **Graceful Degradation:** หาก Search Engine ล่ม ระบบสลับไปใช้ Database Query พื้นฐานชั่วคราวได้
|
||||
|
||||
---
|
||||
|
||||
## 3. Network Design & Security
|
||||
|
||||
### 3.1 Network Segmentation (VLANs)
|
||||
|
||||
| VLAN ID | Name | Purpose | Subnet | Gateway | Notes |
|
||||
| ------- | ------ | ------------------ | --------------- | ------------ | ----------------------------------------- |
|
||||
| 10 | SERVER | Server & Storage | 192.168.10.0/24 | 192.168.10.1 | Servers (QNAP, ASUSTOR). Static IPs ONLY. |
|
||||
| 20 | MGMT | Management & Admin | 192.168.20.0/24 | 192.168.20.1 | Network devices, Admin PC. |
|
||||
| 30 | USER | User Devices | 192.168.30.0/24 | 192.168.30.1 | Staff PC, Printers. |
|
||||
| 40 | CCTV | Surveillance | 192.168.40.0/24 | 192.168.40.1 | Cameras, NVR. Isolated. |
|
||||
| 50 | VOICE | IP Phones | 192.168.50.0/24 | 192.168.50.1 | SIP traffic. Isolated. |
|
||||
| 60 | DMZ | Public Services | 192.168.60.0/24 | 192.168.60.1 | DMZ. Isolated from Internal. |
|
||||
| 70 | GUEST | Guest Wi-Fi | 192.168.70.0/24 | 192.168.70.1 | Isolated Internet Access only. |
|
||||
|
||||
### 3.2 Security Zones
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph PublicZone["🌐 PUBLIC ZONE"]
|
||||
NPM["NPM (Reverse Proxy)<br/>Ports: 80, 443"]
|
||||
end
|
||||
|
||||
subgraph AppZone["📱 APPLICATION ZONE (Docker Network 'lcbp3')"]
|
||||
Frontend["Next.js"]
|
||||
Backend["NestJS"]
|
||||
N8N["n8n"]
|
||||
Gitea["Gitea"]
|
||||
end
|
||||
|
||||
subgraph DataZone["💾 DATA ZONE (QNAP - Internal Only)"]
|
||||
MariaDB["MariaDB"]
|
||||
Redis["Redis"]
|
||||
ES["Elasticsearch"]
|
||||
end
|
||||
|
||||
subgraph InfraZone["🛠️ INFRASTRUCTURE ZONE (ASUSTOR)"]
|
||||
Backup["Backup Services"]
|
||||
Registry["Docker Registry"]
|
||||
Monitoring["Prometheus + Grafana"]
|
||||
end
|
||||
|
||||
PublicZone -->|HTTPS Only| AppZone
|
||||
AppZone -->|Internal API| DataZone
|
||||
DataZone -.->|Backup| InfraZone
|
||||
AppZone -.->|Metrics| InfraZone
|
||||
```
|
||||
|
||||
### 3.3 Network Topology
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Internet
|
||||
WAN[("Internet<br/>WAN")]
|
||||
end
|
||||
|
||||
subgraph Router["ER7206 Router"]
|
||||
R[("ER7206<br/>192.168.20.1")]
|
||||
end
|
||||
|
||||
subgraph CoreSwitch["SG3210X-M2 Core Switch"]
|
||||
CS[("SG3210X-M2<br/>192.168.20.4")]
|
||||
end
|
||||
|
||||
subgraph Servers["VLAN 10 - Servers"]
|
||||
QNAP[(" QNAP<br/>192.168.10.8")]
|
||||
ASUSTOR[(" ASUSTOR<br/>192.168.10.9")]
|
||||
end
|
||||
|
||||
WAN -->|Port 2| R
|
||||
R -->|SFP Port 1| CS
|
||||
CS -->|Port 3-4 LACP| QNAP
|
||||
CS -->|Port 5-6 LACP| ASUSTOR
|
||||
```
|
||||
|
||||
### 3.4 Firewall Rules (ACLs)
|
||||
|
||||
กฎของ Firewall จะถูกกำหนดตามหลักการอนุญาตแค่สิ่งที่ต้องการ (Default Deny)
|
||||
|
||||
| Priority | Rule | Policy | Source | Destination | Ports |
|
||||
| -------- | ---------------------- | ------ | ----------------- | ----------------- | -------------------- |
|
||||
| 1 | Allow-User-DHCP | Allow | Network → VLAN 30 | IP → 192.168.30.1 | DHCP |
|
||||
| 2 | Allow-Guest-DHCP | Allow | Network → VLAN 70 | IP → 192.168.70.1 | DHCP |
|
||||
| 3 | Isolate-Servers | Deny | Network → VLAN 10 | Network → VLAN 30 | All |
|
||||
| 4 | Block-User-to-Mgmt | Deny | Network → VLAN 30 | Network → VLAN 20 | All |
|
||||
| 5 | Allow-User-to-Services | Allow | Network → VLAN 30 | IP → QNAP | Web (443,8443,80,81) |
|
||||
| 100 | Default | Deny | Any | Any | All |
|
||||
|
||||
### 3.5 QoS (Quality of Service) Settings
|
||||
|
||||
| Priority | DSCP Value | Traffic Type | Application |
|
||||
| ----------- | ---------- | --------------------- | ---------------------- |
|
||||
| Highest (7) | EF (46) | Voice (SIP/RTP) | IP Phones (VLAN 50) |
|
||||
| High (6) | AF41 (34) | Video Surveillance | CCTV Cameras (VLAN 40) |
|
||||
| Medium (5) | AF31 (26) | Critical Applications | DMS Backend, Database |
|
||||
| Low (4) | AF21 (18) | Best Effort | Web browsing, Email |
|
||||
|
||||
---
|
||||
|
||||
## 4. API Design & Error Handling
|
||||
|
||||
### 4.1 API Design Principles
|
||||
|
||||
#### API-First Approach
|
||||
|
||||
- **ออกแบบ API ก่อนการ Implement:** ทำการออกแบบ API Endpoint และ Data Contract ให้ชัดเจนก่อนเริ่มเขียนโค้ด
|
||||
- **Documentation-Driven:** ใช้ OpenAPI/Swagger เป็นเอกสารอ้างอิงหลัก
|
||||
- **Contract Testing:** ทดสอบ API ตาม Contract ที่กำหนดไว้
|
||||
|
||||
#### RESTful Principles
|
||||
|
||||
- ใช้ HTTP Methods อย่างถูกต้อง: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
|
||||
- ใช้ HTTP Status Codes ที่เหมาะสม
|
||||
- Resource-Based URL Design
|
||||
- Stateless Communication
|
||||
|
||||
### 4.2 Authentication & Authorization
|
||||
|
||||
#### JWT-Based Authentication
|
||||
|
||||
- **Token Management:**
|
||||
- Access Token Expiration: 8 ชั่วโมง
|
||||
- Refresh Token Expiration: 7 วัน
|
||||
- Token Rotation: รองรับการหมุนเวียน Refresh Token
|
||||
|
||||
#### Authorization (RBAC) (CASL)
|
||||
|
||||
ใช้ระบบ 4-Level Permission Hierarchy (Global, Organization, Project, Contract)
|
||||
|
||||
```typescript
|
||||
@RequirePermission('correspondence.create')
|
||||
@Post('correspondences')
|
||||
async createCorrespondence(@Body() dto: CreateCorrespondenceDto) {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 API Conventions
|
||||
|
||||
#### Base URL Structure
|
||||
|
||||
```
|
||||
https://backend.np-dms.work/api/v1/{resource}
|
||||
```
|
||||
|
||||
#### HTTP Methods & Usage
|
||||
|
||||
| Method | Usage | Idempotent | Example |
|
||||
| -------- | ------------------------------ | ---------- | -------------------------------------- |
|
||||
| `GET` | ดึงข้อมูล (Read) | ✅ Yes | `GET /api/v1/correspondences` |
|
||||
| `POST` | สร้างข้อมูลใหม่ (Create) | ❌ No\* | `POST /api/v1/correspondences` |
|
||||
| `PUT` | อัปเดตทั้งหมด (Full Update) | ✅ Yes | `PUT /api/v1/correspondences/:uuid` |
|
||||
| `PATCH` | อัปเดตบางส่วน (Partial Update) | ✅ Yes | `PATCH /api/v1/correspondences/:uuid` |
|
||||
| `DELETE` | ลบข้อมูล (Soft Delete) | ✅ Yes | `DELETE /api/v1/correspondences/:uuid` |
|
||||
|
||||
### 4.4 Request Format
|
||||
|
||||
**Request Headers:**
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <access_token>
|
||||
Idempotency-Key: <uuid> # สำหรับ POST/PUT/DELETE
|
||||
```
|
||||
|
||||
### 4.5 Response Formats
|
||||
|
||||
#### Success Response
|
||||
|
||||
```typescript
|
||||
{
|
||||
"data": {
|
||||
"uuid": "019505a1-7c3e-7000-8000-abc123def456",
|
||||
"document_number": "CORR-2024-0001",
|
||||
"subject": "...",
|
||||
},
|
||||
"meta": {
|
||||
"timestamp": "2024-01-01T00:00:00Z",
|
||||
"version": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Error Response Format
|
||||
|
||||
```typescript
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Validation failed on input data",
|
||||
"statusCode": 400,
|
||||
"timestamp": "2024-01-01T00:00:00Z",
|
||||
"path": "/api/correspondences",
|
||||
"details": [
|
||||
{
|
||||
"field": "subject",
|
||||
"message": "Subject is required",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.6 Error Handling Strategy
|
||||
|
||||
#### Global Exception Filter
|
||||
|
||||
คลาสจัดการ Error หลักที่จะจับและดัดแปลง Error ส่งคืน Client อย่างสม่ำเสมอ
|
||||
|
||||
#### Custom Business Exception
|
||||
|
||||
สำหรับจัดการข้อผิดพลาดเชิงความสัมพันธ์ หรือเงื่อนไขธุรกิจ
|
||||
|
||||
```typescript
|
||||
throw new BusinessException('Cannot approve correspondence in current status', 'INVALID_WORKFLOW_TRANSITION');
|
||||
```
|
||||
|
||||
### 4.7 API Security & Rate Limiting
|
||||
|
||||
#### File Upload Security
|
||||
|
||||
- **Virus Scanning:** ใช้ ClamAV scan ทุกไฟล์
|
||||
- **File Type Validation:** White-list (PDF, DWG, DOCX, XLSX, ZIP)
|
||||
- **File Size Limit:** 50MB per file
|
||||
- **Two-Phase Storage:** Upload to `temp/` → Commit to `permanent/`
|
||||
|
||||
---
|
||||
|
||||
## 5. AI Architecture (ADR-023/023A)
|
||||
|
||||
### 5.1 AI Integration Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Frontend"
|
||||
UI["Document Review Form"]
|
||||
end
|
||||
|
||||
subgraph "Backend (NestJS)"
|
||||
Gateway["AI Gateway API"]
|
||||
Queue["BullMQ Queues"]
|
||||
Validation["Human Validation"]
|
||||
end
|
||||
|
||||
subgraph "Admin Desktop (Desk-5439)"
|
||||
Ollama["Ollama Engine<br/>gemma4:e4b Q8_0 + nomic-embed-text"]
|
||||
OCR["PaddleOCR + PyThaiNLP"]
|
||||
end
|
||||
|
||||
subgraph "Vector Database"
|
||||
Qdrant["Qdrant<br/>Project-scoped Embeddings"]
|
||||
end
|
||||
|
||||
UI --> Gateway
|
||||
Gateway --> Queue
|
||||
Queue --> Ollama
|
||||
Ollama --> Validation
|
||||
Validation --> Gateway
|
||||
Gateway --> Qdrant
|
||||
```
|
||||
|
||||
### 5.2 Key Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
| ----------------- | ------------------------- | ------------------------------------------------------- |
|
||||
| **AI Gateway** | Backend (NestJS) | API endpoints, validation, audit logging |
|
||||
| **BullMQ Queues** | Backend (NestJS) | ai-realtime (RAG/Suggest), ai-batch (OCR/Extract/Embed) |
|
||||
| **Ollama Engine** | Admin Desktop (Desk-5439) | gemma4:e4b Q8_0 (LLM) + nomic-embed-text (Embedding) |
|
||||
| **OCR Engine** | Admin Desktop (Desk-5439) | PaddleOCR + PyThaiNLP (Thai/English text extraction) |
|
||||
| **Qdrant** | QNAP NAS | Vector storage with project isolation |
|
||||
|
||||
### 5.3 AI Architecture Rules
|
||||
|
||||
- **AI Isolation:** All AI processing on Admin Desktop only (Desk-5439)
|
||||
- **Data Privacy:** No cloud AI services, on-premises only
|
||||
- **Audit Trail:** Log all AI interactions and human validations
|
||||
- **Rate Limiting:** Prevent AI abuse and resource exhaustion
|
||||
- **Validation:** All AI outputs must be validated before use
|
||||
- **Multi-tenant Isolation:** Qdrant queries MUST include projectPublicId filter
|
||||
|
||||
### 5.4 2-Model Stack (ADR-023A)
|
||||
|
||||
- **gemma4:e4b Q8_0** (~4.0GB VRAM) - Main LLM for classification, tagging, extraction
|
||||
- **nomic-embed-text** (~0.3GB VRAM) - Text embedding for RAG
|
||||
- **Total VRAM Peak:** ~4.3GB
|
||||
|
||||
---
|
||||
|
||||
## 6. Architecture Decision Records (ADRs)
|
||||
|
||||
### 6.1 Key ADRs Implemented
|
||||
|
||||
| ADR | Title | Status | Description |
|
||||
| ------------ | --------------------------- | --------- | -------------------------------------- |
|
||||
| **ADR-001** | Unified Workflow Engine | ✅ Active | DSL-based workflow implementation |
|
||||
| **ADR-002** | Document Numbering Strategy | ✅ Active | Document number generation + locking |
|
||||
| **ADR-007** | Error Handling Strategy | ✅ Active | Layered error classification |
|
||||
| **ADR-008** | Email Notification Strategy | ✅ Active | BullMQ + multi-channel notification |
|
||||
| **ADR-009** | Database Migration Strategy | ✅ Active | Schema changes — edit SQL directly |
|
||||
| **ADR-016** | Security Authentication | ✅ Active | Auth, RBAC, file upload security |
|
||||
| **ADR-019** | Hybrid Identifier Strategy | ✅ Active | INT PK + UUIDv7 Public API |
|
||||
| **ADR-021** | Workflow Context | ✅ Active | Integrated workflow & step attachments |
|
||||
| **ADR-023** | Unified AI Architecture | ✅ Active | AI boundaries and pipeline |
|
||||
| **ADR-023A** | AI Model Revision | ✅ Active | 2-Model stack with BullMQ queues |
|
||||
|
||||
### 6.2 ADR References
|
||||
|
||||
For detailed architectural decisions, please refer to:
|
||||
|
||||
- `specs/06-Decision-Records/` - Complete ADR documentation
|
||||
- `AGENTS.md` - Quick-reference rules and enforcement
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **System Context:** `specs/02-Architecture/02-01-system-context.md`
|
||||
- **Software Architecture:** `specs/02-Architecture/02-02-software-architecture.md`
|
||||
- **Network Design:** `specs/02-Architecture/02-03-network-design.md`
|
||||
- **API Design:** `specs/02-Architecture/02-04-api-design.md`
|
||||
- **Decision Records:** `specs/06-Decision-Records/`
|
||||
- **Data Schema:** `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-*.sql`
|
||||
- **Engineering Guidelines:** `specs/05-Engineering-Guidelines/`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
| --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **1.9.2** | 2026-05-18 | Complete restructure following specs/02-Architecture format, added comprehensive diagrams, updated AI Architecture (ADR-023/023A) |
|
||||
| **1.9.0** | 2026-05-13 | AI Architecture consolidation, Agent Infrastructure standardization |
|
||||
| **1.8.0** | 2026-02-23 | Initial architecture documentation |
|
||||
|
||||
---
|
||||
|
||||
_This document is maintained as part of the LCBP3-DMS project specification suite._
|
||||
|
||||
Reference in New Issue
Block a user