[Developer] #571 show VPD context in SQL trace

docs/design/571-vpd-context-trace/README.md

@@ -0,0 +1,47 @@
+# 설계서: 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 앞에 표시해 다음 흐름을 한 화면에서 증명한다.
+
+```text
+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가 같은 결과 카드에 표시되는지 확인한다.