모듈형 포털 설치·운영 계약
목적
각 사용자 포털은 독립적으로 설치·운영 가능한 완결 제품이어야 한다. PortalConsole, FileStore, UiPlatform는 포털의 기본 동작을 막는 필수 의존성이 아니라, 설치 후 선택적으로 결합되는 중앙 서비스다. 반면 portal-foundation은 실행 중인 중앙 서비스가 아니라 포털에 포함되는 공통 UI·보안·runtime 패키지이므로 모든 포털이 기본으로 사용한다.
원칙: 중앙 서비스가 연결되지 않았거나 일시적으로 응답하지 않아도 포털의 핵심 업무 기능, 자체 사용자 관리, 기본 UI는 계속 동작해야 한다.
모듈 역할
| 모듈 | 포털 설치 시 기본 포함 여부 | 책임 | 중앙 서비스 장애 시 동작 |
|---|---|---|---|
portal-foundation | 항상 포함 | 공통 UI component, design token, runtime/security contract | 포털에 package로 포함되므로 영향 없음 |
| 포털 자체 관리 모드 | 기본 제공 | 포털 DB, 초기 관리자, 자체 조직·사용자·권한 | 완전 동작 |
PortalConsole | 선택 연결 | 중앙 조직·사용자·권한·포털 등록·위임 identity | 포털은 마지막 검증 상태의 제한 정책 또는 자체 비상 관리자 정책을 따름 |
FileStore | 선택 연결 | 비정형 파일 원본, 저장 backend, lifecycle, retention, audit | 첨부 기능만 비활성화 또는 읽기 전용; 포털 업무 데이터는 동작 |
UiPlatform | 선택 연결 | 다중 포털의 theme, branding, menu/UI policy 중앙 관리 | 마지막 적용 UI profile 또는 포털 기본 theme로 fallback |
설치 조합
PortalConsole, FileStore, UiPlatform는 서로 독립적으로 선택할 수 있다. 따라서 설치 마법사는 단일한 고정 조합이 아니라 아래의 세 개 선택값을 수집한다.
| 설치 선택 | 값 | 포털의 데이터 소유·동작 방식 |
|---|---|---|
| Identity mode | LOCAL 또는 DIRECTORY | LOCAL은 포털 DB가 사용자·조직·관리자를 소유한다. DIRECTORY는 PortalConsole가 identity를 제공하고 포털은 업무별 role mapping만 유지한다. |
| Asset mode | DISABLED 또는 ASSET_STORE | DISABLED는 첨부 기능을 노출하지 않는다. ASSET_STORE는 포털이 file relation·업무 ACL을 소유하고 FileStore가 원본·보존·감사를 소유한다. |
| UI mode | EMBEDDED 또는 UI_CENTER | EMBEDDED는 portal-foundation 기반의 포털 local theme를 사용한다. UI_CENTER는 중앙 UI profile을 가져오되 local fallback을 반드시 보유한다. |
다음 표는 사용자가 주로 보게 될 대표 구성이다. 다른 조합도 위 세 선택값의 직교 결합으로 지원한다.
| 대표 구성 | 사용 대상 | 사용자·조직 | 첨부파일 | UI 설정 |
|---|---|---|---|---|
| 단독 경량 포털 | 하나의 업무 포털만 사용하는 고객 | 포털 자체 관리 | 없음 또는 자체 비정형 기능 | 포털 기본 theme |
| 단독 + FileStore | 파일 첨부가 필요한 단일 포털 | 포털 자체 관리 | FileStore 선택 연결 | 포털 기본 theme |
| 중앙 identity 포털 | 여러 포털을 중앙 조직 체계로 운영 | PortalConsole | 선택 | 포털 기본 theme 또는 중앙 profile |
| 중앙 통합 운영 | 여러 포털의 파일·브랜딩까지 통합 운영 | PortalConsole | FileStore 선택 연결 | UiPlatform 선택 연결 |
DB 없는 설치 마법사
모든 포털과 PortalConsole는 DB가 없는 상태에서도 /setup 설치 화면을 먼저 제공한다. 일반 업무 화면과 관리자 화면은 설치 완료 전에는 노출하지 않는다.
| 단계 | 설치 화면의 책임 | 저장 위치 |
|---|---|---|
| 1. 저장소 선택 | MySQL 또는 PostgreSQL 선택, host/port/database/TLS 입력 | 브라우저 메모리; 저장 전 연결 시험 |
| 2. 연결 검증 | 권한, version, network/TLS, schema 생성 가능 여부 확인 | 결과만 화면에 표시 |
| 3. 운영 모드 | LOCAL 또는 DIRECTORY 선택 | 설치 요청 payload |
| 4. 선택 서비스 | FileStore와 UiPlatform 연결 여부·endpoint·credential reference 입력 | 설치 요청 payload |
| 5. 초기화 | schema 생성, 초기 관리자 또는 PortalConsole 위임 등록, 기본 UI profile 생성 | 설치 완료 후 서비스 DB |
DB가 아직 없으므로 설치 전 설정은 영구 database row에 저장할 수 없다. 설치 서버는 최소 bootstrap key와 설정 경로만 환경변수로 받고, 설치 화면에서 받은 민감 연결정보는 연결 검증과 설치 transaction에만 사용한다. 설치가 성공한 뒤 필요한 service reference는 포털 DB에 저장하고, secret 원문은 운영 환경의 secret store 또는 환경변수 reference로만 보관한다. 설치 실패 시 브라우저와 서버의 임시 연결정보를 폐기한다.
PortalConsole 연동 계약
DIRECTORY 모드는 PortalConsole가 이미 설치되어 있고 중앙 설치 관리자가 포털 등록을 승인했을 때만 선택할 수 있다. 포털은 PortalConsole가 제공하는 설정 bundle을 받아 자체 DB의 업무 설정에 저장한다. bundle에는 다음만 포함한다.
| 제공 값 | 용도 | 포털이 저장할 수 있는 형태 |
|---|---|---|
directoryBaseUrl | token 검증 및 조직·사용자 조회 | HTTPS URL |
portalRegistrationId | 중앙 포털 등록 식별자 | opaque ID |
issuer, jwksUrl, audience | token claim 검증 | public identity metadata |
roleMapping | 중앙 role을 포털 업무 role로 해석 | allow-listed mapping |
serviceCredentialRef | 서버 간 호출 credential 위치 | secret reference만 저장 |
bootstrapProfile | 초기 theme·menu·feature 기본값 | 검증된 non-secret profile |
포털은 PortalConsole DB connection string, PortalConsole 관리자 password, access token 원문을 받거나 저장하지 않는다. PortalConsole가 연결되지 않은 단독 포털에는 위 bundle이 필요 없으며, 포털 설치 마법사가 자체 관리자·조직·사용자를 생성한다.
FileStore 연동 계약
FileStore는 identity mode와 독립적인 선택 서비스다. 포털은 연결 여부를 자기 관리자 UI에서 언제든지 조회·변경할 수 있지만, 연결·해제는 권한 있는 관리자와 audit event를 요구한다.
| 포털 소유 | FileStore 소유 | 연결 시 저장되는 값 |
|---|---|---|
| 업무 entity와 asset relation, 업무 ACL, 첨부 노출 여부 | 원본 object, checksum, scan status, retention, storage backend, storage audit | assetStoreBaseUrl, portalId, mappingId, credentialRef, 정책 snapshot |
FileStore에는 portal별 mapping이 존재해야 하며, 포털은 자신의 portalId와 승인된 mappingId로만 업로드할 수 있다. R2, Amazon S3, local disk의 backend 선택·bucket/local root·보존 정책은 FileStore 관리자 UI에서 관리한다. 포털 사용자 UI는 공통 portal-foundation attachment component를 사용하되, FileStore가 비활성화된 포털에서는 첨부 기능을 표시하지 않는다.
UiPlatform 연동 계약
UiPlatform는 모든 포털이 설치해야 하는 runtime이 아니다. EMBEDDED mode는 portal-foundation의 default tokens와 포털 DB의 local theme profile만 사용한다. UI_CENTER mode에서만 UiPlatform의 승인된 profile을 받아 branding·theme·menu policy를 적용한다.
UiPlatform profile sync는 pull-and-cache 방식으로 동작한다. 포털은 마지막으로 검증된 profile과 local fallback을 유지하므로 UiPlatform 장애나 네트워크 단절로 포털 화면이 빈 화면이 되지 않는다. 중앙 profile은 업무 권한이나 identity를 직접 바꾸지 않으며, theme·layout·menu visibility처럼 UI 범위의 값만 제어한다.
관리자 UI 책임
| 관리 화면 | local mode | Directory mode | FileStore 연결 | UiPlatform 연결 |
|---|---|---|---|---|
| 설치 마법사 | 자체 DB·초기 관리자 생성 | PortalConsole bundle 검증·등록 | 선택 | 선택 |
| 포털 관리자 | 자체 조직·사용자·role 관리 | 조직·사용자 조회 및 업무 role mapping만 관리 | 연결 상태·허용 mapping·첨부 정책 조회 | local fallback·profile sync 상태 조회 |
| PortalConsole 관리자 | 해당 없음 | 중앙 사용자·조직·포털 등록·bundle 발급 | FileStore 사용 portal 등록 정보 조회 | UiPlatform 사용 portal 등록 정보 조회 |
| FileStore 관리자 | 해당 없음 | 해당 없음 | backend(R2/S3/local), portal mapping, retention, audit, asset lifecycle 관리 | 해당 없음 |
| UiPlatform 관리자 | 해당 없음 | 해당 없음 | 해당 없음 | 중앙 profile, branding, theme, menu policy 관리 |
구현 우선순위
- 모든 서비스의 DB 없는
/setupmode와 설치 완료 상태 guard를 공통 contract로 만든다. - 포털의
LOCALidentity mode를 기본으로 완결하고, PortalConsole bundle 연동을 선택 adapter로 추가한다. - FileStore의 backend·portal mapping·asset lifecycle 관리자 UI를 완성하고, portal-foundation attachment UI가 mapping contract를 사용하게 한다.
- UiPlatform는 optional UI profile provider로만 연결하고, embedded theme fallback을 보장한다.
- 각 조합의 설치·연결·해제·장애 fallback 시나리오를 integration test로 고정한다.