# AI 기반 화면 자동 생성 시스템 설계서

## 1. 개요

### 1.1 목표

사용자가 자연어로 "자재입고페이지 만들어줘"라고 요청하면, AI가 자동으로 완성된 화면과 워크플로우를 생성

### 1.2 핵심 가치

- **제로 코딩**: 대화만으로 화면 생성
- **워크플로우 포함**: 저장 시 재고 업데이트 등 자동 설정
- **기존 시스템 활용**: 새 인프라 최소화, 기존 API 재사용

### 1.3 예상 시나리오

```
사용자: "자재입고페이지 만들어줘"

AI: "입고관리 화면 41개를 분석했습니다.

     ✅ 자동 적용 (90%+ 사용)
     - 레이아웃: 분할화면 (좌: 목록, 우: 상세)
     - 필수 필드: 입고번호, 입고일자, 품목코드, 수량

     💡 추천 기능 (60% 사용)
     - 저장 시 재고 자동 증가
     [추가하기]

     ➕ 선택 필드
     [ ] 창고 (68%)  [ ] 공급업체 (61%)

     [화면 생성하기]"

사용자: "재고 연동 추가하고, 창고 필드도 넣어줘"

AI: "화면을 생성했습니다.
     - 화면명: 자재 입고관리
     - 레이아웃: 분할화면
     - 필드: 입고번호, 입고일자, 품목, 수량, 창고
     - 워크플로우: 저장 시 inventory_stock +qty
     
     [미리보기] [메뉴에 추가]"
```

---

## 2. 시스템 아키텍처

```
 ┌───────────────────────────────────────────────────────────────┬───────────────────────────────┐
│                     신규 개발 (AI 담당)                          │ 기존 드래그앤드랍 시스템          │
│  ┌─────────────┐     ┌──────────────────────────────┐         │  ┌─────────────────────┐    │
│  │  Chat UI    │────▶│     AI 서비스               │           │   │ D&D UI Builder      │    │
│  └─────────────┘     │ • LLM 호출 (Claude/GPT)     │           │   └─────────┬──────────┘    │
│                      │ • 패턴 분석 + RAG 검색       │             │            │               │
│                      │ • JSON 생성                  │           │            ▼               │
│                      └──────────────┬──────────────┘          │  ┌─────────────────────┐    │
└─────────────────────────────────────┼─────────────────────---──┴─┼─────────────────────┬─────┘
                                      │ 기존 API 호출                │ 기존 API 호출          │
                                      ▼                            ┼─────────────────────┘
                                                                   ▼
┌-------------------------------------------------------------------------------┐
│                          기존 시스템 (vexplor)                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                           │
│  │ Screen API  │  │  Flow API   │  │ Dataflow API│                           │
│  └─────────────┘  └─────────────┘  └─────────────┘                           │
│                           │                                                  │
│                    ┌──────┴──────┐                                           │
│                    │  PostgreSQL │                                           │
│                    └─────────────┘                                           │
└-------------------------------------------------------------------------------┘
```

### 설계 원칙

| 원칙                  | 설명                              |
| --------------------- | --------------------------------- |
| 기존 코드 변경 최소화 | 기존 백엔드/프론트 수정 없음      |
| 기존 API 재사용       | AI가 기존 API를 "사용자처럼" 호출 |
| RAG 기반 지식 주입    | 필요한 패턴만 동적으로 LLM에 주입 |
| **Assistive AI**      | AI는 결정하지 않고, 사용자의 결정을 돕는다 |

---

## 3. AI가 화면을 "알아서" 만드는 방법

### 3.1 지식 소스

| 데이터          | 테이블                             | 활용                |
| --------------- | ---------------------------------- | ------------------- |
| 기존 화면       | screen_definitions, screen_layouts | 패턴 학습           |
| 테이블 라벨     | table_labels                       | 테이블 검색         |
| 컬럼 라벨       | column_labels                      | 필드→컴포넌트 매핑 |
| 워크플로우 패턴 | workflow_patterns (신규)           | 비즈니스 로직       |

### 3.2 통계 기반 패턴 분석

> **핵심 아이디어**: 사용자들이 이미 만든 화면들을 분석해서 "입고 화면은 보통 이렇게 생겼더라"를 알아내는 것

#### 예시: "입고페이지 만들어줘" 요청 시

**Step 1. 테이블 찾기**

