lcbp3/specs/200-fullstacks/228-migration-arch-refactor/data-model.md

// File: specs/200-fullstacks/228-migration-arch-refactor/data-model.md // Change Log: // - 2026-05-22: Phase 1 data model for migration architecture refactor

Data Model: ADR-028 Migration Architecture Refactor

New Tables (SQL Delta Required — ADR-009)

tags

CREATE TABLE tags (
  id          INT PRIMARY KEY AUTO_INCREMENT,
  public_id   CHAR(36) NOT NULL UNIQUE,       -- UUIDv7 (ADR-019)
  project_id  INT NULL REFERENCES projects(id) ON DELETE CASCADE,
  tag_name    VARCHAR(100) NOT NULL,
  color_code  VARCHAR(30) DEFAULT 'default',
  description TEXT,
  created_by  INT REFERENCES users(id),
  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted_at  TIMESTAMP NULL,
  UNIQUE KEY uq_tag_project (project_id, tag_name)
);

correspondence_tags

CREATE TABLE correspondence_tags (
  correspondence_id INT NOT NULL REFERENCES correspondences(id) ON DELETE CASCADE,
  tag_id            INT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
  is_ai_suggested   BOOLEAN DEFAULT FALSE,
  confidence        DECIMAL(4,3) NULL,           -- AI confidence score (0.000–1.000)
  created_by        INT REFERENCES users(id),
  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (correspondence_id, tag_id)
);

Existing Tables (Updated by this Feature)

import_transactions (เก็บถาวร — Audit Trail)

-- ตารางนี้มีอยู่แล้วใน migration SQL
-- เพิ่ม index สำหรับ audit queries:
CREATE INDEX idx_import_transactions_batch ON import_transactions(batch_id);
CREATE INDEX idx_import_transactions_doc   ON import_transactions(document_number);

migration_review_queue (Drop หลัง Gate #3)

Column	Type	Notes
id	INT AUTO_INCREMENT PK	—
batch_id	VARCHAR(50)	FK migration_progress
document_number	VARCHAR(100)	จาก Excel
temp_attachment_id	VARCHAR(36)	UUID — cleaned up หลัง commit หรือ 24h
ai_job_id	VARCHAR(36) NULL	BullMQ job ID — เพิ่มโดย SQL delta 2026-05-22-alter-migration-review-queue.sql (ไม่มีใน 03-04 migration SQL เดิม)
ai_confidence	DECIMAL(4,3)	0.000–1.000
ai_summary	TEXT	—
suggested_tags	JSON	[{name, is_new, confidence}]
status	ENUM('PENDING','APPROVED','REJECTED','ERROR')	—
reviewed_by	INT NULL	FK users(id)
reviewed_at	TIMESTAMP NULL	—

BullMQ Job Types (New)

migrate-document (ai-batch queue)

Input payload:

interface MigrateDocumentJobPayload {
  tempAttachmentId: string;      // UUID ของ temp file
  documentNumber: string;
  title: string;
  existingTags: TagOption[];     // project tags สำหรับ AI ใช้ประกอบ
  systemCategories: string[];    // categories จาก /api/meta/categories
  batchId: string;
}

Output (stored in job result):

interface MigrateDocumentJobResult {
  isValid: boolean;
  confidence: number;            // 0.0–1.0
  category: string;
  summary: string;
  suggestedTags: {
    name: string;
    description: string;
    isNew: boolean;
    confidence: number;
  }[];
  detectedIssues: string[];
  ocrMethod: 'fast-path' | 'slow-path';
  processingTimeMs: number;
}

cleanup-temp-files (ai-batch queue — Scheduled)

รัน Scheduled ทุก 1 ชั่วโมง — ลบ temp attachments ที่:

• is_temporary = TRUE
• created_at < NOW() - INTERVAL 24 HOUR
• ไม่มี committed_at (ยังไม่ถูก commit)

Entity Relationships

projects (1) ──── (N) tags
tags (N) ──── (N) correspondences  [through correspondence_tags]
migration_review_queue (1) ──── (1) import_transactions
migration_review_queue.temp_attachment_id → attachments.public_id

State Transitions: Migration Review Record

[Queued by n8n]
      ↓
  PENDING
  ├── (confidence ≥ 0.85 + is_valid) → PENDING (ready for batch import)
  ├── (0.60 ≤ confidence < 0.85)     → PENDING (flagged for careful review)
  └── (confidence < 0.60 OR !is_valid) → REJECTED (auto)
      ↓
  [Human Review by DC/Admin/Superadmin]
      ├── Execute Import → APPROVED → Correspondence created
      └── Reject → REJECTED