From 9f4620505714223868c51ec363856bd3f536412d Mon Sep 17 00:00:00 2001 From: devmrko Date: Mon, 3 Aug 2026 13:32:59 +0900 Subject: [PATCH] docs: add HMM MCP VPD operations guide --- docs/README.md | 8 ++++ docs/runbooks/hmm-mcp-vpd-operations.md | 54 +++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/runbooks/hmm-mcp-vpd-operations.md diff --git a/docs/README.md b/docs/README.md index 4f685e7..38497eb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,3 +61,11 @@ docs/ `Draft`(작성) → `Approved`(QA/Reviewer 통과 후) → `Superseded`(대체 시 상단 표기, 삭제 금지). 구현이 설계서와 달라지면 **코드가 아니라 설계서를 먼저 고치고** 다시 구현한다. ``` +# 문서 안내 + +## HMM 운영 문서 + +- [HMM MCP·VPD 운영 가이드](runbooks/hmm-mcp-vpd-operations.md) +- [HMM MCP 토큰 설정](runbooks/hmm-mcp-token-configuration.md) + +공통 MCP·VPD·Data Redaction·DDS 절차는 `main`의 공통 운영 문서를 기준으로 한다. diff --git a/docs/runbooks/hmm-mcp-vpd-operations.md b/docs/runbooks/hmm-mcp-vpd-operations.md new file mode 100644 index 0000000..8807a86 --- /dev/null +++ b/docs/runbooks/hmm-mcp-vpd-operations.md @@ -0,0 +1,54 @@ +# HMM MCP·VPD 운영 가이드 + +## 1. 적용 범위 + +이 문서는 HMM 백오피스와 AI Web Agent Console의 운영 특성만 다룬다. 공통 MCP, +VPD, Data Redaction, DDS 설치·검증 원칙은 `main`의 공통 운영 문서를 따른다. + +## 2. HMM 실행 흐름 + +```text +업무 사용자 로그인 + → HttpOnly 인증 cookie 또는 Bearer 검증 + → MCP 요청의 업무 사용자 결정 + → 팀·담당 선사 권한을 DB context에 설정 + → 보호된 HMM View 조회 또는 Select AI 도구 호출 + → VPD 행 제한 · Redaction 적용 · FGA 증적 기록 + → 선사 KPI·배정·휴가/조직 정보 반환 +``` + +서비스 계정 또는 OCI client-credentials token은 서비스 연결 승인용이다. 업무 사용자 +권한은 로그인 사용자와 `CB_*` 권한 매핑, 팀·담당 선사 데이터로 결정한다. + +## 3. 운영 데이터와 권한 기준 + +| 영역 | 권한 기준 | 확인 대상 | +| --- | --- | --- | +| 선사 KPI | 사용자의 팀·담당 선사 | VPD predicate, 선사 배정 | +| 조직/휴가 | 사용자·팀 소속 | leave/team VPD policy | +| MCP 도구 | 광고된 도구와 사용자 인증 | `BACKOFFICE_MCP_TOOLS`, `tools/list` | +| 민감 정보 | Redaction 정책과 예외 권한 | 대상 컬럼, policy, 조회 결과 | + +## 4. 일상 점검 순서 + +1. 로그인 사용자와 MCP Bearer가 같은 업무 주체로 해석되는지 확인한다. +2. `tools/list`의 공개 도구와 실제 호출 가능 도구가 일치하는지 확인한다. +3. 서로 다른 팀 또는 담당 선사 사용자가 같은 질문에서 다른 행 집합을 받는지 확인한다. +4. 민감 컬럼의 마스킹 결과와 FGA의 `CLIENT_IDENTIFIER`, `RLS_INFO`를 확인한다. +5. 권한 변경 뒤 다음 요청에 즉시 반영되는지 확인한다. + +## 5. 장애 대응 + +| 증상 | 확인 순서 | +| --- | --- | +| 로그인했는데 MCP 401/403 | cookie/Bearer, 사용자 매핑, 토큰 만료·회수 | +| 선사 데이터가 0건 | 팀·담당 선사 배정, session context, VPD predicate | +| 다른 팀 데이터 노출 | 보호 View, VPD policy 적용 객체, 권한 매핑 | +| MCP 도구 호출 실패 | 환경변수 도구 목록, 입력 스키마, endpoint 상태 | +| 감사 행 없음 | 요청 식별자, FGA policy, Unified Audit Trail | + +## 6. 관련 자료 + +- [HMM MCP VPD 런타임 설계](../design/740-hmm-mcp-vpd-runtime/README.md) +- [HMM MCP Bearer 설계](../design/712-hmm-backoffice-mcp-bearer/README.md) +- [HMM 토큰 설정 런북](hmm-mcp-token-configuration.md)