```sql
-- "입고"라는 단어로 table_labels 검색
SELECT table_name, table_label FROM table_labels 
WHERE table_label LIKE '%입고%';

-- 결과: inbound_mng (입고관리)
```

**Step 2. 이 테이블을 쓰는 기존 화면 찾기**

```sql
-- inbound_mng 테이블을 사용하는 화면들 조회
SELECT * FROM screen_definitions 
WHERE table_name = 'inbound_mng';

-- 결과: 41개 화면 발견!
```

**Step 3. 41개 화면의 "공통점" 분석**

레이아웃 통계:

| 레이아웃                         | 개수  | 비율     |
| -------------------------------- | ----- | -------- |
| split-panel (좌: 목록, 우: 상세) | 32개  | **78%**  |
| table-list (목록만)              | 6개   | 15%      |
| form (폼만)                      | 3개   | 7%       |

필드 사용 통계:

| 필드                   | 사용 화면 수 | 비율     |
| ---------------------- | ------------ | -------- |
| inbound_no (입고번호)  | 41개         | **100%** |
| inbound_date (입고일자)| 41개         | **100%** |
| item_code (품목코드)   | 40개         | **98%**  |
| qty (수량)             | 39개         | **95%**  |
| warehouse_code (창고)  | 28개         | 68%      |
| supplier_code (공급업체)| 25개        | 61%      |

**Step 4. 확신도(Confidence)에 따라 다르게 처리**

AI는 통계 결과의 확신도에 따라 행동을 다르게 합니다:

| 확신도 | 기준 | AI 행동 | 예시 |
| ------ | ---- | ------- | ---- |
| **높음** | 90%+ | 자동 적용 | 필수 필드(입고번호, 일자) 자동 추가 |
| **중간** | 60~90% | 추천하며 확인 | "분할화면으로 만들까요? (78% 사용)" |
| **낮음** | 60% 미만 | 옵션 나열 | "창고 필드 추가할까요? (68%)" |

```
AI 판단 예시:
- 레이아웃: split-panel (78%) → "분할화면으로 생성합니다"
- 필수 필드: 입고번호, 입고일자 (100%) → 자동 추가
- 워크플로우: 입고→재고 (60%) → "💡 재고 자동 연동 추가할까요?"
- 선택 필드: 창고 (68%) → "추가 필드: [ ] 창고 [ ] 공급업체"
```

**핵심**: 확실한 것은 빠르게 처리하고, 애매한 것은 사용자에게 물어본다.

#### 비유: "맛집 추천 AI"와 같은 원리

| 맛집 추천 AI | 화면 생성 AI |
| ------------ | ------------ |
| "강남에서 점심 뭐 먹지?" | "입고페이지 만들어줘" |
| 강남 식당 1000개 리뷰 분석 | 기존 입고 화면 41개 분석 |
| "70%가 파스타집, 평균 1.5만원" | "78%가 분할화면, 100%가 입고번호 사용" |
| "파스타집 추천드릴까요?" | "분할화면으로 만들까요?" |

### 3.3 RAG 기반 동적 지식 주입 (핵심)

> **문제**: 모든 도메인 지식을 프롬프트에 넣으면 Context Window 초과

> **해결**: 필요한 지식만 검색해서 동적 주입

```
사용자: "입고페이지 만들어줘"
        ↓
1. 키워드 추출: "입고"
        ↓
2. workflow_patterns 검색 → "입고→재고 증가" 패턴 발견
        ↓
3. LLM 프롬프트에 해당 패턴만 주입
        ↓
4. 재고 증가 로직 포함된 화면 생성
```

#### 장점

| 장점          | 설명                               |
| ------------- | ---------------------------------- |
| 토큰 절약     | 관련 패턴 1-2개만 주입             |
| 확장성        | 패턴 1000개여도 프롬프트 길이 동일 |
| 회사별 커스텀 | company_code로 회사별 패턴 적용    |

### 3.4 멀티테넌트 & Fallback 전략

회사마다 테이블명이 다르거나, 신규 회사라 기존 화면이 없을 수 있습니다.

**데이터 검색 우선순위:**

```
1순위: 해당 회사의 기존 화면 (가장 정확)
       ↓ 없거나 부족하면
2순위: 전체 회사의 익명화된 통계 (company_code 제외, 패턴만)
       ↓ 그래도 부족하면
3순위: vexplor 표준 템플릿 (기본 레이아웃 + 필수 필드)
```

**여러 테이블이 검색될 때:**

