vpd-permission-poc/docs/design/618-structured-data-browser/README.md

설계서: 정형 데이터 원장 조회 (#618)

상태: Implemented · QA passed · deployed 작성: [AI] Architect · 최종수정: 2026-07-07 추적성 — Redmine: #618 · 관련 ADR: 없음 · 구현 파일: StructuredDataController, StructuredDataService, structured-data.html · 테스트: StructuredDataServiceTest, GuidedFlowTemplateTest

1. 목적 (Why)

VPD 권한 운영자가 KBAIPOC의 정형 보험 원장 데이터를 별도 SQL 도구 없이 빠르게 확인할 수 있게 한다.

2. 범위 (Scope)

• 포함: POC_2의 고객·상품·계약·담보·청구·외부보유·이해관계자 7개 테이블 선택, 컬럼명, 최대 50건 읽기 전용 미리보기.
• 제외 (out of scope): 임의 SQL 실행, 데이터 수정·삭제, VPD 정책 자동 생성, RAG/약관/백업·시스템 테이블 표시.

3. 인수조건 (Acceptance Criteria)

• 연동 도구 메뉴에서 정형 데이터 조회 화면으로 이동할 수 있다.
• 지정된 7개 테이블만 선택할 수 있다.
• 선택한 테이블의 컬럼 순서와 최대 50건의 행을 표시한다.
• 허용 목록 밖의 table 파라미터는 SQL 문자열에 포함되지 않고 거부된다.
• 데이터가 없거나 DB 조회가 실패해도 안전한 안내를 표시한다.

4. 컨텍스트 & 제약

• 데이터 owner는 현재 KBAIPOC의 POC_2로 고정한다.
• 백오피스는 관리자용 읽기 화면이므로 페이지를 인증 뒤에만 제공한다.
• 고객 식별 정보는 현 POC의 RRN_MASKED처럼 이미 마스킹된 컬럼만 사용한다. 운영 데이터에 적용하기 전에는 별도 VPD/마스킹 정책을 연결한다.

5. 아키텍처 개요

브라우저 GET /structured-data?table=customers
        ↓
StructuredDataController
        ↓
StructuredDataService (7개 고정 allowlist)
        ↓
JdbcTemplate → POC_2.KB_CUSTOMERS (ROWNUM <= 50)
        ↓
Thymeleaf 표 미리보기

사용자 입력은 allowlist key 선택에만 쓰고, DB owner·테이블명은 서버 상수에서만 가져온다. JDBC I/O는 서비스에 두고, 테이블 카탈로그 검증은 순수 메서드로 분리한다.

6. 데이터 모델

key	DB 테이블	업무명
customers	KB_CUSTOMERS	고객원장 / 고객 기본정보
products	KB_PRODUCTS	상품원장 / 보험상품 마스터
contracts	KB_CONTRACTS	계약원장 / 보험계약 정보
coverages	KB_COVERAGES	담보원장 / 보장·특약 정보
claims	KB_CLAIMS	청구원장 / 보험금 청구·지급 정보
external-holdings	KB_EXTERNAL_HOLDINGS	외부보유정보 원장 / 타사·외부 가입·보유 정보
stakeholders	KB_STAKEHOLDERS	이해관계자 원장 / 역할·담당자 매핑

7. 함수 명세 (Function Specs)

함수	책임	입력	출력	에러/실패	복잡?
requireTable	allowlist key를 테이블 정의로 해석	key	table definition	알 수 없는 key 거부	단순
preview	컬럼과 제한된 행을 조회	key	preview view	DB 접근 오류를 안전한 메시지로 변환	단순

8. 흐름 / 알고리즘

1. 기본값으로 고객원장을 선택한다.
2. 요청 key가 7개 allowlist에 있는지 검증한다.
3. ALL_TAB_COLUMNS에서 표시 컬럼 순서를 읽는다.
4. 고정 owner/table로 최대 50건을 조회한다.
5. 컬럼 헤더와 행을 표로 렌더링한다.

9. 엣지케이스 & 에러 처리

• 알 수 없는 key: SQL을 만들지 않고 안내 메시지를 표시한다.
• 대상 테이블이 없거나 권한이 없음: DB 오류 원문 대신 대상/권한 점검 안내를 표시한다.
• 0건: 빈 결과 안내와 함께 컬럼 헤더는 유지한다.

10. 테스트 계획

• 카탈로그가 정확히 7개 key와 테이블을 포함하는지 단위 테스트한다.
• 허용 목록 밖 key를 거부하는지 단위 테스트한다.
• 템플릿·메뉴가 정형 데이터 조회 경로와 읽기 전용 안내를 포함하는지 정적 템플릿 테스트한다.

11. 리스크 & 대안 검토

• 관리자 JDBC로 직접 조회하므로 운영 개인정보를 그대로 보여줄 수 있다. 따라서 임의 SQL과 RAG/백업 테이블 노출을 제외하고, 현 POC에서는 마스킹된 고객 식별자만 있는 7개 원장으로 범위를 제한한다.
• 최종 사용자별 행 보기가 필요하면 이 페이지가 아니라 ORDS + VPD 검증 경로를 사용한다.

12. 미해결 질문 (Open Questions)

• 운영 전환 시 POC_2 owner를 환경 설정으로 분리할지 결정한다.
• 행 단위 VPD 적용 결과를 이 화면에서 볼 필요가 생기면 검증 세션을 필수 입력으로 하는 별도 화면으로 분리한다.

13. 구현·배포 검증

• mvn test 통과: allowlist 7개 테이블과 비허용 key 거부 단위 테스트, 메뉴·도움말 템플릿 검증을 포함한다.
• VM SQLcl에서 백오피스 계정으로 POC_2.KB_CUSTOMERS 110건을 읽을 수 있음을 확인했다.
• vpd-backoffice.service에 새 JAR를 배포한 뒤 인증된 /structured-data?table=customers 응답에서 KB_CUSTOMERS, CUST_ID, 고객원장 렌더링을 확인했다.