refactor #558: collapse secondary UI guidance

src/main/resources/static/css/app.css

@@ -209,6 +209,55 @@ body {
   margin: .35rem 0 0;
 }
 
+/* Keep the main task visible while moving background guidance out of the way. */
+.context-summary {
+  color: var(--rw-muted);
+  margin: .35rem 0 0;
+}
+
+.explanation-details {
+  background: var(--rw-surface-muted);
+  border: 1px solid var(--rw-border);
+  border-radius: 8px;
+  margin-top: .7rem;
+  padding: .65rem .8rem;
+}
+
+.explanation-details > summary {
+  color: var(--rw-primary);
+  cursor: pointer;
+  font-size: .84rem;
+  font-weight: 800;
+  list-style-position: inside;
+}
+
+.explanation-details[open] > summary {
+  border-bottom: 1px solid var(--rw-border);
+  margin-bottom: .65rem;
+  padding-bottom: .55rem;
+}
+
+.explanation-details p,
+.explanation-details ul,
+.explanation-details ol {
+  color: var(--rw-muted);
+  line-height: 1.55;
+  margin: .35rem 0 0;
+}
+
+.explanation-details > :last-child {
+  margin-bottom: 0;
+}
+
+.content-band > .explanation-details:first-child {
+  margin-top: 0;
+}
+
+.explanation-details.explanation-warning {
+  background: #fff8e8;
+  border-color: #e7d29c;
+}
+
 .architecture-strip {
   align-items: stretch;
   display: grid;

src/main/resources/templates/dashboard.html

@@ -7,7 +7,11 @@
   <header class="page-title guided-hero">
     <span class="architecture-kicker">권한을 정하면 DB가 그대로 지킵니다</span>
     <h1>누가 어떤 데이터를 볼 수 있는지 설계하고, 실제 결과까지 확인하세요.</h1>
+    <p class="context-summary">권한 설계 → DB 보호 연결 → 토큰 발급 → 실제 결과 확인</p>
+    <details class="explanation-details">
+      <summary>전체 흐름 설명 보기</summary>
       <p>사용자·그룹·역할에 권한을 연결하면 Oracle VPD가 요청할 때마다 그 규칙을 읽어 허용된 행만 반환합니다. 별도 SQL 필터를 만드는 일은 예외적인 고급 작업입니다.</p>
+    </details>
   </header>
 
   <div class="alert alert-warning" th:if="${runtimeErrorMessage}">

src/main/resources/templates/effective-matrix.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>유효 권한 매트릭스</h1>
-    <p>백오피스 사용자, 그룹, 역할, 권한의 최종 상속 결과를 확인합니다.</p>
+    <p class="context-summary">사용자별로 최종 적용되는 역할·권한·보호 객체를 확인합니다.</p>
+    <details class="explanation-details">
+      <summary>이 표를 읽는 방법</summary>
+      <p>백오피스 사용자, 그룹, 역할, 권한의 최종 상속 결과를 확인합니다. 직접 역할과 그룹을 통한 상속 역할을 나누어 보여주므로 권한이 어디에서 왔는지 추적할 수 있습니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-warning" th:if="${runtimeError}">
@@ -23,7 +27,7 @@
     <div class="section-heading">
       <div>
         <h2>권한 해석 기준</h2>
-        <p class="section-subtitle">여기의 사용자는 Oracle DB schema user가 아니라 Bearer Token으로 식별되는 백오피스 application user입니다.</p>
+        <p class="section-subtitle">Bearer Token으로 식별되는 백오피스 사용자 기준입니다.</p>
       </div>
       <a class="btn btn-sm rw-btn-secondary" href="/permissions">권한 관리로 이동</a>
     </div>
@@ -45,12 +49,15 @@
         <strong th:text="${matrix.permissionCount()}">0</strong>
       </div>
     </div>
+    <details class="explanation-details">
+      <summary>권한이 계산되는 순서 보기</summary>
       <ol class="setup-steps">
         <li>사용자 관리에서 application user를 등록합니다.</li>
         <li>그룹 관리에서 사용자를 그룹에 넣고 그룹에 역할을 부여합니다.</li>
         <li>권한 관리에서 역할에 TABLE/VIEW 행 규칙과 컬럼 NULL 정책을 부여합니다.</li>
         <li>토큰을 발급하면 ORDS handler가 token user context를 설정하고 VPD가 이 권한을 적용합니다.</li>
       </ol>
+    </details>
   </section>
 
   <section class="content-band">

src/main/resources/templates/groups.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>그룹 관리</h1>
+    <p class="context-summary">사용자를 묶고 역할을 한 번에 상속시키는 관리 화면입니다.</p>
+    <details class="explanation-details">
+      <summary>그룹 권한 흐름 설명 보기</summary>
       <p>사용자 그룹을 만들고 그룹에 사용자와 역할을 부여합니다. 권한은 역할에 연결되고, 사용자는 직접 역할과 그룹 역할을 함께 상속합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-success" th:if="${message}" th:text="${message}"></div>

src/main/resources/templates/mcp-chatbot.html

@@ -6,7 +6,11 @@
 <main class="container page-shell">
   <section class="page-heading compact-heading">
     <h1 class="h3">MCP Chatbot</h1>
+    <p class="context-summary">질문을 분석해 알맞은 MCP 도구와 VPD/ORDS 결과를 답변으로 연결합니다.</p>
+    <details class="explanation-details">
+      <summary>Chatbot 처리 흐름 보기</summary>
       <p>질문을 MCP tool로 라우팅하고, 권한 태그·VPD 행 제한·ORDS 결과를 답변으로 정리합니다.</p>
+    </details>
   </section>
 
   <section th:if="${runtimeError}" class="alert alert-warning">
@@ -17,7 +21,11 @@
   <section class="content-band chat-shell">
     <div class="chat-message assistant-message">
       <strong>질문 실행</strong>
-      <p>아래 예시를 누르거나 직접 질문을 입력하세요. Bearer Token 원문을 붙여 넣거나 사용자를 선택해 10분 임시 토큰으로 실제 ORDS/VPD 결과를 조회할 수 있습니다.</p>
+      <p>예시를 선택하거나 질문을 직접 입력하세요.</p>
+      <details class="explanation-details">
+        <summary>토큰과 조회 결과 설명 보기</summary>
+        <p>Bearer Token 원문을 붙여 넣거나 사용자를 선택해 10분 임시 토큰으로 실제 ORDS/VPD 결과를 조회할 수 있습니다.</p>
+      </details>
     </div>
 
     <div id="mcp-chatbot-result" class="chat-thread">

src/main/resources/templates/mcp-client-demo.html

@@ -6,7 +6,11 @@
 <main class="container page-shell">
   <section class="page-heading">
     <h1>MCP Client Demo</h1>
+    <p class="context-summary">Java client가 MCP 연결과 도구 목록 계약만 확인합니다.</p>
+    <details class="explanation-details">
+      <summary>Client Demo의 범위 보기</summary>
       <p>백오피스 Java client가 MCP message endpoint의 initialize/tools/list 계약을 확인합니다. 실제 tool 선택과 호출은 reasoning 결과를 받은 MCP client가 담당합니다.</p>
+    </details>
   </section>
 
   <section th:if="${runtimeError}" class="alert alert-warning">
@@ -18,9 +22,10 @@
     <h2>Java Client 호출</h2>
     <form hx-post="/mcp-client-demo" hx-target="#mcp-client-demo-result" hx-swap="innerHTML" class="form-grid">
       <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}">
