#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: 전체 구성

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

HMM 사용자: 팀장, 팀원, 관리자
인터넷 공개 HTTPS: hmm.cloud-handson.com, hmm-backoffice.cloud-handson.com
OCI 서울 리전
- Compute VM + Nginx
- AI Web Agent Console
- VPD Backoffice + 사용자 Bearer MCP /mcp
- OCI Object Storage의 HR PDF
- Autonomous Database HMMAIPOC
- OCI Generative AI
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 적용 흐름

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

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

검증

.drawio가 XML로 파싱되고 페이지가 정확히 2개다.
두 페이지 모두 필수 구성요소와 흐름 라벨을 포함한다.
공식 OCI 라이브러리 stencil이 원본에 포함된다.
SVG를 PNG로 렌더링해 잘림, 겹침, 읽기 어려운 글자, 불필요한 선 교차를 확인한다.
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 육안 검사: 흰 배경, 제목 대비, 구성요소 잘림 없음, 주요 연결선과 설명 식별 가능

5.8 KiB Raw Blame History Unescape Escape