공통 UI 및 중앙 테마 연동 인수인계서

작성 목적: UiPlatform, portal-foundation, ProcessCenter 사이의 공통 UI 변경 사항과 현재 staging에서 발생하는 중앙 테마 API 인증 문제를 다음 개발자가 즉시 이어서 처리할 수 있도록 정리한다.

기준 시각: 2026-09-06 21:36 KST

1. 최종 결론

현재 공통 UI 코드와 ProcessCenter staging 배포는 정상이다. 그러나 ProcessCenter가 UiPlatform의 중앙 테마 API를 호출할 때 사용하는 인증 계약이 구버전 상태로 남아 있다. UiPlatform 화면에서 API Key Manager를 제거했지만, 서버의 테마 API는 여전히 UI_CENTER_THEME_API_KEY 또는 ui_center_api_keys 테이블을 통한 Bearer API Key 인증을 요구한다.

그 결과 ProcessCenter staging은 중앙 테마 정책을 읽지 못하고 기본 테마로 fallback한다. 화면에는 다음 상태가 확인된다.

중앙 테마 설정을 불러오지 못해 기본 테마를 사용합니다.

따라서 강력 새로고침이나 단순 재배포로는 문제가 해결되지 않는다. 구 API Key 인증을 새 공통 서비스 인증 방식으로 교체하는 코드 작업이 남아 있다.

2. 저장소 및 현재 커밋

저장소	브랜치	현재 커밋	상태
`portal-foundation`	`fix/sidebar-brand-and-active-menu-typography`	`ebbd0a5 fix: unify PortalFrame common chrome`	원격과 동일, 작업 트리 clean
`UiPlatform`	`main`	`b6f2fc6 chore: vendor profile control cleanup`	원격과 동일, 작업 트리 clean
`ProcessCenter`	`main`	`73e51f7 ci: validate common UI without content tests`	원격과 동일, 작업 트리 clean

관련 저장소 경로는 다음과 같다.

text

/home/ubuntu/portal-foundation
/home/ubuntu/UiPlatform
/home/ubuntu/ProcessCenter

3. 완료된 공통 UI 작업

3.1 portal-foundation

portal-foundation을 공통 UI의 단일 소유자로 두고 다음 항목을 반영했다.

PortalFrame 공통 레일 및 상단바 스타일 통합
콘텐츠 제목 바 높이 52px 적용
제목 폰트 20px / 700 적용
선택 메뉴 아이콘을 활성 강조선과 동일한 accent 토큰으로 정렬
라이트·다크 모드에서 rail, header, canvas, ink 토큰 사용
레일 접기·펴기 기능 복구
접기·펴기 버튼 테두리 제거
접힌 상태에서 토글 아이콘을 메뉴 아이콘과 같은 X축에 정렬
접기·펴기 아이콘을 패널 분할 형태의 아이콘으로 통일
사용자 정보 옆의 중복 chevron 제거
기존 통합 탐색 문구를 통합 검색으로 변경
PortalShell 검색 입력이 기존 PortalExploreDialog로 연결되도록 수정
검색어를 UiPlatform의 메뉴 결과 필터링에 반영
선택·비선택 메뉴의 폰트 크기와 굵기 통일
공통 CSS에서 consumer portal이 덧씌우는 shell 스타일을 최소화

주요 파일은 다음과 같다.

text

portal-foundation/packages/ui-react/src/index.tsx
portal-foundation/packages/ui-react/src/PortalShell.tsx
portal-foundation/packages/ui-react/styles/styles.css

3.2 UiPlatform

UiPlatform에는 portal-foundation 0.6.33 tarball을 vendoring하여 반영했다.

text

UiPlatform/vendor/hohyun94-portal-foundation-0.6.33.tgz
UiPlatform/pnpm-lock.yaml

또한 UiPlatform 공통 검색 결과에 현재 메뉴 구조를 연결했고, 조건부 useMemo 호출로 발생했던 React error #310을 제거했다.

3.3 ProcessCenter

ProcessCenter에는 최신 Foundation tarball과 lockfile을 반영했다. 소비 포탈이 공통 shell을 별도 CSS로 덧씌우던 규칙도 일부 제거했다.

공통 UI 변경의 검증 목적에 맞추어 CI에서 콘텐츠 기능 전체 테스트 대신 공통 UI smoke validation을 실행하도록 조정했다.

4. staging 배포 검증 결과

배포 프로젝트는 H Project, 환경은 staging이다.

서비스	URL	확인 결과

ProcessCenter 최신 배포는 다음 상태다.