```
사용자: "입고페이지 만들어줘"

AI: "입고 관련 테이블이 3개 있습니다:
     1. 자재입고관리 (material_inbound)
     2. 제품입고관리 (product_inbound)
     3. 반품입고관리 (return_inbound)
     
     어떤 테이블로 만들까요?"
```

### 3.5 기존 시스템 분석 결과

**발견된 학습 가능 데이터:**

- `transferData` 액션: 14개 (발주→입고, 수주→출고 등)
- 제어관리 프레임워크: `dataflowControlService.ts` 존재
- 입고→재고 규칙: 아직 정의되지 않음 → AI가 생성하면 됨

---

## 4. 개발 범위

### 4.1 AI 담당 (신규)

| 작업                                 | 파일                          | 우선순위     |
| ------------------------------------ | ----------------------------- | ------------ |
| AI 채팅 API                          | `aiRoutes.ts`               | P0           |
| 화면 패턴 분석                       | `screenAnalyzer.ts`         | P0           |
| LLM 호출                             | `llmService.ts`             | P0           |
| **워크플로우 패턴 검색 (RAG)** | `workflowPatternService.ts` | **P0** |
| 채팅 UI                              | `AIChatPanel.tsx`           | P0           |
| **workflow_patterns 테이블**   | DB                            | **P0** |

```typescript
// 패턴 검색 핵심 로직
export async function searchWorkflowPatterns(userIntent: string, companyCode: string) {
  const keywords = extractKeywords(userIntent);
  
  return await query(`
    SELECT * FROM workflow_patterns
    WHERE intent_keywords && $1::text[]
      AND (company_code = $2 OR company_code = '*')
    ORDER BY priority DESC
    LIMIT 3
  `, [keywords, companyCode]);
}
```

### 4.2 vexplor 담당 (기존 보완)

| 작업           | 현재 상태 | 필요 작업           |
| -------------- | --------- | ------------------- |
| 화면 생성 API  | ✅ 존재   | 문서화              |
| 워크플로우 API | ✅ 존재   | 문서화              |
| 제어관리 API   | ✅ 존재   | AI 활용 가능        |
| table_labels   | 부분 존재 | 주요 테이블 한글 라벨 |
| column_labels  | 부분 존재 | web_type 보완       |

#### 4.2.1 table_labels가 필요한 이유

AI가 "입고"라는 단어로 테이블을 찾으려면 한글 라벨이 있어야 합니다.

**현재 상태:**

| table_name | table_label | AI 검색 |
| ---------- | ----------- | ------- |
| inbound_mng | **입고관리** | ✅ "입고" 검색 가능 |
| outbound_mng | **출고관리** | ✅ "출고" 검색 가능 |
| production_record | production_record | ❌ "생산" 검색 불가 |
| purchase_order_master | purchase_order_master | ❌ "발주" 검색 불가 |

**필요 작업**: 주요 업무 테이블에 한글 라벨 추가

```sql
UPDATE table_labels SET table_label = '생산실적' WHERE table_name = 'production_record';
UPDATE table_labels SET table_label = '발주관리' WHERE table_name = 'purchase_order_master';
```

#### 4.2.2 column_labels의 web_type이 필요한 이유

AI가 컬럼을 보고 **어떤 컴포넌트를 생성할지** 결정해야 합니다.

**현재 상태** (inbound_mng):

| column_name | column_label | web_type |
| ----------- | ------------ | -------- |
| inbound_date | 입고일 | **null** |
| inbound_qty | 입고수량 | **null** |
| item_code | 품목코드 | **null** |

**web_type이 null이면?** → AI가 모든 필드를 text-input으로 만들어버림

**web_type이 있으면:**

| column_name | web_type | AI가 생성할 컴포넌트 |
| ----------- | -------- | ------------------- |
| inbound_date | **date** | 📅 날짜 선택기 |
| inbound_qty | **number** | 🔢 숫자 입력 |
| item_code | **entity** | 🔍 품목 검색 팝업 |
| memo | **textarea** | 📝 여러 줄 텍스트 |

**필요 작업**: 주요 테이블 컬럼에 web_type 추가

```sql
UPDATE column_labels SET web_type = 'date' WHERE column_name LIKE '%_date';
UPDATE column_labels SET web_type = 'number' WHERE column_name LIKE '%_qty';
UPDATE column_labels SET web_type = 'entity' WHERE column_name LIKE '%_code' AND column_name != 'company_code';
UPDATE column_labels SET web_type = 'textarea' WHERE column_name = 'memo';
```

