승인된 Manifest 릴리스·배포 설계

목표

UiPlatform에서 승인된 PortalThemeManifest를 immutable한 portal-foundation 릴리스 산출물로 만들고, 포털별 호환성·구독·배포 상태를 확인하면서 점진적으로 적용한다.

책임 경계

단계	소유자
Manifest 초안·검증·승인	UiPlatform
공통 UI 런타임 API·Manifest 스키마	portal-foundation
패키지 빌드·GitHub Packages 게시	CI/CD 또는 UiPlatform release worker
포털 catalog·접근정책·capability	PortalConsole
포털별 배포 요청·적용 상태	UiPlatform
포털 업무 데이터·최종 권한	각 포털

릴리스 흐름

DRAFT
  → VALIDATED
  → APPROVED
  → BUILDING
  → PUBLISHED
  → DEPLOYING
  → APPLIED

DRAFT와 APPROVED는 Manifest 내용과 검증 결과를 저장한다. PUBLISHED 이후에는 Manifest와 portal-foundation package version을 변경하지 않는다. 변경이 생기면 새 themeKey 또는 새 semver 릴리스를 만든다.

승인 시 검증

UiPlatform는 승인 전에 다음을 확인한다.

1. validatePortalThemeManifest()가 성공하는지 확인한다.
2. foundationRange가 대상 portal-foundation 릴리스와 호환되는지 확인한다.
3. --pf-* 토큰만 사용하고, UI 컴포넌트 외부의 업무 CSS 선택자를 포함하지 않는지 검사한다.
4. Preview 렌더링 결과와 접근성 smoke test를 생성한다.
5. 이전 승인 릴리스와 Manifest diff를 기록한다.

패키지 릴리스 연결

승인된 Manifest는 portal-foundation 소스에 직접 덮어쓰지 않고 별도 release artifact로 저장한다.

manifest artifact
  ├─ manifest.json
  ├─ portal-foundation version
  ├─ SHA-256 digest
  └─ validation report

CI는 artifact digest를 기준으로 패키지를 빌드하고 GitHub Packages에 게시한다. UiPlatform는 GitHub token이나 package publish credential을 브라우저에 노출하지 않으며, release worker 또는 CI secret만 사용한다.

포털별 배포

UiPlatform는 PortalConsole catalog와 현재 포털의 portal-foundation 버전을 조회해 대상별로 다음을 판정한다.

판정	동작
호환·구독·활성	배포 queue에 추가
호환되지 않음	배포하지 않고 SKIPPED 기록
미구독	사용자 승인 전까지 대기
endpoint 없음	FAILED가 아닌 UNAVAILABLE로 기록
적용 후 오류	직전 APPLIED 릴리스로 rollback 대상 지정

배포 요청에는 releaseKey, manifestDigest, portalId, requestId를 포함한다. 포털은 적용 후 digest와 package version을 보고하고, UiPlatform는 이를 배포 ledger에 기록한다.

API 확장안

기존 release 상태 응답을 깨지 않도록 optional field로 확장한다.

type UiCenterRelease = {
  releaseKey: string;
  packageVersion: string;
  themeVersion: string;
  manifest?: {
    themeKey: string;
    version: string;
    digest: string;
    validationStatus: "VALIDATED" | "FAILED";
  };
};

향후 필요한 명령은 다음과 같다.

uiCenter.createThemeDraft
uiCenter.validateThemeDraft
uiCenter.approveThemeDraft
uiCenter.publishThemeRelease
uiCenter.deployThemeRelease
uiCenter.rollbackThemeRelease

초기 구현에서는 createThemeDraft, validateThemeDraft, publishThemeRelease를 UiPlatform 서버에서 담당하고, 기존 approveRelease와 deployRelease는 호환 alias로 유지한다.

롤백 원칙

롤백은 이전 release artifact를 다시 배포하는 방식으로 수행한다. 승인된 Manifest를 수정하거나 삭제하지 않으며, 문제가 된 릴리스에는 실패 사유·대상 포털·digest·requestId를 기록한다. 이렇게 해야 포털별 적용 상태와 재현 가능한 릴리스 이력을 보존할 수 있다.

Publish API와 queue worker

승인된 초안은 uiCenter.publishThemeRelease를 통해서만 발행한다. API는 themeKey, version, releaseKey, packageVersion을 받고, 상태가 APPROVED가 아니면 거부한다. 발행 결과에는 canonical Manifest, SHA-256 manifestDigest, validation report가 포함되며, 동일 releaseKey는 재사용하지 않는다.

queue worker는 processThemeDeploymentQueue로 실행하거나 별도 scheduler에서 호출한다. worker는 PortalConsole catalog를 M2M으로 조회하고, enabled인 포털 중 theme capability를 광고한 포털만 대상으로 삼는다. 각 포털의 deployment.endpoint와 Secret Manager credential reference로 배포 요청을 생성한다.

PORTAL_CONTROL_CENTER_URL
PORTAL_CONTROL_CENTER_M2M_TOKEN
UI_PLATFORM_PORTAL_TOKEN_<PORTAL_ID>
UI_PLATFORM_DEPLOY_MAX_ATTEMPTS=3

배포 요청에는 releaseKey, manifestDigest, x-ui-center-release-key, x-ui-center-manifest-digest를 포함한다. worker는 포털별 결과를 독립적으로 처리하고, catalog에 없거나 capability·credential이 없는 경우 각각 UNAVAILABLE 또는 SKIPPED로 기록한다. 실제 Manifest 본문은 artifact store 또는 release endpoint 계약이 확정된 뒤 전달하며, 현재 1차 worker는 digest 기반 멱등 요청을 사용한다.