refs #745: add OCI HMM architecture diagrams

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는 사용하지 않는다.