vpd-permission-poc/docs/design/577-persona-ux-audit/README.md

# VPD 권한 운영 전 페이지 페르소나 UX 리뷰와 개선 로드맵

> **상태**: Review complete · UX-1/UX-2 implementation in progress
> **작성**: [AI] UX Facilitator · **최종수정**: 2026-06-30
> **추적성** — Redmine: #577 · 하위 구현: #575 대시보드, #576 기본 검증 사용자명, #599 설정, #605 권한 관리

## 1. 리뷰 방법

세 페르소나가 같은 화면을 다른 기준으로 검토했다.

| 페르소나 | 실패로 보는 상황 | 판단 기준 |
|---|---|---|
| UI/UX 전문가 | 정보가 같은 밀도로 쏟아져 다음 행동을 고르지 못함 | 시선 순서, 한 화면의 결정 수, 진행 상태, 빈 상태 |
| 권한 설계자 | 편한 조작이 권한 영향·fail-closed 원칙을 숨김 | 대상/주체/효과/영향 범위, 복구 가능성, 증적 |
| 엔드유저 | “그래서 지금 뭘 해야 하지?”를 5초 안에 답하지 못함 | 업무 언어, 기존 값 확인, 성공 기준, 되돌리기 |

공통 결론은 **설명은 충분하지만, 실행 화면이 ‘관리 매뉴얼’처럼 길다**는 점이다. 모든 페이지를 카드로 더 꾸미는 대신 다음 원칙으로 정리한다.

1. 첫 화면에는 주 행동 하나와 현재 상태만 둔다.
2. 대상·주체·영향을 입력 전에 보여 주고, 기술 설명은 접는다.
3. 목록은 탐색용, 상세/편집은 선택한 항목 중심으로 분리한다.
4. VPD·토큰·ORDS는 같은 검증 여정으로 연결하고 성공 증적을 다음 화면으로 넘긴다.

## 2. 페이지별 토론과 개선 백로그

