refs #739: add Smilegate MCP operations guide

docs/runbooks/smilegate-mcp-operations.md

@@ -0,0 +1,63 @@
+# Smilegate MCP·Select AI 운영 가이드
+
+## 1. 목적과 공통 문서 경계
+
+이 문서는 Smilegate 게임 데이터 질의에만 적용한다. MCP, VPD, Data Redaction, DDS의
+공통 설치·보안 원칙은 `main`의 공통 운영 가이드를 따른다. 여기서는 게임 식별, DB
+실행 계획, Few-shot, 고객 질의 검증처럼 Smilegate에만 필요한 규칙을 정의한다.
+
+## 2. 기본 질의 흐름
+
+```text
+질문
+ → oracle.select_ai.game_query_plan
+ → DB가 게임·데이터 가능 여부·executionTasks 결정
+ → QUERY task만 smilegate_fewshot_nl2sql 호출
+ → 승인·검증 예제 검색
+ → SHOWSQL 생성 · SELECT/WITH 검증 · read-only 실행
+ → generatedSql + items + rowCount를 Portal에 반환
+```
+
+`game_query_plan`은 항상 첫 호출이다. Portal과 Java는 게임명, prefix, 물리 테이블,
+지표 필터를 하드코딩하거나 보정하지 않는다.
+
+## 3. 운영자가 관리하는 DB 객체
+
+| 목적 | 주요 객체/스크립트 | 운영 원칙 |
+| --- | --- | --- |
+| 게임 식별 | `SG_GAME_CATALOG`, `80_sg_game_mention_extract.sql`, `81_sg_game_query_plan.sql` | 별칭·지원 여부·대상 테이블을 DB에서 결정 |
+| QA/Few-shot | `SG_QA_VECTOR_EXAMPLE`, `75_sgmp_qa_vector_retrieval.sql`, `140_sgmp_hybrid_fewshot_reranking.sql` | 승인·검증 예제만 검색 |
+| 메타데이터 | comment/annotation API, 게임별 View·테이블 정의 | Select AI가 객체 역할과 조인을 이해하도록 관리 |
+| 고객 기준 판정 | `129`~`142` SQL 및 QA 이력 | 값뿐 아니라 SQL 의미를 확인 |
+
+## 4. Few-shot 승인과 리타이어
+
+- `APPROVED` 및 `VERIFIED` 예제만 후보가 된다.
+- `RETIRED` 예제는 질문이 같아도 검색하지 않는다.
+- 예제 SQL은 런타임에 직접 실행하지 않는다. SQL 구조·필수 필터·집계 정의를 새 SHOWSQL 생성의 참고 자료로만 사용한다.
+- 실패 원인은 데이터 부재, 게임 식별, 메타데이터, 지표 정의, 예제 부족으로 분류한다.
+- 수정은 Java의 예외 목록이 아니라 DB의 example 상태·설명·SQL template·평가 기준에 반영한다.
+
+## 5. 고객 질의 검증 순서
+
+1. 게임이 `SUPPORTED`이며 데이터 대상이 있는지 확인한다.
+2. `executionTasks`가 대상별로 생성됐는지 확인한다.
+3. `generatedSql`이 날짜·지표·필터·집계 기준을 보존하는지 확인한다.
+4. `items`, `rowCount`, 빈 결과와 SQL 오류를 구분한다.
+5. 결과값이 같아도 기준 SQL의 필수 조건이 다르면 QA 실패로 처리한다.
+6. 실패 사례를 검토한 뒤 필요한 경우에만 새로운 승인 Few-shot을 등록한다.
+
+## 6. 자주 보는 장애
+
+| 증상 | 확인 순서 |
+| --- | --- |
+| 게임 미식별 | 별칭 카탈로그, 거리 임계값, `game_query_plan` 결과 |
+| SQL 미실행 | `REPORT_UNAVAILABLE` 사유와 data eligibility |
+| Few-shot 미적용 | 승인/검증/리타이어 상태와 hybrid score |
+| 잘못된 집계 | 고객 기준 SQL, annotation, 예제 설명 |
+| 읽기 전용 거절 | SHOWSQL 원문과 SQL validator 결과 |
+
+## 7. 관련 자료
+
+- [현재 MCP 도구 운영 안내](../smilegate-mcp-current-operation-guide.md)
+- [Few-shot NL2SQL MCP 설계](../design/735-sgmp-fewshot-nl2sql-mcp/README.md)

docs/smilegate-mcp-current-operation-guide.md

@@ -1,5 +1,8 @@
 # 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`을 호출한다.