[UX] #577 clarify VPD flow and SQL evidence

docs/design/567-ords-vpd-sql-trace/README.md

@@ -148,6 +148,8 @@
 
 Oracle은 VPD의 내부 rewrite 결과를 별도 최종 SQL 문자열로 `V$SQL`에 보관하지 않는다. 따라서 원문 SQL과 실행계획 predicate를 함께 제시하는 것이 실제 실행에 대한 DB 증적이다. `executions`, `rows_processed`, `elapsed_time`, `buffer_gets`는 cursor 누적값이며 단일 HTTP 요청만의 계측값은 아니다.
 
+화면에서는 설명용 표현을 **실행 요청 SQL (재현)**, cursor에서 읽은 원문을 **실제 DB cursor SQL**로 구분한다. `V$SQL` 권한이 없는 환경에서도 재현 SQL은 표시하고, 실제 cursor 증적이 없다는 이유를 별도로 표시한다.
+
 최근 SQL 매칭은 대상 객체와 최근 2분 실행 시각으로 고르므로, 같은 객체를 동시에 호출하는 운영 환경에서는 다른 요청 cursor가 선택될 가능성이 있다. 현재 UI는 이를 “최근 실행 증적”으로 명시한다. 요청별 완전 상관이 필요해지면 ORDS Handler에 검증 요청 ID를 주입해 고유 SQL comment/module-action으로 cursor를 추적하는 후속 작업으로 확장한다.
 
 실행 증적 연결에는 최소한 `V$SQL`과 `DBMS_XPLAN.DISPLAY_CURSOR`를 조회할 수 있는 catalog 권한이 필요하다. 해당 권한은 ORDS parsing schema 연결에서 먼저 조회하고, 사용할 수 없으면 백오피스 연결로 한 번 더 시도한다. Autonomous의 일반 `ADMIN` 계정은 `SYS.V_$SQL` 권한을 다른 계정에 위임하지 못할 수 있으므로, 이 경우에는 DBA가 [34_agent_ords_execution_evidence_grant.sql](../../sql/adb/34_agent_ords_execution_evidence_grant.sql)을 실행해야 한다. cursor 미발견과 catalog 권한 미보유는 UI에서 서로 다른 안내로 표시하며, 어느 경우도 권한 검증 결과를 실패시키지 않는다.

docs/design/577-persona-ux-audit/README.md

@@ -104,7 +104,7 @@ UX-1부터 시작한다. 기존 데이터 모델과 VPD 로직은 바꾸지 않
 | 별도 Filter 관리 | 고급 접근 조건 | 예외 정책 기능 |
 | 운영 상태 / 연결 설정 | 운영 현황 / 시스템 설정 | 운영성·연동 설정 기능 |
 
