feat(migration): ADR-028 migration architecture refactor

- เพิ่ม POST /api/ai/jobs + GET /api/ai/jobs/:jobId endpoints (FR-001, FR-002) - เพิ่ม BullMQ Worker MigrateDocumentWorker + OCR auto-detect (FR-003, FR-004) - เพิ่ม cleanup-temp-files + expire-pending-reviews workers (FR-005, FR-005a/b) - สร้าง SQL deltas: tags, correspondence_tags, alter migration_review_queue (FR-006, ADR-009) - เพิ่ม MigrationReviewService.commitRecord() + SELECT FOR UPDATE (FR-007, FR-007a) - เพิ่ม CASL permission migration.commit + MigrationReviewController (FR-007) - สร้าง TagsModule + TagsService + TagsController (US3) - สร้าง Migration Review Queue frontend page + ReviewQueueTable (US2) - อัปเดต n8n guide: deterministic Idempotency-Key + token pre-flight (FR-001a, FR-010a/b) - สร้าง spec.md, plan.md, tasks.md, data-model.md, contracts/, quickstart.md - สร้าง ADR-028 document + validation-report.md (PASS 32/32 tasks, 173/173 tests)
2026-05-22 17:10:07 +07:00
parent 990d80e16d
commit a2973be208
55 changed files with 4256 additions and 107 deletions
@@ -16,7 +16,7 @@
 - รักษาโครงสร้างความสัมพันธ์ (Project / Contract / Ref No.) และระบบการทำ Revision ตาม Business Rules
 - **Checkpoint Support:** รองรับการหยุดและเริ่มงานต่อ (Resume) จากจุดที่ค้างอยู่ได้กรณีเกิดเหตุขัดข้อง

-> **Note:** เอกสารนี้ขยายความถึงวิธีปฏิบัติ (Implementation) จากการตัดสินใจทางสถาปัตยกรรมใน [ADR-017: Ollama Data Migration Architecture](../06-Decision-Records/ADR-017-ollama-data-migration.md)
+> **Note:** เอกสารนี้ขยายความถึงวิธีปฏิบัติ (Implementation) จากการตัดสินใจทางสถาปัตยกรรมใน [ADR-023A: Unified AI Architecture — Model Revision](../06-Decision-Records/ADR-023A-unified-ai-architecture.md)

 ---

@@ -49,47 +49,30 @@
 - ติดตั้ง Ollama บน Desktop (Desk-5439, RTX 2060 SUPER 8GB)
 - No DB credentials, Internal network only

-#### 🔍 เปรียบเทียบผลลัพธ์ที่คาดหวัง
+#### 🔍 AI Model Stack (ADR-023A)

-| งาน                   | Typhoon2-4B | Qwen2.5-7B | OpenThaiGPT-7B |
-| --------------------- | ----------- | ---------- | -------------- |
-| ความเร็ว (ток/วินาที) | ~35-45      | ~8-12      | ~10-15         |
-| ความเข้าใจบริบทไทย    | ดีมาก       | ดี         | ดีมาก          |
-| การสร้างแท็กแม่นยำ    | ⭐⭐⭐⭐    | ⭐⭐⭐⭐   | ⭐⭐⭐⭐⭐     |
-| ความเสถียรบน 8GB      | ✅ สูง      | ⚠️ ปานกลาง | ⚠️ ปานกลาง     |
+ใช้ **2 โมเดลเท่านั้น** ตาม ADR-023A — รันบน Desk-5439 เท่านั้น **ห้ามเปลี่ยนโดยไม่ review ADR:**
+
+| โมเดล | VRAM (โดยประมาณ) | หน้าที่ |
+| ------ | ---------------- | ------- |
+| `gemma4:e4b Q8_0` | ~4.0GB | OCR Post-processing, Metadata Extraction, Classification |
+| `nomic-embed-text` | ~0.3GB | Embedding 768-dim สำหรับ Qdrant |
+| **รวม (peak)** | **~4.3GB** | **เผื่อ headroom ~3.7GB สำหรับ KV Cache** |

 ```bash
-# แนะนำ: llama3.2:3b (เร็ว, VRAM ~3GB, เหมาะ Classification) หรือ ollama run llama3.2:3b
-ollama pull llama3.2:3b
+# ติดตั้งโมเดล (รันบน Desk-5439 เท่านั้น)
+ollama pull gemma4:e4b
+ollama pull nomic-embed-text

-# ทางเลือกที่ 1: เร็ว + ไทยดี (แนะนำ)
-ollama pull scb10x/typhoon2.1-gemma3-4b
-ollama run scb10x/typhoon2.1-gemma3-4b --system "คุณเป็นผู้ช่วยจัดหมวดหมู่เอกสารภาษาไทย โปรดตอบกลับในรูปแบบ JSON เท่านั้น" --option temperature=0.2 --option num_ctx=4096
-
-# ทางเลือกที่ 2: คุณภาพสูง (โมเดลที่คุณใช้อยู่)
-ollama pull qwen2.5:7b-instruct-q4_K_M
-ollama run qwen2.5:7b-instruct-q4_K_M --system "คุณเป็นผู้ช่วยจัดหมวดหมู่เอกสารภาษาไทย โปรดตอบกลับในรูปแบบ JSON เท่านั้น" --option temperature=0.2 --option num_ctx=4096
-# ถ้า Q4_K_M ยังหนักไป ลอง Q3_K_M (คุณภาพลดเล็กน้อย แต่ประหยัดแรม)
-ollama pull qwen2.5:7b-instruct-q3_K_M
-
-# ทางเลือกที่ 3: ไทยเฉพาะทาง
-ollama pull promptnow/openthaigpt1.5-7b-instruct-q4_k_m
-ollama run openthaigpt1.5-7b-instruct-q4_k_m --system "คุณเป็นผู้ช่วยจัดหมวดหมู่เอกสารภาษาไทย โปรดตอบกลับในรูปแบบ JSON เท่านั้น" --option temperature=0.2 --option num_ctx=4096
-
-# เปิด terminal อีกหน้าต่างแล้วรัน
+# ตรวจสอบ GPU usage
 watch -n 1 nvidia-smi
-
-# Fallback: mistral:7b-instruct-q4_K_M (แม่นกว่า, VRAM ~5GB)
-# ollama pull mistral:7b-instruct-q4_K_M
 ```

