# #745 OCI 스타일 HMM AI 데이터 접근 아키텍처

> 상태: Approved
> Redmine: #745
> 구현 산출물: `docs/architecture/hmm-ai-data-access-architecture.*`
> 생성 도구: `tools/architecture/generate-hmm-oci-architecture.mjs`

## 목적

HMM 데모의 애플리케이션, MCP, ADB 보안 실행 경계, AI 모델, 문서 지식과 외부
PostgreSQL federation을 한 장에서 설명할 수 있는 아키텍처 그림을 만든다. 세부 요청 흐름은
두 번째 페이지에 분리해 사용자 Bearer Token이 실제 VPD 행 필터로 연결되는 지점을 명확히 한다.

기준 스타일은 `/Users/joungminko/Downloads/OCI Style Guide for Drawio`의
`OCI Library.xml`과 `Read-ME.drawio`다. OCI 서비스는 공식 라이브러리 도형을 사용하고,
외부 서비스는 `3rd Party Cloud` 경계와 중립 색상으로 구분한다.

## 산출물

| 파일 | 용도 |
|---|---|
| `docs/architecture/hmm-ai-data-access-architecture.drawio` | 편집 가능한 2페이지 원본 |
| `docs/architecture/hmm-ai-data-access-architecture-overview.svg` | 전체 구성 검토·문서 삽입용 |
| `docs/architecture/hmm-ai-data-access-architecture-security-flow.svg` | 요청·보안 흐름 검토용 |
| 같은 이름의 `.png` | 일반 문서·메신저 공유용 |
| `docs/architecture/README.md` | 범례, 현행 기준, 편집·재생성 방법 |

## 페이지 1: 전체 구성

다음 경계를 왼쪽에서 오른쪽으로 배치한다.

1. HMM 사용자: 팀장, 팀원, 관리자
2. 인터넷 공개 HTTPS: `hmm.cloud-handson.com`, `hmm-backoffice.cloud-handson.com`
3. OCI 서울 리전
   - Compute VM + Nginx
   - AI Web Agent Console
   - VPD Backoffice + 사용자 Bearer MCP `/mcp`
   - OCI Object Storage의 HR PDF
   - Autonomous Database HMMAIPOC
   - OCI Generative AI
4. 3rd Party Cloud: AWS RDS for PostgreSQL

ADB 내부에는 아래 실행 요소를 표시한다.

- MCP Tool catalog와 시작 검증: `BACKOFFICE_MCP_TOOLS` → `USER_AI_AGENT_TOOLS.ENABLED`
- ADB Agent Tool: `resolve_hr_term`, `search_hr_policy`
- Java `SELECT_AI`: `search_hr_data`
- 비면제 런타임 사용자 `CB_ORDS`
- `HMM_ACCESS_CTX`, `HMM_LEAVE_SCOPE_POLICY`, HR 정형 테이블
- 문서 메타데이터, Abstract, Tag, Chunk, Embed 4 Vector
- `HMM_RDS_PG_LINK`와 `HMM_RDS_*_V`, 선사 배정 View

모델 연결은 용도를 구분한다.

- GPT-5.4 Mini: 질문 계획, Select AI SQL 생성, 답변 합성
- Cohere Embed 4: HR 용어와 정책 문서 임베딩

## 페이지 2: MCP 요청과 VPD 적용 흐름

다음 순서를 번호로 표시한다.

1. Agent가 인증된 `initialize`/`tools/list`를 호출한다.
2. 백오피스가 사용자 Bearer Token의 해시, 만료, 회수와 재직 상태를 확인한다.
3. `tools/call`에서 Tool 유형을 분기한다.
4. `AGENT_TOOL`은 `DBMS_CLOUD_AI_AGENT.RUN_TOOL`을 호출한다.
5. `search_hr_data`는 ADMIN 세션에서 `DBMS_CLOUD_AI.GENERATE(..., 'showsql')`로
   승인 객체만 사용하는 읽기 전용 SQL을 만든다.
6. 같은 `CB_ORDS` JDBC 세션에서 `CB_ORDS_HANDLER_PKG.SET_VPD_CONTEXT`를 호출한다.
7. `HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER`가 `HMM_ACCESS_CTX`를 설정한다.
8. `CB_ORDS`가 SQL을 실행하면 `HMM_LEAVE_SCOPE_POLICY`가 SELF/MANAGED_TEAM/ALL
   predicate를 자동 적용한다.
9. 트랜잭션을 rollback하고 `CLEAR_VPD_CONTEXT`로 세션 문맥을 제거한다.
10. 필터링된 결과와 근거만 Agent에 반환한다.

서버 기동 흐름은 요청 흐름과 분리한다. `AGENT_TOOL targetName`이
`USER_AI_AGENT_TOOLS`에 없거나 `ENABLED`가 아니면 서버는 준비 상태가 되지 않으며
불완전한 `tools/list`를 광고하지 않는다.

## 시각 규칙

- 기본 글꼴: `Oracle Sans`, 대체 글꼴 `Arial`, `sans-serif`
- 본문 색: `#312D2A`
- OCI 경계 배경/선: `#F5F4F2` / `#9E9892`
- OCI 강조선: `#AE562C`
- Oracle red 강조: `#C74634`
- 외부 Cloud 경계: 흰색 배경, `#6B7280` 점선
- 정상 데이터 흐름: 실선, 보안·컨텍스트 적용: Oracle red 실선, 관리/적재: 점선
- 선 교차를 최소화하고 연결선에는 동작 이름을 직접 표기한다.
- 스타일 가이드의 안내 전용 pink와 Courier New는 사용하지 않는다.

## 생성기 계약

`generate-hmm-oci-architecture.mjs`는 OCI Library 경로와 출력 디렉터리를 인자로 받는다.
라이브러리에서 아래 공식 도형을 제목으로 찾아 원본 Draw.io에 포함한다.

- `Identity and Security - User`
- `Compute - Virtual Machine VM`
- `Database - Autonomous DB`
- `Analytics and AI - Artificial Intelligence`
- `Storage - Object Storage`
- `Identity and Security - Vault`

필수 도형이 없으면 불완전한 그림을 만들지 않고 실패한다. 생성 결과는 비밀번호, Token,
OCID를 포함하지 않는다.

## 검증

1. `.drawio`가 XML로 파싱되고 페이지가 정확히 2개다.
2. 두 페이지 모두 필수 구성요소와 흐름 라벨을 포함한다.
3. 공식 OCI 라이브러리 stencil이 원본에 포함된다.
4. SVG를 PNG로 렌더링해 잘림, 겹침, 읽기 어려운 글자, 불필요한 선 교차를 확인한다.
5. `git diff --check`와 비밀값 패턴 검사를 통과한다.

## 롤백

`docs/architecture/hmm-ai-data-access-architecture*`와 생성기를 제거하면 된다. 애플리케이션,
DB, OCI 리소스와 운영 설정은 이 작업에서 변경하지 않는다.

## 검증 결과

- Draw.io XML 파싱: PASS
- 페이지 수와 이름: `2` / `01 · 전체 구성`, `02 · MCP 요청과 VPD`
- OCI 공식 stencil 포함: PASS
- 필수 구성요소·보안 흐름 검사: PASS
- 비밀값 패턴 검사: PASS
- 동일 입력 재생성 byte 비교: PASS
- diagrams.net 실제 렌더링: `1840×1120`, `1840×1090`
- PNG 육안 검사: 흰 배경, 제목 대비, 구성요소 잘림 없음, 주요 연결선과 설명 식별 가능