# HMM MCP 데모 사용자 preset (#699)

> 상태: Verified / Deployed (2026-07-23)
> 추적: Redmine #699 / Git 브랜치: `hmm-backoffice`
> 대상: `hmm.cloud-handson.com` / `/opt/hmm-poc4`

## 목적

HMM AI 업무 에이전트에서 HMM 가상 HR 조직의 팀장·팀원을 선택해 같은 질문을 사용자 관점으로
시험한다. MCP 접속 토큰과 데모 사용자 정보를 분리하여 토큰 원문을 화면·JSON·Git에 남기지 않는다.

## 구성

```text
vpd_token_presets.json (사용자 ID·역할·팀·테스트 문맥·mcp_token_env)
  → Streamlit 데모 사용자 선택
  → HMM MCP gateway bearer token (HMM_MCP_BEARER_TOKEN, 서버 .env 전용)
  → hmm-mcp.cloud-handson.com/mcp
  → HMM HR Select AI Agent Tool
```

- JSON 파일명은 이전 배포 호환성을 위해 유지한다. 내용은 KB VPD 사용자가 아닌 HMM HR 데모 사용자다.
- 각 preset은 `mcp_token_env`로 서버 환경변수만 참조한다. token 원문은 절대 JSON에 쓰지 않는다.
- 선택한 사용자는 자연어의 ‘나’, ‘내’, ‘우리 팀’을 해석하는 데모 문맥이다. 현재 HMM MCP의 gateway
  token은 공용이므로 이 선택 자체가 DB 행 수준 권한을 강제한다고 표시하지 않는다.
- HMM MCP 허용 도구는 `resolve_hr_term`, `search_hr_data`, `search_hr_policy` 세 개다.
- 호출 인자는 `tools/list`의 schema를 기준으로 생성한다. 기본 도구에도 레거시 `prompt`/`limit`를
  강제하지 않으며 `search_hr_data`·`search_hr_policy`는 `query`, `resolve_hr_term`은 `term`을 전달한다.
- MCP 호환 서버의 `status/result` 응답에서 `result` 문자열은 정책 본문 근거다. 화면 요약에는
  길이와 앞부분을 표시하고, 최종 답변 합성에는 제한된 길이의 원문을 전달한다.
- 사용자 ID·역할·팀 문맥은 `search_hr_data`의 ‘나/우리 팀’ 해석에만 사용한다.
  `search_hr_policy`와 `resolve_hr_term`에는 원 질문/원 용어만 전달해 벡터·lexical 검색어를 오염시키지 않는다.

## 런타임 구성

- Streamlit은 `requirements.txt`의 OCI SDK를 `/opt/hmm-poc4/.venv`에 설치해 사용한다.
- OCI Generative AI 인증은 `/home/opc/.oci/config`의 `DEFAULT` profile과 해당 private key를 사용한다.
- `OCI_AUTH_TYPE=config_file`, `OCI_CONFIG_FILE`, `OCI_PROFILE`, `OCI_GENAI_COMPARTMENT_ID`는
  배포 서버 `/opt/hmm-poc4/.env`에서 관리하고 저장소에는 값을 기록하지 않는다.
- MCP 호출 상세 JSON/code 영역은 공통 `presentation.py`에서 배경·글자색을 함께 고정한다.
- 브라우저의 dark color-scheme과 관계없이 답변 목록, expander header, 보조 버튼도 밝은 배경과
  어두운 글자색을 사용한다.

## 완료 기준

1. 팀장 E1001과 팀원 preset이 사이드바에서 선택된다.
2. MCP bearer token은 화면·대화 JSON·Git에 노출되지 않는다.
3. E1001의 ‘우리 팀 대기 휴가’와 E1005/E1007의 ‘내 휴가’가 HMM MCP로 정상 호출된다.
4. 기존 KB MCP·KB VPD 안내가 HMM HR 질문 생성 경로에 사용되지 않는다.
5. OCI SDK가 `DEFAULT` profile로 GPT-5.4-mini를 실제 호출한다.
6. MCP 호출 상세의 JSON·code가 밝은 테마에서 읽힌다.

## 배포 검증

- `/opt/hmm-poc4/config/vpd_token_presets.json`: E1001, E1002, E1003, E1005, E1007 및
  `HMM_MCP_BEARER_TOKEN` 간접 참조 확인
