RagService 아키텍처와 소유권 경계

목적

RagService는 기업 내 여러 포탈이 보유한 승인된 문서를 정제·청킹·임베딩·권한 인식 검색·근거 기반 응답으로 처리하는 독립 서비스다. ProcessCenter, DocumentLibrary, GuideCenter 등 개별 포탈은 원본 업무 데이터와 사용자 경험을 소유하며, RagService는 원본의 사본을 권한·보존 정책과 함께 검색용으로 처리한다.

RagService는 원본 시스템을 대체하거나 전사 데이터를 무조건 색인하지 않는다. 포탈별 opt-in 정책, 원본 포탈의 권한 정보, 조직/테넌트/보안등급 RLS 조건이 모두 만족된 콘텐츠만 후보 검색과 LLM 컨텍스트에 사용한다.

공급자 관리 포탈과 설정 소유권

공급자 운영자는 다음 세 관리 포탈을 명확히 분리해 사용한다. 개별 업무 포탈은 이 세 관리 포탈의 정책을 소비하지만, 공급자 관리 역할을 중복 구현하지 않는다.

공급자 관리 포탈	소유 도메인	책임	다른 서비스에서 보이는 범위
PortalConsole	조직·사용자·포탈 등록	등록 포탈 식별자, OIDC/API credential, 중앙 identity·권한 원장, 최초 bootstrap 관리자	RagService와 UiPlatform가 신뢰하는 중앙 원장
RagService	문서 정제·RAG 적용	포탈별 RAG opt-in, 자료 유형, 민감도 상한, 보존기간, 청킹/임베딩/모델, 실패 재처리와 검색 실행	UiPlatform는 서비스 요약과 안전한 진입만 표시
UiPlatform	공통 UI 적용	공통 테마·패키지·UI 배포 대상과 배포 상태	RAG 상세 정책을 중복 보유하지 않음
각 업무 포탈	원본 업무 데이터와 업무 ACL	원본 데이터, 변경 이벤트, 데이터 삭제 통지	RagService에 서명된 수집 계약으로 발행

이 경계는 RagService와 UiPlatform 간 설정 중복·동기화 충돌을 방지한다. 상세 설정은 RagService, 전사 탐색과 요약은 UiPlatform, 포탈 신뢰 원장과 사용자 권한은 PortalConsole에 둔다.

권한과 데이터 흐름

RagService 수집 조건

RagService는 다음 필드를 포함한 포탈 발행 계약 없이는 문서를 수집하지 않는다.

필드	목적
portalId	PortalConsole에 등록된 포탈과의 일치 확인
sourceDocumentId, sourceVersion	멱등 수집·변경 추적·삭제 전파
tenantId, organizationIds, securityLevel	PostgreSQL RLS principal으로 변환
resourceType, classification, retentionUntil	포탈별 RAG opt-in 정책·보존 검증
contentLocator 또는 임시 다운로드 URL	원본 포탈이 제한한 읽기 경로
checksum, contentType, sizeBytes	변조·형식·용량 검사

RAG 검색은 먼저 PostgreSQL RLS에서 후보 행을 제한하고, 그 이후에만 embedding similarity와 LLM 컨텍스트 조립을 수행한다. 애플리케이션 또는 브라우저가 tenant/조직/보안등급을 임의로 공급하거나 상승시킬 수 없다. 조직 조건은 자기 조직 일치가 기본이고, 예외로 공용 버킷(my.app_public_org_id — 전사 공지 등)이 있으면 같은 테넌트의 모든 조직이 읽을 수 있다(등급 조건은 공용 버킷에도 그대로 적용 — infra/postgres/init/10-b2b-rag-rls.sql의 app_rls_allows, 식별자 상수는 ragcenter/identity.py). 기존 배포 반영: init SQL은 컨테이너 초기화 때만 돌므로, 이 변경은 대상 DB에 CREATE OR REPLACE FUNCTION app_current_public_org_id()와 app_rls_allows(...)만 적용하면 된다(테이블·데이터 변경 없음 — psql -f 또는 \i).

PortalConsole 연동 계약

RagService는 PortalConsole에 rag-center 포탈 principal로 등록된다. 중앙 API는 다음의 최소 권한을 분리한다.

연산	요구 scope	설명
등록 포탈 목록 조회	rag:read	RAG 대상 선택 화면의 read-only 목록
포탈 RAG 적용 승인 상태 조회	rag:read	설정 충돌 및 비활성 포탈 확인
포탈별 수집 상태 기록	rag:sync	결과 요약만 기록하며 원문을 전송하지 않음
포탈 관리자 위임 검증	rag:admin	RagService 상세 설정 변경의 중앙 검증

PortalConsole에는 이 전용 read/sync 계약을 별도 endpoint로 추가한다. 기존 ui-center release-status endpoint를 재사용하지 않으며, UI 배포 데이터와 RAG 정책을 섞지 않는다.

배포 원칙