-      <div class="alert alert-info span-2 mb-0">
+      <details class="explanation-details span-2">
-        이 화면은 고정된 기본 MCP endpoint에서 initialize와 tools/list만 확인합니다. 질문 기반 tool 선택·Bearer Token 전달·tools/call은 MCP Reasoning 또는 외부 MCP client 흐름에서 수행합니다.
+        <summary>이번 테스트에서 확인하는 계약 보기</summary>
-      </div>
+        <p>이 화면은 고정된 기본 MCP endpoint에서 initialize와 tools/list만 확인합니다. 질문 기반 tool 선택·Bearer Token 전달·tools/call은 MCP Reasoning 또는 외부 MCP client 흐름에서 수행합니다.</p>
+      </details>
       <button class="btn rw-btn-primary" type="submit">MCP 계약 확인</button>
     </form>
   </section>

src/main/resources/templates/mcp-reasoning.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>MCP Reasoning</h1>
+    <p class="context-summary">질문에 맞는 MCP tool을 자동 선택하고 결과를 설명합니다.</p>
+    <details class="explanation-details">
+      <summary>Reasoning 처리 흐름 보기</summary>
       <p>질문을 근거로 MCP tool을 고르고, Bearer Token으로 VPD/ORDS 결과를 조회한 뒤 모델이 설명합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-warning" th:if="${runtimeError}">
