HMM 백오피스 사용자·그룹·역할·토큰 관리 전환 (#702)

상태: Implemented 추적: Redmine #702 / Git 브랜치: hmm-backoffice 대상: hmm-backoffice.cloud-handson.com, HMMAIPOC / ADMIN

목적

기존 KB/VPD 데모의 CB_* 사용자·그룹·역할·Bearer 토큰 모델을 HMM HR 데모의 실제 기준 테이블로 바꾼다. 직원과 조직 정보는 이미 적재된 HMM 테이블을 재사용하고, 접근 제어에만 필요한 테이블은 HMM_ACCESS_* 접두어로 추가한다.

기준 테이블과 소유권

관리 기능	기준 테이블	처리 방식
사용자	`HMM_HR_EMPLOYEES`	기존 직원 ID·사번·성명·소속팀·재직 상태를 직접 사용
조직 참조	`HMM_ORG_TEAMS`	직원 생성 시 소속팀 검증에 사용
접근 그룹	`HMM_ACCESS_GROUPS`, `HMM_ACCESS_GROUP_MEMBERS`	HR 조직과 독립적인 논리 접근 그룹을 새로 관리
역할	`HMM_ACCESS_ROLES`, `HMM_EMPLOYEE_ACCESS_ROLES`, `HMM_GROUP_ACCESS_ROLES`	직원 직접 역할과 그룹 상속 역할을 분리
토큰	`HMM_ACCESS_BEARER_TOKENS`	원문은 발급 화면에서 한 번만 표시하고 SHA-256 해시만 저장
감사	`HMM_ACCESS_AUDIT`	사용자·그룹·역할·토큰 변경 이력 저장
지식 문서	`HMM_KNOWLEDGE_DOCUMENTS`	파일명·원문·BLOB·Abstract·생성일자를 저장
지식 청크	`HMM_KNOWLEDGE_CHUNKS`, `HMM_KNOWLEDGE_TAGS`	문서별 청크와 정규화된 Tag·벡터를 저장

HMM_ORG_TEAMS는 인사 조직 원장이므로 접근 그룹과 혼합하지 않는다. 이로써 한 직원이 여러 업무 접근 그룹에 속하면서도 인사 소속팀은 하나로 유지된다.

데이터 흐름

HMM_HR_EMPLOYEES ──< HMM_EMPLOYEE_ACCESS_ROLES >── HMM_ACCESS_ROLES
        │
        └──< HMM_ACCESS_GROUP_MEMBERS >── HMM_ACCESS_GROUPS
                                                │
                                                └──< HMM_GROUP_ACCESS_ROLES >── HMM_ACCESS_ROLES

HMM_HR_EMPLOYEES ──< HMM_ACCESS_BEARER_TOKENS
HMM_ACCESS_AUDIT records every backoffice change

HMM_KNOWLEDGE_DOCUMENTS ──< HMM_KNOWLEDGE_CHUNKS ──< HMM_KNOWLEDGE_TAGS

화면 및 호환성

/users는 HMM_HR_EMPLOYEES를 사용자 목록으로 표시한다. 활성/비활성은 employment_status의 ACTIVE/INACTIVE에 매핑한다.
/groups는 HMM_ACCESS_GROUPS를 관리한다. HR 팀 이동 기능으로 오해되지 않도록 논리 접근 그룹임을 화면에 명시한다.
/roles는 HMM 접근 역할만 관리한다.
/tokens는 HMM 직원에게 토큰을 발급·회수한다. KB 이해당사자 원장은 참조하지 않는다.
/objects, /permissions, /masking-rules, /probe, MCP 화면은 삭제하지 않는다. 기존 CB 화면 계약은 CB_PROTECTED_*, CB_PERMISSION*, CB_VECTOR_* 호환 뷰로 유지하고, 실제 데이터는 HMM_ACCESS_* 및 HMM_KNOWLEDGE_*에 저장한다.
애플리케이션 시작 시 HmmKnowledgeSchemaInitializer가 HMM 지식 테이블·시퀀스·인덱스를 멱등적으로 준비하고 CB_VECTOR_* 조회 호환 뷰를 갱신한다. 기존 물리 CB_VECTOR_* 테이블이 존재하는 환경은 덮어쓰지 않는다.

재사용 가능한 정형 원장 카탈로그

/structured-data와 /schema-metadata의 데이터 원본명, Oracle owner, 안내 문구, 최대 조회 건수, 허용 테이블 목록은 Java·HTML에 하드코딩하지 않는다.
기본 HMM 정의는 src/main/resources/config/structured-data-catalog.json에 둔다. 배포 환경에서는 BACKOFFICE_STRUCTURED_DATA_CATALOG_LOCATION=file:/.../structured-data-catalog.json으로 외부 JSON을 지정할 수 있어 다른 회사 PoC에서 애플리케이션 코드를 수정하지 않고 재사용할 수 있다.
각 테이블 정의는 key, tableName, businessName, description을 기본으로 하고 필요하면 previewColumns, maskingPolicyName을 추가한다. 화면 카드, metadata 대상, 실제 SELECT 허용 목록, ASO 관리 대상은 모두 이 단일 JSON을 기준으로 생성한다. VECTOR/BLOB 등 JDBC 원장 미리보기에 부적합한 컬럼은 previewColumns에서 제외하되 DB 메타데이터 화면에는 계속 표시한다.
owner와 table name은 Oracle 단순 식별자 규칙, key는 URL key 규칙으로 시작 시 검증한다. 중복 key, 중복 table, 빈 목록, 허용 범위를 벗어난 row limit은 기동 실패로 처리해 동적 SQL 범위를 닫는다.
HMM 기본 카탈로그는 ADMIN의 조직, 직원, 휴가 잔여, 휴가 신청, 일별 근태, HR 표준 용어 원장만 노출한다. 기존 KBAIPOC, POC_2, KB_* 보험 원장은 HMM 배포 카탈로그에 포함하지 않는다.

HMM MCP 및 시스템 설정

운영 MCP 주소는 환경변수 BACKOFFICE_HMM_MCP_PUBLIC_URL로 관리하며 기본값은 사용자 토큰용 주소는 https://hmm-backoffice.cloud-handson.com/mcp이다. 시스템 설정과 MCP 연동 화면은 이 값을 표시하므로 도메인 변경 시 화면 소스를 수정하지 않는다.
HMM MCP와 백오피스 호환 /mcp는 동일하게 resolve_hr_term, search_hr_data, search_hr_policy를 제공한다. 각각 HMM_HR_TERM_RESOLVER, HMM_HR_NORMALIZED_DATA_SEARCH, HMM_HR_POLICY_SEARCH만 읽기 전용으로 실행한다.
ORDS_BASE_URL은 기존 VPD/ORDS 접근 검증과 Handler 관리용 선택 설정이다. HMM HR 질의 및 Agent Factory MCP 호출에는 사용하지 않는다. 비워 두면 레거시 ORDS 기능만 미설정 상태가 된다.
HMM 기동 시 과거 KB 데모의 오사카 ORDS 주소가 정확히 저장된 경우에만 제거한다. 운영자가 별도로 지정한 다른 ORDS 주소는 보존한다.

브랜치·배포 기준

Smilegate 기준은 main이며, HMM 백오피스의 구현·배포·검증은 hmm-backoffice 브랜치만 사용한다.
HMM 배포 전에 현재 브랜치명을 확인하고, main 또는 hmm-ai-agent 브랜치에서는 HMM 백오피스 JAR를 배포하지 않는다.
메뉴 전수 점검은 로그인 세션으로 원래 메뉴 URL 전체를 순회한다. HTTP 200만으로 통과시키지 않고 화면 내 ORA-, 데이터 처리 오류, Whitelabel Error Page도 함께 검사한다.

보안·검증

토큰 원문, DB 비밀번호, Wallet은 테이블·Git·로그에 저장하지 않는다.
DDL은 재실행 가능해야 하며 기존 HR 행을 수정하거나 삭제하지 않는다.
배포 전 전체 자동 테스트를 통과시키고, 배포 후 사용자·접근 그룹·역할·토큰뿐 아니라 보호 객체, 권한, 마스킹, 접근 검증, 지식자료, MCP, 운영 메뉴를 로그인 세션으로 전수 확인한다.

롤백

애플리케이션은 이전 JAR로 되돌릴 수 있다. 새 HMM_ACCESS_* 테이블은 운영 데이터가 생긴 뒤에는 삭제하지 않으며, 문제 발생 시 화면 매퍼만 이전 버전으로 복구한다.

2026-07-23 배포·전수 검증

운영 JSON: /home/opc/apps/vpd-backoffice/config/structured-data-catalog.json
systemd override: 20-structured-data-catalog.conf
자동 테스트: mvn test 103건 통과
브라우저 검증: 로그인 세션으로 메뉴 URL 26개 전부 HTTP 200, 오류 alert 0건, ORA- 0건, KBAIPOC/POC_2/KB 보험원장 표시 0건, page error 0건, console error 0건
정형 원장 실데이터: 조직 1행, 직원 7행, 휴가 잔여 7행, 휴가 신청 8행, 일별 근태 14행, HR 표준 용어 21행 렌더링 확인
용어 원장의 VECTOR 컬럼은 previewColumns에서 제외해 관리자 미리보기에는 사람이 읽을 수 있는 표준 코드·명칭·설명·임베딩 시각만 표시하고, DB 메타데이터 관리에서는 전체 컬럼을 유지한다.