350 lines
11 KiB
YAML
350 lines
11 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: OCR & AI Extraction Prompt Management API
|
|
version: 1.0.0
|
|
description: >
|
|
Admin endpoints for managing OCR system prompts and AI extraction prompts.
|
|
หมายเหตุ: route จริง map กับ controller ที่มีอยู่แล้ว `@Controller('ai/prompts')`
|
|
(ADR-029) + global prefix `/api` → base path `/api/ai/prompts`.
|
|
`promptType` และ `versionNumber` เป็น path params. create/activate/update
|
|
ต้องมี header `Idempotency-Key` (ADR-016). ไม่มี publicId-based routes
|
|
และไม่มี pagination/query filter ในของจริง (filter ตาม promptType ผ่าน path).
|
|
|
|
paths:
|
|
/api/ai/prompts/{promptType}:
|
|
get:
|
|
summary: List all versions for a prompt type
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
responses:
|
|
"200":
|
|
description: List of prompt versions (newest versionNumber first)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/AiPromptDto"
|
|
post:
|
|
summary: Create new prompt version (starts inactive)
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/IdempotencyKeyHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreatePromptDto"
|
|
responses:
|
|
"201":
|
|
description: Prompt version created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: "#/components/schemas/AiPromptDto"
|
|
"400":
|
|
description: Validation error (missing required placeholder, >4000 chars, or missing Idempotency-Key)
|
|
|
|
/api/ai/prompts/{promptType}/{versionNumber}:
|
|
delete:
|
|
summary: Delete a prompt version (cannot delete active version)
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/VersionNumberPath"
|
|
responses:
|
|
"204":
|
|
description: Prompt version deleted
|
|
"404":
|
|
description: Prompt version not found
|
|
"400":
|
|
description: Cannot delete active prompt (BusinessException CANNOT_DELETE_ACTIVE_PROMPT)
|
|
|
|
/api/ai/prompts/{promptType}/{versionNumber}/activate:
|
|
post:
|
|
summary: Activate this prompt version (pessimistic lock + deactivates others)
|
|
description: >
|
|
ของจริงใช้ pessimistic_write lock ใน transaction และไม่รับ expectedVersion.
|
|
@VersionColumn มีไว้ดักการแก้ไขซ้อนตอน save เท่านั้น — ยังไม่มี 409 flow ตาม spec.
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/VersionNumberPath"
|
|
- $ref: "#/components/parameters/IdempotencyKeyHeader"
|
|
responses:
|
|
"200":
|
|
description: Prompt activated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: "#/components/schemas/AiPromptDto"
|
|
"404":
|
|
description: Prompt version not found
|
|
|
|
/api/ai/prompts/{promptType}/{versionNumber}/note:
|
|
patch:
|
|
summary: Update manual note for a prompt version
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/VersionNumberPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UpdatePromptNoteDto"
|
|
responses:
|
|
"200":
|
|
description: Note updated
|
|
|
|
/api/ai/prompts/{promptType}/{versionNumber}/context-config:
|
|
get:
|
|
summary: Get context config for a prompt version
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/VersionNumberPath"
|
|
responses:
|
|
"200":
|
|
description: Context config object (or null)
|
|
put:
|
|
summary: Update context config (project/contract scope) for a prompt version
|
|
tags: [AI Prompts]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/PromptTypePath"
|
|
- $ref: "#/components/parameters/VersionNumberPath"
|
|
- $ref: "#/components/parameters/IdempotencyKeyHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ContextConfigDto"
|
|
responses:
|
|
"200":
|
|
description: Context config updated
|
|
|
|
# --- AI Sandbox (มีอยู่แล้วใน AiController @Controller('ai')) ---
|
|
/api/ai/admin/sandbox/ocr:
|
|
post:
|
|
summary: Submit OCR sandbox job (Step 1 — uses active ocr_system prompt)
|
|
tags: [AI Sandbox]
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
description: PDF file to OCR
|
|
engineType:
|
|
type: string
|
|
enum: [auto, np-dms-ocr]
|
|
default: auto
|
|
responses:
|
|
"202":
|
|
description: OCR job accepted (poll GET /api/ai/admin/sandbox/job/{id})
|
|
|
|
/api/ai/admin/sandbox/extract:
|
|
post:
|
|
summary: Submit AI extraction sandbox job (Step 2 — uses active ocr_extraction prompt)
|
|
tags: [AI Sandbox]
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"202":
|
|
description: Extraction job accepted
|
|
|
|
/api/ai/admin/sandbox/rag-prep:
|
|
post:
|
|
summary: Submit RAG Prep sandbox job (Step 3 — มีอยู่แล้ว, SandboxRagPrepDto)
|
|
tags: [AI Sandbox]
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SandboxRagPrepDto"
|
|
responses:
|
|
"202":
|
|
description: RAG Prep job accepted
|
|
|
|
components:
|
|
schemas:
|
|
AiPromptDto:
|
|
type: object
|
|
properties:
|
|
publicId:
|
|
type: string
|
|
format: uuid
|
|
promptType:
|
|
type: string
|
|
enum:
|
|
[
|
|
ocr_system,
|
|
ocr_extraction,
|
|
rag_query_prompt,
|
|
rag_prep_prompt,
|
|
classification_prompt,
|
|
]
|
|
versionNumber:
|
|
type: integer
|
|
template:
|
|
type: string
|
|
contextConfig:
|
|
type: object
|
|
properties:
|
|
temperature:
|
|
type: number
|
|
topP:
|
|
type: number
|
|
maxTokens:
|
|
type: integer
|
|
modelName:
|
|
type: string
|
|
isActive:
|
|
type: boolean
|
|
testResultJson:
|
|
type: object
|
|
nullable: true
|
|
manualNote:
|
|
type: string
|
|
nullable: true
|
|
lastTestedAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
activatedAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
# หมายเหตุ: AiPromptResponseDto จริงไม่ expose `version`, `createdBy`, `id`
|
|
# (createdBy เป็น INT FK ถูก @Exclude ตาม ADR-019)
|
|
|
|
CreatePromptDto:
|
|
type: object
|
|
required: [template]
|
|
description: >
|
|
ตรงกับ CreateAiPromptDto จริง — promptType เป็น path param ไม่ใช่ body.
|
|
template สูงสุด 4000 ตัวอักษร (@MaxLength). ตรวจ placeholder ตาม promptType.
|
|
properties:
|
|
template:
|
|
type: string
|
|
maxLength: 4000
|
|
description: Prompt template content (ต้องมี placeholder ตาม promptType เช่น {{ocr_text}})
|
|
contextConfig:
|
|
type: object
|
|
nullable: true
|
|
|
|
UpdatePromptNoteDto:
|
|
type: object
|
|
properties:
|
|
manualNote:
|
|
type: string
|
|
nullable: true
|
|
|
|
ContextConfigDto:
|
|
type: object
|
|
description: ตรงกับ ContextConfigDto จริง (pageSize/language/outputLanguage/filter)
|
|
properties:
|
|
pageSize:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
language:
|
|
type: string
|
|
outputLanguage:
|
|
type: string
|
|
filter:
|
|
type: object
|
|
nullable: true
|
|
properties:
|
|
projectId:
|
|
type: string
|
|
format: uuid
|
|
description: project publicId (UUID) — resolve เป็น internal id ภายหลัง
|
|
contractId:
|
|
type: string
|
|
format: uuid
|
|
|
|
SandboxRagPrepDto:
|
|
type: object
|
|
description: ตรงกับ backend/src/modules/ai/dto/sandbox-rag-prep.dto.ts (มีอยู่แล้ว)
|
|
|
|
parameters:
|
|
PromptTypePath:
|
|
name: promptType
|
|
in: path
|
|
required: true
|
|
description: ประเภท prompt (เช่น ocr_system, ocr_extraction)
|
|
schema:
|
|
type: string
|
|
enum:
|
|
[
|
|
ocr_system,
|
|
ocr_extraction,
|
|
rag_query_prompt,
|
|
rag_prep_prompt,
|
|
classification_prompt,
|
|
]
|
|
VersionNumberPath:
|
|
name: versionNumber
|
|
in: path
|
|
required: true
|
|
description: เลข version (ParseIntPipe)
|
|
schema:
|
|
type: integer
|
|
IdempotencyKeyHeader:
|
|
name: Idempotency-Key
|
|
in: header
|
|
required: true
|
|
description: Unique key เพื่อป้องกัน duplicate operation (ADR-016)
|
|
schema:
|
|
type: string
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: >
|
|
JWT + RbacGuard. ทุก endpoint ต้องการ permission `system.manage_all`
|
|
(JwtAuthGuard + RbacGuard + @RequirePermission).
|