| 페이지 | UI/UX 전문가 | 권한 설계자 | 엔드유저 | 합의한 개선 | 우선순위 |
|---|---|---|---|---|---|
| 대시보드 | 설명·현황·표가 동등하게 경쟁 | 보호 상태의 근거가 약함 | 다음 행동이 불명확 | 핵심 작업·현재 상태·4단계 레일만 전면, 상세 접기 — **#575 완료** | 완료 |
| 사용자 | 생성/목록/역할 부여가 세 구역으로 흩어짐 | 역할 해제 영향이 안 보임 | “이 사람에게 지금 어떤 권한이 있나?”를 다시 찾아야 함 | 행 선택 시 현재 역할·그룹·토큰 요약을 보여 주는 사용자 작업 패널, 역할 부여 전 영향 미리보기 | P0 |
| 그룹 | 사용자와 역할 배정이 긴 한 페이지에 누적 | 그룹 상속 범위가 숨음 | 그룹을 바꾸면 누가 영향받는지 모름 | 그룹 선택형 master-detail, 영향 사용자 수·상속 역할을 상단에 고정, 해제 전 영향 확인 | P0 |
| 역할 | 민감도·설명·삭제가 표 안에서 동등 | 역할 삭제/변경 영향이 중요 | 역할이 누구에게 쓰이는지 모름 | 역할 상세에서 연결 사용자·그룹·권한을 먼저 보여 주고, 삭제는 영향 없음일 때만 노출 | P0 |
| 권한 관리 | wizard가 길고 선택의 결과가 늦게 보임 | ALLOW/DENY, 행/열 규칙의 조합 위험 | ‘ALL’을 누르면 무엇이 보이는지 불안 | 역할→객체→행 범위→컬럼→검토의 5단계 progress, 즉시 영향 문장과 변경 요약 고정 | P0 |
| 유효 권한 매트릭스 | 사용자/그룹/역할 표 세 개가 한꺼번에 큼 | 최종 권한 근거를 추적해야 함 | 내 사용자 하나만 보고 싶음 | 기본은 사용자 탭+검색, 선택 시 권한 근거 타임라인; 그룹/역할은 보조 탭으로 분리 | P0 |
| ORDS 조회 대상 | 등록·경로·핸들러 설정이 한 화면에 섞임 | 보호 대상과 handler 연결 상태를 분리해야 함 | 무엇을 등록해야 하는지 모름 | 객체 등록 후 ‘보호 연결하기’ 단계 CTA, 목록에는 VPD/handler/검증 상태 배지 | P1 |
| DB 보호 연결 | 객체 목록·개별 적용·일괄 적용·정책 목록이 매우 김 | 적용/해제의 DB 영향이 중요 | 어떤 객체부터 연결할지 모름 | 미연결 객체를 기본 큐로, 선택 시 영향/복구 설명과 검증 CTA; 일괄 적용은 고급으로 접기 | P0 |
| 검증 세션 | 발급과 이력이 분리되어 다음 행동이 약함 | 토큰 원문 보안과 만료가 핵심 | 발급 뒤 무엇을 복사/어디로 가나 | 사용자 선택→만료→발급→즉시 결과 확인의 단일 handoff, 이력은 보조 탭 | P0 |
| 권한 결과 확인 | 입력과 증적이 좋지만 초보자가 object/token 선택에서 멈춤 | VPD predicate와 실제 결과는 반드시 함께 보여야 함 | 내 상황으로 빠르게 시험하고 싶음 | ‘검증 사용자’ 기본 모드와 ‘Bearer 직접 입력’ 고급 모드 분리, 결과에 다음 조치 추천 | P0 |
| ORDS 핸들러 | 소스·편집이 기술자 화면으로 바로 열림 | handler 변경은 VPD 우회 위험 | 보통 사용자는 건드릴 이유가 없음 | 상태/경로/보호 객체만 기본 표시, 소스·수정은 고급 상세와 영향 경고로 격리 | P1 |
| 지식 검색 관리 | 등록·정책·검색 세 큰 작업이 세로로 길게 누적 | 벡터 검색과 접근 조건을 혼동하기 쉬움 | 검색만 해 보고 싶음 | ‘자료 등록 / 접근 정책 / 검색 검증’ 탭화, 검색을 기본 탭으로 하고 정책은 요약 배지 | P1 |
| MCP Chatbot | 대화, 토큰, 기술 설명의 경계가 약함 | 도구 호출과 권한 결과의 근거 필요 | 질문만 하고 싶음 | 질문 패널 우선, 호출된 도구·권한 근거는 답변 아래 접힌 evidence로 표시 | P1 |
| MCP Reasoning | 도구 목록과 실행 입력이 같은 밀도 | 자동 선택 근거/권한 거부를 보여야 함 | 왜 이 도구가 선택됐는지 알고 싶음 | 질문→선택 도구→권한 결과→답변의 단계형 결과 타임라인 | P1 |
| MCP Client | Java 호출, 흐름, 설정이 한 페이지 | 실행 대상 endpoint 검증 필요 | API 호출 방법만 알고 싶음 | 복사 가능한 최소 호출 예시를 전면, 런타임 진단·프로토콜 설명은 접기 | P2 |
| MCP SSE | endpoint/tool/JSON-RPC 예시가 문서형 | 배포/인증 상태가 우선 | 연결 가능한지부터 알고 싶음 | 연결 상태·endpoint 복사·도구 수를 상단 요약, 프로토콜 예시는 탭/상세로 이동 | P2 |
| 운영 상태 | 표 중심의 상태 나열 | 장애 시 영향 범위/복구가 필요 | 지금 정상인가만 알고 싶음 | 건강/주의/장애를 요약 배너로, 항목별 영향·권장 조치·최근 확인 시각 제공 | P1 |
| 설정 | ORDS, schema preview, 초기화가 한 화면에 있고 위험 | 초기화는 오조작 방지가 필요 | URL만 바꾸고 싶음 | 연결 설정과 DB 초기화를 분리; 초기화는 별도 위험 화면·명시 확인·백업 안내 | P0 |
| 별도 Filter 관리 | 고급 내용을 충분히 경고하지만 길다 | 기본 권한체계 우회 여부가 중요 | 이 화면을 써야 하는지 모르겠음 | 시작 시 ‘기본 권한으로 가능한가?’ 결정 카드, 실제 filter 편집은 조건 충족 시에만 열기 | P1 |
| 로그인 | 업무 시작점/권한 범위 설명 없음 | 운영 계정임을 명확히 해야 함 | 어디에 로그인하는지 모름 | 제품 목적·환경 표시·지원 경로를 최소한으로 추가 | P2 |