@@ -27,7 +31,11 @@
       <label>
         Bearer Token 원문
         <input class="form-control" name="bearerToken" type="password" autocomplete="off">
-        <span class="form-hint">등록 토큰을 선택하지 않습니다. 원문을 붙여 넣거나 아래에서 임시 토큰 사용자를 선택하세요.</span>
+        <span class="form-hint">원문을 붙여 넣거나 임시 토큰 사용자를 선택하세요.</span>
+        <details class="explanation-details">
+          <summary>토큰 처리 방식 보기</summary>
+          <p>등록 토큰을 목록에서 선택하지 않습니다. 원문은 저장하지 않고 요청에만 사용합니다.</p>
+        </details>
       </label>
       <label>
         임시 토큰 사용자 (선택)
@@ -35,7 +43,11 @@
           <option value="">원문 토큰 사용</option>
           <option th:each="user : ${users}" th:value="${user.userId()}" th:text="${user.username()}"></option>
         </select>
-        <span class="form-hint">선택하면 reasoning 실행 중 10분 토큰을 발행하고 완료 즉시 회수합니다.</span>
+        <span class="form-hint">실행 중 발행하고 완료 즉시 회수합니다.</span>
+        <details class="explanation-details">
+          <summary>임시 토큰 상세 보기</summary>
+          <p>선택하면 reasoning 실행 중 10분 토큰을 발행하고 완료 즉시 회수합니다.</p>
+        </details>
       </label>
       <label>
         Limit

src/main/resources/templates/mcp-sse.html

@@ -6,7 +6,11 @@
 <main class="container page-shell">
   <section class="page-heading">
     <h1>MCP SSE</h1>
+    <p class="context-summary">외부 MCP client가 ORDS 조회 도구를 호출하는 SSE 연결 정보를 제공합니다.</p>
+    <details class="explanation-details">
+      <summary>SSE와 context path 설명 보기</summary>
       <p>보호 객체 ORDS 조회를 외부 MCP client에서 호출할 수 있도록 context path별 SSE transport로 제공합니다.</p>
+    </details>
   </section>
 
   <section th:if="${runtimeError}" class="alert alert-warning">
@@ -36,6 +40,8 @@
   </section>
 
   <section class="content-band">
+    <details class="explanation-details">
+      <summary>Endpoint 상세 보기</summary>
       <h2>Endpoint</h2>
     <div class="table-responsive">
       <table class="table align-middle">
@@ -71,6 +77,7 @@
         </tbody>
       </table>
       </div>
+    </details>
   </section>
 
   <section class="content-band">
@@ -109,15 +116,20 @@
   </section>
 
   <section class="content-band">
+    <details class="explanation-details">
+      <summary>tools/call parameter 예시 보기</summary>
       <h2>tools/call Arguments</h2>
       <pre class="code-block">{
   "bearerToken": "vpd_live_xxx",
   "limit": 50
 }</pre>
       <p class="form-hint">벡터 검색 tool인 <code>CB_VECTOR_SEARCH_DOCUMENTS</code>는 여기에 외부 임베딩 모델이 만든 <code>embedding</code> 숫자 배열을 추가합니다. 토큰·limit은 모든 tool에 공통이고, embedding은 벡터 tool에만 필요합니다.</p>
+    </details>
   </section>
 
   <section class="content-band">
+    <details class="explanation-details">
+      <summary>JSON-RPC 예시 보기</summary>
       <h2>JSON-RPC 예시</h2>
     <div class="probe-exchange-grid">
       <div class="probe-exchange">
@@ -154,6 +166,7 @@
 }</pre>
       </div>
       </div>
+    </details>
   </section>
 </main>
 </body>

src/main/resources/templates/objects.html

@@ -6,14 +6,19 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>ORDS 조회 대상 등록</h1>
+    <p class="context-summary">DB 객체를 조회 Handler에 연결하는 화면입니다. 접근 권한은 별도로 관리합니다.</p>
+    <details class="explanation-details">
+      <summary>이 화면의 역할 설명 보기</summary>
       <p>이 화면은 DB 객체를 HTTP로 연결할 경로만 등록합니다. 누가 어떤 행을 볼 수 있는지는 권한 규칙과 VPD에서 결정합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-info">
