[Documenter] #575 document dashboard help diagrams

docs/design/575-dashboard-action-centered-ui/README.md

@@ -1,8 +1,8 @@
 # 설계서: 대시보드 작업 중심 정보 구조 (#575)
 
-> **상태**: Implemented · QA passed
+> **상태**: Implemented · deployed · QA passed
-> **작성**: [AI] Architect · **최종수정**: 2026-06-30
+> **작성**: [AI] Architect · **최종수정**: 2026-07-03
-> **추적성** — Redmine: #575 · 구현: `dashboard.html`, `app.css`, `GuidedFlowTemplateTest`
+> **추적성** — Redmine: #575 · 구현: `dashboard.html`, `app.css`, `GuidedFlowTemplateTest` · 관련 UX 감사: [#577](../577-persona-ux-audit/README.md)
 
 ## 목적
 
@@ -19,6 +19,20 @@
   └ Macro/Micro 설명 + 보호 객체/ORDS 경로 테이블
 ```
 
+## 도움말 다이어그램
+
+첫 화면을 설명 중심 화면으로 되돌리지 않기 위해, 설명은 상단의 접힌 `도움말: 메뉴와 권한 적용 구조 보기` 안에 둔다. 다이어그램은 별도 이미지 파일이 아닌 접근 가능한 인라인 SVG로 구현한다. 따라서 테마 색상과 글꼴을 공통 CSS 변수로 일관되게 적용하고, 확대해도 선명하며, 각 그림의 제목과 설명을 보조 기술에 제공한다.
+
+| 그림 | 전달하는 내용 | 운영자가 얻는 답 |
+|---|---|---|
+| 설정·검증 순서 | 사용자·그룹 → 역할 → 접근 규칙 → 보호·연결 → 유효 권한·접근 검증 | 처음부터 어떤 메뉴를 어떤 순서로 써야 하는가 |
+| 요청별 VPD 적용 흐름 | Bearer Token → `CB_ORDS` → `CB_AGENT_CTX` → VPD 조건 계산 → 보호 데이터 | 같은 실행 계정인데 왜 사용자마다 다른 결과가 나오는가 |
+| 권한 데이터 모델(축약 ERD) | 사용자/그룹의 역할이 권한·규칙을 거쳐 보호 대상으로 연결되는 구조 | 직접 역할과 그룹 상속이 어떻게 합쳐지는가 |
+
+- 설정 순서 그림은 권한이 토큰에 복사되지 않고 다음 요청의 VPD 조건 계산에 동적으로 반영된다는 점을 함께 표시한다.
+- `diagram-canvas`는 작은 화면에서 그림을 축소해 읽기 어렵게 만들지 않고 가로 스크롤을 제공한다.
+- 번호 배지, 주 경로, 보조 연결, 데이터·검증 노드를 구분해 처음 보는 운영자가 흐름의 우선순위를 빠르게 파악하게 한다.
+
 ## 인수조건
 
 - [x] 첫 화면에 핵심 작업 두 개와 현재 상태가 함께 보인다.
@@ -33,3 +47,6 @@
 - 배포 후 인증된 HTTP 점검: dashboard 및 users/groups/roles/permissions/tokens/probe/ORDS 등 주요 18개 화면이 모두 `200`을 반환했다.
 - dashboard 응답에서 작업 중심 영역(`dashboard-command-center`), 4단계 레일(`workflow-steps`), 기본으로 접힌 상세 영역(`dashboard-details`)을 확인했다.
 - 개발 중 발견한 dashboard fragment 문법 오류는 수정하고 템플릿 테스트가 fragment 형식을 검사하도록 보완했다.
+- 2026-07-02: 도움말 SVG 추가 후 `mvn test`를 다시 통과했다.
+- 2026-07-02: 운영 백오피스를 새 JAR로 재기동했고 `/login`이 HTTP `200`을 반환했다. 시작 로그에서 `vpd-backoffice-pool` 연결과 DB 카탈로그 캐시 예열을 확인했다.
+- 2026-07-02: SQLcl로 `SELECT 'DB_CONNECTION_OK' FROM dual` 및 `CB_AGENT_DOC_VPD_FILTER` 상태(`VALID`)를 확인했다.

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

@@ -118,11 +118,13 @@ UX-1부터 시작한다. 기존 데이터 모델과 VPD 로직은 바꾸지 않
 - 보호 상태의 동작 설명은 상단 도움말로 옮기고, 기본 화면은 보호 대상과 적용 작업부터 보이게 한다.
 - 운영 현황은 긴 ORDS·VPD 값 때문에 오른쪽 열이 밀리지 않도록 고정 열 폭과 줄바꿈을 적용한다.
 
-## 10. 홈·도움말 정보 구조 보완 — 2026-07-01
+## 10. 홈·도움말 정보 구조 보완 — 2026-07-01~03
 
 첫 화면은 설명을 길게 나열하는 대시보드가 아니라, `권한 관리 → 보호·검증 → 연동 도구 → 운영`의 큰 업무 흐름과 바로 시작할 행동, 현재 상태를 보여준다. 메뉴의 상세 역할과 권한 처리 원리는 홈의 도움말에서만 확장한다.
 
 - 도움말은 각 메뉴의 책임을 짧게 설명하고, 운영자가 길을 잃지 않도록 관리자 기능의 범위를 별도로 명시한다.
+- 도움말 첫 그림은 `사용자·그룹 → 역할 → 접근 규칙 → 보호·연결 → 유효 권한·접근 검증`의 5단계 설정 흐름이다. 설정 변경이 토큰에 복사되는 방식이 아니라 다음 요청의 VPD 조건 계산에 반영된다는 점을 표시해, 운영자가 재발급 여부를 혼동하지 않게 한다.
 - 권한 적용 다이어그램은 하나의 VPD/DDS 실행 계정(`CB_ORDS`)이 요청 토큰으로 실제 업무 사용자(`CB_APP_USER`)를 식별한 뒤 `CB_AGENT_CTX`를 설정하고, 역할·권한 테이블을 읽어 VPD 조건을 계산하는 구조를 보인다.
 - ERD는 직접 역할(`CB_USER_ROLE`)과 그룹 상속(`CB_USER_GROUP` → `CB_GROUP_ROLE`)이 같은 역할·권한·규칙 체계로 합쳐지는 점을 보여준다. 이 구조 때문에 실행 DB 계정을 사용자마다 만들지 않아도 요청별로 다른 데이터 범위가 적용된다.
+- 세 그림은 인라인 SVG이며, 제목·설명을 제공하고 작은 화면에서는 가로 스크롤로 가독성을 보존한다. 구현 및 배포 검증은 [#575 대시보드 설계서](../575-dashboard-action-centered-ui/README.md)에 기록한다.
 - 접근 검증에는 읽기용 **실행 요청 SQL**과 실제 DB cursor 증적을 구분한다. `V$SQL`/`DBMS_XPLAN` 권한이 있으면 원문 SQL·SQL_ID·Predicate Information을 보여주며, 없으면 재현 SQL은 보여주되 증적 권한이 없다는 상태를 명확히 표시한다. Oracle VPD의 내부 최종 rewrite 문자열은 별도 SQL 텍스트로 보관되지 않는다.

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

@@ -2002,6 +2002,18 @@ body {
   stroke: var(--rw-success);
 }
 
+.diagram-node-step circle {
+  fill: var(--rw-text);
+}
+
+.diagram-node-accent circle {
+  fill: var(--rw-primary);
+}
+
+.diagram-node-data circle {
+  fill: var(--rw-success);
+}
+
 .diagram-node text,
 .erd-entity text {
   fill: var(--rw-text);
@@ -2025,6 +2037,26 @@ body {
   font-size: 11px;
 }
 
+.diagram-step-number {
+  fill: #fff !important;
+  font-size: 12px;
+  font-weight: 800;
+}
+
+.setup-flow-return {
+  fill: none;
+  stroke: var(--rw-border-strong);
+  stroke-dasharray: 4 4;
+  stroke-width: 1.5;
+}
+
+.setup-flow-note {
+  fill: var(--rw-muted);
+  font-family: "Oracle Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-size: 13px;
+  text-anchor: middle;
+}
+
 .product-help-sql {
   background: var(--rw-primary-soft);
   border: 1px solid color-mix(in srgb, var(--rw-primary) 26%, var(--rw-border));

src/main/resources/templates/dashboard.html

@@ -33,6 +33,29 @@
           </dl>
         </section>
 
+        <section class="product-help-section">
+          <h2>처음 설정할 때의 순서</h2>
+          <p>권한을 먼저 만들고 보호 대상을 연결한 뒤, 실제 사용자 토큰으로 결과를 검증합니다. 권한은 토큰에 복사되지 않아 이후 변경도 다음 요청부터 반영됩니다.</p>
+          <div class="diagram-canvas">
+            <svg class="product-flow-diagram setup-flow-diagram" viewBox="0 0 1120 245" role="img" aria-labelledby="setup-flow-title setup-flow-desc">
+              <title id="setup-flow-title">VPD 권한 설정과 검증 순서</title>
+              <desc id="setup-flow-desc">사용자와 그룹, 역할, 접근 규칙, 보호 대상을 차례로 설정하고 유효 권한과 실제 조회 결과를 검증하는 흐름</desc>
+              <defs><marker id="setup-flow-arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z"/></marker></defs>
+              <path class="diagram-link" marker-end="url(#setup-flow-arrow)" d="M205 100 H238"/>
+              <path class="diagram-link" marker-end="url(#setup-flow-arrow)" d="M415 100 H448"/>
+              <path class="diagram-link" marker-end="url(#setup-flow-arrow)" d="M625 100 H658"/>
+              <path class="diagram-link" marker-end="url(#setup-flow-arrow)" d="M835 100 H868"/>
+              <g class="diagram-node diagram-node-step"><rect x="30" y="52" width="175" height="96" rx="12"/><circle cx="57" cy="77" r="15"/><text x="57" y="82" class="diagram-step-number">1</text><text x="117" y="85" class="diagram-node-title">사용자·그룹</text><text x="117" y="113" class="diagram-node-detail">업무 대상을 등록</text></g>
+              <g class="diagram-node diagram-node-step"><rect x="240" y="52" width="175" height="96" rx="12"/><circle cx="267" cy="77" r="15"/><text x="267" y="82" class="diagram-step-number">2</text><text x="327" y="85" class="diagram-node-title">역할</text><text x="327" y="113" class="diagram-node-detail">직접·그룹 역할 부여</text></g>
+              <g class="diagram-node diagram-node-step diagram-node-accent"><rect x="450" y="52" width="175" height="96" rx="12"/><circle cx="477" cy="77" r="15"/><text x="477" y="82" class="diagram-step-number">3</text><text x="537" y="85" class="diagram-node-title">접근 규칙</text><text x="537" y="113" class="diagram-node-detail">객체·행·컬럼 설정</text></g>
+              <g class="diagram-node diagram-node-step diagram-node-accent"><rect x="660" y="52" width="175" height="96" rx="12"/><circle cx="687" cy="77" r="15"/><text x="687" y="82" class="diagram-step-number">4</text><text x="747" y="85" class="diagram-node-title">보호·연결</text><text x="747" y="113" class="diagram-node-detail">VPD·ORDS 대상 확인</text></g>
+              <g class="diagram-node diagram-node-step diagram-node-data"><rect x="870" y="52" width="220" height="96" rx="12"/><circle cx="897" cy="77" r="15"/><text x="897" y="82" class="diagram-step-number">5</text><text x="977" y="85" class="diagram-node-title">유효 권한·접근 검증</text><text x="977" y="113" class="diagram-node-detail">토큰으로 실제 결과 확인</text></g>
+              <path class="setup-flow-return" d="M980 166 V192 H117 V166"/>
+              <text x="548" y="218" class="setup-flow-note">규칙 변경은 다음 요청의 VPD 조건 계산에 동적으로 반영됩니다.</text>
+            </svg>
+          </div>
+        </section>
+
         <section class="product-help-section">
           <h2>요청마다 권한이 적용되는 흐름</h2>
           <div class="diagram-canvas">