# Smilegate Data & AI PoC — 현재 MCP 도구 운영 안내

> 전체 운영 절차는 [Smilegate MCP·Select AI 운영 가이드](runbooks/smilegate-mcp-operations.md)를,
> 고객사와 무관한 보안·VPD·Data Redaction 기준은 `main`의 공통 운영 문서를 따른다.

## 1. 현재 기본 실행 경로

모든 게임 데이터 질문은 먼저 `oracle.select_ai.game_query_plan`을 호출한다.

```text
일반 데이터 분석 질문
game_query_plan → smilegate_fewshot_nl2sql

게임별·일반 분석 질문
game_query_plan → executionTasks → smilegate_fewshot_nl2sql
```

`game_query_plan`은 게임 카탈로그, 별칭, 벡터 검색 결과를 사용하여 질의 범위를 `NONE`,
`SINGLE`, `MULTI`, `ALL` 중 하나로 판정하고 `executionTasks`를 발급한다. 다음 worker에는
원 질문을 보존한 DB 작업 인자와 `GAME QUERY REFERENCE`를 전달한다. Portal은 이를 보정하지
않고 task 종료 상태를 합산한다.

## 2. 기본 실행 MCP 도구

### `oracle.select_ai.game_query_plan`

- 모든 게임 데이터 질의의 필수 첫 단계다.
- OCI GenAI Chat으로 질문에서 게임명 후보를 식별하고 게임 카탈로그 벡터 검색 결과를 검증한다.
- `targetType`, `supportedGames`, `dataEligibleTargets`, 미매칭 대상을 반환한다.
- 게임명·prefix·물리 테이블을 Java나 포털 코드에서 하드코딩하지 않는다.

### `oracle.select_ai.smilegate_fewshot_nl2sql`

- AU 외 일반 분석 질의의 주 실행 도구다.
- 현재 질문으로 QA 벡터 저장소에서 승인·검증된 유사 Few-shot 예제를 찾는다.
- 선택된 Few-shot 예제의 질문·승인 SQL·논리 객체 역할을 현재 질문 및 `queryPlan`과 함께 Select AI 프롬프트에 추가한다.
- ADB `DBMS_CLOUD_AI.GENERATE(..., 'showsql')`로 SQL을 생성한다.
- 생성 SQL을 읽기 전용으로 검증한 후 실행한다.
- Few-shot 근거, 생성 SQL, 실행 결과, 행 수를 반환한다.
- 예제 승인·리타이어·유사도 기준은 DB가 관리한다. Java/Portal은 지표 조건이나
  검색 결과를 보정하지 않는다.

### `oracle.select_ai.game_daily_au_lookup`

- 고정 정의 AU를 별도로 점검할 때 쓰는 전용 도구다. 고객 질의의 기본 실행 경로는
  `executionTasks`가 지정한 worker이며, 일반적으로 `smilegate_fewshot_nl2sql`이다.
- 입력은 `queryPlan`과 선택적인 `baseDate(YYYY-MM-DD)`다.
- `queryPlan`의 게임 키를 `SG_GAME_CATALOG`에서 다시 검증하고 `USER_MASTER_OBJECT_NAME`을 동적으로 선택한다.
- 선택된 사용자 마스터 객체에 대해 아래 정의로 AU를 집계한다.

```sql
SELECT COUNT(DISTINCT GUID) AS AU_COUNT
FROM <catalog_user_master_object>
WHERE BASE_DT = :baseDate
  AND AU_FLAG = 1
  AND EXPT_USER_YN = 'N'
```

- 게임명·별칭·prefix·물리 테이블명을 입력값이나 코드에서 직접 사용하지 않는다.
- `SINGLE`, `MULTI`, `ALL` 계획의 각 대상에 대해 결과를 반환한다.

## 3. 등록돼 있으나 기본 경로에서 직접 실행하지 않는 도구

### `oracle.select_ai.qa_vector_search`

- 유사 질문과 승인 SQL 예제를 직접 확인하는 관리자·점검용 도구다.
- 일반 질의에서는 `smilegate_fewshot_nl2sql`이 내부적으로 Few-shot 검색을 수행하므로 별도 호출하지 않는다.

### `oracle.select_ai.qa_vector_store`

- 검토 완료한 질문·읽기 전용 SQL·검토 메모를 Few-shot 벡터 지식으로 저장하는 관리자 도구다.
- 사용자 질의 실행 중에는 호출하지 않는다.

### `oracle.select_ai.game_catalog_resolve`

- 게임명 후보의 벡터 검색 결과를 독립적으로 점검하는 진단 도구다.
- 정상 흐름에서는 `game_query_plan` 내부의 게임 식별 과정이 이 역할을 수행한다.

### `oracle.select_ai.game_scope_resolve`

- 과거 게임 범위와 별칭 매칭을 점검하기 위한 보조 도구다.
- 현재 기본 판정 기준은 `game_query_plan`이므로 정상 경로에는 넣지 않는다.

### `oracle.select_ai.smilegate_game_text2sql`

- Few-shot을 붙이지 않은 기본 Select AI 결과를 비교·점검하는 보조 Text2SQL 도구다.
- 고객용 기본 분석 경로는 `smilegate_fewshot_nl2sql`이다.

### `oracle.select_ai.smilegate_game_showprompt`

- SQL 생성에 전달된 최종 Select AI 프롬프트를 확인하는 진단 도구다.
- 테이블 comment, 컬럼 annotation, 제약조건, 게임 범위 계획, Few-shot 근거가 프롬프트에 반영됐는지 점검한다.
- SQL을 실행하지 않는다.

### `oracle.select_ai.fewshot_preflight`

- Few-shot 후보의 적합성을 별도로 확인할 때 사용하는 점검 도구다.
- 현재 `smilegate.cloud-handson.com` 포털의 기본 질문 allowlist와 기본 실행 경로에는 직접 넣지 않는다.

## 4. 실제 검증 결과

| 항목 | 확인 결과 |
|---|---|
| 질문 | 카제나의 2026-07-15 AU |
| 게임 범위 | `SINGLE / SUPPORTED` |
| 게임 키 | `STOVE_CHAOSZERO` |
| 카탈로그 선택 객체 | `CZN_COMN_USER_MST` |
| AU 실행 상태 | `GAME_AU_LOOKUP / READY` |
| 기준일 | `2026-07-15` |
| 반환 AU | `0` |

이 검증에서 테이블명은 코드에 고정하지 않았으며, 게임 계획 결과와 `SG_GAME_CATALOG` 메타데이터를 통해 선택됐다.

## 5. 운영 원칙

1. 게임 범위 판단과 실행 작업 생성은 항상 `game_query_plan`이 담당한다.
2. Portal은 DB task를 실행·합성하며, 질문·SQL·결과를 보정하지 않는다.
3. 분석성 질의는 승인·검증된 Few-shot 기반 Select AI로 처리한다.
4. `RETIRED` 예제는 검색하지 않으며, 승인/리타이어는 DB에 저장한다.
5. 정답지 SQL을 런타임에 실행하지 않는다. Select AI가 새로 만든 읽기 전용 SQL만 실행한다.
6. 문제 발생 시 SHOWPROMPT, 생성 SQL, 실행 결과, 판정 이력을 근거로 metadata·Few-shot을 보완한다.