-상단 메뉴는 VPD 업무 범위를 빠짐없이 드러내는 `권한 관리 · 보호·검증 · 연동 도구 · 운영·고급`으로 구성한다. 각 영역은 사용자·역할·접근 규칙, 보호 상태·검증 세션, 조회 연동·지식 검색·MCP, 운영 현황·고급 접근 조건·시스템 설정을 각각 포함한다. DDS와 공통으로 가져가는 것은 메뉴 분류가 아니라 **두 줄 탐색 방식**이다. 첫 줄에는 제품명·1차 메뉴·로그아웃을 함께 두고, 1차 메뉴를 누르면 해당 하위 메뉴가 팝업으로 뜨지 않고 바로 아래 전폭 줄에 표시된다. 현재 페이지가 속한 메뉴는 처음부터 아래 줄을 열어 둔다. 절차나 구현 방식이 아니라 사용자가 하려는 일을 메뉴명으로 쓴다. 메뉴와 기본 화면, wizard에도 `1.`, `2.`, 단계 레일, `01/02` 배지를 두지 않는다. 선택된 입력 영역은 역할·대상·접근 범위처럼 의미 있는 이름으로만 표시한다.
+상단 메뉴는 VPD 업무 범위를 빠짐없이 드러내는 `권한 관리 · 보호·검증 · 연동 도구 · 운영`으로 구성한다. 각 영역은 사용자·역할·접근 규칙, 보호 상태·검증 세션, 조회 연동·지식 검색·MCP, 운영 현황을 각각 포함한다. 시스템 연결, DB 준비, 고급 접근 조건은 일반 업무 메뉴와 섞지 않고 오른쪽 **관리자** 유틸리티로 분리한다. DDS와 공통으로 가져가는 것은 메뉴 분류가 아니라 **두 줄 탐색 방식**이다. 첫 줄에는 제품명·1차 메뉴·관리자·로그아웃을 함께 두고, 1차 메뉴를 누르면 해당 하위 메뉴가 팝업으로 뜨지 않고 바로 아래 전폭 줄에 표시된다. 현재 페이지가 속한 메뉴는 처음부터 아래 줄을 열어 둔다. 절차나 구현 방식이 아니라 사용자가 하려는 일을 메뉴명으로 쓴다. 메뉴와 기본 화면, wizard에도 `1.`, `2.`, 단계 레일, `01/02` 배지를 두지 않는다. 선택된 입력 영역은 역할·대상·접근 범위처럼 의미 있는 이름으로만 표시한다.
 
 기본 페이지는 제목과 현재 설정·주요 행동만 노출한다. VPD/ORDS 처리 원리, 배경 설명, 주의사항은 상단의 공통 `도움말` 버튼을 눌렀을 때만 펼친다. 이 규칙으로 제품 화면이 관리 매뉴얼처럼 보이는 문제를 줄이고, 설정 자체를 전면에 둔다.
 
@@ -117,3 +117,12 @@ UX-1부터 시작한다. 기존 데이터 모델과 VPD 로직은 바꾸지 않
 - 접근 규칙 목록은 ID·고정 ACTION·삭제 경고를 기본 열에서 빼고, 필요한 삭제 영향만 행의 `관리` 상세에서 확인하게 한다.
 - 보호 상태의 동작 설명은 상단 도움말로 옮기고, 기본 화면은 보호 대상과 적용 작업부터 보이게 한다.
 - 운영 현황은 긴 ORDS·VPD 값 때문에 오른쪽 열이 밀리지 않도록 고정 열 폭과 줄바꿈을 적용한다.
+
+## 10. 홈·도움말 정보 구조 보완 — 2026-07-01
+
+첫 화면은 설명을 길게 나열하는 대시보드가 아니라, `권한 관리 → 보호·검증 → 연동 도구 → 운영`의 큰 업무 흐름과 바로 시작할 행동, 현재 상태를 보여준다. 메뉴의 상세 역할과 권한 처리 원리는 홈의 도움말에서만 확장한다.
+
+- 도움말은 각 메뉴의 책임을 짧게 설명하고, 운영자가 길을 잃지 않도록 관리자 기능의 범위를 별도로 명시한다.
+- 권한 적용 다이어그램은 하나의 VPD/DDS 실행 계정(`CB_ORDS`)이 요청 토큰으로 실제 업무 사용자(`CB_APP_USER`)를 식별한 뒤 `CB_AGENT_CTX`를 설정하고, 역할·권한 테이블을 읽어 VPD 조건을 계산하는 구조를 보인다.
+- ERD는 직접 역할(`CB_USER_ROLE`)과 그룹 상속(`CB_USER_GROUP` → `CB_GROUP_ROLE`)이 같은 역할·권한·규칙 체계로 합쳐지는 점을 보여준다. 이 구조 때문에 실행 DB 계정을 사용자마다 만들지 않아도 요청별로 다른 데이터 범위가 적용된다.
+- 접근 검증에는 읽기용 **실행 요청 SQL**과 실제 DB cursor 증적을 구분한다. `V$SQL`/`DBMS_XPLAN` 권한이 있으면 원문 SQL·SQL_ID·Predicate Information을 보여주며, 없으면 재현 SQL은 보여주되 증적 권한이 없다는 상태를 명확히 표시한다. Oracle VPD의 내부 최종 rewrite 문자열은 별도 SQL 텍스트로 보관되지 않는다.