refs #740: add Few-shot management tab

docs/design/740-smilegate-fewshot-management-tab/README.md

@@ -0,0 +1,30 @@
+# Smilegate 질문별 Few-shot 관리 탭 (#740)
+
+## 프로젝트 개요
+
+Smilegate Portal은 고객 질답 벤치마크를 실행하고, Oracle Select AI MCP가 승인된 few-shot 예제를 검색해 읽기 전용 SQL을 생성·실행하는 서비스다. 고객 질문, 실행 이력, few-shot 예제는 Oracle ADB의 `SG_AI_QA_QUESTION`, `SG_AI_QA_ANSWER`, `SG_QA_VECTOR_EXAMPLE`에 보관한다.
+
+## 목표
+
+Portal에 **Few-shot 관리** 탭을 추가해 운영자가 질문별 few-shot 내용을 확인하고 수정할 수 있게 한다.
+
+## 설계
+
+- 질문 목록은 기존 고객 QA 기준 파일을 사용하고, 예제는 `source_type=CUSTOMER_QA_BENCHMARK` 및 `source_case_id=질문 코드`로 연결한다.
+- 탭은 질문, 예제 SQL, 설명, 참조 종류, 적용 게임 범위, 논리 객체 역할, 검토 메모, 검색 상태를 표시한다.
+- 저장은 예제 본문과 메타데이터를 갱신하고 embedding 입력과 vector embedding을 함께 재생성한다. 따라서 수정 후 벡터 검색이 수정 전 내용과 어긋나지 않는다.
+- 저장 시 상태를 자동 승인하지 않는다. `APPROVED`는 기존 승인 정책에 맞는 운영자 선택으로만 유지·변경하며, `RETIRED` 예제는 검색에서 제외된다.
+- 물리 게임 테이블명은 예제의 정책 값으로 넣지 않고 논리 `object_role`만 보관한다. 게임 범위는 현재 query plan이 권위 있는 원천이다.
+
+## 완료 기준
+
+1. 인증된 Portal에서 기존 아키텍처·시나리오와 함께 Few-shot 관리 탭을 볼 수 있다.
+2. 질문을 고르면 해당 few-shot 예제의 전체 내용을 확인할 수 있다.
+3. 유효한 값으로 수정 후 저장하면 다시 열었을 때 저장 내용이 보인다.
+4. Python 단위 테스트가 저장 입력 검증과 DB 갱신 SQL을 확인한다.
+
+## 검증 계획
+
+- `python -m pytest`로 Portal 테스트를 실행한다.
+- Python compile 검사로 Streamlit 모듈 구문을 확인한다.
+- DB 접속 설정이 있는 환경에서는 질문별 예제 조회와 수정 후 재조회로 검증한다.