Platform Docs

Appearance

통합 탐색·답변(§14) 연계 — Guide Center ​

상태: 셸 정렬 + 검색·답변 배선 + 검색 어댑터 노출 완료(2026-10-05) · 운영 등록만 남음 참조 구현: ProcessCenter explore.gatewayAsk · AgentCenter explore.ask · DocumentLibrary server/exploreGateway.ts

1. 한 일 ​

  1. 셸 정렬 — portal-foundation 0.6.46 → 0.6.168. 최신 PF 에서 PortalFrame 이 제거되어 셸 교체가 필수다.
    • client/src/components/PortalFoundation.tsx 재수출 배럴: PortalFrame → PortalShell, PortalFrameProps → PortalShellProps(재수출하는 나머지 심볼은 0.6.168 에 그대로 있다).
    • client/src/pages/Home.tsx: PortalShell 로 교체. 셸에 adminHref·quickLinks·footer prop 이 없으므로 관리자 진입은 roleSwitch, 번역 운영 바로가기와 기존 footer 는 sidebarFooter 로 옮겼다.
    • 상단 검색창은 이제 탐색 대화창(PortalShell → PortalTopNav → PortalExploreDialog)을 연다. searchValue/onSearchChange 는 대화창 입력을 구동하고, 페이지 내 매뉴얼 필터가 같은 값을 쓴다.
  2. 서버 위임(server/exploreGateway.ts) — 위임 토큰(경로 B: client_id·client_secret → {원장}/api/internal/delegation-token)을 사용자·audience 별로 캐시하고, 게이트웨이 /api/explore/v1/ask 를 호출한다.
  3. 라우터(server/exploreRouter.ts, appRouter.explore) — capabilities(답변 슬롯 구성 여부)와 ask(위임). 위임 주체는 세션의 directoryUserId 다.
  4. 클라이언트(client/src/features/explore/useShellExplore.ts) — 검색 결과는 매뉴얼 카탈로그에서 만들고(같은 검색어로 거른 같은 노드), 답변은 trpc.explore.ask 로 받는다. 인용 없는 답변은 버린다(§2-4).
  5. 검증 — pnpm check 0 · pnpm build 0 · pnpm test 84 passed(신규 16: 위임 발급·캐시·반쪽 구성·게이트웨이 호출, 결과·답변 변환·페이지 복원, 어댑터 토큰 계약).
  6. 검색 어댑터 노출(server/explore-adapter.ts) — POST /api/explore/v1/search(서비스 토큰 인증). 권한 축을 그대로 지킨다: 게이트웨이가 준 x-explore-subject-id(Directory 사용자 ID)로 이 포털 사용자를 찾고(getUserByDirectoryUserId → 없으면 getUserByOpenId), 찾지 못하면 미인증 취급해 공개 노드만 내보낸다. 카탈로그 해석은 화면과 같다(visibleCatalog((영속 카탈로그) ?? getLocalizedCatalog, user)).
  7. 딥링크(client/src/pages/Home.tsx) — 결과 href 가 /?page=<pageId> 다. Home 이 ?page= 를 읽어 매뉴얼을 열고, 선택 시 주소를 갱신한다(replaceState) — 포털 간 이동이 실제로 그 화면을 연다.

2. 남은 일 ​

  1. 운영 등록 — 원장 PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON(clientId: "guide-center", delegationAudiences: ["explore-gateway"], delegationScopes: ["search:read"]), ExploreGateway PORTAL_SERVICE_TOKENS_JSON["guide-center"](어댑터용 서비스 토큰) + portal_configurations 등록.
  2. env — EXPLORE_GATEWAY_URL, EXPLORE_GATEWAY_AUDIENCE, GUIDE_CENTER_SERVICE_CLIENT_SECRET, EXPLORE_SERVICE_TOKEN. 표는 docs/deployment-coolify.md.

3. 지킨 규칙 ​

  • 게이트웨이는 답을 만들지 않는다(오케스트레이션만) — 정본은 중앙 RAG(RagService)다.
  • 검색은 각 포털이 소유한다(위임하지 않는다). 답변만 위임한다.
  • 답을 만들 수 없는 배포·세션은 슬롯을 켜지 않는다(capabilities) — 눌러도 답이 없는 버튼을 만들지 않는다(§19.3).
  • 답이 없는 것(provider 무응답)과 못 만든 것(연계 미구성)을 같은 화면으로 뭉개지 않는다(§10.5).