vpd-permission-poc/docs/design/576-human-readable-verification-users/README.md

설계서: 기본 검증 사용자의 사람 이름 표시 (#576)

상태: Implemented · QA passed 작성: [AI] Architect · 최종수정: 2026-06-30 추적성 — Redmine: #576 · 구현: 17_agent_ords_security_local_vpd_setup.sql, 39_agent_ords_default_user_display_name.sql, 사용자·매트릭스·probe 화면

목적

agent_all, agent_fin_self, agent_hr는 사용자명인데 역할명처럼 읽혀 사용자와 권한 범위를 혼동시킨다. 사용자명은 사람이 식별되는 이름으로 표시하고, 권한 범위는 기존 역할명으로 분리한다.

user_id	이전 사용자명	새 사용자명	유지되는 역할
101	agent_hr	이에이치알	HR_DEPT_ROLE
102	agent_fin_self	박파이넨스	FIN_SELF_ROLE
103	agent_all	김어드민	ALL_DOC_ROLE

영향과 안전성

• user_id를 유지하므로 CB_AGENT_BEARER_KEY.user_id, CB_USER_ROLE, 그룹 상속, VPD context 및 기존 토큰은 변하지 않는다.
• 운영 DB에는 idempotent rename migration(39)을 적용한다. seed(17)도 같은 이름으로 갱신해 새 환경이 일관되게 생성된다.
• agent_sales 등 별도 업무 시나리오 사용자는 이번 범위에서 바꾸지 않는다.

인수조건

• 사용자·유효 권한·probe 화면이 새 사용자명을 표시한다.
• role 10·20·30과 user ID 101·102·103의 매핑은 유지된다.
• 기존 발급 토큰으로 VPD/ORDS 조회가 계속 동작한다.
• seed와 운영 migration이 같은 이름을 적용한다.

QA 결과

• 39_agent_ords_default_user_display_name.sql을 운영 DB에 적용했다.
• mvn test: 60 tests, 0 failures.
• 인증된 사용자 목록·유효 권한 화면에서 새 사용자명과 기존 역할명 분리를 확인했다.
• vector /probe smoke: 101=이에이치알, 102=박파이넨스, 103=김어드민으로 표시되며 각각 기존 1 = 1 VPD predicate, SCORE Top-K, WHERE d.embedding IS NOT NULL ORDER BY score 결과를 유지했다.