설계서: SQL trace의 set_vpd_context 사용자 컨텍스트 표시 (#571)

상태: Approved 작성: [AI] Architect · 최종수정: 2026-06-30 추적성 — Redmine: #571 · 선행 기능: #567, #570 · 구현 파일: probe-result.html, TokenContextView, ProbeController · 테스트: GuidedFlowTemplateTest, mvn test

1. 목적

권한 적용 SQL trace에서 최종 predicate만 보여 사용자와 predicate의 연결이 끊겨 보이는 문제를 해결한다. set_vpd_context가 설정한 CB_AGENT_CTX.USER_ID와 백오피스가 해석한 사용자·역할·그룹을 predicate 앞에 표시해 다음 흐름을 한 화면에서 증명한다.

Bearer Token
  → set_vpd_context
  → CB_AGENT_CTX.USER_ID = 사용자 ID
  → 사용자/역할/그룹 권한 규칙 조회
  → VPD predicate
  → effective SQL

2. 설계 원칙

SQL에 AND USER_ID = ... 같은 가짜 조건을 추가하지 않는다. 벡터 검색 대상에는 USER_ID 컬럼이 없고, 실제 VPD 함수는 사용자 context로 권한 규칙을 계산한 뒤 대상 데이터의 TECH_TAG predicate를 반환한다.
context는 실제 토큰에서 해석된 TokenContextView를 사용한다. Bearer 원문은 표시하지 않는다.
USER_ID, 사용자명, 직접 역할, 그룹, 상속 역할은 trace 영역의 “set_vpd_context 사용자 컨텍스트” 카드에 표시한다.
아래 VPD predicate는 바로 위 context에서 계산된 결과라는 설명을 명시한다.

3. 인수조건

토큰 적용 후 SQL에 CB_AGENT_CTX.USER_ID와 사용자명이 표시된다.
직접 역할·그룹·상속 역할이 context 카드에서 확인된다.
context → VPD가 추가한 WHERE 조건 → 권한 적용 SQL 순서가 화면에 보인다.
SQL 본문에 실제 존재하지 않는 USER_ID 조건을 삽입하지 않는다.
invalid/inactive token처럼 context가 없을 때는 기존 “토큰에서 사용자를 찾지 못함” 안내를 유지한다.
Bearer 원문과 임베딩 숫자는 context 카드에 표시하지 않는다.
전체 Maven 테스트와 실제 vector probe smoke가 통과한다.

4. 화면 계약

TokenContextView.userId()를 CB_AGENT_CTX.USER_ID 값으로 표시하고, username, directRoles, groups, inheritedRoles를 사람이 읽을 수 있는 label로 표시한다. predicate와 effective SQL은 기존 ProbeResult 필드를 그대로 사용한다.

5. 검증

템플릿 테스트에서 set_vpd_context 사용자 컨텍스트, CB_AGENT_CTX.USER_ID, VPD가 추가한 WHERE 조건, 권한 적용 SQL을 확인한다.
mvn test.
vector /probe에서 agent_all 또는 선택 사용자의 ID/역할과 TAG predicate가 같은 결과 카드에 표시되는지 확인한다.