포털 연동 설정 재구성 (2026-10-15)
제보: "포털 연동 설정에 대해서 좀 고치려고 해. 이 기능은 볼 때마다 헷갈려." 이 문서는 무엇을 왜 어떻게 바꿨는지, 무엇이 남았는지의 기록이다.
1. 실측한 원인 (코드 근거)
| # | 원인 | 근거(정리 전) |
|---|---|---|
| 1 | 포털 → 콘솔 호출 키를 만드는 경로가 셋인데 전부 portal_api_key_settings 에 쌓여 목록에 섞였다 | ① 01단계 번들 dsvc_(server/portalRegistration.ts) ② 「기존 키 등록」 ③ 중앙 발급 dpk_(server/portalCredentialDelivery.ts) · 자동 구축도 ③을 호출(server/portalProvisioning.ts) |
| 2 | ①③이 섞여 "활성 키 2개" 경고를 사람이 표에서 눈으로 판단해야 했다(마지막 사용 시각 비교 안내까지 붙었다) | 같은 포털에 활성 키가 여럿이면 어느 것이 쓰이는지 알 수 없음 |
| 3 | 같은 것을 일곱 이름으로 불렀다 | 포털 호출 인증 키 · 호출 인증 키 · 호출 키 · 등록된 포털 호출 키 · 활성 중앙 발급 키 · 중앙 API key · DirectoryService API Key |
| 4 | 상태가 화면 구조를 바꿨다 — 등록 포털 유무·온보딩 토글에 따라 키 섹션이 숨거나(showApiKeys=false) 같은 폼 위에 단계 탭(01/02)이 겹쳤다 | 상태 3분기 + 단계 탭 + 토글 |
| 5 | 상단이 안내문 4문장 + 지표 4개 + 콘솔 밖(UiPlatform) 안내의 연속이었다 | 지표 그리드 + .portal-integration-next-step |
| 6 | 배포 환경변수 이름 기본값이 세 곳에서 갈렸다 | 스키마 컬럼 기본값·자동 구축은 PORTAL_CONSOLE_PORTAL_API_KEY, 전달 기본값·소비 포털 실사용은 PORTAL_CONSOLE_API_KEY |
2. 정한 규칙 (앞으로 이 화면을 볼 기준)
- 대상은 이름 하나, 방식은 이름을 바꾸지 않는다. 키 자체는 언제나
포털 호출 키이고, 만들어진 방식(중앙 발급/기존 키 등록)과 전달(자동 전달)은 형용어다. 용어 원천:client/src/lib/portalIntegrationTerms.ts· 계약:portalIntegrationTerms.test.ts(옛 이름이 화면 문구나 관리자용 서버 메시지에 들어오면 파일·줄·대체 이름과 함께 실패한다). - 상태가 화면 구조를 바꾸지 않는다. 한 포털을 고르면 ① 등록 정보 ② 포털 호출 키 ③ 배포·전달(+R2 자격증명)이 항상 같은 순서로 보인다. 다른 것은 빈 상태 안내뿐이다.
- 구간은 둘. 「자동 구축」은 구간이 아니라 신규 포털을 만드는 방식(
&view=provisioning)이다. - 포털당 활성 포털 호출 키는 하나. 교체는 회전이다 — 자동으로는 대상 적용(health 2xx)이 확인된 뒤에만, 그 외에는 관리자가 「이 키만 남기기」로 명시적으로. (적용 전에 옛 키를 내리면 포털이 401 로 멈춘다.)
- 전달 환경변수 이름의 정본은
PORTAL_CONSOLE_API_KEY(shared/portalDelivery.ts). 기존 행은 자동 변경하지 않는다.
3. 단계별 변경 (커밋 단위)
| 단계 | 커밋 | 내용 |
|---|---|---|
| 1 | 5c8c87b | 용어 단일 원천 + 계약 검사(화면 문구 client/src + 관리자용 서버 메시지 7파일), 화면·에러·서버 문구 이름 통일, 서버 기본 라벨(<포털명> 포털 호출 키) 통일 |
| 2 | 82d0437 | 통합 구간 재구성 — 상태 분기·단계 탭·온보딩 토글 삭제, ①→②→③ 고정, 지표는 목록 열로, 안내문은 섹션 설명으로, 죽은 CSS 12규칙 정리 |
| 3 | ccd80ae | 구간 3 → 2 — 자동 구축을 「신규 포털」 진입 방식으로 흡수(옛 주소 별칭 유지) |
| 4 | edfa85f | 회전 규칙 한 곳(retireSupersededPortalCallKeys) + 관리자 명시 회전 settings.rotatePortalApiKeys(감사 ROTATE_PORTAL_API_KEY) + 경고 축소 |
| 5 | cb93bf6 | 전달 환경변수 이름 정본 통일(shared/portalDelivery.ts) + 화면 경고·문서 |
| 6 | 이 커밋 | 문서 게시 + 앱 패치 버전 1.0.21 |
4. 화면이 이렇게 바뀌었다
포털 연동 설정
├─ 구간 탭: [포털] [포털 접속 권한] ← 3 → 2
└─ 포털 구간 (선택한 포털 하나에 대해 항상 같은 순서)
① 포털 등록 정보 목록 표에 '포털 호출 키'·'전달' 열(예전 상단 지표 그리드 자리)
「신규 등록」(직접) · 「자동 구축」(저장소·배포까지)
② 포털 호출 키 항상 보인다(예전에는 토글에 숨었다) · 「기존 키 등록」 · 「이 키만 남기기」
③ 키 발급·등록 발급 직후 키 원문 1회 표시 + 대상 플랫폼 등록 안내(2026-10-17)5. 검증
pnpm check0 ·pnpm test546건 통과(정리 전 539건 + 신규 계약 7건) ·pnpm build성공 — 각 단계마다 로컬 게이트 통과 후 커밋.- 신규/갱신 계약:
client/src/lib/portalIntegrationTerms.test.ts(용어 단일성·금지어) ·server/portalCredentialDelivery.contract.test.ts(회전 규칙·APPLIED 뒤 회전·버전 없는 키 동반 retire) ·server/portalDeliverySecretName.contract.test.ts(정본 한 곳) ·client/src/lib/directoryAdminStyles.test.ts(상태 분기·단계 탭 부재, ①→②→③ 순서, 명시 회전 UI). - 브라우저 검수는 하지 못했다 — 로컬 콘솔은 DB 환경변수 없이는
/setup으로 제한된다(같은 한계가PORTAL_INTEGRATION_FLOW_AUDIT_2026-08-25.md에도 적혀 있다). 배포 후 관리자 화면에서 ①→②→③ 순서·키 회전·정본 경고를 눈으로 확인해야 한다.
6. 남은 일 / 다음에 볼 것 (2026-10-17 일부 대체됨)
2026-10-17: 배포 연계(자동 구축·배포 대상·자동 전달·적용 확인·R2)를 화면에서 제거했다. 아래 항목 중 자동 회전·R2 회전 관련은 화면에서 더 이상 다루지 않는다. 새 키 발급·등록 절차는
docs/PORTAL_KEY_REGISTRATION.md를 따른다.
- [ ] 배포 후 실제 화면 검수(위 5번) — 특히 ② 포털 호출 키의 「이 키만 남기기」와 ③ 키 발급·등록 안내.
- [x] 기존 배포 대상 행의 전달 이름 이슈 — 화면에서 배포 대상 자체를 제거해 더 이상 다루지 않는다.
- [ ] 자동 회전이 실제로 도는 경로가 아직 좁다 — 지금은
portal_credential_deliveries가DEPLOY_QUEUED로 남아 health 확인 뒤APPLIED가 되는 경우뿐이고, 온프레미스 수동 적용은 화면의 명시 회전을 쓴다. 자동 전달이 아니라 수동 적용을 확인하는 절차를 자동화할지는 별도 판단(포털이 언제 새 키를 읽었는지 콘솔이 알 방법이 없다). - [ ] R2 자격증명(③ 안)도 같은 회전 규칙을 쓸지 검토 — 지금은
r2CredentialDelivery.ts가 자체 retire 로직을 갖는다.
7. 2026-10-17 — 배포 연계 제거, 키 발급·등록 안내로 대체
실제 운영에서 포털마다 배포 플랫폼이 달랐고, 신규 포털도 콘솔의 자동 구축 화면을 쓰지 않았다. 그래서 ③의 배포 대상·자동 전달·적용 상태 확인·전달 이력·R2 자격증명과 ①의 자동 구축 진입점을 화면에서 제거했다. ③은 포털 호출 키 발급 + 대상 플랫폼 등록 안내가 되었다.
- 발급 응답이 키 원문을 한 번만 반환한다(목록은 메타데이터만).
- 발급 시 자동 전달을 호출하지 않는다. 기존 API·DB는 호환을 위해 남긴다.
- 상세 절차·플랫폼별 예시:
docs/PORTAL_KEY_REGISTRATION.md