191 lines
7.8 KiB
Markdown
191 lines
7.8 KiB
Markdown
# Data Model: OCR & AI Extraction Prompt Management
|
|
|
|
**Feature**: 238-ocr-ai-prompt-separation
|
|
**Date**: 2026-06-17
|
|
|
|
## Entity: AiPrompt (Extended from ADR-029)
|
|
|
|
### Database Schema
|
|
|
|
> **สถานะ**: ตาราง `ai_prompts` มีอยู่แล้วจริง (ADR-029, deltas 2026-05-25 / 2026-06-06 / 2026-06-15) — ข้างล่างคือ schema **จริง** ไม่ใช่ข้อเสนอ งานนี้ไม่ได้สร้างตารางใหม่ — มีเพียง seed `ocr_system` เท่านั้น
|
|
|
|
```sql
|
|
-- File (ของจริง): specs/03-Data-and-Storage/deltas/2026-05-25-create-ai-prompts.sql
|
|
-- + 2026-06-06-add-ai-prompts-public-id.sql
|
|
-- + 2026-06-15-fix-ai-prompts-columns.sql
|
|
|
|
CREATE TABLE ai_prompts (
|
|
id INT AUTO_INCREMENT PRIMARY KEY, -- internal PK (ไม่ expose, ADR-019)
|
|
public_id UUID NOT NULL UNIQUE, -- MariaDB native UUID for API (ADR-019)
|
|
prompt_type VARCHAR(50) NOT NULL, -- 'ocr_system', 'ocr_extraction', etc.
|
|
version_number INT NOT NULL, -- User-visible version number (1, 2, 3...)
|
|
template TEXT NOT NULL, -- Prompt content
|
|
field_schema JSON NULL, -- definition ของ fields ที่คาดหวังใน JSON result
|
|
context_config JSON NULL, -- Master Data context filtering (project/contract scope)
|
|
is_active TINYINT(1) NOT NULL DEFAULT 0, -- Only one active per prompt_type
|
|
test_result_json JSON NULL, -- ผล sandbox run ล่าสุด
|
|
manual_note TEXT NULL, -- annotation จาก admin
|
|
last_tested_at TIMESTAMP NULL,
|
|
activated_at TIMESTAMP NULL,
|
|
created_by INT NOT NULL, -- FK users(user_id) — INT ไม่ใช่ created_by_public_id
|
|
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
|
version INT NOT NULL DEFAULT 1, -- @VersionColumn optimistic locking (delta 2026-06-15)
|
|
|
|
UNIQUE KEY uk_type_version (prompt_type, version_number),
|
|
INDEX idx_prompt_type_active (prompt_type, is_active),
|
|
FOREIGN KEY (created_by) REFERENCES users(user_id)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
|
|
```
|
|
|
|
### TypeScript Entity (Backend)
|
|
|
|
> **สถานะ**: entity มีอยู่แล้วที่ `backend/src/modules/ai/prompts/ai-prompts.entity.ts` (ไม่ใช่ `entities/ai-prompt.entity.ts`). ข้างล่างคือโครงสร้าง**จริง** — งาน 238 ไม่ต้องสร้าง entity ใหม่
|
|
|
|
```typescript
|
|
// File: backend/src/modules/ai/prompts/ai-prompts.entity.ts (มีอยู่แล้ว)
|
|
|
|
import {
|
|
Entity,
|
|
PrimaryGeneratedColumn,
|
|
Column,
|
|
CreateDateColumn,
|
|
VersionColumn,
|
|
} from 'typeorm';
|
|
import { Exclude } from 'class-transformer';
|
|
|
|
@Entity('ai_prompts')
|
|
export class AiPrompt {
|
|
@PrimaryGeneratedColumn()
|
|
@Exclude() // ADR-019: INT PK ไม่ expose ใน API
|
|
id!: number;
|
|
|
|
@Column({ name: 'public_id', type: 'uuid', unique: true })
|
|
publicId!: string;
|
|
|
|
@Column({ name: 'prompt_type', length: 50 })
|
|
promptType!: string; // 'ocr_system' | 'ocr_extraction' | 'rag_query_prompt' | 'rag_prep_prompt' | 'classification_prompt'
|
|
|
|
@Column({ name: 'version_number' })
|
|
versionNumber!: number;
|
|
|
|
@Column({ type: 'text' })
|
|
template!: string;
|
|
|
|
@Column({ name: 'field_schema', type: 'json', nullable: true })
|
|
fieldSchema!: Record<string, unknown> | null;
|
|
|
|
@Column({ name: 'context_config', type: 'json', nullable: true })
|
|
contextConfig!: Record<string, unknown> | null;
|
|
|
|
@Column({ name: 'is_active', type: 'tinyint', width: 1, default: 0 })
|
|
isActive!: boolean;
|
|
|
|
@Column({ name: 'test_result_json', type: 'json', nullable: true })
|
|
testResultJson!: Record<string, unknown> | null;
|
|
|
|
@Column({ name: 'manual_note', type: 'text', nullable: true })
|
|
manualNote!: string | null;
|
|
|
|
@Column({ name: 'last_tested_at', type: 'timestamp', nullable: true })
|
|
lastTestedAt!: Date | null;
|
|
|
|
@Column({ name: 'activated_at', type: 'timestamp', nullable: true })
|
|
activatedAt!: Date | null;
|
|
|
|
@Column({ name: 'created_by' })
|
|
@Exclude() // FK ไม่ expose โดยตรง
|
|
createdBy!: number;
|
|
|
|
@CreateDateColumn({ name: 'created_at' })
|
|
createdAt!: Date;
|
|
|
|
@VersionColumn({ name: 'version' })
|
|
version!: number; // optimistic locking
|
|
}
|
|
```
|
|
|
|
### Validation Rules
|
|
|
|
| Prompt Type | Required Placeholders | Validation |
|
|
|-------------|----------------------|------------|
|
|
| `ocr_system` | None | Free-form system prompt |
|
|
| `ocr_extraction` | `{{ocr_text}}` | Must contain at least this placeholder |
|
|
| `ocr_extraction` | `{{master_data_context}}` | Optional - does NOT block save if absent |
|
|
| `rag_prep_prompt` | `{{text}}` | Must contain `{{text}}` placeholder for chunking input |
|
|
|
|
### State Transitions
|
|
|
|
```
|
|
[DRAFT] → [ACTIVE] → [INACTIVE]
|
|
↓ ↓
|
|
[DELETED] [NEW_VERSION]
|
|
```
|
|
|
|
- **DRAFT**: สร้างใหม่, ยังไม่ active
|
|
- **ACTIVE**: กำลังใช้งาน (is_active = true)
|
|
- **INACTIVE**: เคย active แต่ถูกแทนที่ด้วย version ใหม่
|
|
- **NEW_VERSION**: สร้าง version ใหม่จาก existing prompt
|
|
|
|
### Relationships
|
|
|
|
```mermaid
|
|
ai_prompts ||--o{ ai_jobs : "used_by"
|
|
ai_prompts ||--|| users : "created_by"
|
|
```
|
|
|
|
- **ai_jobs**: Reference prompt ที่ใช้ในการทำ OCR/Extraction
|
|
- **users**: Admin ที่สร้าง prompt version
|
|
|
|
### Query Patterns
|
|
|
|
```typescript
|
|
// 1. Get active prompt for a type
|
|
const activePrompt = await repo.findOne({
|
|
where: { promptType: 'ocr_system', isActive: true }
|
|
});
|
|
|
|
// 2. Get version history for a prompt type
|
|
const versions = await repo.find({
|
|
where: { promptType: 'ocr_extraction' },
|
|
order: { versionNumber: 'DESC' }
|
|
});
|
|
|
|
// 3. การ activate ปัจจุบัน (ของจริง) ใช้ PESSIMISTIC lock ใน transaction
|
|
// @VersionColumn มีไว้ดักการแก้ไขซ้อนตอน save แต่ activate() ไม่รับ expectedVersion
|
|
const promptToActivate = await queryRunner.manager.findOne(AiPrompt, {
|
|
where: { promptType, versionNumber },
|
|
lock: { mode: 'pessimistic_write' },
|
|
});
|
|
```
|
|
|
|
> **หมายเหตุ optimistic vs pessimistic**: research.md เสนอ optimistic locking (`expectedVersion` + HTTP 409) แต่ `activate()` ของจริงใช้ `pessimistic_write`. ถ้าจะทำ flow 409 ตาม spec ต้องแก้ signature ของ `activate()` ให้รับ `expectedVersion` และเทียบกับ `version` ก่อน save
|
|
|
|
### SQL Delta Script (ADR-009)
|
|
|
|
```sql
|
|
-- Delta for this feature
|
|
-- File: specs/03-Data-and-Storage/deltas/2026-06-17-seed-ocr-system-prompt.sql
|
|
|
|
-- version column มีอยู่แล้วจาก 2026-06-15-fix-ai-prompts-columns.sql — บรรทัดนี้ idempotent เผื่อ env เก่า
|
|
ALTER TABLE ai_prompts ADD COLUMN IF NOT EXISTS `version` INT NOT NULL DEFAULT 1;
|
|
|
|
-- Seed default OCR system prompt (ถ้ายังไม่มี active ของ type นี้)
|
|
-- ใช้ created_by INT FK → users(user_id) และ username='superadmin' ตาม pattern ของ delta เดิม
|
|
INSERT INTO ai_prompts (
|
|
public_id, prompt_type, version_number, template,
|
|
context_config, is_active, activated_at, created_by
|
|
)
|
|
SELECT
|
|
UUID(),
|
|
'ocr_system',
|
|
1,
|
|
'Extract all text from this PDF page accurately.',
|
|
'{"temperature": 0.1, "topP": 0.6}',
|
|
1,
|
|
CURRENT_TIMESTAMP,
|
|
(SELECT user_id FROM users WHERE username = 'superadmin' LIMIT 1)
|
|
WHERE NOT EXISTS (
|
|
SELECT 1 FROM ai_prompts WHERE prompt_type = 'ocr_system' AND is_active = 1
|
|
);
|
|
```
|