UI플랫폼(UiPlatform) 재편 범위 — 표현 규칙 전용 vs 공통 플랫폼 서비스군
작성 시각: 2026-09-13 상태: 검토(결정 전) — 확정 시 docs/DECISION_LOG.md에 결정을 기록하고 docs/SERVICE_BOUNDARIES.md를 갱신한다.
1. 이 문서의 목적
UiPlatform를 UI플랫폼으로 개명·재편할 때 책임을 표현 규칙(UI) 전용으로 유지할지, 공통 플랫폼 서비스군(AI·검색 등 포함)으로 확장할지 결정하기 위한 근거를 정리한다. AI 기능을 어디에 두는지가 이 결정에 직접 걸려 있다.
2. 현재 확정된 플랫폼 경계 (기존 문서 근거)
| 서비스 | 확정된 책임 | 근거 문서 |
|---|---|---|
| PortalConsole (PortalConsole) | 사용자·조직·인증·포털 등록·포털 접근권한·capability·endpoint·운영 상태 | PortalConsole/docs/SERVICE_BOUNDARIES.md |
| UI플랫폼 (UiPlatform) | 공통 UI 패키지·테마·릴리스 workflow·포털별 구독·배포 요청·적용 상태 | UiPlatform/docs/SERVICE_BOUNDARIES.md |
| FileStore | 첨부 원본 저장·보호·감사·보존, 승인 파일을 RagService로 발행(ragPublishAllowed) | FileStore/docs/ARCHITECTURE.md |
| RagService | 발행 파일의 정제·색인·RLS 검색, 답변 생성 로직 | FileStore/docs/ARCHITECTURE.md, UiPlatform/docs/SERVICE_BOUNDARIES.md |
| ExploreGateway | 다중 포털 검색 조합 | PortalConsole·UiPlatform SERVICE_BOUNDARIES.md |
| 각 소비 포탈 (ProcessCenter 등) | 고유 업무 기능·화면·DB·배포 운영 정책 | UiPlatform/docs/ARCHITECTURE.md |
UI플랫폼의 금지 의존성(이미 문서에 명시): 포털 업무 데이터 · 사용자별 업무 권한의 최종 판정 · ExploreGateway의 검색 실행 · FileStore의 파일 본문 · RagService의 인덱스와 답변 생성 로직.
즉 "AI/검색은 UI플랫폼이 소유하지 않는다"가 이미 경계 문서로 확정돼 있다.
3. AI 기능 3계층의 배치 (제안)
| AI 계층 | 예시 | 소유자(제안) | 근거 |
|---|---|---|---|
| 계약·유틸 | provider 계약·구조화 JSON·요약 유틸 (@hohyun94/portal-ai) | portal-foundation(공용 라이브러리) | 소비 포털이 빌드해야 하는 재사용 계약 |
| 포털별 적용 | 게시본 요약 트리거, 번역 대상 필드 | 각 소비 포탈 | 업무 정책 |
| LLM 완성(모델·키·비용·감사·프롬프트) | 요약·번역·정합성 분석 | RagService(범위 포함 여부 결정) | 이미 답변 생성·인덱스를 소유 |
| 벡터 색인·RLS 검색 | 유사 문서·질의응답 | RagService | 기존 확정 |
| 다중 포털 검색 조합 | 통합 검색 | ExploreGateway | 기존 확정 |
| 원본 파일·발행 | 첨부·스캔·발행 | FileStore | 기존 확정 |
UI플랫폼은 위 어느 계층도 소유하지 않는다 — 기존 금지 의존성과 일치한다.
4. 실측: 현재 중복과 이관 후보
UiPlatform가 실제로 가진 데이터(스키마 실측) — 표현 규칙·릴리스·배포·런타임 설정에 한정된다. ui_theme_drafts · ui_theme_release_artifacts · ui_theme_deployment_queue · ui_portal_theme_policies · ui_center_runtime_config (+ 서버 모듈: themePolicyApi, themeDeploymentWorker, themeWorkflow, uiCenterStatus, boardVariants, lightThemeContract)
ProcessCenter가 자체 제공 중인 라우터 — 실측 검증 결과
| 라우터 | 성격(검증) | 판단 |
|---|---|---|
themePolicy | 이미 위임 완료 — server/themePolicyGateway.ts가 UiPlatform의 /api/portal-theme/v1/catalog·/policy/{portalId}를 서비스 토큰 + ETag 캐시 + stale fallback으로 조회한다. 포털은 정책을 저장하지 않고 사용자별 선택(userThemePreference)만 보관한다. | 정리 대상 아님(현행 유지) — 이미 "UI플랫폼 기준 + 포털 구독" 패턴이다 |
runtimeSettings | PC의 앱 런타임·배포 설정(identityMode·deploymentProfile·PortalConsole 연동·portal_runtime_settings 테이블). UiPlatform의 ui_center_runtime_config는 UiPlatform 자기 서비스 설정이라 중복이 아니다. | UI플랫폼 도메인 아님(현행 유지) |
portalMenu, portalGroups | 표현 규칙(메뉴 트리·퀵링크·그룹 접근)을 포털이 자체 DB로 소유 — portal_menu_items·portal_quick_links·portal_menu_audits·portal_user_groups·portal_group_members·portal_group_permissions | 포털 소유 확정(2026-09-13) — 메뉴는 화면 구조·업무 동선·라우팅과 결합되어 포털마다 다르다 |
rag, explore | ExploreGateway 소유 도메인 — 위임 클라이언트·이중화(P1·P2) 완료 | 진행 중(ProcessCenter/docs/EXPLORE_GATEWAY_DELEGATION_PLAN.md) |
notices | "공통 기능 Asset" 원칙 대상(중앙 통합 ✗) | 현행 유지 |
5. 결정 (2026-09-13 확정)
UI플랫폼은 AI 기능을 관장하지 않는다 — UI(표현 규칙)에만 집중한다.
| 선택지 | 내용 | 결정 |
|---|---|---|
| A. 표현 규칙 전용 | 개명 + 테마·릴리스·배포·런타임 설정만 소유 | ✅ 채택 |
| B. 공통 플랫폼 서비스군으로 확장 | AI·검색·알림까지 UI플랫폼에 통합 | ❌ 기각 |
| C. 하이브리드(운영 콘솔 화면) | 표현 규칙 + AI 운영 화면 | ❌ 기각(아래 이유) |
이유: AI 기능 중에는 프론트엔드 없이 도는 것(배치 색인·요약 생성·정합성 점검 등)이 상당수이므로, 화면·표현 규칙을 소유하는 UI플랫폼이 AI 런타임을 관장하면 책임과 릴리스 수명주기가 섞인다. UI플랫폼은 공통 UI 패키지·테마·릴리스·배포·런타임 설정(표현 규칙)만 소유한다.
6. 결정이 필요한 항목 (RAG 소유자)
RagService는 별도 서비스로 두지 않는다. RAG의 본질적 행위(색인된 문서에 대한 검색 실행과 근거 기반 응답)는 ExploreGateway가 소유한다.
| 후보 | 주장 | 평가 |
|---|---|---|
| ExploreGateway로 통합 | 검색 실행·조합을 이미 소유. RAG도 "검색 실행"의 한 종류 | ✅ 채택 — 소비자(조합)와 공급자(색인)를 한 서비스가 일관되게 운영 |
| 별도 RagService 유지 | 색인 파이프라인·벡터 저장을 분리 | ❌ 서비스만 늘고, 발행(FileStore)→색인→검색→조합 흐름이 두 서비스로 쪼개짐 |
Ai-Core 서비스 신설 | AI 전담 서비스 | ❌ 이름이 공용 라이브러리 @hohyun94/portal-ai(ai-core)와 충돌하고, ExploreGateway와 역할 중복 |
메뉴/그룹 — 포털 소유 확정(2026-09-13)
- 결정: 메뉴 트리·퀵링크·그룹 접근 규칙은 각 포털이 소유한다. UI플랫폼은 메뉴 데이터를 저장·배포하지 않고 공통 메뉴 UX 규칙·컴포넌트만 제공한다.
- 이유: 메뉴는 포털의 화면 구조·업무 동선·라우팅·권한과 직접 결합되어 포털별로 체계가 다르다. 중앙 소유 시 포털 화면 개편마다 UI플랫폼 릴리스가 필요해져 릴리스 수명주기가 묶인다.
- 참고(다른 위임의 선례): 테마 정책은 UI플랫폼 소유·포털 구독(
themePolicyGateway— 서비스 토큰·ETag 캐시·stale fallback)으로 이미 정착했다. 검색·RAG도 같은 패턴으로 ExploreGateway에 위임한다(ProcessCenter/docs/EXPLORE_GATEWAY_DELEGATION_PLAN.md). - 반영 위치:
SERVICE_BOUNDARIES.md(책임 표·비소유 문구),ARCHITECTURE.md(개별 포털 역할 표),DECISION_LOG.md(2026-09-13 항목).
경계 정리
- ExploreGateway: 다중 포털 탐색 실행 조합(control plane catalog + 사용자 Scope로 포털 어댑터 선택·실행·결과 정규화). 문서 색인은 소유하지 않는다.
- RagService(별도 서비스): 문서 인덱스·RAG·citation — 정제·청킹·인덱싱·pgvector RLS 검색·근거 기반 응답.
- 소비 포털: ExploreGateway가 호출하는 탐색 어댑터를 제공한다(ProcessCenter:
POST /api/explore/v1/search). - 벡터 저장: 애플리케이션 서비스가 아니라 PostgreSQL+pgvector 또는 외부 벡터 DB가 담당(계약은
@hohyun94/portal-ai·VectorStore). - FileStore: 원본 보관·스캔·승인 후 RagService로 발행(
ragPublishAllowed의미 유지). - LLM 완성(요약·번역·정합성): 검색과 무관한 범용 기능이므로 **ModelGateway(모델 게이트웨이)**가 모델 접근·키·쿼터·비용·감사를 소유하고, 소비 포털은 그 주소로 호출한다(현재
PRIVATE_LLM_URL지점).
정정(2026-09-13): 저장소 실사 결과 RagService·ExploreGateway가 이미 존재하여 위와 같이 공존 구조로 정정했다(§6 상단의 이전 결정 대체). 근거:
UiPlatform/docs/DECISION_LOG.md(서비스 경계 정정 항목).
7. 결정 후 처리 (체크리스트)
- [x]
docs/SERVICE_BOUNDARIES.md에 AI·검색 소유자 행 추가(ExploreGateway: 색인·벡터 검색·근거 기반 응답, 금지 의존성에 모델 게이트웨이 추가) - [x]
docs/DECISION_LOG.md에 결정 기록(2026-09-13 — UI플랫폼 범위, RAG 소유자) - [x]
ProcessCenter/docs/DB_STRATEGY.md의 AI 계층 소유자 표를 확정 내용으로 갱신(ExploreGateway·모델 게이트웨이 반영) - [x] FileStore 문서 표기 갱신(RagService → ExploreGateway 색인 API) —
FileStore/docs/ARCHITECTURE.md·ADMIN_CONSOLE.md+ 코드 주석 2건(커밋379ebb3) - [x] ProcessCenter
themePolicy·runtimeSettings실측 검증 — 둘 다 정리 대상 아님(테마는 이미themePolicyGateway로 UI플랫폼 구독, 런타임 설정은 앱·배포 도메인) - [x] 메뉴/그룹 소유자 결정 — 포털 소유 확정(2026-09-13) ·
SERVICE_BOUNDARIES·ARCHITECTURE·DECISION_LOG반영 - [x]
rag·explore라우터의 ExploreGateway 위임 계획 수립 →ProcessCenter/docs/EXPLORE_GATEWAY_DELEGATION_PLAN.md(계약 초안·단계별 전환·폴백) - [x] 모델 게이트웨이(ModelGateway) 이름·범위 확정 →
docs/MODEL_GATEWAY_SCOPE.md(소비 포털 주소 교체는 P1로 후속)