refs #745: add OCI HMM architecture diagrams

docs/README.md

@@ -17,6 +17,7 @@ docs/
   adr/               ← Architecture Decision Records: 가로지르는 결정 기록
     _TEMPLATE.md
     NNNN-<title>.md
+  architecture/      ← 현행 시스템 아키텍처 Draw.io 원본과 검토용 SVG/PNG
   reference/         ← 레퍼런스: 구현된 모듈/함수/설정 사양 (구현 "후" 동기화)
   guides/            ← How-to / 사용 가이드 / 튜토리얼 (사용자·운영자 대상)
   pipeline/          ← 개발 프로세스 문서 (큐 프로토콜·런북)

docs/architecture/README.md

@@ -0,0 +1,76 @@
+# 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는 사용하지 않는다.

docs/design/745-hmm-oci-architecture/README.md

@@ -0,0 +1,128 @@
+# #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 육안 검사: 흰 배경, 제목 대비, 구성요소 잘림 없음, 주요 연결선과 설명 식별 가능