- MCP `tools/list`: `search_hr_data`, `resolve_hr_term`, `search_hr_policy` 확인
- E1001 문맥의 한국어 `search_hr_data` 실제 호출 및 UTF-8 응답 확인
- `/opt/hmm-poc4/.venv/bin/python`에서 `openai.gpt-5.4-mini` 실제 호출 확인
- systemd `ExecStart`를 `/opt/hmm-poc4/.venv/bin/python -m streamlit ...`로 고정
- Chromium dark color-scheme에서 MCP JSON 계산값 확인:
  배경 `rgb(246, 248, 250)`, 글자 `rgb(23, 43, 58)`
- 정책 질문 브라우저 검증: 12월 31일 기준 사용촉진조치 시 미사용 연차 이월 없음과
  입사 2년차부터 차기 발생연차 50% 선사용 제한을 답변했다.
- dark color-scheme 계산값: expander 배경 `rgb(246, 248, 250)`, 보조 버튼 배경
  `rgb(255, 255, 255)`, 답변 목록·expander·버튼 글자 `rgb(23, 43, 58)`

## 전 화면 브라우저 검증 기준 (2026-07-23)

다음 화면과 패널을 각각 실제 Chromium에서 열어 렌더링, 오류 alert, 핵심 조작, 색상 대비를 확인한다.

1. 로그인: 입력 필드, 로그인 유지, 실패 안내, 정상 로그인, 로그아웃
2. 아키텍처: 운영 구조와 질의 처리 흐름
3. 시나리오: 샘플 선택, 질문 입력, 저장된 답변, MCP 상세
4. 감사로그: HMM 접근 이벤트 유형·상태·기간 필터, 지표와 이벤트 표
5. 보안관리: 업무 프로세스와 `hmm-backoffice` 운영 포털 링크
6. 사이드바: 데모 사용자 5명, 대화 검색·세션, 대화 관리, MCP 고급 설정

페이지 오류, HTTP 4xx/5xx, 흰 배경의 흰 글자, 검은 배경의 검은 글자, 가로 overflow가 없어야 한다.

### HMM 감사로그 데이터 원천

- 포털 감사로그 탭은 KB PoC의 `POC_2` FGA 카탈로그를 조회하지 않는다.
- DB 접속값은 `POC4_AUDIT_DB_USER`, `POC4_AUDIT_DB_PASSWORD`, `POC4_AUDIT_DSN`으로
  분리하고 Git에 값을 저장하지 않는다. ADB가 TLS 서버 인증을 허용하므로 운영 환경은 1521 TLS
  접속 기술자를 사용해 Wallet PEM 암호 입력 대기를 제거한다.
- 상호 TLS가 필요한 다른 환경에서는 `POC4_AUDIT_WALLET_DIR`와
  `POC4_AUDIT_WALLET_PASSWORD`를 함께 지정한다. Wallet 암호 없이 단순 TNS alias만 지정하는
  불완전한 설정은 시작 시 안전한 오류로 처리한다.
- 이벤트 원천은 `ADMIN.HMM_ACCESS_AUDIT`이다. 이벤트 유형, 성공/실패, 대상 key/object, 처리 행 수,
  오류 코드와 메시지를 최근 순으로 표시한다.
- 비활성 Streamlit tab의 글자·배경색도 공통 presentation CSS에서 명시해 OS dark color-scheme과
  무관하게 WCAG AA 수준의 대비를 유지한다.

### 2026-07-23 전수검사 결과

- 실제 Chromium에서 로그인·아키텍처·시나리오·감사로그·보안관리 5개 화면을 각각 열었다.
- 필수 문구 누락 0, 낮은 색상 대비 0, 가로 overflow 0이다.
- 브라우저 page error 0, console error 0, HTTP 오류 0이다.
- 데모 사용자 5명 선택·복원, 대화 검색·JSON 다운로드, MCP discovery cache 갱신을 확인했다.
- 감사로그 필터 2개, 새로고침, 상세 토글이 렌더링되고 `ADMIN.HMM_ACCESS_AUDIT` 0건 상태를
  정상적인 empty state로 표시한다.
- 보안관리의 `https://hmm-backoffice.cloud-handson.com/` 링크는 HTTP 200이다.
- 상세 증적은 `docs/reports/2026-07-23-hmm-portal-full-browser-audit.md`에 기록한다.
