포털 연동 설정 흐름 검수 기록

검수일: 2026-08-25

개정 (2026-10-15) — 용어 기준을 단일 원천으로 옮긴다. 아래 「키 용어 기준」은 화면에서 그대로 지켜지지 않았다. 실측(client/src/pages/DirectoryAdmin.tsx)에서 같은 개념(포털 서버가 중앙 DirectoryService 를 호출할 때 쓰는 인증 키)을 일곱 이름으로 불렀고 — 「포털 호출 인증 키」· 「호출 인증 키」·「호출 키」·「등록된 포털 호출 키」·「활성 중앙 발급 키」·「중앙 API key」· 「DirectoryService API Key」— 관리자는 "이름이 비슷한 키가 왜 여러 개인가"를 화면마다 다시 해석해야 했다. 그래서 용어를 client/src/lib/portalIntegrationTerms.ts 한 곳으로 옮기고, 옛 이름이 화면·관리자용 서버 메시지에 되돌아오면 portalIntegrationTerms.test.ts 가 파일·줄과 함께 막는다. 아래 표가 그 원천의 사본이다(원천이 바뀌면 이 표도 함께 고친다).

키 용어 기준

개념 이름은 하나, 방식을 이름으로 만들지 않는다. 만들어진 방식(중앙 발급 / 기존 키 등록)은 키의 이름이 아니라 형용어로 붙는다.

개념	쓸 이름	쓰지 않는 이름(계약이 막는다)
포털 서버가 콘솔을 호출할 때 쓰는 인증 키	포털 호출 키	호출 인증 키 · 호출 키 · 중앙 발급 키 · 중앙 API key · 중앙 Key · DirectoryService API Key · API Key
콘솔이 키를 만들어 암호문으로 보관·전달하는 방식	중앙 발급	초기 Key · 자동 발급 · 중앙 관리 Key
포털이 이미 쓰는 키를 콘솔에 등록하는 방식(MANAGED)	기존 키 등록	호출 키 등록 · 관리형 등록
콘솔이 키를 대상 환경변수에 넣고 재배포까지 요청하는 것	자동 전달	Secret 갱신 · 전달
콘솔 로그인 전용 키	관리자 키	관리자 API Key
R2 endpoint·bucket·key 묶음	R2 자격증명	R2 bundle

원천: client/src/lib/portalIntegrationTerms.ts (PORTAL_TERMS · LEGACY_PORTAL_TERM_RULES) 계약: client/src/lib/portalIntegrationTerms.test.ts — 화면 문구(client/src)와 관리자에게 그대로 보이는 서버 메시지 7개 파일을 검사한다. 검사에서 빼는 파일은 이유와 함께 그 테스트에 적는다 (모델 게이트웨이의 API key 는 프로바이더 자격증명이라 다른 개념이다).

아직 남은 일(별도 단계): 이름만 통일한 상태이며, 같은 키를 만드는 경로가 세 개(01단계 번들 발급 · 기존 키 등록 · 중앙 발급)라 키 목록에 섞여 보이는 문제, 상태에 따라 화면 구조가 갈라지는 문제, 배포 환경변수 이름의 기본값이 갈리는 문제(§서버 기본값)는 화면 재구성 단계에서 다룬다 — todo.md 「포털 연동 설정 재구성 (2026-10-15)」.

서버 기본값 — 정본을 정했다 (2026-10-15)

배포 대상의 환경변수 이름 기본값이 세 곳에서 갈려 있었다.

위치	(정리 전) 값
server/portalCredentialDelivery.ts normalizeSecretKey	PORTAL_CONSOLE_API_KEY
scripts/ensure-credential-delivery-schema.mjs(컬럼 기본값) · server/portalProvisioning.ts	PORTAL_CONSOLE_PORTAL_API_KEY
화면 fallback(DirectoryAdmin.tsx)	두 값이 섞여 있었다

정본은 PORTAL_CONSOLE_API_KEY 로 정하고 shared/portalDelivery.ts (PORTAL_DELIVERY_SECRET_KEY_NAME) 한 곳에서 스키마 기본값·자동 구축·전달·화면이 같은 값을 쓰게 했다. 근거: 소비 포털이 실제로 이 이름을 먼저 읽는다 — ProcessCenter server/directorySyncService.ts (PORTAL_CONSOLE_API_KEY ?? PORTAL_CONSOLE_PORTAL_API_KEY) · server/runtimeSettings.ts (이 이름이 없으면 중앙관리 모드 거부) · GuideCenter server/termLinkDirectory.ts(이 이름 우선) · docs/portal-api-key-auth-runbook.md §3-b. 소비 포털은 옛 이름도 envAliases 로 함께 받으므로 기존 배포를 바꾸지 않아도 된다. 기존 행의 값은 자동으로 바꾸지 않고, 다르면 화면이 정본과 확인 방법(envAliases)을 알린다. 계약: server/portalDeliverySecretName.contract.test.ts.

브라우저 검수

로컬 PortalConsole는 데이터베이스 환경변수가 없어 /setup으로 제한되므로 인증된 관리 화면까지 로컬 브라우저에서 진입할 수 없었다. 스테이징 URL도 현재 브라우저 세션에서 렌더링된 관리 화면 요소가 확인되지 않아 배포 화면 직접 검수는 제한되었다. 대신 TypeScript 검사와 포털 설정·API 키·자격증명 전달 관련 서버 계약 테스트를 수행한다.