vpd-permission-poc/docs/design/702-hmm-backoffice-identity/README.md

# 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 메타데이터 관리에서는 전체 컬럼을 유지한다.