text

ACTIVE
ci: validate common UI without content tests
Deployment successful

ProcessCenter staging JavaScript에는 다음 최신 변경 흔적이 포함되어 있다.

pf-portal-frame__header
통합 검색
process-center-frame

staging CSS에는 다음 공통 규칙이 포함되어 있다.

PortalFrame header 52px
제목 20px / 700
--pf-rail
--pf-canvas
grid-template-columns: 248px minmax(0, 1fr)

따라서 현재 문제는 Foundation tarball 누락이나 배포 실패가 아니다.

5. UiPlatform의 ProcessCenter 테마 정책 검증 결과

UiPlatform staging의 포털별 테마 정책 화면에서 다음 포털을 직접 선택하여 확인했다.

text

Process Center · process-center

확인된 정책은 다음과 같다.

항목	확인 값
포털 ID	`process-center`
사용자 선택 정책	관리자 지정
기본 테마 강제 적용	활성화
허용 테마	Portal Foundation 기본 테마
테마 키	`default`
버전	`1.0.0`
포털 기본 테마	Portal Foundation 기본 테마

따라서 UiPlatform에 ProcessCenter 정책이 등록되지 않은 문제는 아니다. 정책 데이터는 존재한다.

6. 미해결 원인: 인증 계약 불일치

6.1 ProcessCenter의 현재 호출 방식

파일:

text

ProcessCenter/server/themePolicyGateway.ts

현재 구현은 다음 환경변수를 요구한다.

text

UI_PLATFORM_ORIGIN
UI_CENTER_THEME_API_KEY

그리고 UiPlatform 요청에 다음 헤더를 보낸다.

text

authorization: Bearer <UI_CENTER_THEME_API_KEY>

호출 경로는 다음과 같다.

text

GET /api/portal-theme/v1/catalog
GET /api/portal-theme/v1/policy/process-center
PUT /api/portal-theme/v1/policy/process-center

6.2 UiPlatform의 현재 인증 방식

파일:

text

UiPlatform/server/themePolicyApi.ts
UiPlatform/server/db.ts
UiPlatform/drizzle/schema.ts
UiPlatform/drizzle/schema.pg.ts

현재 UiPlatform API는 다음 순서로 인증한다.

Authorization: Bearer 헤더를 읽는다.
UI_CENTER_THEME_API_KEY 환경변수와 비교한다.
일치하지 않으면 validateUiCenterApiKey()를 호출한다.
ui_center_api_keys 테이블의 활성 key hash를 조회한다.

관련 코드의 핵심은 다음과 같다.

const configured = process.env.UI_CENTER_THEME_API_KEY?.trim();
if (configured && bearer === configured) return true;
return validateUiCenterApiKey(bearer);

현재 UiPlatform staging의 테마 API를 인증 없이 호출하면 다음 응답이 반환된다.

text

HTTP 401
{"error":"Theme API authorization required"}

6.3 제거 작업과 backend의 잔존 코드

커밋 00bca7b refactor: standardize sharp UI and remove key manager에서 API Key Manager UI와 키 발급·폐기 기능은 제거됐다.

그러나 다음 backend 요소는 남아 있다.

validateUiCenterApiKey()
uiCenterApiKeys schema
ui_center_api_keys 데이터베이스 테이블
UI_CENTER_THEME_API_KEY 환경변수 검사
ProcessCenter의 Bearer API Key 전송

즉, UI는 새 구조처럼 보이지만 backend 공통 테마 API는 구 API Key 구조에 머물러 있다. 이것이 현재 401과 fallback의 직접 원인이다.

7. 다음 개발자가 해야 할 작업

새 인증 방식의 정확한 계약은 제품·보안 정책 담당자와 먼저 확정해야 한다. 현재 저장소에서 확인되는 사실만으로는 API Key Manager 제거 이후의 대체 인증 프로토콜이 구현되어 있지 않다. 따라서 임의로 인증을 제거하거나 테마 API를 무인증 공개로 바꾸면 안 된다.

권장 작업 순서는 다음과 같다.

7.1 새 인증 계약 확정

다음 질문에 대한 답을 먼저 결정한다.

질문	결정 필요 사항
인증 주체	ProcessCenter 서비스인가, PortalConsole 위임 토큰인가, 관리형 클라우드 내부 서비스 토큰인가
토큰 발급자	PortalConsole, UiPlatform, 별도 인증 서비스 중 어느 곳인가
전달 방식	`Authorization: Bearer`, mTLS, signed request, 관리형 클라우드 shared variable 중 어느 방식인가
포털 식별	`process-center`를 토큰 claim 또는 header로 검증할지 여부
권한 범위	catalog read, policy read, policy write를 분리할지 여부
만료·갱신	토큰 만료 및 rotation을 어떻게 처리할지 여부

