690403:2205 Modify AI (Add Gemma4 & PaddleOCR

specs/06-Decision-Records/ADR-017B-ollama.md

@@ -0,0 +1,317 @@
+# ADR-017B: Smart Legacy Document Digitization (AI-Powered Use Case Extension)
+
+**Status:** Accepted
+**Date:** 2026-03-27
+**Version:** 1.8.2 (Aligned with ADR-020)
+**Decision Makers:** Development Team, AI Integration Lead
+**Related Documents:**
+
+- [ADR-020: AI Intelligence Integration Architecture](./ADR-020-ai-intelligence-integration.md) — Overall AI Architecture & RFA-First Strategy
+- [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md)
+- [ADR-018: AI Boundary Policy](./ADR-018-ai-boundary.md) — AI Physical Isolation (No Direct DB/Storage Access)
+- [n8n Migration Setup Guide](../03-Data-and-Storage/03-05-n8n-migration-setup-guide.md)
+- [Legacy Data Migration Plan](../03-Data-and-Storage/03-04-legacy-data-migration.md)
+- [Migration Business Scope](../03-Data-and-Storage/03-06-migration-business-scope.md)
+- [Glossary](../00-Overview/00-02-glossary.md)
+
+> **Note:** ADR-017B เป็น Use Case Extension ของ ADR-017 ที่ขยายขอบเขตการใช้งาน Ollama จาก Migration Batch สู่ระบบจัดหมวดหมู่เอกสารอัจฉริยะ (Smart Categorization) พร้อมควบคุมตาม ADR-018 (AI Isolation Policy) และเป็นส่วนหนึ่งของ ADR-020 (Unified AI Architecture).
+
+---
+
+## Context and Problem Statement
+
+### ปัญหาที่ต้องการแก้ไข
+
+โครงการ LCBP3 มีเอกสารเก่าจำนวนมาก (กว่า 20,000 ฉบับ) ที่ต้องนำเข้าสู่ระบบ DMS ใหม่ การจัดหมวดหมู่และสกัด Metadata ด้วยมือมีปัญหาหลัก 3 ประการ:
+
+1. **Manual Labor สูง:** ต้องใช้เวลานานในการอ่านและพิมพ์ข้อมูล Metadata (Data Entry)
+2. **Human Error:** ความผิดพลาดจากการพิมพ์ (Typo) โดยเฉพาะเลขที่สัญญาและชื่อเฉพาะ
+3. **Searchability:** ไฟล์ PDF ที่เป็นแค่ภาพสแกน (Scanned) ไม่สามารถค้นหาเนื้อหาได้
+
+### ข้อจำกัดที่สำคัญ
+
+- **Data Privacy:** เอกสารก่อสร้างท่าเรือเป็นความลับ ห้ามส่งข้อมูลขึ้น Cloud AI Provider
+- **Cost Constraint:** การใช้ Cloud AI (~$0.01–0.03 ต่อ Record) อาจสูงถึง $600 สำหรับ 20,000 records
+- **Hardware Limitation:** ต้องรันบนเครื่องที่มีอยู่ (i7-9700K / 32GB RAM / RTX 2060 Super 8GB)
+
+---
+
+## Decision Drivers
+
+- **Security First (ADR-018):** AI ต้องรันบน Admin Desktop (Desk-5439) เท่านั้น — ห้ามรันบน QNAP/Production Server
+- **Privacy Guaranteed:** ประมวลผลภายในเครือข่ายองค์กร (On-Premise) เท่านั้น
+- **Cost Effectiveness:** Zero Cost สำหรับ AI Inference (ไม่มีค่า Pay-per-use)
+- **Data Integrity:** ข้อมูลที่ AI สกัดต้องผ่าน Human Verification ก่อน Commit ลงระบบจริง
+- **AI Isolation (ADR-018):** AI ห้ามเข้าถึง Database/Storage โดยตรง — ต้องสื่อสารผ่าน DMS API เท่านั้น
+- **Recoverability:** รองรับ Checkpoint/Resume และ Rollback ได้สมบูรณ์
+
+---
+
+## Considered Options
+
+### Option 1: Manual Data Entry (No AI)
+
+**Pros:**
+
+- ไม่ต้องลงทุน Hardware เพิ่ม
+- ความแม่นยำ 100% (ถ้าพิมพ์ถูก)
+
+**Cons:**
+
+- ❌ ใช้เวลานานมาก (อาจเป็นสัปดาห์หรือเดือน)
+- ❌ Human Error สูง (Typo, Inconsistency)
+- ❌ ไม่สามารถทำให้ Scanned PDF ค้นหาได้
+
+### Option 2: Cloud AI Service (OpenAI, Google Vision, Azure AI)
+
+**Pros:**
+
+- AI ฉลาดสูง แม่นยำมาก
+- ไม่ต้องดูแล Infrastructure
+
+**Cons:**
+
+- ❌ **ผิดนโยบาย Data Privacy** — เอกสารก่อสร้างท่าเรือเป็นความลับ
+- ❌ **ค่าใช้จ่ายสูง** (~$600 สำหรับ 20,000 records)
+- ❌ Dependency กับ External Service
+
+### Option 3: Local AI (Ollama + Gemma 4 9B) + n8n + Human Verification ⭐ (Selected)
+
+**Pros:**
+
+- ✅ **Privacy Guaranteed** — รันภายในเครือข่ายองค์กร
+- ✅ **Zero Cost** — ไม่มีค่า Pay-per-use
+- ✅ **AI Isolation (ADR-018)** — AI รันบน Desktop แยกต่างหาก ไม่เข้าถึง DB โดยตรง
+- ✅ **Human-in-the-Loop** — Admin ตรวจสอบก่อน Commit
+- ✅ **Recoverability** — รองรับ Checkpoint/Resume
+- ✅ **Clean Architecture** — แยก Migration Logic ออกจาก Core Application
+
+**Cons:**
+
+- ❌ ต้องเปิด Desktop ทิ้งไว้ดูแล GPU Temperature
+- ❌ Model ขนาดเล็กอาจแม่นยำน้อยกว่า Cloud AI → ต้องมี Human Review Queue
+- ❌ ใช้เวลา Migration ~16.6 ชั่วโมง (~3–4 คืน)
+
+---
+
+## Decision Outcome
+
+**Chosen Option:** Option 3 — Local AI (Ollama + Gemma 4 9B) + n8n + Human Verification
+
+**Rationale:**
+
+ประยุกต์ใช้ Hardware ที่มีอยู่ (i7-9700K + RTX 2060 Super) โดยไม่ขัดหลัก Privacy และ Security ของโครงการ n8n ช่วยลด Risk ที่จะกระทบ Core Backend และรองรับ Checkpoint/Resume ได้ดีกว่าการเขียน Script เอง นอกจากนี้ยังสอดคล้องกับ **ADR-018 (AI Boundary)** ที่กำหนดให้ AI ต้องรันบน Admin Desktop แยกต่างหาก และไม่สามารถเข้าถึง Database/Storage โดยตรงได้
+
+---
+
+## Implementation Architecture
+
+### System Components
+
+| Component | รายละเอียด | ที่ตั้ง |
+|-----------|-----------|---------|
+| **Migration Orchestrator** | n8n (Docker บน QNAP NAS) | QNAP NAS |
+| **AI Processing Engine** | Ollama + Gemma 4 9B (9.6 GB) | Admin Desktop (Desk-5439) |
+| **OCR Engine** | Tesseract หรือ Google Vision (On-prem) | Same as AI |
+| **Verification UI** | Next.js Frontend — Review Mode | Web Browser |
+| **Database** | MariaDB — Staging + Production | QNAP NAS |
+| **File Storage** | Two-Phase Storage (Temp → Permanent) | NAS Mounts |
+
+### Workflow (Main Success Scenario)
+
+```
+[1. Ingestion]        → Batch Upload (PDF/Scan)
+      ↓
+[2. Pre-processing]   → File Validation (NestJS)
+      ↓
+[3. OCR Layer]        → Raw Text Extraction (Tesseract)
+      ↓
+[4. AI Analysis]      → Gemma 4 9B via Ollama (Desk-5439)
+      ↓
+[5. Staging]          → migration_review_queue (MariaDB)
+      ↓
+[6. Verification]     → Admin Review UI (Next.js)
+      ↓
+[7. Commit]           → POST /api/migration/commit_batch
+      ↓
+[8. Finalization]     → Permanent Storage (QNAP)
+```
+
+### AI Processing Flow (ADR-018 Compliant)
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Scanned PDF   │────▶│  OCR Engine     │────▶│   Raw Text      │
+│   (Staging)     │     │  (Tesseract)    │     │   (Text)        │
+└─────────────────┘     └─────────────────┘     └────────┬────────┘
+                                                         │
+                              ┌──────────────────────────┘
+                              ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  DMS Backend    │◀────│  Ollama API     │◀────│  AI Prompt      │
+│  (Validation)   │     │  (Desk-5439)    │     │  (Gemma 4 9B)   │
+└────────┬────────┘     └─────────────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  JSON Metadata  │────▶ migration_review_queue
+│  (Validated)    │
+└─────────────────┘
+```
+
+> ⚠️ **ADR-018 Enforcement:** AI (Ollama) อยู่บน Desktop Desk-5439 แยกต่างหาก — ไม่มี Direct DB Access หรือ File System Access โดยตรง ทุกการสื่อสารผ่าน DMS Backend API เท่านั้น
+
+---
+
+## AI Prompt Specification (Prompt Engineering)
+
+### Document Analysis Prompt
+
+```markdown
+บทบาท: คุณคือผู้ช่วยจัดการเอกสารวิศวกรรมโยธาประจำโครงการท่าเรือแหลมฉบัง เฟส 3
+ภารกิจ: อ่านข้อความดิบจากการสแกน และสรุปข้อมูลออกมาในรูปแบบ JSON เท่านั้น
+
+ข้อความดิบ: [RAW_TEXT_FROM_OCR]
+
+รูปแบบ JSON ที่ต้องการ:
+{
+  "document_type": "รายงาน/สัญญา/จดหมายโต้ตอบ",
+  "contract_number": "เลขที่สัญญา (ถ้ามี)",
+  "contractor_name": "ชื่อบริษัทผู้รับเหมา",
+  "work_phase": "Phase ของงาน (เช่น งานถมทะเล, งานไฟฟ้า)",
+  "summary": "สรุปเนื้อหาสำคัญ 1-2 ประโยค",
+  "key_dates": ["วันที่ในเอกสาร", "วันกำหนดส่งงาน"]
+}
+```
+
+### Extracted Metadata Schema
+
+| Field | Type | คำอธิบาย |
+|-------|------|---------|
+| `document_type` | enum | Correspondence / RFA / Drawing / Minutes / Contract |
+| `contract_number` | string | เลขที่สัญญา (เช่น LCBP3-C1) |
+| `contractor_name` | string | ชื่อบริษัทผู้รับเหมา |
+| `work_phase` | string | Phase งาน (จาก Master Data) |
+| `work_zone` | string | Zone F, Basin 3, etc. |
+| `priority` | enum | ด่วนที่สุด / ด่วน / ปกติ |
+| `summary` | string | สรุปเนื้อหา 4-5 ประโยค |
+| `confidence` | float | 0.0–1.0 (ความมั่นใจของ AI) |
+| `suggested_tags` | array | Tags ที่แนะนำ (is_new: true/false) |
+
+> ⚠️ **Patch Note:** `document_type` ต้องตรงกับ System Enum จาก `GET /api/meta/categories` เท่านั้น — ห้าม hardcode Category List ใน Prompt (ดู ADR-017)
+
+---
+
+## Security & Compliance (ADR-018)
+
+### AI Isolation Requirements
+
+| Rule | Implementation |
+|------|----------------|
+| **Physical Isolation** | Ollama รันบน Admin Desktop (Desk-5439) เท่านั้น |
+| **No Direct DB Access** | AI ต้องสื่อสารผ่าน DMS API → Backend → Database |
+| **No Direct Storage Access** | File operations ผ่าน StorageService เท่านั้น |
+| **Validation Layer** | Backend ตรวจสอบ AI Output ก่อน Write ทุกครั้ง |
+| **Audit Logging** | ทุก AI Request/Response บันทึกใน Audit Log |
+
+### Two-Phase Storage (Storage Governance)
+
+**ข้อห้าม:**
+
+```bash
+❌ mv /data/dms/staging_ai/TCC-COR-0001.pdf /final/path/...
+```
+
+**ข้อบังคับ (ADR-017):**
+
+```
+Phase 1: Temp Upload (โดย n8n)
+✅ POST /api/storage/upload
+   → ได้ผลลัพธ์เป็น attachment_id (เช่น 1024)
+   → ไฟล์จะถูกระบุเป็น is_temporary = TRUE
+
+Phase 2: Final Commit (โดย Admin ผ่าน Frontend)
+✅ POST /api/migration/commit_batch
+   body: { queue_ids: [1, 2, 3] }
+```
+
+---
+
+## Confidence Threshold Policy
+
+ข้อมูลทุกชุดจาก AI จะถูกส่งเข้า `migration_review_queue` โดยจัดสถานะตาม Confidence:
+
+| Confidence Level | สถานะ | การดำเนินการ |
+|-----------------|-------|--------------|
+| `≥ 0.85` และ `is_valid = true` | PENDING | พร้อมให้ Admin Batch Import |
+| `0.60–0.84` | PENDING | ไฮไลต์ให้ Admin ตรวจสอบก่อน |
+| `< 0.60` หรือ `is_valid = false` | REJECTED | รอ Admin แก้ไข Manual |
+| AI Parse Error | ERROR_LOG | Trigger Fallback Logic |
+
+---
+
+## Performance Estimation
+
+| Parameter | ค่า |
+|-----------|-----|
+| Delay ระหว่าง Request | 2 วินาที |
+| Inference Time (avg) | ~1 วินาที |
+| เวลาต่อ Record | ~3 วินาที |
+| จำนวน Record | 20,000 |
+| **เวลารวม** | ~60,000 วินาที (~16.6 ชั่วโมง) |
+| **จำนวนคืนที่ต้องใช้** | **~3–4 คืน** (รัน 22:00–06:00) |
+
+> **Recommendation:** สำหรับเครื่อง i7-9700K / 32GB RAM / RTX 2060 Super 8GB แนะนำให้ใช้ Queue (BullMQ) ประมวลผลไฟล์แบบ Sequential (ทีละไฟล์) เพื่อให้ Gemma 4 9B (9.6 GB) ทำงานได้เสถียรที่สุดใน VRAM 8GB
+
+---
+
+## Consequences
+
+### Positive Consequences
+
+1. ✅ **Privacy Guaranteed** — ไม่มีข้อมูลออกนอกเครือข่ายองค์กร
+2. ✅ **Zero AI Cost** — ไม่มีค่าใช้จ่าย Pay-per-use
+3. ✅ **Security Compliant (ADR-018)** — AI Isolation ชัดเจน
+4. ✅ **Human-in-the-Loop** — ความถูกต้อง 100% ก่อน Commit
+5. ✅ **Recoverability** — รองรับ Checkpoint/Resume และ Rollback
+6. ✅ **Searchable Legacy** — Scanned PDF กลายเป็น Searchable Metadata
+
+### Negative Consequences
+
+1. ❌ **Operational Overhead** — ต้องดูแล GPU Temperature และ Desktop Uptime
+2. ❌ **Accuracy Trade-off** — Model ขนาดเล็กอาจแม่นยำน้อยกว่า Cloud AI
+3. ❌ **Time Investment** — ต้องใช้เวลา ~3–4 คืนในการ Migration
+4. ❌ **Hardware Dependency** — ต้องพึ่งพา Desktop Desk-5439
+
+### Mitigation Strategies
+
+- **Human Review Queue** — บังคับตรวจสอบทุก record ก่อน Commit
+- **Confidence Threshold** — แบ่งระดับตามความมั่นใจของ AI
+- **Fallback Model** — Auto-switch ไป mistral:7b-instruct เมื่อ Error ≥ Threshold
+- **Monitoring** — ตรวจสอบ GPU Temperature และ Progress ตลอดเวลา
+
+---
+
+## Related Documents
+
+- [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md) — Architecture หลักสำหรับ Migration
+- [ADR-018: AI Boundary Policy](./ADR-018-ai-boundary.md) — Security Isolation สำหรับ AI
+- [03-05-n8n-migration-setup-guide.md](../03-Data-and-Storage/03-05-n8n-migration-setup-guide.md) — คู่มือติดตั้ง n8n Workflow
+- [03-04-legacy-data-migration.md](../03-Data-and-Storage/03-04-legacy-data-migration.md) — แผน Migration แบบละเอียด
+- [03-06-migration-business-scope.md](../03-Data-and-Storage/03-06-migration-business-scope.md) — Go/No-Go Gates และ Business Scope
+- [00-02-glossary.md](../00-Overview/00-02-glossary.md) — คำศัพท์และตัวย่อในระบบ DMS
+
+---
+
+## Document History
+
+| Version | Date       | Author     | Changes |
+|---------|------------|------------|---------|
+| 1.0.0   | 2026-02-26 | Nattanin   | Initial Use Case Specification |
+| 1.8.1   | 2026-03-27 | Tech Lead  | **Refactored to ADR format** — Aligned with ADR-017, ADR-018, and Project Specs |
+
+---
+
+**Last Updated:** 2026-03-27
+**Status:** Accepted
+**Next Review:** 2026-06-01 (Quarterly review)