RagService는 컨테이너·VM·온프레미스 어디에서도 같은 API 계약과 PostgreSQL/pgvector 스키마를 사용한다. 문서 변환·OCR·로컬 모델처럼 OS 패키지와 대형 모델이 필요한 작업자는 온프레미스 Docker Compose로 분리할 수 있다. 관리 UI와 API는 stateless로 배포하며, queue/worker는 후속 단계에서 배포 환경에 맞게 별도 확장한다.

관리자 bootstrap과 로컬 위임 모델

RagService와 UiPlatform는 일반 사용자 계정을 별도 생성하지 않는다. PortalConsole에서 중앙 identity를 검증한 Directory 관리자가 최초 bootstrap 관리자로 진입하고, bootstrap 이후에만 서비스별 운영 역할을 위임할 수 있다.

주체	최초 접근	권한	제약
PortalConsole 중앙 관리자	Directory JWT의 directoryAdmin=true 또는 중앙 rag:admin 위임	RagService bootstrap, 모든 정책 설정, 로컬 관리자 위임·철회	PortalConsole 계정이 비활성화·권한 철회되면 즉시 접근 불가
RagService 로컬 관리자	중앙 관리자가 서비스 내부 역할로 위임	포탈 대상 정책, 수집/재처리, 모델·보존 설정, 감사 조회	중앙 계정을 대체할 수 없고 자신의 상위 권한을 부여할 수 없음
RagService 운영자	로컬 관리자가 한정 역할로 위임	수집 상태 확인, 오류 재처리 등 범위 제한 작업	포탈 opt-in, 관리자 위임, 보안 상한 변경 불가
일반 사용자	기본적으로 미부여	RagService 운영 UI 접근 불가	업무 포탈의 권한 범위에서만 RAG 검색 가능

RagService는 매 요청마다 PortalConsole 발급 토큰의 subject, 활성 상태, rag:admin 또는 위임 scope를 검증한다. 로컬 위임 레코드는 중앙 subject를 참조할 뿐 독자 비밀번호·인증 수단을 저장하지 않는다. 중앙 관리자가 처음으로 로그인할 때만 bootstrap role을 idempotent하게 생성하며, 이후 로그인에는 이미 생성된 역할을 재사용한다.

UiPlatform도 동일한 Directory bootstrap 규칙을 사용하지만, RagService의 상세 RAG 정책을 변경하지 않는다. UiPlatform에서는 RagService 관리 서비스의 가용성, bootstrap 완료 여부, 위임 관리자 수, 경고 상태와 안전한 상세 화면 진입만 제공한다.

사용자 포탈과 공통 UI 적용

일반 사용자는 PortalConsole, RagService, UiPlatform의 공급자 운영 화면을 사용하지 않는다. 사용자는 콘텐츠·업무 분류에 따른 ProcessCenter, DocumentLibrary, GuideCenter 등 사용자 포탈에 로그인한다. 각 사용자 포탈은 UiPlatform가 배포·관리하는 공통 UI 패키지와 테마 정책을 적용하고, PortalConsole의 중앙 로그인·조직·권한을 소비한다.

사용자 포탈의 책임	중앙 서비스가 제공하는 기능
업무·콘텐츠 화면, 원본 데이터, 업무별 ACL, 문서 변경·삭제 이벤트	PortalConsole: 로그인·조직·사용자 권한·포탈 등록
포탈별 검색/질문 UI와 근거 표시	UiPlatform: 공통 UI 컴포넌트·테마·배포 정책
RAG 검색 요청의 사용자 세션 전달과 결과 표시	RagService: 승인된 데이터만 정제·색인·RLS 검색·근거 기반 응답

따라서 공통 UI는 모든 사용자 포탈에 적용되지만, RagService의 상세 운영 설정은 사용자 포탈 UI에 복제하지 않는다. 사용자 포탈은 RagService가 발행한 권한 범위 내 결과와 출처만 표시한다.

원본 첨부자산과 RAG 색인 경계

첨부파일의 원본 관리 화면은 RagService에 통합하지 않는다. 원본 자산은 업무 문서와 동일하게 소유 포탈 또는 공통 자산 관리 도메인이 보관·배포·삭제·감사해야 하며, RagService는 해당 파일이 검색 인덱스에 포함될 수 있는지와 현재 처리 상태만 관리한다.

기능	소유 위치	RagService에서의 처리
업로드·다운로드·버전·바이러스 검사·저장소 lifecycle	소유 포탈 또는 공통 Asset/Attachment 관리	수집 전 검증이 완료된 읽기 경로만 수신
업무 엔터티와 첨부파일 연결, 원본 ACL, 삭제	소유 포탈	삭제/ACL 변경 이벤트를 받아 index purge 또는 재권한 처리
텍스트/표/OCR 추출, 청킹, 임베딩, 검색 제외·재색인	RagService	파일별 처리 결과와 실패 사유를 관리 UI에서 제공
전사 첨부파일 탐색·보존 관리	향후 DocumentLibrary 또는 공통 자산 관리 포탈	RAG 상태를 참조 정보로 표시 가능

RagService 운영 화면에는 원본 파일 편집·다운로드 기능 대신 RAG 적용됨, 정제 실패, 재색인 대기, 정책 제외, 원본 삭제 대기와 같은 검색 인덱스 상태만 표시한다.