---

## 5. 데이터베이스 스키마 (AI 전용)

```sql
-- 핵심: 워크플로우 패턴 (RAG 지식 베이스)
CREATE TABLE workflow_patterns (
    pattern_id SERIAL PRIMARY KEY,
    category VARCHAR(50) NOT NULL,           -- 'inventory', 'sales'
    pattern_name VARCHAR(200) NOT NULL,      -- '입고→재고 증가'
    intent_keywords TEXT[] NOT NULL,         -- ['입고', '자재입고', 'inbound']
    description TEXT,
    source_table_hint VARCHAR(100),          -- 'inbound_mng'
    target_table_hint VARCHAR(100),          -- 'inventory_stock'
    logic_template JSONB NOT NULL,           -- 제어관리 생성 템플릿
    company_code VARCHAR(20) DEFAULT '*',
    priority INTEGER DEFAULT 100,
    is_active BOOLEAN DEFAULT true
);

CREATE INDEX idx_workflow_patterns_keywords ON workflow_patterns USING GIN(intent_keywords);

-- 초기 데이터
INSERT INTO workflow_patterns (category, pattern_name, intent_keywords, description, source_table_hint, target_table_hint, logic_template) VALUES
('inventory', '입고→재고 증가', 
 ARRAY['입고', '구매입고', '자재입고', 'inbound'],
 '입고 저장 시 재고 수량 증가',
 'inbound_mng', 'inventory_stock',
 '{"actionType": "upsert", "operation": "increment", "fieldMappings": [{"source": "item_code", "target": "item_code", "type": "key"}, {"source": "inbound_qty", "target": "qty", "type": "increment"}]}'::jsonb
),
('inventory', '출고→재고 감소', 
 ARRAY['출고', '판매출고', 'outbound'],
 '출고 저장 시 재고 수량 감소',
 'outbound_mng', 'inventory_stock',
 '{"actionType": "update", "operation": "decrement", "fieldMappings": [{"source": "item_code", "target": "item_code", "type": "key"}, {"source": "outbound_qty", "target": "qty", "type": "decrement"}]}'::jsonb
);

-- 동의어 매핑 (P1)
CREATE TABLE keyword_mapping (
    id SERIAL PRIMARY KEY,
    keyword VARCHAR(100) NOT NULL,
    table_name VARCHAR(100) NOT NULL,
    company_code VARCHAR(20) DEFAULT '*'
);

-- AI 대화 이력 (P2)
CREATE TABLE ai_conversations (
    id SERIAL PRIMARY KEY,
    session_id VARCHAR(100) NOT NULL,
    company_code VARCHAR(20) NOT NULL,
    user_id VARCHAR(50) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE ai_messages (
    id SERIAL PRIMARY KEY,
    conversation_id INTEGER REFERENCES ai_conversations(id),
    role VARCHAR(20) NOT NULL,
    content TEXT NOT NULL,
    metadata JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
```

---

## 6. 개발 로드맵

### Phase 1: MVP

**AI:**

- 채팅 UI + LLM 연동
- 화면 패턴 분석
- workflow_patterns 테이블 + RAG 검색

**vexplor:**

- API 스펙 문서화 (screen, flow)
- 주요 테이블 한글 라벨 20개

### Phase 2: 워크플로우

**AI:**

- 자연어 → 워크플로우 변환
- dataflow_diagrams 자동 생성

**vexplor:**

- 워크플로우 API 문서화

### Phase 3: 고도화

- 대화형 수정 ("왼쪽 패널 넓혀줘")
- 멀티턴 컨텍스트
- 사용자 피드백 학습

---

## 7. vexplor 체크리스트

### 즉시 (P0)

- [ ] POST /api/screen/create 스펙
- [ ] POST /api/flow/definitions 스펙
- [ ] 화면 레이아웃 JSON 예시

### 1주 내 (P1)

- [ ] 주요 테이블 20개 한글 라벨
  - inbound_mng, outbound_mng, inventory_stock
  - item_info, customer_mng, supplier_mng
  - sales_order_mng, purchase_order_mng
- [ ] column_labels web_type 보완

---

## 8. 성공 지표

| 지표                 | 목표      |
| -------------------- | --------- |
| 화면 생성 성공률     | 90%+      |
| 평균 생성 시간       | 10초 이내 |
| 수정 없이 사용       | 70%+      |
| 워크플로우 자동 연결 | 80%+      |