lcbp3/specs/200-fullstacks/224-intent-classification/plan.md

Implementation Plan: Intent Classification System

Branch: 224-intent-classification | Date: 2026-05-19 | Spec: spec.md Input: ADR-024 Intent Classification Strategy + CONTEXT.md AI Runtime Layer

---

Summary

สร้าง Intent Classification System สำหรับ AI Runtime Layer ตามกลยุทธ์ Hybrid (Pattern First → LLM Fallback) ที่กำหนดใน ADR-024 ระบบจะแปลงคำถามธรรมชาติ (ภาษาไทย/อังกฤษปน) จาก User เป็น Server-side Intent enum ก่อน Route ไปยัง AI Tool Layer (ADR-025)

แนวทางเทคนิค:

• Backend: NestJS Module (IntentClassifierModule) พร้อม Service สำหรับ Pattern Matching และ LLM Fallback
• Database: ตาราง ai_intent_definitions และ ai_intent_patterns (SQL Delta ตาม ADR-009)
• Caching: Redis (TTL 5 นาที) สำหรับ Patterns
• AI: Ollama gemma4:e2b บน Admin Desktop (Desk-5439) สำหรับ LLM Fallback
• Frontend: Admin UI สำหรับจัดการ Intent และ Patterns + Test Console

---

Technical Context

Language/Version: TypeScript 5.x (NestJS 11) + Next.js 16 Primary Dependencies:

• Backend: NestJS, TypeORM, ioredis (Redis), axios (Ollama HTTP)
• Frontend: React, TanStack Query, shadcn/ui components Storage: MariaDB 11.8 (Intent Definitions/Patterns), Redis (Cache), Ollama (LLM) Testing: Jest (Backend Unit/Integration), Vitest (Frontend Unit), Playwright (E2E) Target Platform: QNAP NAS (Docker), Admin Desktop (Ollama) Project Type: Web application (Backend + Frontend) Performance Goals:
• Pattern Match: < 10ms (cache hit), < 50ms (cache miss)
• LLM Fallback: < 2000ms (รวม Pattern Check) Constraints:
• GPU Budget: RTX 2060 Super 8GB (ใช้ร่วมกับ RAG, OCR, Embedding)
• LLM Semaphore: Max 3 concurrent calls
• Bilingual Input: ไทย/อังกฤษปน + typo tolerance Scale/Scope:
• 12 Intent Definitions (v1)
• 50+ concurrent users
• 70-80% Pattern Hit Rate target

---

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Rule	Status	Notes
ADR-019 UUID	✅	ใช้ publicId (UUIDv7 string) ทุก API — ไม่มี parseInt
ADR-009 Schema	✅	SQL Delta file สำหรับตารางใหม่ — ไม่ใช้ TypeORM migration
ADR-016 Security	✅	CASL Guard บน Admin API, JWT Auth, Rate Limiting
ADR-023A AI Boundary	✅	Ollama บน Admin Desktop — AI ไม่เข้า DB โดยตรง
ADR-007 Error Handling	✅	Layered error classification — user-friendly messages
TypeScript Strict	✅	Zero any, zero console.log (ใช้ NestJS Logger)
i18n	✅	ใช้ i18n keys — ไม่ hardcode ภาษาไทย/อังกฤษ

ผ่าน Gate ทั้งหมด — พร้อมดำเนินการ Phase 0

---

Project Structure

Documentation (this feature)

specs/200-fullstacks/224-intent-classification/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (OpenAPI specs)
├── tasks.md             # Phase 2 output (speckit-tasks)
└── checklists/          # Quality checklists

Source Code (repository root)

backend/
├── src/
│   ├── modules/
│   │   └── ai/
│   │       ├── intent-classifier/          # NEW: Intent Classification Module
│   │       │   ├── intent-classifier.module.ts
│   │       │   ├── intent-classifier.service.ts
│   │       │   ├── intent-classifier.controller.ts
│   │       │   ├── entities/
│   │       │   │   ├── intent-definition.entity.ts
│   │       │   │   └── intent-pattern.entity.ts
│   │       │   ├── dto/
│   │       │   │   ├── classify-query.dto.ts
│   │       │   │   ├── classification-result.dto.ts
│   │       │   │   ├── create-intent-definition.dto.ts
│   │       │   │   └── create-intent-pattern.dto.ts
│   │       │   └── interfaces/
│   │       │       ├── classification-result.interface.ts
│   │       │       └── intent-category.enum.ts
│   │       └── ai.module.ts                # UPDATE: Add IntentClassifierModule
│   └── database/
│       └── seeds/
│           └── ai-intent.seed.ts           # Seed 12 Intent Definitions

frontend/
├── app/
│   └── (admin)/
│       └── admin/
│           └── ai/
│               └── intent-classification/  # NEW: Admin UI
│                   ├── page.tsx            # Intent Definitions List
│                   ├── [intentCode]/
│                   │   ├── page.tsx        # Intent Detail + Patterns
│                   │   └── patterns/
│                   │       └── page.tsx    # Pattern Management
│                   └── test-console/
│                       └── page.tsx        # Test Console
├── components/
│   └── ai/
│       └── intent-classification/          # NEW: Reusable Components
│           ├── intent-form.tsx
│           ├── pattern-form.tsx
│           ├── test-console-panel.tsx
│           └── classification-result-card.tsx
├── hooks/
│   └── ai/
│       └── use-intent-classification.ts    # TanStack Query hooks
└── lib/
    └── services/
        └── ai-intent.service.ts            # API client

Structure Decision: Web application (NestJS Backend + Next.js Frontend) — ตามโครงสร้างที่มีอยู่แล้วใน LCBP3

---

Complexity Tracking

ไม่มี Constitution Violations ที่ต้องอธิบายเพิ่มเติม — ทุกอย่างสอดคล้องกับ ADRs ที่มีอยู่

---

Phase 0: Research

ดูรายละเอียดใน research.md

หัวข้อที่ต้อง Research:

1. Redis Cache Strategy สำหรับ Patterns (TTL + Invalidation)
2. Ollama HTTP API Integration (gemma4:e2b)
3. Semaphore Pattern ใน NestJS (p-limit หรือ RxJS)
4. Regex Validation ใน TypeORM/Class-Validator

---

Phase 1: Design Artifacts

Data Model

ดูรายละเอียดใน data-model.md

API Contracts

ดูรายละเอียดใน contracts/

Quick Start

ดูรายละเอียดใน quickstart.md

---

Next Steps

1. ✅ Phase 0 Complete — Research ใน research.md
2. ✅ Phase 1 Complete — Design artifacts: data-model.md, contracts/, quickstart.md
3. ⏳ Phase 2 — รอ /speckit-tasks สร้าง tasks.md
4. ⏳ Phase 3 — รอ /speckit-analyze ตรวจสอบความสอดคล้อง