## 3. 우선순위와 실행 묶음

| 실행 묶음 | 페이지 | 목표 | 선행/완료 조건 |
|---|---|---|---|
| UX-1 권한 주체와 최종 권한 | 사용자, 그룹, 역할, 유효 권한 매트릭스 | ‘누가 어떤 역할을 통해 무엇을 보는가’를 한 흐름으로 이해 | 영향 미리보기, 선택형 상세, 사용자 중심 매트릭스 |
| UX-2 보호·검증 여정 | 권한, DB 보호 연결, 토큰, probe, 설정 | 권한 생성부터 실제 DB 증적까지 끊기지 않게 연결 | 단계별 handoff, 위험/복구 안내, 고급 분리 |
| UX-3 연동 도구 정리 | objects, ORDS, vector, MCP 4종, 운영 상태, filter | 운영 화면과 개발자 화면의 밀도를 분리 | 요약 상태 우선, 기술 상세 접기/탭화 |
| UX-4 일관성 정리 | 로그인, 빈 상태, 문구, 배지, 모바일 | 모든 화면의 용어·행동·상태 표현을 정렬 | 공통 컴포넌트/카피 가이드 |

## 4. 첫 구현 범위: UX-1

UX-1부터 시작한다. 기존 데이터 모델과 VPD 로직은 바꾸지 않고 화면의 정보 구조만 바꾼다.

1. 사용자/그룹/역할 화면에 선택된 주체의 현재 연결과 영향 수를 먼저 보여 준다.
2. 유효 권한 매트릭스는 기본을 ‘사용자’로 두고, 선택한 사용자 한 명의 직접 역할·그룹 상속·최종 역할·보호 객체 근거를 순서대로 표시한다.
3. 그룹/역할 기준 전체 표는 보조 탐색으로 유지하되 기본 접힘 또는 탭 뒤로 보낸다.
4. 이 변경 뒤 실제 사용자 `김어드민`, `박파이넨스`, `이에이치알`로 권한 근거와 probe 결과를 교차 검증한다.

## 5. 완료 정의

- 각 실행 묶음은 Redmine 하위 이슈, 설계서, 테스트, 실제 배포 HTTP 확인을 남긴다.
- 화면 변경은 권한 계산·VPD predicate·토큰 보안 동작을 바꾸지 않는다.
- UI/UX 전문가, 설계자, 엔드유저 관점의 미해결 반론이 있으면 이 문서와 Redmine에 기록하고 다음 묶음에서 해소한다.

## 6. UX-1 진행 기록

- 유효 권한 매트릭스를 사용자 중심 탭형 구조로 변경했다. 기본 화면은 선택한 사용자 한 명의 직접 역할, 그룹 상속, 최종 역할, 보호 객체, 권한 수를 보여 준다.
- 그룹/역할 전체 표는 제거하지 않고 보조 탭으로 이동했다.
- 복합 Thymeleaf 속성과 layout fragment를 실제로 처리하는 `EffectiveMatrixTemplateRenderTest`를 추가해 UI template parse 오류를 빌드에서 검출한다.

## 7. UX-2 진행 기록 — 권한 생성 안전성 (#605)