-    <strong>벡터 지식자료 검색 흐름:</strong>
+    <strong>벡터 검색 예제:</strong> 문서 청크와 기술 태그를 등록한 뒤 전용 ORDS 검색을 연결합니다.
-    문서를 청크로 나누고 기술 태그를 붙인 뒤 전용 ORDS 검색을 등록합니다.
+    <details class="explanation-details mt-2">
-    그 다음 <a href="/permissions">권한 관리</a>에서 <code>특정 기술 태그</code>를 여러 개 추가하면
+      <summary>벡터 지식자료 검색 흐름 설명 보기</summary>
-    태그 중 하나라도 맞는 청크만 검색됩니다.
+      <p>문서를 청크로 나누고 기술 태그를 붙인 뒤 전용 ORDS 검색을 등록합니다. 그 다음 <a href="/permissions">권한 관리</a>에서 <code>특정 기술 태그</code>를 여러 개 추가하면 태그 중 하나라도 맞는 청크만 검색됩니다.</p>
+    </details>
   </div>
 
   <section th:replace="~{fragments/layout :: architectureStrip('ords')}"></section>
@@ -23,7 +28,11 @@
 
   <section class="content-band">
     <h2>조회 대상 추가 (예제 Handler)</h2>
-    <p class="section-subtitle">DB 객체 하나를 하나의 조회 Handler로 연결하는 예제입니다. 대상 추가 후 Handler를 생성하면 VPD context 설정과 기본 SELECT가 포함된 PL/SQL이 만들어지며, 소스 보기에서 실제 업무에 맞게 수정할 수 있습니다.</p>
+    <p class="section-subtitle">DB 객체 하나를 하나의 조회 Handler로 연결하는 시작 예제입니다.</p>
+    <details class="explanation-details">
+      <summary>대상 추가 후 생성되는 내용 보기</summary>
+      <p>대상 추가 후 Handler를 생성하면 VPD context 설정과 기본 SELECT가 포함된 PL/SQL이 만들어집니다. 소스 보기에서 실제 업무에 맞게 수정할 수 있습니다.</p>
+    </details>
     <form method="post" action="/objects" class="form-grid">
       <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}">
       <input type="hidden" name="owner" required>
@@ -58,13 +67,10 @@
       </label>
       <button class="btn btn-primary" type="submit">대상 추가</button>
     </form>
-    <div class="alert alert-info mt-3 mb-0">
+    <details class="explanation-details explanation-warning mt-3">
-      <strong>생성되는 예제 흐름:</strong>
+      <summary>기본 Handler 예제와 수정 가이드 보기</summary>
-      <code>cb_ords_handler_pkg.set_vpd_context(:auth_header)</code>로 토큰의 사용자·역할 컨텍스트를 넣고,
+      <p><code>cb_ords_handler_pkg.set_vpd_context(:auth_header)</code>로 토큰의 사용자·역할 컨텍스트를 넣고, 선택한 한 테이블에 <code>SELECT ... FROM OWNER.TABLE</code>을 실행한 뒤 JSON으로 반환합니다. 이것은 유일한 사용 방식이 아니라 시작점이며, Handler 소스와 ORDS 메타데이터에서 수정할 수 있습니다. 컬럼 민감도·마스킹은 이 화면에서 다루지 않고 <a href="/permissions">권한 관리의 원문 표시 허용 컬럼</a>에서 별도로 설정합니다.</p>
-      선택한 한 테이블에 <code>SELECT ... FROM OWNER.TABLE</code>을 실행한 뒤 JSON으로 반환합니다.
+    </details>
-      이것은 유일한 사용 방식이 아니라 시작점이며, Handler 소스와 ORDS 메타데이터에서 수정할 수 있습니다.
-      컬럼 민감도·마스킹은 이 화면에서 다루지 않고 <a href="/permissions">권한 관리의 원문 표시 허용 컬럼</a>에서 별도로 설정합니다.
-    </div>
   </section>
 
   <section class="content-band">
@@ -135,11 +141,13 @@
           </tr>
           <tr>
             <td colspan="6" class="policy-source-cell">
+              <details class="explanation-details">
+                <summary>이 대상의 자동 연결 흐름 보기</summary>
                 <div class="object-handler-explainer">