7.2 UiPlatform 수정

새 인증 계약에 맞추어 다음을 수정한다.

server/themePolicyApi.ts의 authorized() 교체
server/db.ts의 validateUiCenterApiKey() 제거 또는 새 인증 어댑터로 대체
drizzle/schema.ts와 drizzle/schema.pg.ts의 uiCenterApiKeys 사용 여부 정리
API Key Manager 제거 커밋에 남아 있는 backend 잔재 정리
인증 실패 시 401뿐 아니라 원인과 request ID를 서버 로그에 남김
테마 API에 catalog read 및 portal policy read 권한을 명시

7.3 ProcessCenter 수정

다음 파일을 새 인증 어댑터에 맞게 교체한다.

text

ProcessCenter/server/themePolicyGateway.ts
ProcessCenter/server/routers/themePolicy.ts
ProcessCenter/client/src/App.tsx

특히 UI_CENTER_THEME_API_KEY 직접 참조를 제거하고, 공통 Foundation 또는 서버 전용 auth adapter에서 새 토큰을 공급하도록 만든다.

7.4 공통 Foundation 수정 여부 판단

새 인증이 모든 소비 포탈에서 공통으로 사용된다면 다음 위치에 공통 서버 adapter를 추가하는 것이 적절하다.

text

portal-foundation/packages/runtime-core
portal-foundation/packages/ui-react

브라우저 코드에는 서비스 인증 정보를 절대 노출하지 않는다. 중앙 테마 API 호출은 반드시 포털 서버에서 실행한다.

7.5 배포 후 검증

인증 구현 후 다음 순서로 검증한다.

UiPlatform staging의 catalog API를 새 인증으로 호출한다.
process-center 정책 API가 200과 정책 JSON을 반환하는지 확인한다.
ProcessCenter staging을 재배포한다.
ProcessCenter 화면에서 fallback 문구가 사라지는지 확인한다.
UiPlatform에서 정책의 기본 테마 또는 모드를 변경한다.
ProcessCenter를 새로고침하여 rail, topbar, canvas, title 색상이 변경되는지 확인한다.
라이트·다크 모드와 레일 접기·펴기를 각각 확인한다.

8. 권장 검증 명령

다음 명령은 인증 정보를 출력하지 않고 상태만 확인하기 위한 예시다.

bash

cd /home/ubuntu/ProcessCenter
pnpm run test:common-ui
pnpm run check
pnpm run build

cd /home/ubuntu/UiPlatform
pnpm run check
pnpm run build

현재 인증 실패 재현 명령은 다음과 같다.

bash

curl -sS -w '\nHTTP %{http_code}\n' \

현재 결과:

text

{"error":"Theme API authorization required"}
HTTP 401

새 인증 구현 후에는 이 명령을 새 인증 헤더 또는 새 인증 클라이언트로 실행하여 200과 catalog JSON을 확인해야 한다.

9. 주의 사항

UI_CENTER_THEME_API_KEY를 새로 만들거나 임의의 값을 넣는 방식은 API Key Manager가 제거된 현재 구조와 맞지 않는다.
테마 API를 무인증으로 공개하면 모든 외부 호출자가 테마 catalog와 포털 정책을 조회하거나 정책을 변경할 수 있으므로 금지한다.
관리형 클라우드 변수의 실제 secret 값은 문서, 커밋, 로그에 기록하지 않는다.
process-center 정책 자체는 이미 정상 등록되어 있으므로, 정책을 중복 생성하거나 삭제할 필요가 없다.
Foundation CSS를 다시 덧씌우는 방식으로 현상을 해결하지 않는다. 현재 staging 번들에는 공통 CSS가 이미 포함되어 있다.
PortalConsole가 Sleeping 상태인 환경에서는 새 위임 토큰 방식의 검증이 실패할 수 있으므로, 인증 방식에 PortalConsole가 포함되면 해당 서비스 상태도 함께 확인한다.

10. 인수인계 대상 파일 요약

