SGMP DB 기반 게임 범위 Resolver (#731)

목표

복수 게임이 포함된 데이터 질문에서 애플리케이션 코드나 에이전트 지시문에 게임명, prefix, 테이블명을 넣지 않는다. DB가 제공하는 게임 범위 뷰를 먼저 조회하고, 조회 가능으로 판정된 게임에만 기존 Few-shot NL2SQL MCP를 호출한다.

범위와 원칙

기존 oracle.select_ai.smilegate_fewshot_nl2sql은 예제 검색, SQL 생성, 읽기 전용 실행을 담당하는 worker로 유지한다.
새 game_scope_resolve MCP는 SQL을 생성하거나 실행하지 않는다.
공통 백오피스는 환경변수로 지정된 DB view 이름과 MCP tool 이름만 안다.
게임명, alias, GAME_ID, GAME_PREFIX, 대상 object는 DB view의 데이터로만 결정한다.
지원 여부는 대상 날짜의 행 수가 아니라, 현재 승인된 조회 object가 존재하는지로 판정한다. 데이터가 0건인 날도 정상 조회 범위다.

DB 공통 계약

고객 DB는 환경변수 BACKOFFICE_GAME_SCOPE_VIEW로 지정된 view를 제공한다. view는 아래 별칭(column alias)을 반환한다.

Column	의미
`GAME_KEY`	내부 게임 식별자
`PROFILE_NAME`	승인 object list를 판정한 Select AI profile
`DISPLAY_NAME`	화면 표시용 정식 게임명
`GAME_ALIAS`	질문에서 찾을 게임명 또는 별칭
`QUERY_ALLOWED_YN`	승인된 조회 object 존재 여부 (`Y`/`N`)
`REASON_CODE`	미지원 또는 보류 사유 코드
`ALIAS_PRIORITY`	동일/중첩 alias 정렬 우선순위
`SCOPE_VERSION`	object list 변경 시 함께 갱신되는 버전

Smilegate view는 전체 게임 마스터와 alias를 기준으로 하고, 현재 Select AI profile별 승인 object list와 실제 object 존재 여부를 조합해 QUERY_ALLOWED_YN을 계산한다. 따라서 등록 게임이지만 현재 조회 object가 없는 게임도 N으로 반환된다.

MCP와 ReAct 계약

포털 ReAct는 게임 데이터 질의 전에 game_scope_resolve(question)를 호출한다.
resolver는 질문 문자열과 GAME_ALIAS를 정규화해 포함 관계를 찾고, 우선순위와 alias 길이로 중복을 제거한다. 동일 우선순위의 복수 게임은 AMBIGUOUS로 반환한다.
QUERY_ALLOWED_YN=Y인 scope에는 서명·만료된 opaque scopeToken과 worker tool 이름을 반환한다.
ReAct는 nextAction=CALL_WORKER인 항목만 Few-shot NL2SQL에 전달한다. UNSUPPORTED와 AMBIGUOUS는 SQL 실행 없이 결과에 표시한다.
Few-shot worker는 scope token을 검증하고, token에 담긴 DB scope로만 prompt를 보강한다.

검증

view가 지원 게임과 object list 미연결 게임을 각각 반환하는지 확인한다.
resolver MCP의 결과에 구체 게임/테이블 하드코딩이 없는지 확인한다.
STD-06에서 미지원 게임은 worker가 호출되지 않고, 지원 게임 결과에는 few-shot 예제, 생성 SQL, 실행 결과가 포함되는지 확인한다.
기존 단일 게임 Few-shot NL2SQL 및 미게임명 거절 guardrail 회귀를 확인한다.

논리 조인 메타데이터

COMN_GAME_ALIAS_BAS는 하나의 게임에 여러 alias 행을 갖기 때문에 GAME_ID가 유일키가 아니다. 따라서 공통 transaction table의 GAME_ID에 물리 FK를 추가하지 않는다. 대신 78_sgmp_game_alias_logical_joins.sql이 fact table에 GAME_ALIAS_JOIN annotation을 추가한다. 이 annotation은 게임명 필터에서 EXISTS 또는 DISTINCT GAME_ID alias subquery를 사용하고, alias 원본을 직접 조인해 집계 행을 늘리지 않도록 설명한다. Prefix 전용 테이블은 가짜 FK 없이 기존 alias/prefix 소유 범위 annotation을 유지한다.

보류 항목

전체 게임 마스터에 미지원 게임이 없다면 DB만으로 그 이름을 게임으로 식별할 수 없다. 이 경우 고객 원천 게임 마스터를 view에 연결하는 작업이 선행되어야 하며, 모델 추측으로 보완하지 않는다.