-                <strong>이 대상에서 자동으로 연결되는 것</strong>
+                  <strong>토큰 헤더 → VPD context 설정 → 선택한 단일 테이블의 기본 SELECT → JSON 응답</strong>
-                <span>토큰 헤더 → VPD context 설정 → 선택한 단일 테이블의 기본 SELECT → JSON 응답</span>
                   <small>행 접근은 권한 규칙/VPD가 담당합니다. 원문 표시 예외는 권한 관리 Step 4에서 여러 컬럼을 등록하세요.</small>
                 </div>
+              </details>
               <div th:if="${object.objectName() != 'CB_VECTOR_SEARCH_DOCUMENTS'}"
                    th:id="${'handler-source-' + object.objectId()}" class="text-muted small">
                 소스 보기를 누르면 기본 Handler PL/SQL이 표시됩니다.

src/main/resources/templates/operation-status.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>운영 상태</h1>
-    <p>보호 객체별 ORDS handler, VPD policy, 권한 rule, 최근 검증 상태를 확인합니다.</p>
+    <p class="context-summary">보호 객체별 연결 상태와 최근 검증 결과를 한눈에 봅니다.</p>
+    <details class="explanation-details">
+      <summary>운영 상태 항목 설명 보기</summary>
+      <p>보호 객체별 ORDS handler, VPD policy, 권한 rule, 최근 검증 상태를 확인합니다. 이상이 있을 때는 해당 객체의 권한·VPD·ORDS 순서로 점검하세요.</p>
+    </details>
   </div>
 
   <section class="content-band">

src/main/resources/templates/ords-handlers.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>ORDS 핸들러</h1>
-    <p>Bearer Token을 DB 컨텍스트로 변환하는 ORDS Handler와 PL/SQL 흐름을 확인합니다.</p>
+    <p class="context-summary">토큰을 DB 권한 컨텍스트로 바꾸는 Handler를 확인·수정합니다.</p>
+    <details class="explanation-details">
+      <summary>Handler 처리 흐름 설명 보기</summary>
+      <p>Bearer Token을 DB 컨텍스트로 변환한 뒤 VPD가 권한체계를 적용합니다. 아래 소스는 등록된 ORDS Handler가 실제로 실행하는 기술 세부 내용입니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-success" th:if="${message}" th:text="${message}"></div>
@@ -24,10 +28,10 @@
       <span>Template: <strong th:text="${handler.template()}">vpd/documents</strong></span>
     </div>
     <div class="probe-exchange-grid">
-      <section class="probe-exchange">
+      <details class="explanation-details technical-details">
-        <h3>Header Bindings</h3>
+        <summary>Header Bindings 보기</summary>
         <pre th:text="${handler.parameters()} ?: 'No parameters'"></pre>
-      </section>
+      </details>
       <section class="probe-exchange">
         <h3>Handler Source</h3>
         <form method="post" action="/ords-handlers/update">
@@ -43,10 +47,10 @@
           </div>
         </form>
       </section>
-      <section class="probe-exchange span-2">
+      <details class="explanation-details technical-details span-2">
-        <h3>Bearer Token -> User Context Package</h3>
+        <summary>Bearer Token → User Context Package 보기</summary>
         <pre th:text="${handler.packageSource()}"></pre>
-      </section>
+      </details>
     </div>
   </section>
 </main>

src/main/resources/templates/permissions.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>권한 관리</h1>
-    <p>VPD policy function이 참조할 사용자, 역할, 행 규칙, 컬럼 원문 허용 규칙을 저장합니다.</p>
+    <p class="context-summary">역할이 어떤 객체의 어느 행과 컬럼을 볼 수 있는지 정의합니다.</p>
+    <details class="explanation-details">
+      <summary>권한 규칙과 VPD의 관계 보기</summary>
+      <p>VPD policy function이 참조할 사용자, 역할, 행 규칙, 컬럼 원문 허용 규칙을 저장합니다. 이 화면에서 만든 규칙이 기본 Filter의 동적 입력이 됩니다.</p>
+    </details>
   </div>
 
   <section th:replace="~{fragments/layout :: architectureStrip('permission')}"></section>