영역	파일	상태
공통 shell	`portal-foundation/packages/ui-react/src/index.tsx`	최신 공통 UI 반영
공통 shell	`portal-foundation/packages/ui-react/src/PortalShell.tsx`	최신 검색·토글 반영
공통 CSS	`portal-foundation/packages/ui-react/styles/styles.css`	52px·테마 토큰·레일 규칙 반영
ProcessCenter 테마 호출	`ProcessCenter/server/themePolicyGateway.ts`	구 API Key 방식, 교체 필요
ProcessCenter bootstrap	`ProcessCenter/client/src/App.tsx`	API 실패 시 기본 테마 fallback
UiPlatform 테마 API	`UiPlatform/server/themePolicyApi.ts`	구 Bearer API Key 검증, 교체 필요
UiPlatform API 검증	`UiPlatform/server/db.ts`	`validateUiCenterApiKey()` 잔존
UiPlatform schema	`UiPlatform/drizzle/schema.ts`	`ui_center_api_keys` 잔존
UiPlatform schema	`UiPlatform/drizzle/schema.pg.ts`	`ui_center_api_keys` 잔존
ProcessCenter CI	`ProcessCenter/.github/workflows/ci.yml`	공통 UI smoke validation 중심
ProcessCenter CI	`ProcessCenter/.github/workflows/verify.yml`	공통 UI 검증 범위 반영

11. 인수인계 상태 한 줄 요약

공통 UI 코드와 staging 배포는 완료되었고 process-center 테마 정책도 정상 등록되어 있다. 현재 작업의 유일한 핵심 blocker는 API Key Manager 제거 후에도 UiPlatform와 ProcessCenter에 남아 있는 구버전 공통 테마 API 인증 계약이다.

assets

common-ui-template-guide

공통 UI 및 중앙 테마 연동 인수인계서

1. 최종 결론

2. 저장소 및 현재 커밋

3. 완료된 공통 UI 작업

3.1 portal-foundation

3.2 UiPlatform

3.3 ProcessCenter

4. staging 배포 검증 결과

5. UiPlatform의 ProcessCenter 테마 정책 검증 결과

6. 미해결 원인: 인증 계약 불일치

6.1 ProcessCenter의 현재 호출 방식

6.2 UiPlatform의 현재 인증 방식

6.3 제거 작업과 backend의 잔존 코드

7. 다음 개발자가 해야 할 작업

7.1 새 인증 계약 확정

7.2 UiPlatform 수정

7.3 ProcessCenter 수정

7.4 공통 Foundation 수정 여부 판단

7.5 배포 후 검증

8. 권장 검증 명령

9. 주의 사항

10. 인수인계 대상 파일 요약

11. 인수인계 상태 한 줄 요약

References

공통 UI 및 중앙 테마 연동 인수인계서 ​

1. 최종 결론 ​

2. 저장소 및 현재 커밋 ​

3. 완료된 공통 UI 작업 ​

3.1 portal-foundation ​

3.2 UiPlatform ​

3.3 ProcessCenter ​

4. staging 배포 검증 결과 ​

5. UiPlatform의 ProcessCenter 테마 정책 검증 결과 ​

6. 미해결 원인: 인증 계약 불일치 ​

6.1 ProcessCenter의 현재 호출 방식 ​

6.2 UiPlatform의 현재 인증 방식 ​

6.3 제거 작업과 backend의 잔존 코드 ​

7. 다음 개발자가 해야 할 작업 ​

7.1 새 인증 계약 확정 ​

7.2 UiPlatform 수정 ​

7.3 ProcessCenter 수정 ​

7.4 공통 Foundation 수정 여부 판단 ​

7.5 배포 후 검증 ​

8. 권장 검증 명령 ​

9. 주의 사항 ​

10. 인수인계 대상 파일 요약 ​

11. 인수인계 상태 한 줄 요약 ​

References ​

공통 UI 및 중앙 테마 연동 인수인계서

1. 최종 결론

2. 저장소 및 현재 커밋

3. 완료된 공통 UI 작업

3.1 portal-foundation

3.2 UiPlatform

3.3 ProcessCenter

4. staging 배포 검증 결과

5. UiPlatform의 ProcessCenter 테마 정책 검증 결과

6. 미해결 원인: 인증 계약 불일치

6.1 ProcessCenter의 현재 호출 방식

6.2 UiPlatform의 현재 인증 방식

6.3 제거 작업과 backend의 잔존 코드

7. 다음 개발자가 해야 할 작업

7.1 새 인증 계약 확정

7.2 UiPlatform 수정

7.3 ProcessCenter 수정

7.4 공통 Foundation 수정 여부 판단

7.5 배포 후 검증

8. 권장 검증 명령

9. 주의 사항

10. 인수인계 대상 파일 요약

11. 인수인계 상태 한 줄 요약

References