권한 관리 화면은 5단계 구조가 있었지만, 이전에는 다음 단계와 단계 표시를 눌러 필수 선택을 건너뛸 수 있었다. `ALL`과 조건 규칙을 섞으면 서버가 저장 시 거부했기 때문에, 사용자는 긴 입력 뒤에야 실패를 알게 됐다.

- 역할과 보호 객체에 빈 선택지를 두어 적용 주체와 대상을 명시적으로 고르게 한다.
- 다음/단계 이동/저장 시 1~3단계를 검증한다. 빠진 역할·객체·비교 값, 중복 규칙, `ALL`과 조건 규칙의 혼용은 해당 단계에서 이유를 보여 주고 이동을 막는다.
- 상단 요약에 직접 사용자·그룹·그룹 상속 사용자 수와 저장 준비 상태를 고정한다.
- 최종 검토에 `전체 행 허용/거부` 또는 조건부 영향 문장과 되돌리기 방법을 표시한다. 마지막 권한을 삭제하면 보호 객체가 비활성화될 수 있음을 저장 전에 안내한다.
- 브라우저 검증을 우회한 POST도 역할 누락·객체 형식·행 규칙 오류를 flash 오류로 돌려준다. 서버의 `PermissionService` 검증은 그대로 최종 방어선으로 유지한다.

검증 범위는 `GuidedFlowTemplateTest`, `PermissionServiceTest`, 전체 Maven 테스트 및 배포 후 `/permissions` HTTP 확인이다.

## 8. 제품 표면 명칭 정리 — VPD 권한 운영

`VPD Backoffice`는 구현 방식과 내부 운영 도구 성격만 드러내므로 제품 표면에서 제거한다. 제품명은 **VPD 권한 운영**으로 통일한다. VPD는 보호 방식의 이름으로 유지하되, ORDS·Handler·Filter·MCP 같은 구현 용어는 고급 운영 또는 기술 상세에서만 사용한다.

| 기존 표현 | 제품 표면 표현 | 비고 |
|---|---|---|
| VPD Backoffice | VPD 권한 운영 | 상단, 로그인, 브라우저 제목 |
| 권한 관리 | 접근 규칙 | 역할별 데이터 범위 설정 |
| DB 보호 연결 / VPD 설정 | 보호 상태 | DB 객체 보호 정책의 확인·연결 |
| 권한 결과 확인 | 접근 검증 | 검증 세션으로 실제 조회 실행 |
| ORDS 조회 대상 | 조회 대상 | ORDS는 화면 상세에서만 표기 |
| ORDS 핸들러 | 조회 연동 | 고급 운영 메뉴 |
| 지식 검색 관리 | 지식자료 관리 | 등록·정책·검색 기능 |
| 별도 Filter 관리 | 고급 접근 조건 | 예외 정책 기능 |
| 운영 상태 / 연결 설정 | 운영 현황 / 시스템 설정 | 운영성·연동 설정 기능 |

상단 메뉴는 DDS와 같은 네 업무 영역인 `권한 관리 · 보호 정책 관리 · 지식자료 관리 · 접근 검증`으로 구성한다. ORDS·MCP·Filter·시스템 설정은 기본 제품 메뉴에서 빼고 관련 화면의 고급 링크에서만 연다. 절차나 구현 방식이 아니라 사용자가 하려는 일을 메뉴명으로 쓴다. 메뉴와 기본 화면에는 `1.`, `2.`, 단계 레일, `01/02` 배지를 두지 않는다. 순서가 실제 입력 제약인 wizard에서만 단계 번호를 사용한다.

기본 페이지는 제목과 현재 설정·주요 행동만 노출한다. VPD/ORDS 처리 원리, 배경 설명, 주의사항은 상단의 공통 `도움말` 버튼을 눌렀을 때만 펼친다. 이 규칙으로 제품 화면이 관리 매뉴얼처럼 보이는 문제를 줄이고, 설정 자체를 전면에 둔다.