690519:1631 224 to 226 AI #01

specs/200-fullstacks/224-intent-classification/contracts/intent-classification-api.yaml

@@ -0,0 +1,450 @@
+openapi: 3.0.3
+info:
+  title: Intent Classification API
+  description: API สำหรับ Intent Classification ตาม ADR-024 (Hybrid Pattern First → LLM Fallback)
+  version: 1.0.0
+  contact:
+    name: NAP-DMS Development Team
+
+servers:
+  - url: http://localhost:3001/api
+    description: Local Development
+  - url: https://api.nap-dms.work/api
+    description: Production
+
+tags:
+  - name: Intent Classification
+    description: แปลงคำถามธรรมชาติ → Server-side Intent
+  - name: Intent Management
+    description: Admin API สำหรับจัดการ Intent Definitions และ Patterns
+
+paths:
+  # === Intent Classification ===
+  /ai/intent/classify:
+    post:
+      summary: Classify User Query
+      description: |
+        แปลงคำถามธรรมชาติจาก User เป็น Server-side Intent enum
+        ใช้ Hybrid Strategy: Pattern First → LLM Fallback
+      tags: [Intent Classification]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ClassifyQueryRequest'
+            example:
+              query: "สรุปเอกสารนี้"
+              projectPublicId: "019505a1-7c3e-7000-8000-abc123def456"
+      responses:
+        '200':
+          description: Classification successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ClassificationResult'
+              examples:
+                pattern-match:
+                  summary: Pattern Match (cache hit)
+                  value:
+                    intentCode: "SUMMARIZE_DOCUMENT"
+                    confidence: 1.0
+                    method: "pattern"
+                    latencyMs: 8
+                llm-fallback:
+                  summary: LLM Fallback
+                  value:
+                    intentCode: "GET_RFA"
+                    confidence: 0.85
+                    method: "llm_fallback"
+                    params:
+                      contractPublicId: "019505a1-7c3e-7000-8000-xyz789abc123"
+                    latencyMs: 1250
+                fallback:
+                  summary: No Match (FALLBACK)
+                  value:
+                    intentCode: "FALLBACK"
+                    confidence: 0.0
+                    method: "llm_fallback"
+                    latencyMs: 2100
+        '400':
+          description: Invalid request (missing query)
+        '401':
+          description: Unauthorized
+        '429':
+          description: Too many requests (rate limit)
+
+  # === Intent Definitions (Admin) ===
+  /admin/ai/intent-definitions:
+    get:
+      summary: List Intent Definitions
+      description: ดึงรายการ Intent Definitions ทั้งหมด
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: category
+          in: query
+          schema:
+            type: string
+            enum: [read, suggest, utility]
+          description: Filter by category
+        - name: isActive
+          in: query
+          schema:
+            type: boolean
+          description: Filter by active status
+      responses:
+        '200':
+          description: List of intent definitions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/IntentDefinition'
+
+    post:
+      summary: Create Intent Definition
+      description: สร้าง Intent Definition ใหม่ (System Admin only)
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateIntentDefinitionRequest'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntentDefinition'
+        '409':
+          description: Intent code already exists
+
+  /admin/ai/intent-definitions/{intentCode}:
+    parameters:
+      - name: intentCode
+        in: path
+        required: true
+        schema:
+          type: string
+        example: "GET_RFA"
+
+    get:
+      summary: Get Intent Definition
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Intent definition found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntentDefinition'
+        '404':
+          description: Intent not found
+
+    patch:
+      summary: Update Intent Definition
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateIntentDefinitionRequest'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntentDefinition'
+
+  # === Intent Patterns (Admin) ===
+  /admin/ai/intent-definitions/{intentCode}/patterns:
+    parameters:
+      - name: intentCode
+        in: path
+        required: true
+        schema:
+          type: string
+
+    get:
+      summary: List Patterns for Intent
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: List of patterns
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/IntentPattern'
+
+    post:
+      summary: Create Pattern for Intent
+      description: เพิ่ม Pattern ใหม่สำหรับ Intent นี้
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateIntentPatternRequest'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntentPattern'
+        '400':
+          description: Invalid regex pattern
+
+  /admin/ai/intent-patterns/{publicId}:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+
+    get:
+      summary: Get Pattern
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Pattern found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntentPattern'
+
+    patch:
+      summary: Update Pattern
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateIntentPatternRequest'
+      responses:
+        '200':
+          description: Updated
+
+    delete:
+      summary: Delete Pattern (soft delete)
+      tags: [Intent Management]
+      security:
+        - bearerAuth: []
+      responses:
+        '204':
+          description: Deleted
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  schemas:
+    # === Classification ===
+    ClassifyQueryRequest:
+      type: object
+      required: [query]
+      properties:
+        query:
+          type: string
+          maxLength: 200
+          description: คำถามจาก user (trim แล้ว)
+          example: "สรุปเอกสารนี้"
+        projectPublicId:
+          type: string
+          format: uuid
+          description: Context project
+        userPublicId:
+          type: string
+          format: uuid
+          description: Context user
+        currentDocumentId:
+          type: string
+          format: uuid
+          description: Document ที่เปิดอยู่ (ถ้ามี)
+
+    ClassificationResult:
+      type: object
+      properties:
+        intentCode:
+          type: string
+          description: Intent ที่จำแนกได้
+          example: "SUMMARIZE_DOCUMENT"
+        confidence:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: ความมั่นใจ (1.0 = pattern match)
+          example: 1.0
+        method:
+          type: string
+          enum: [pattern, llm_fallback, semaphore_overflow, llm_error]
+          description: วิธีที่ใช้จำแนก
+        params:
+          type: object
+          additionalProperties: true
+          description: Parameters ที่สกัดได้ (optional)
+        latencyMs:
+          type: integer
+          description: เวลาที่ใช้ทั้งหมด (ms)
+          example: 8
+
+    # === Intent Definition ===
+    IntentDefinition:
+      type: object
+      properties:
+        publicId:
+          type: string
+          format: uuid
+        intentCode:
+          type: string
+          example: "GET_RFA"
+        descriptionTh:
+          type: string
+          example: "ดึง RFA ตาม filter"
+        descriptionEn:
+          type: string
+          example: "Get RFA by filters"
+        category:
+          type: string
+          enum: [read, suggest, utility]
+        isActive:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    CreateIntentDefinitionRequest:
+      type: object
+      required: [intentCode, descriptionTh, descriptionEn, category]
+      properties:
+        intentCode:
+          type: string
+          pattern: '^[A-Z][A-Z0-9_]*$'
+          example: "GET_CONTRACT"
+        descriptionTh:
+          type: string
+          maxLength: 255
+        descriptionEn:
+          type: string
+          maxLength: 255
+        category:
+          type: string
+          enum: [read, suggest, utility]
+
+    UpdateIntentDefinitionRequest:
+      type: object
+      properties:
+        descriptionTh:
+          type: string
+          maxLength: 255
+        descriptionEn:
+          type: string
+          maxLength: 255
+        isActive:
+          type: boolean
+
+    # === Intent Pattern ===
+    IntentPattern:
+      type: object
+      properties:
+        publicId:
+          type: string
+          format: uuid
+        intentCode:
+          type: string
+        language:
+          type: string
+          enum: [th, en, any]
+        patternType:
+          type: string
+          enum: [keyword, regex]
+        patternValue:
+          type: string
+          maxLength: 255
+        priority:
+          type: integer
+          description: ลำดับการตรวจสอบ (ต่ำ = ตรวจก่อน)
+        isActive:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    CreateIntentPatternRequest:
+      type: object
+      required: [patternType, patternValue]
+      properties:
+        language:
+          type: string
+          enum: [th, en, any]
+          default: any
+        patternType:
+          type: string
+          enum: [keyword, regex]
+        patternValue:
+          type: string
+          maxLength: 255
+        priority:
+          type: integer
+          default: 100
+
+    UpdateIntentPatternRequest:
+      type: object
+      properties:
+        language:
+          type: string
+          enum: [th, en, any]
+        patternType:
+          type: string
+          enum: [keyword, regex]
+        patternValue:
+          type: string
+          maxLength: 255
+        priority:
+          type: integer
+        isActive:
+          type: boolean