@@ -66,7 +70,10 @@
                              data-group-users=${#strings.listJoin(groupUsersByRole[role.roleId()], '|')}"></option>
           </select>
         </label>
+        <details class="explanation-details">
+          <summary>역할 선택 기준 보기</summary>
           <p class="wizard-hint">선택한 역할의 표시 보호 등급 상한(참고)도 preview에 반영됩니다. 행을 볼 수 있는 권한과는 별개입니다.</p>
+        </details>
         <div class="effective-preview">
           <div class="field-block-title">선택 역할 영향도</div>
           <dl>
@@ -105,7 +112,10 @@
             </optgroup>
           </select>
         </label>
+        <details class="explanation-details">
+          <summary>객체 선택 기준 보기</summary>
           <p class="wizard-hint">DB 스키마 객체를 선택하면 저장 시 보호 객체가 자동 등록됩니다.</p>
+        </details>
         <div class="effective-preview">
           <div class="field-block-title">선택 객체 컬럼 (표시 보호 참고)</div>
           <dl>
@@ -155,7 +165,10 @@
               <button class="btn btn-outline-secondary" type="button" data-rule-add>추가</button>
             </div>
           </div>
+          <details class="explanation-details">
+            <summary>행 규칙과 기술 태그 OR 조건 보기</summary>
             <p class="wizard-hint">특정 기술 태그는 기본적으로 <code>TECH_TAG</code> 컬럼을 봅니다. 같은 ALLOW 권한에 태그를 여러 개 추가하면 “태그 A 또는 태그 B”로 조회되고, DENY 태그는 허용 결과에서 제외됩니다. 객체에 TECH_TAG가 없으면 실제 태그 컬럼을 직접 지정하세요.</p>
+          </details>
         </div>
       </div>
 
@@ -178,7 +191,10 @@
           <input class="form-control" name="visibleColumns" placeholder="예: CONTENTS, SOURCE_URI">
           <span class="selected-column-list" data-selected-visible-columns aria-live="polite"></span>
         </label>
+        <details class="explanation-details">
+          <summary>원문 표시 허용 컬럼 안내 보기</summary>
           <p class="wizard-hint">쉼표로 여러 컬럼을 등록하거나 위 버튼을 여러 번 누르세요. 등록하지 않은 민감 컬럼은 기본 표시 보호를 유지합니다. 행을 볼 수 있는지는 이 목록이 아니라 권한 규칙과 VPD가 결정합니다.</p>
+        </details>
       </div>
 
       <div class="wizard-panel" data-wizard-step="5">

src/main/resources/templates/probe.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>권한 결과 확인</h1>
+    <p class="context-summary">토큰을 사용해 실제로 보이는 행과 컬럼을 확인합니다.</p>
+    <details class="explanation-details">
+      <summary>검증 단계 설명 보기</summary>
       <p>한 사용자의 토큰으로 실제 데이터를 요청해, 설계한 권한이 DB에서 그대로 적용되는지 확인합니다.</p>
+    </details>
   </div>
 
   <section th:replace="~{fragments/layout :: architectureStrip('ords')}"></section>
@@ -15,7 +19,11 @@
     <div>
       <span class="architecture-kicker">이번 단계에서 확인하는 것</span>
       <h2>“이 사용자는 이 데이터에서 무엇을 볼 수 있는가?”</h2>
+      <p>토큰과 대상 객체를 입력하면 실제 조회 결과를 보여줍니다.</p>
+      <details class="explanation-details">
+        <summary>권한 판정 과정 보기</summary>
         <p>토큰은 사용자를 찾는 열쇠입니다. 서버가 직접 역할과 그룹 상속 역할을 합치고, VPD가 저장된 행·열 규칙을 적용한 결과를 보여줍니다.</p>
+      </details>
     </div>
     <a class="btn rw-btn-secondary" href="/tokens">테스트 토큰이 없나요? 먼저 발급하기</a>
   </section>

src/main/resources/templates/roles.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>역할 관리</h1>
-    <p>사용자에게 부여할 역할을 관리합니다. 아래 등급은 허용된 행의 컬럼 표시 보호 상한을 기록하는 참고값이며, 행 접근 권한은 권한 규칙과 VPD에서 결정합니다.</p>
+    <p class="context-summary">권한 규칙을 묶어 사용자·그룹에 부여하는 단위입니다.</p>
+    <details class="explanation-details">
+      <summary>역할과 표시 보호 상한 설명 보기</summary>
+      <p>사용자에게 부여할 역할을 관리합니다. 표시 보호 등급 상한은 허용된 행에서 원문으로 볼 수 있는 컬럼 등급의 참고값이며, 행 접근 권한은 권한 규칙과 VPD에서 결정합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-success" th:if="${message}" th:text="${message}"></div>

src/main/resources/templates/settings.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>설정</h1>
-    <p>백오피스에서 사용하는 외부 연동 값을 관리합니다.</p>
+    <p class="context-summary">ORDS 연결값과 백오피스 DB 준비 상태를 확인합니다.</p>
+    <details class="explanation-details">
+      <summary>설정 화면의 범위 보기</summary>
+      <p>백오피스에서 사용하는 외부 연동 값을 관리합니다. DB 준비 상태에서는 메타데이터, VPD runtime, ORDS runtime, grant를 연결 사용자 기준으로 점검합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-success" th:if="${message}" th:text="${message}"></div>

src/main/resources/templates/tokens.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>테스트 토큰 발급</h1>
-    <p>검증할 사용자를 나타내는 토큰을 만들고, 한 번만 표시되는 원문을 다음 단계에서 사용합니다.</p>
+    <p class="context-summary">검증할 사용자의 일회성 Bearer Token을 발급합니다.</p>
+    <details class="explanation-details">
+      <summary>토큰 보관 방식 설명 보기</summary>
+      <p>검증할 사용자를 나타내는 토큰을 만들고, 한 번만 표시되는 원문을 다음 단계에서 사용합니다. 원문은 저장하지 않고 해시와 식별용 prefix만 보관합니다.</p>
+    </details>
   </div>
 
   <section th:replace="~{fragments/layout :: architectureStrip('token')}"></section>

src/main/resources/templates/users.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>사용자 관리</h1>
-    <p>Bearer Token과 권한 매핑에 사용할 내부 사용자를 관리합니다.</p>
+    <p class="context-summary">토큰과 권한의 기준이 되는 백오피스 사용자를 관리합니다.</p>
+    <details class="explanation-details">
+      <summary>사용자와 DB 계정의 차이 보기</summary>
+      <p>Bearer Token과 권한 매핑에 사용할 내부 사용자를 관리합니다. 여기의 사용자는 Oracle DB schema 계정이 아니라 권한체계에서 식별하는 application user입니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-success" th:if="${message}" th:text="${message}"></div>

src/main/resources/templates/vpd-filter-policies.html

@@ -7,7 +7,11 @@
   <div class="page-title">
     <span class="badge text-bg-warning">고급 설정</span>
     <h1 class="mt-2">별도 Filter 관리</h1>
+    <p class="context-summary">기본 권한체계로 표현할 수 없는 객체 전용 조건만 관리합니다.</p>
+    <details class="explanation-details">
+      <summary>별도 Filter를 사용하는 기준 보기</summary>
       <p>일반 권한은 이 화면에서 만들지 않습니다. 권한체계로 표현할 수 없는 객체 전용 조건이 있을 때만 별도 함수를 추가합니다.</p>
+    </details>
   </div>
 
   <div class="alert alert-warning" th:if="${runtimeError}">
@@ -25,6 +29,8 @@
       </div>
       <a class="btn btn-sm rw-btn-primary" href="/permissions">권한 규칙으로 이동</a>
     </div>
+    <details class="explanation-details">
+      <summary>운영자 설정과 DB 자동 처리의 차이 보기</summary>
       <div class="macro-micro-grid">
         <div>
           <h3>운영자가 관리하는 것</h3>
@@ -35,14 +41,16 @@
           <p><code>CB_AGENT_DOC_VPD_FILTER</code>가 요청마다 그 권한을 합쳐 predicate를 만들고, 권한이나 유효한 컨텍스트가 없으면 <code>1=0</code>으로 차단합니다.</p>
         </div>
       </div>
+    </details>
     <div class="protected-function-card">
       <strong>보호되는 핵심 함수</strong>
       <code>CB_AGENT_DOC_VPD_FILTER</code>
       <span>이 화면과 서버 양쪽에서 직접 덮어쓰기를 차단합니다.</span>
     </div>
-    <div class="alert alert-info mt-3 mb-0">
+    <details class="explanation-details mt-3">
-      <strong>Filter 설명:</strong> 이 화면의 function은 DB가 행을 걸러낼 predicate를 반환합니다. 기본 함수는 사용자·그룹·역할·TAG 권한을 동적으로 읽고, 별도 Filter는 객체 고유 조건을 추가할 때만 사용합니다. 저장하는 설명에는 대상, 조건, 예상되는 허용/차단 결과를 적습니다.
+      <summary>Filter 설명과 작성 기준 보기</summary>
-    </div>
+      <p><strong>Filter 설명:</strong> 이 화면의 function은 DB가 행을 걸러낼 predicate를 반환합니다. 기본 함수는 사용자·그룹·역할·TAG 권한을 동적으로 읽고, 별도 Filter는 객체 고유 조건을 추가할 때만 사용합니다. 저장하는 설명에는 대상, 조건, 예상되는 허용/차단 결과를 적습니다.</p>
+    </details>
   </section>
 
   <section class="content-band">

src/main/resources/templates/vpd-policies.html

@@ -6,7 +6,11 @@
 <main class="container py-4">
   <div class="page-title">
     <h1>DB 보호 연결</h1>
+    <p class="context-summary">권한체계를 실제 TABLE/VIEW에 연결하고 적용 상태를 확인합니다.</p>
+    <details class="explanation-details">
+      <summary>VPD 보호 연결의 의미 보기</summary>
       <p>권한 화면에서 만든 사용자·그룹·역할·행·열 규칙을 Oracle VPD가 실제 TABLE/VIEW에 적용하도록 연결합니다.</p>
+    </details>
   </div>
 
   <section th:replace="~{fragments/layout :: architectureStrip('vpd')}"></section>
@@ -35,17 +39,22 @@
       <strong>→</strong>
       <span>허용된 데이터만 반환</span>
     </div>
-    <p class="text-muted mb-0"><code>CB_AGENT_DOC_VPD_FILTER</code>가 요청할 때마다 현재 권한체계를 읽습니다. 일상적인 권한 변경은 이 함수나 predicate가 아니라 <a href="/permissions">권한 규칙</a>에서 하세요.</p>
+    <p class="text-muted mb-0"><code>CB_AGENT_DOC_VPD_FILTER</code>가 요청마다 권한체계를 읽습니다. 일반 변경은 <a href="/permissions">권한 규칙</a>에서 합니다.</p>
-    <div class="alert alert-info mt-3 mb-0">
+    <details class="explanation-details mt-3">
-      <strong>이 화면의 역할:</strong> policy는 “어느 객체의 어떤 SQL에 어떤 Filter function을 붙일지”를 정합니다. 행의 실제 허용/차단 조건은 권한 규칙과 Filter function이 계산하고, 컬럼 표시 보호는 별도 설정입니다.
+      <summary>Policy와 Filter의 역할 구분 보기</summary>
-    </div>
+      <p>Policy는 “어느 객체의 어떤 SQL에 어떤 Filter function을 붙일지”를 정합니다. 행의 실제 허용/차단 조건은 권한 규칙과 Filter function이 계산하고, 컬럼 표시 보호는 별도 설정입니다.</p>
+    </details>
   </section>
 
   <section class="content-band">
     <div class="section-heading">
       <div>
         <h2>보호할 수 있는 DB 객체</h2>
-        <p class="section-subtitle">VPD가 붙었는지, 권한 규칙과 검증 경로가 준비됐는지 한곳에서 확인합니다. 아래 기본 적용에서는 객체만 선택하면 됩니다.</p>
+        <p class="section-subtitle">VPD 적용 상태와 권한·검증 경로를 확인합니다.</p>
+        <details class="explanation-details">
+          <summary>객체 상태 항목 설명 보기</summary>
+          <p>VPD가 붙었는지, 권한 규칙과 검증 경로가 준비됐는지 한곳에서 확인합니다. 아래 기본 적용에서는 객체만 선택하면 됩니다.</p>
+        </details>
       </div>
       <span class="badge text-bg-secondary" th:text="${#lists.size(vpdTargets)}">0</span>
     </div>
@@ -199,7 +208,11 @@
       <div>
         <span class="architecture-kicker">권장 · 일반 작업</span>
         <h2>객체 하나에 권한체계 연결</h2>
-        <p class="section-subtitle">객체만 선택하면 표준 동적 함수, SELECT 정책, 즉시 활성화를 서버가 안전한 기본값으로 적용합니다.</p>
+        <p class="section-subtitle">객체를 선택하면 표준 동적 정책을 기본값으로 적용합니다.</p>
+        <details class="explanation-details">
+          <summary>기본 적용 내용 보기</summary>
+          <p>객체만 선택하면 표준 동적 함수, SELECT 정책, 즉시 활성화를 서버가 안전한 기본값으로 적용합니다.</p>
+        </details>
       </div>
     </div>
     <form method="post" action="/vpd-policies/default" class="form-grid default-vpd-form">