-ใช้ ทางเลือกที่ 1
-
 **ทดสอบ Ollama:**

 ```bash
 curl http://192.168.20.100:11434/api/generate \
-  -d '{"model":"llama3.2:3b","prompt":"reply: ok","stream":false}'
+  -d '{"model":"gemma4:e4b","prompt":"reply: ok","stream":false}'
 ```

 **Concurrency Configuration:**
@@ -122,6 +105,8 @@ CREATE TABLE IF NOT EXISTS migration_progress (

 **Tags Table (สำหรับ AI Tag Extraction):**

+> 🔴 **Pre-requisite (Blocking):** ตาราง `tags` และ `correspondence_tags` **ยังไม่มีใน production schema** — ต้องสร้าง SQL delta ใน `specs/03-Data-and-Storage/deltas/` ตาม ADR-009 ก่อน Migration เริ่ม
+
 ```sql
 -- ตาราง Master เก็บ Tags (Global หรือ Project-specific)
 CREATE TABLE tags (
@@ -241,41 +226,55 @@ n8n ต้องเก็บ categories นี้ไว้ใน Workflow Variab
 #### Node 3: File Processor (Extract PDF Text & Temp Upload)

 - ตรวจสอบไฟล์ PDF มีอยู่จริงบน NAS `/share/np-dms/staging_ai`
- **Extract PDF Text:** ใช้ Apache Tika สกัดข้อความจากเอกสาร
+- **OCR/Text Extraction:** ดำเนินการโดย BullMQ Worker บน Desk-5439 (PyMuPDF Fast Path หากมี text layer > 100 chars/page หรือ PaddleOCR + PyThaiNLP Slow Path หาก scanned — ตาม ADR-023A Section 4.2) — n8n ไม่ extract text เอง
 - **Two-Phase Storage (Upload):**
  - n8n ยิง `POST /api/storage/upload` ส่งไฟล์ PDF เข้า Backend
  - Backend อัพโหลดไฟล์, กำหนด `is_temporary = TRUE`
  - Backend ส่งคืน `attachment_id` ให้ n8n (จะเรียกว่า `temp_attachment_id`)
+  - **Temp File TTL:** Backend ลบ temp file อัตโนมัติหาก job `failed` หรือไม่มี commit ภายใน **24 ชั่วโมง** (Scheduled cleanup job ใน BullMQ)

-#### Node 4: AI Analysis (Sequential เท่านั้น)
+#### Node 4: AI Job Submission & Polling (via BullMQ)

-**System Prompt:**
+> 🔴 **Pre-requisite (Blocking):** Endpoint `POST /api/ai/jobs` (type: `migrate-document`) **ยังไม่มีใน Backend** — ต้องพัฒนาและทดสอบก่อน Migration Phase เริ่ม (เพิ่มใน Go/No-Go Gate #1)

-```text
-You are a Document Controller for a large construction project.
-Your task is to validate document metadata, summarize content, and suggest relevant tags.
-You MUST respond ONLY with valid JSON. No explanation, no markdown.
+> ⚠️ **ADR-023A:** n8n ห้ามเรียก Ollama โดยตรง — ต้องผ่าน DMS API → BullMQ เท่านั้น เพื่อให้ RBAC, ADR-007 Error Handling และ `ai_audit_logs` ครอบคลุมทุก job โดยอัตโนมัติ
+
+**Step 1: Submit AI Job**
+
+```http
+POST /api/ai/jobs
+Authorization: Bearer <MIGRATION_TOKEN>
+Content-Type: application/json
+
+{
+  "type": "migrate-document",
+  "payload": {
+    "temp_attachment_id": "{{$json.temp_attachment_id}}",
+    "document_number": "{{$json.document_number}}",
+    "title": "{{$json.title}}",
+    "existing_tags": "{{$json.existing_tags_json}}",
+    "system_categories": "{{$json.system_categories}}"
+  }
+}
 ```

-**User Prompt:**
+Response: `{ "jobId": "<uuid>" }`

-```text
-Validate and summarize this document. Respond in JSON.
-Document Number: {{$json.document_number}}
-Title: {{$json.title}}
-Extracted Text: {{$json.extracted_text}}
+**Step 2: Poll Job Result (n8n Loop Node)**

-Existing Project Tags: {{$json.existing_tags_json}}
+```http
+GET /api/ai/jobs/{{jobId}}
+Authorization: Bearer <MIGRATION_TOKEN>
+```

-Analyze the content to provide:
-1. Validation of Subject/Dates with PDF text.
-2. A 4-5 sentence summary.
-3. Suggest tags. Select from Existing Project Tags if applicable. If no existing tag fits, suggest a NEW one (set is_new: true).
+Poll ทุก 5 วินาที จนกว่า `status = "completed"` หรือ `"failed"` (timeout 120 วินาที)

-Respond ONLY with this exact JSON structure:
+**AI Output Contract (จาก BullMQ Worker — gemma4:e4b Q8_0):**
+
+```json
 {
-  "is_valid": true | false,
-  "confidence": 0.0 to 1.0,
+  "is_valid": true,
+  "confidence": 0.92,
  "category": "Correspondence",
  "summary": "<4-5 sentence summary>",
  "suggested_tags": [
@@ -285,6 +284,8 @@ Respond ONLY with this exact JSON structure:
 }
 ```

+> **Note:** System Prompt และ User Prompt อยู่ใน BullMQ Worker (Backend NestJS) ไม่ใช่ใน n8n Workflow
+
 #### Node 5: Staging Ingestion (Insert to Review Queue)

 ข้อมูลทั้งหมดที่ผ่าน n8n และ AI Model **จะต้องไม่ถูกอัพเดทเข้าตารางหลักอัตโนมัติ** แต่จะถูกบังคับนำเข้าตาราง Staging `migration_review_queue` แทน เพื่อรอมนุษย์จัดการผ่าน Frontend UI
@@ -319,7 +320,7 @@ ON DUPLICATE KEY UPDATE status = VALUES(status), ai_summary = VALUES(ai_summary)
 1. หน้าจอ **Frontend Management UI** ดึงข้อมูลจาก `migration_review_queue`
 2. Admin สามารถ Browse & Edit ข้อมูล
 3. **Tag Review:** Admin สามารถพิจารณา Tags ที่เป็น `is_new: true` ว่าควรตีตก หรือเปลี่ยนไปแมตช์ของเดิม
-4. Admin กดปุ่ม **Execute Import** ส่งให้ Backend รัน Final Commit.
+4. ผู้มีสิทธิ์ (`DOCUMENT_CONTROLLER` | `ADMIN` | `SUPERADMIN`) กดปุ่ม **Execute Import** ส่งให้ Backend รัน Final Commit.
 5. Backend ยิงคำสั่งสร้าง Correspondence, นำ `temp_attachment_id` ไปผูกกับ Revision, ปรับเป็น `is_temporary = FALSE` และสร้าง/เชื่อม Tags จริง.

 ---
@@ -416,7 +417,7 @@ WHERE batch_id = 'migration_20260226';
 | 4        | Idempotency ซ้ำ             | `import_transactions` table + Backend คืน HTTP 200            |
 | 5        | Revision Drift              | ตรวจ Excel revision column → Route ไป Review Queue            |
 | 6        | Storage bypass              | ห้าม move file โดยตรง — ผ่าน Backend API เท่านั้น             |
-| 7        | GPU VRAM Overflow           | ใช้เฉพาะ Quantized Model (q4_K_M)                             |
+| 7        | GPU VRAM Overflow           | ใช้ `gemma4:e4b Q8_0` + `nomic-embed-text` (~4.3GB peak) — ต่ำกว่า VRAM 8GB อย่างมีเสถียรภาพ ตาม ADR-023A |
 | 8        | ดิสก์ NAS เต็ม              | ปิด "Save Successful Executions" ใน n8n                       |
 | 9        | Migration Token ถูกขโมย     | Token 7 วัน, IP Whitelist `<NAS_IP>` เท่านั้น                 |
 | 11       | AI Tag Extraction ผิดพลาด   | Tag confidence < 0.6 → ส่งไป Review Queue / บันทึกใน metadata |
@@ -3,7 +3,7 @@
 > **สำหรับ n8n Free Plan (Self-hosted)** - ไม่ใช้ Environment Variables
 > **Version:** 1.8.0-free | **Last Updated:** 2026-03-04

-เอกสารนี้จัดทำขึ้นเพื่อรองรับการ Migration เอกสาร PDF 20,000 ฉบับ ตามแผนใน `03-04-legacy-data-migration.md` และ `ADR-017-ollama-data-migration.md`
+เอกสารนี้จัดทำขึ้นเพื่อรองรับการ Migration เอกสาร PDF 20,000 ฉบับ ตามแผนใน `03-04-legacy-data-migration.md` และ `ADR-023A-unified-ai-architecture.md`

 ---

@@ -120,8 +120,9 @@ const CONFIG = {

  // Ollama Settings
  OLLAMA_HOST: 'http://192.168.20.100:11434',
-  OLLAMA_MODEL_PRIMARY: 'llama3.2:3b',
-  OLLAMA_MODEL_FALLBACK: 'mistral:7b-instruct-q4_K_M',
+  OLLAMA_MODEL: 'gemma4:e4b',         // ห้ามเปลี่ยน — กำหนดโดย ADR-023A
+  EMBED_MODEL: 'nomic-embed-text',     // สำหรับ Embedding เท่านั้น
+  // ไม่มี FALLBACK model — BullMQ concurrency=1 จัดการ GPU usage

  // Backend Settings
  BACKEND_URL: 'https://backend.np-dms.work',
@@ -164,7 +165,7 @@ return [{ json: { config_loaded: true, timestamp: new Date().toISOString() } }];
 1. **สร้าง Dedicated User สำหรับ Migration เท่านั้น** (แนะนำใช้ชื่อ `migration_bot`)
 2. **ใช้ Token ที่มีสิทธิ์จำกัด** (เฉพาะ API ที่จำเป็น)
 3. **Rotate Token ทันทีหลัง Migration เสร็จ**
-4. **💡 หมายเหตุ:** Backend ระบบ DMS ได้ถูกตั้งค่าให้สร้าง Token แบบไม่มีวันหมดอายุ (100 ปี) สำหรับ User ชื่อ `migration_bot` โดยเฉพาะ เพื่อป้องกันปัญหา Token หมดอายุระหว่างที่ Workflow กำลังทำงานข้ามวัน
+4. **💡 หมายเหตุ:** Token Expiry ≤ **7 วัน** ตาม ADR-023 — ต้อง Renew ทุกสัปดาห์ระหว่าง Migration Phase และ **Revoke ทันทีวัน Go-Live** (ดู Timeline ใน 03-06 Section 4)

 **Credentials (ถ้าใช้):**

@@ -210,14 +211,14 @@ mysql -h <DB_HOST> -u migration_bot -p lcbp3_production < lcbp3-v1.8.0-migration

 **ตารางที่สร้าง (6 ตาราง ชั่วคราว — ลบได้หลัง Migration เสร็จ):**

-| ตาราง                      | วัตถุประสงค์                       |
-| -------------------------- | ---------------------------------- |
-| `migration_progress`       | Checkpoint ติดตามความคืบหน้า Batch |
-| `migration_review_queue`   | รายการที่ต้องตรวจสอบโดยคน          |
-| `migration_errors`         | Error Log                          |
-| `migration_fallback_state` | สถานะ AI Model Fallback            |
-| `import_transactions`      | Idempotency ป้องกัน Import ซ้ำ     |
-| `migration_daily_summary`  | สรุปผลรายวัน                       |
+| ตาราง                      | วัตถุประสงค์                       | Retention |
+| -------------------------- | ---------------------------------- | --------- |
+| `migration_progress`       | Checkpoint ติดตามความคืบหน้า Batch | Drop หลัง Gate #3 |
+| `migration_review_queue`   | รายการที่ต้องตรวจสอบโดยคน          | Drop หลัง Gate #3 |
+| `migration_errors`         | Error Log                          | Drop หลัง Gate #3 |
+| `migration_fallback_state` | สถานะ AI Model Fallback            | Drop หลัง Gate #3 |
+| `import_transactions`      | Idempotency + **Audit Trail**      | ✅ เก็บถาวร (ไม่ Drop) |
+| `migration_daily_summary`  | สรุปผลรายวัน                       | Drop หลัง Gate #3 |

 ---

@@ -230,6 +231,7 @@ mysql -h <DB_HOST> -u migration_bot -p lcbp3_production < lcbp3-v1.8.0-migration

 ### Node 1: Pre-flight Checks & Data Reader

+- **Pre-flight Token Validation (FR-010a):** เรียก API `GET /api/auth/me` ก่อนประมวลผลเพื่อตรวจสอบความถูกต้องและอายุของ `MIGRATION_TOKEN` หากไม่ผ่าน (401 Unauthorized) ให้ยุติการทำงานทันทีเพื่อป้องกันการส่ง API ที่ล้มเหลว
 - ตรวจสอบ Backend Health และ Ollama Ping
 - อ่าน Checkpoint (`last_processed_index`) จาก `migration_progress`
 - Batch ข้อมูลจาก Excel ตามตาราง `BATCH_SIZE` ปกติ (50-100)
@@ -244,17 +246,21 @@ mysql -h <DB_HOST> -u migration_bot -p lcbp3_production < lcbp3-v1.8.0-migration

 ### Node 3: Text Extraction & Temp Upload

- ใช้ **Apache Tika** (ผ่าน `Extract PDF Text` node หรือ HTTP Request) สกัดข้อความ (OCR/Text) ออกจาก PDF ใน staging
+- **OCR/Text Extraction ดำเนินการโดย BullMQ Worker** (Desk-5439) — n8n ไม่ extract เอง (PyMuPDF Fast Path / PaddleOCR + PyThaiNLP Slow Path ตาม ADR-023A Section 4.2)
 - แนบไฟล์ไปยัง Backend: ยิง HTTP Request **`POST /api/storage/upload`** ของ Backend
 - รอรับผลลัพธ์เป็น `temp_attachment_id` (หมายความว่าไฟล์นี้เข้าข่าย Temporary ถูกเก็บจัดการใน NAS เรียบร้อยแล้ว)
 - Output: ไฟล์พร้อมใช้งาน, ได้เนื้อหา Text มาเตรียม prompt

-### Node 4: AI Analysis
+### Node 4: AI Job Submission & Polling

- วาง System Prompt บังคับ Output JSON
- โยน Metadata (Title, Date, DB Lookups) พร้อม Extracted PDF Text คุยกับ **Ollama `llama3.2:3b`**
- ให้ AI วิเคราะห์ และสรุปเป็น `ai_summary`
- ให้ AI แนะนำ Tags ใหม่หรือเลือก Tags เดิมจาก `existing_tags_json`
+> ⚠️ **ADR-023A:** ห้ามเรียก Ollama โดยตรง — ต้องผ่าน DMS API → BullMQ
+
+- **Idempotency-Key Deterministic (FR-001a):** ส่ง header `Idempotency-Key` ในรูปแบบ `{batchId}:{documentNumber}` (ตัวอย่าง: `migration_20260226:DOC-001`) เพื่อให้แน่ใจว่าการส่งคำขอประมวลผลเอกสารซ้ำจะไม่มีผลซ้ำซ้อนในระบบ และไม่ใช้ random UUID
+- **Graceful Token Expiry (FR-010b):** หากพบข้อผิดพลาด 401 Unauthorized ในระหว่างที่ทำการประมวลผล (mid-batch) ให้ทำการอัปเดตสถานะใน `migration_progress` เป็น `TOKEN_EXPIRED` เพื่อบันทึก Checkpoint ล่าสุดและหยุดการรัน เพื่อให้สามารถดึงข้อมูล token ใหม่มาใส่แล้วกด Resume ต่อจากจุดเดิมได้ทันที
+- Submit: `POST /api/ai/jobs` พร้อม `temp_attachment_id`, `document_number`, `title`, `existing_tags`, `system_categories`
+- Response: `{ "jobId": "<uuid>" }`
+- Poll: `GET /api/ai/jobs/{{jobId}}` ทุก 5 วินาที จน `status = "completed"` (timeout 120 วินาที)
+- AI inference ใช้ `gemma4:e4b Q8_0` ผ่าน BullMQ Worker — System/User Prompt อยู่ใน Backend NestJS ไม่ใช่ใน n8n

 ### Node 5: Parse & Validate

@@ -503,5 +509,5 @@ mysql -h <DB_HOST> -u migration_bot -p -e "SELECT COUNT(DISTINCT ct.corresponden

 ---

-**เอกสารฉบับนี้จัดทำขึ้นสำหรับ n8n Free Plan (Self-hosted) ตาม ADR-017 และ 03-04**
+**เอกสารฉบับนี้จัดทำขึ้นสำหรับ n8n Free Plan (Self-hosted) ตาม ADR-023A และ 03-04**
 **Version:** 1.8.0-free | **Last Updated:** 2026-03-04 | **Author:** Development Team
@@ -11,18 +11,17 @@ related:

 - specs/03-Data-and-Storage/03-04-legacy-data-migration.md ← Technical Implementation
 - specs/03-Data-and-Storage/03-05-n8n-migration-setup-guide.md
- specs/06-Decision-Records/ADR-017-ollama-data-migration.md
- specs/06-Decision-Records/ADR-018-ai-boundary.md
+- specs/06-Decision-Records/ADR-023A-unified-ai-architecture.md
 - specs/00-Overview/00-04-stakeholder-signoff-and-risk.md ← Risk Register (RISK-002)

 ---

 > [!IMPORTANT]
-> เอกสารนี้กำหนด **ขอบเขตทางธุรกิจ** ของการ Migration เท่านั้น  
+> เอกสารนี้กำหนด **ขอบเขตทางธุรกิจ** ของการ Migration เท่านั้น
 > รายละเอียดทางเทคนิค (n8n Workflow, Ollama Prompt, API Spec) อยู่ใน `03-04-legacy-data-migration.md`

 > [!NOTE]
-> "เอกสารเก่า" คือเอกสารที่บริหารจัดการผ่าน Email + File Share ก่อนระบบ LCBP3-DMS  
+> "เอกสารเก่า" คือเอกสารที่บริหารจัดการผ่าน Email + File Share ก่อนระบบ LCBP3-DMS
 > จำนวน: ประมาณ **20,000 ไฟล์ PDF** พร้อม Metadata ใน Excel

 ---
@@ -33,7 +32,7 @@ related:
 | ----------------- | ------------------------------------------------------------- |
 | **Continuity**    | ผู้ใช้สามารถค้นหาและอ้างอิงเอกสารเก่าในระบบใหม่ได้ทันที       |
 | **Traceability**  | Workflow ใหม่สามารถ Link กลับไปยัง Correspondence เก่าได้     |
-| **Searchability** | เอกสารเก่าถูก Index ใน Elasticsearch — ค้นหาได้ด้วย Full-text |
+| **Searchability** | เอกสารเก่าถูก Index ใน Elasticsearch (Full-text keyword) และ Qdrant (Semantic RAG) — ค้นหาได้ทั้ง keyword และ context-aware |
 | **Compliance**    | Audit Trail ครบ: รู้ว่าใครนำเข้า เมื่อไหร่ จาก Batch ไหน      |

 ---
@@ -58,7 +57,7 @@ related:
 **เงื่อนไข Include:**

 - ไฟล์ต้องเป็น PDF (หรือ DWG สำหรับ Drawing)
- ไฟล์ต้อง Readable โดย Tika/Ollama (ไม่ Corrupted)
+- ไฟล์ต้อง Readable โดย OCR Service — PyMuPDF (Fast Path) หรือ PaddleOCR (Slow Path) ไม่ Corrupted (ตาม ADR-023A Section 4.2)
 - มี Row ใน Excel Metadata ที่ตรงกัน (document_number ไม่ว่าง)

 ---
@@ -195,6 +194,7 @@ T+1 เดือน:
 | Idempotency Test: รัน Batch ซ้ำ          | 0 Duplicate Records               | SQL Count                      |
 | Organization Mapping ครบ                 | 100%                              | Lookup Table review            |
 | Frontend Review UI พร้อมใช้งาน           | ✅                                | UAT Passed สำหรับหน้าจออนุมัติ |
+| **Backend `POST /api/ai/jobs` พร้อมใช้งาน** | ✅ (Blocking) | ทดสอบ `type: migrate-document` สำเร็จ — ยังไม่มีใน Backend ต้องพัฒนาก่อน |
 | Migration Bot Token Active + Whitelisted | ✅                                | API Test                       |
 | Staging NAS Space: ≥ 500GB free          | ✅                                | QNAP Dashboard                 |

@@ -223,6 +223,7 @@ T+1 เดือน:
 | User Search Test: สามารถค้นหา Legacy Doc ใน ES | ✅       |
 | Zero Orphan Files ใน Staging                   | ✅       |
 | Legacy System Archive เสร็จ (Compress + Store) | ✅       |
+| Drop Migration Tables (ยกเว้น `import_transactions`) | ✅ | `migration_progress`, `migration_review_queue`, `migration_errors`, `migration_fallback_state`, `migration_daily_summary` |

 ---

@@ -236,6 +237,7 @@ T+1 เดือน:
 | **Tier 1 Document List**                 | Document Control ทุก Org | ยืนยัน T-5                               |
 | **Daily Monitoring (n8n Runs)**          | Nattanin P.              | T-3 ถึง Go-Live                          |
 | **Admin Review Queue & AI Tag Approval** | Document Control (สค.)   | ทุกเช้าวันทำงาน (บังคับตรวจสอบ New Tags) |
+| **Final Commit (Execute Import)** | `DOCUMENT_CONTROLLER` \| `ADMIN` \| `SUPERADMIN` | กดปุ่ม Execute Import หลัง Review ครบ |
 | **Post-migration Verification**          | Nattanin P.              | After each Gate                          |
 | **Legacy System Archival**               | กทท. IT + NAP            | T+30                                     |

@@ -0,0 +1,14 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-alter-migration-review-queue.rollback.sql
+-- Change Log:
+-- - 2026-05-22: ลบคอลัมน์ ai_job_id ออกจากตาราง migration_review_queue ตาม ADR-028
+
+-- Delta Rollback: ลบคอลัมน์ ai_job_id ในตาราง migration_review_queue
+-- Date: 2026-05-22
+-- Related ADR: ADR-028, ADR-023A
+
+-- ------------------------------------------------------------
+-- การลบคอลัมน์ (Rollback changes)
+-- ------------------------------------------------------------
+
+ALTER TABLE migration_review_queue 
+DROP COLUMN ai_job_id;
@@ -0,0 +1,16 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-alter-migration-review-queue.sql
+-- Change Log:
+-- - 2026-05-22: เพิ่มคอลัมน์ ai_job_id ในตาราง migration_review_queue ตาม ADR-028
+
+-- Delta: เพิ่มคอลัมน์ ai_job_id ในตาราง migration_review_queue
+-- Date: 2026-05-22
+-- Related ADR: ADR-028, ADR-023A
+-- Applied in: v1.9.0 -> v1.9.5
+
+-- ------------------------------------------------------------
+-- การปรับปรุงตาราง migration_review_queue (Schema changes)
+-- ------------------------------------------------------------
+
+ALTER TABLE migration_review_queue 
+ADD COLUMN ai_job_id VARCHAR(36) NULL COMMENT 'BullMQ Job ID สำหรับงานประมวลผล AI'
+AFTER storage_temp_path;
@@ -0,0 +1,14 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-create-tags-tables.rollback.sql
+-- Change Log:
+-- - 2026-05-22: ย้อนกลับตาราง tags และ correspondence_tags ตาม ADR-028
+
+-- Delta Rollback: ลบตาราง tags และ correspondence_tags
+-- Date: 2026-05-22
+-- Related ADR: ADR-028
+
+-- ------------------------------------------------------------
+-- การลบตาราง (Rollback changes)
+-- ------------------------------------------------------------
+
+DROP TABLE IF EXISTS correspondence_tags;
+DROP TABLE IF EXISTS tags;
@@ -0,0 +1,47 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-create-tags-tables.sql
+-- Change Log:
+-- - 2026-05-22: สร้างตาราง tags และ correspondence_tags ตาม ADR-028
+
+-- Delta: สร้างตาราง tags และ correspondence_tags
+-- Date: 2026-05-22
+-- Related ADR: ADR-028, ADR-019
+-- Applied in: v1.9.0 -> v1.9.5
+
+-- ------------------------------------------------------------
+-- การสร้างตาราง tags (Schema changes)
+-- ------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS tags (
+  id          INT PRIMARY KEY AUTO_INCREMENT COMMENT 'ID ภายในระบบ',
+  public_id   CHAR(36) NOT NULL UNIQUE COMMENT 'UUIDv7 สำหรับการใช้งานภายนอก (ADR-019)',
+  project_id  INT NULL COMMENT 'ID โครงการ (NULL = Global Tag)',
+  tag_name    VARCHAR(100) NOT NULL COMMENT 'ชื่อแท็ก',
+  color_code  VARCHAR(30) DEFAULT 'default' COMMENT 'รหัสสีสำหรับ UI',
+  description TEXT COMMENT 'คำอธิบายเพิ่มเติม',
+  created_by  INT COMMENT 'ผู้สร้างแท็ก',
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่สร้าง',
+  updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'วันที่แก้ไขล่าสุด',
+  deleted_at  TIMESTAMP NULL COMMENT 'วันที่ลบ (Soft Delete)',
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (created_by) REFERENCES users(user_id) ON DELETE SET NULL,
+  UNIQUE KEY uq_tag_project (project_id, tag_name),
+  INDEX idx_tags_deleted_at (deleted_at)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางเก็บข้อมูลแท็กจัดหมวดหมู่เอกสาร';
+
+-- ------------------------------------------------------------
+-- การสร้างตาราง correspondence_tags (Schema changes)
+-- ------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS correspondence_tags (
+  correspondence_id INT NOT NULL COMMENT 'ID ของเอกสาร',
+  tag_id            INT NOT NULL COMMENT 'ID ของแท็ก',
+  is_ai_suggested   BOOLEAN DEFAULT FALSE COMMENT 'แท็กนี้แนะนำโดย AI หรือไม่',
+  confidence        DECIMAL(4,3) NULL COMMENT 'ค่าความมั่นใจของ AI (0.000–1.000)',
+  created_by        INT COMMENT 'ผู้เชื่อมโยงแท็ก',
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'วันที่เชื่อมโยง',
+  PRIMARY KEY (correspondence_id, tag_id),
+  FOREIGN KEY (correspondence_id) REFERENCES correspondences(id) ON DELETE CASCADE,
+  FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE,
+  FOREIGN KEY (created_by) REFERENCES users(user_id) ON DELETE SET NULL,
+  INDEX idx_correspondence_tags_lookup (tag_id)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'ตารางเชื่อมโยงความสัมพันธ์แบบ M:N ระหว่างเอกสารและแท็ก';
@@ -0,0 +1,95 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-drop-migration-tables.rollback.sql
+-- Change Log:
+-- - 2026-05-22: กู้คืนโครงสร้างตาราง staging ทั้งหมด 5 ตารางสำหรับระบบย้ายข้อมูลกรณีเกิดเหตุฉุกเฉิน (Phase 6)
+
+-- Delta Rollback: กู้คืนตาราง Staging ชั่วคราว (Recreate Staging Tables)
+-- Date: 2026-05-22
+-- Related ADR: ADR-028
+
+-- ------------------------------------------------------------
+-- การกู้คืนตาราง Staging ทั้งหมด 5 ตาราง
+-- ------------------------------------------------------------
+
+-- 1. กู้คืนตารางความคืบหน้าของ Migration Progress
+CREATE TABLE IF NOT EXISTS migration_progress (
+  batch_id VARCHAR(50) PRIMARY KEY,
+  last_processed_index INT DEFAULT 0,
+  STATUS ENUM('RUNNING', 'COMPLETED', 'FAILED') DEFAULT 'RUNNING',
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'Migration: Batch Progress';
+
+-- 2. กู้คืนตารางคิวตรวจสอบสำหรับเอกสาร (Review Queue)
+CREATE TABLE IF NOT EXISTS migration_review_queue (
+  id INT NOT NULL AUTO_INCREMENT,
+  uuid CHAR(36) NOT NULL DEFAULT (uuid()) COMMENT 'UUID Public Identifier (ADR-019)',
+  document_number VARCHAR(100) NOT NULL,
+  subject TEXT COMMENT 'หัวข้อเรื่องภาษาไทยหรืออังกฤษ',
+  original_subject TEXT COMMENT 'หัวข้อเรื่องเดิมจากระบบจัดเก็บเดิม',
+  body TEXT NULL COMMENT 'เนื้อความย่อจาก AI',
+  ai_suggested_category VARCHAR(50),
+  ai_confidence DECIMAL(4, 3),
+  ai_issues JSON,
+  review_reason VARCHAR(255),
+  status ENUM('PENDING', 'APPROVED', 'IMPORTED', 'REJECTED') NOT NULL DEFAULT 'PENDING',
+  reviewed_by VARCHAR(100),
+  reviewed_at TIMESTAMP NULL,
+  project_id INT NULL COMMENT 'Project ID ของโครงการ',
+  sender_organization_id INT NULL COMMENT 'Sender ID ของผู้ส่ง',
+  receiver_organization_id INT NULL COMMENT 'Receiver ID ของผู้รับ',
+  received_date DATE NULL,
+  issued_date DATE NULL,
+  remarks TEXT,
+  ai_summary TEXT,
+  extracted_tags JSON,
+  temp_attachment_id INT NULL,
+  ai_job_id VARCHAR(36) NULL COMMENT 'BullMQ Job ID สำหรับงานประมวลผล AI',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_doc_number (document_number),
+  UNIQUE KEY uq_migration_review_uuid (uuid)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'Migration: Review Queue';
+
+-- 3. กู้คืนตารางแสดงประวัติข้อผิดพลาดการย้ายข้อมูล (Error Log)
+CREATE TABLE IF NOT EXISTS migration_errors (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  batch_id VARCHAR(50),
+  document_number VARCHAR(100),
+  error_type ENUM(
+    'FILE_NOT_FOUND',
+    'MISSING_FILENAME',
+    'FILE_ERROR',
+    'AI_PARSE_ERROR',
+    'API_ERROR',
+    'DB_ERROR',
+    'SECURITY',
+    'UNKNOWN'
+  ),
+  error_message TEXT,
+  raw_ai_response TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_batch_id (batch_id),
+  INDEX idx_error_type (error_type)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'Migration: Error Log';
+
+-- 4. กู้คืนตารางสถานะสำหรับ AI Model Fallback State
+CREATE TABLE IF NOT EXISTS migration_fallback_state (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  batch_id VARCHAR(50) UNIQUE,
+  recent_error_count INT DEFAULT 0,
+  is_fallback_active BOOLEAN DEFAULT FALSE,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'Migration: Fallback Model State';
+
+-- 5. กู้คืนตารางแสดงข้อมูลสรุปรายวันของ Migration (Daily Summary)
+CREATE TABLE IF NOT EXISTS migration_daily_summary (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  batch_id VARCHAR(50),
+  summary_date DATE,
+  total_processed INT DEFAULT 0,
+  auto_ingested INT DEFAULT 0,
+  sent_to_review INT DEFAULT 0,
+  rejected INT DEFAULT 0,
+  errors INT DEFAULT 0,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uq_batch_date (batch_id, summary_date)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = 'Migration: Daily Summary';
@@ -0,0 +1,26 @@
+-- File: specs/03-Data-and-Storage/deltas/2026-05-22-drop-migration-tables.sql
+-- Change Log:
+-- - 2026-05-22: ดรอปตาราง staging ทั้งหมดหลังย้ายข้อมูลเสร็จสิ้น (Phase 6) โดยยังคงรักษาตาราง import_transactions ไว้ป้องกันการย้ายข้อมูลซ้ำ
+
+-- Delta: ดรอปตาราง Staging ชั่วคราว (Post-Migration Cleanup)
+-- Date: 2026-05-22
+-- Related ADR: ADR-028
+
+-- ------------------------------------------------------------
+-- การล้างตาราง Staging เพื่อประหยัดพื้นที่ระบบจัดเก็บข้อมูล (Cleanups)
+-- ------------------------------------------------------------
+
+-- ลบตารางแสดงข้อมูลสรุปรายวันของ Migration
+DROP TABLE IF EXISTS migration_daily_summary;
+
+-- ลบตารางสถานะสำหรับ AI Model Fallback State
+DROP TABLE IF EXISTS migration_fallback_state;
+
+-- ลบตารางแสดงประวัติข้อผิดพลาดการย้ายข้อมูล
+DROP TABLE IF EXISTS migration_errors;
+
+-- ลบตารางคิวตรวจสอบสำหรับเอกสาร
+DROP TABLE IF EXISTS migration_review_queue;
+
+-- ลบตารางความคืบหน้าของ Migration Progress
+DROP TABLE IF EXISTS migration_progress;