# HMM AI 데이터 접근 아키텍처

OCI Draw.io Style Guide의 공식 서비스 도형과 Oracle 색상 규칙으로 정리한 HMM 데모
아키텍처다. Draw.io 원본은 두 페이지로 구성한다.

| 페이지 | 설명 | 미리보기 |
|---|---|---|
| `01 · 전체 구성` | HMM 사용자, Compute, Backoffice MCP, ADB, GenAI, Object Storage, AWS RDS federation | [SVG](hmm-ai-data-access-architecture-overview.svg) · [PNG](hmm-ai-data-access-architecture-overview.png) |
| `02 · MCP 요청과 VPD` | Tool 광고 시작 검증, 사용자 Bearer 인증, Agent Tool과 Select AI 분기, `CB_ORDS` VPD 실행 | [SVG](hmm-ai-data-access-architecture-security-flow.svg) · [PNG](hmm-ai-data-access-architecture-security-flow.png) |

편집 원본: [hmm-ai-data-access-architecture.drawio](hmm-ai-data-access-architecture.drawio)

## 현행 기준

- 사용자별 MCP: `https://hmm-backoffice.cloud-handson.com/mcp`
- 공개 Tool 계약: `BACKOFFICE_MCP_TOOLS`
- ADB Agent Tool: `resolve_hr_term`, `search_hr_policy`
- Java Select AI Tool: `search_hr_data`
- Select AI SQL 생성: ADMIN 세션
- 보호 SQL 실행: `CB_ORDS` 비면제 읽기 전용 세션
- VPD 문맥: `HMM_ACCESS_CTX`
- 휴가 정책: `HMM_LEAVE_SCOPE_POLICY`
- 정책 문서: Object Storage PDF → Abstract/Tag/Chunk/Embed 4 Vector
- 선사 실적: AWS RDS PostgreSQL → `HMM_RDS_PG_LINK` → ADB federation View
- 공용 호환 게이트웨이 `hmm-mcp.cloud-handson.com`은 사용자별 VPD MCP 주소가 아니다.

## 흐름을 읽는 방법

- 파란 실선: 사용자 요청 또는 읽기 전용 데이터 실행
- Oracle red 실선: 인증, 보안 Context, VPD 적용
- 주황 점선: 모델 호출 또는 문서 적재
- 회색 실선: 외부 PostgreSQL federation
- 녹색 실선: 정상 결과와 세션 정리

`AGENT_TOOL`과 `SELECT_AI`의 DB 세션은 구분한다.

- `AGENT_TOOL`: 기본 datasource의 같은 connection에서
  `SET_USER_BY_BEARER → DBMS_CLOUD_AI_AGENT.RUN_TOOL → CLEAR_USER`
- `search_hr_data`: ADMIN이 SQL만 생성하고, `CB_ORDS`의 같은 connection에서
  `SET_VPD_CONTEXT → SELECT → ROLLBACK → CLEAR_VPD_CONTEXT`

## 재생성

로컬 OCI 라이브러리 경로를 명시한다. 비밀번호, Token, OCID는 입력하지 않는다.

```bash
node tools/architecture/generate-hmm-oci-architecture.mjs \
  "/Users/joungminko/Downloads/OCI Style Guide for Drawio/OCI Library.xml" \
  docs/architecture
```

SVG와 PNG는 diagrams.net의 embed exporter를 Playwright로 호출해 실제 Draw.io 렌더링과
동일하게 만든다. 인터넷 연결과 Playwright Chromium이 필요하다.

```bash
node tools/architecture/export-drawio.mjs \
  docs/architecture/hmm-ai-data-access-architecture.drawio \
  docs/architecture
```

구조, 필수 문구, OCI stencil, 비밀값 패턴, 렌더링 크기를 검사한다.

```bash
node tools/architecture/validate-hmm-architecture.mjs docs/architecture
```

## 스타일 기준

- 기준 파일: `OCI Library.xml`, `Read-ME.drawio`
- 글꼴: Oracle Sans
- 본문: `#312D2A`
- OCI 경계: `#F5F4F2` / `#9E9892`
- OCI 강조: `#AE562C`
- 보안 강조: `#C74634`
- 외부 Cloud: 흰 배경과 회색 점선
- Style Guide의 안내용 pink와 Courier New는 사용하지 않는다.