Platform Docs

Appearance

통합 탐색·답변(§14) 연계 이관 계획 — Document Library ​

상태: 1~4단계 완료(2026-10-05) · 5단계(게이트웨이 어댑터 노출)·6단계(운영 등록) 남음 선행: Guide Center·Document Library §16 용어 파이프라인(완료) 참조 구현(검증됨): ProcessCenter explore.gatewayAsk / AgentCenter explore.ask(exploreAskService)

1. 목표 ​

셸 상단 검색창이 중앙 통합 탐색이 되고, 질문은 게이트웨이 → 중앙 RAG(RagService) 가 답한다. 검색은 이 포털 색인(kind=document 로 게이트웨이에 제공), 답변은 게이트웨이 위임이 정본이며 자기 색인은 폴백이다 (ExploreGateway/docs/adapter-onboarding.md §3-2).

2. 실측한 제약 (2026-10-05 확인) ​

항목사실영향
현재 PF@hohyun94/portal-foundation 0.6.46 (file:vendor/...tgz)122버전 뒤처짐
PortalFrame0.6.168 에서 제거됨(export 없음)셸 교체가 필수다 — 유지 불가
PortalShell0.6.168 에 존재. antd 를 의존성으로 번들(antd ^6.6.3)소비자가 antd 를 선언할 필요 없다
PortalShellPropssearchValue·onSearchChange·onSearchSubmit·exploreResults·onExploreSelect·onExploreAsk·exploreAnswer·exploreAnswerLoading 보유탐색 슬롯은 이미 있다
quickLinks·quickLinksLabelPortalShellProps 에 없다DL 의 바로가기를 다른 슬롯으로 옮겨야 한다(결정 필요)
유지되는 APIPortalIcon·DocumentLibraryMark·buildPortalNavigationItems·buildPortalQuickLinks·PortalMenuItem·PortalQuickLink내비게이션·바로가기 빌더 로직은 그대로 쓸 수 있다
DL 의 PF 사용면client/src/components/PortalShell.tsx 래퍼 + Login.tsx(AuthCard) + App.tsx(PortalThemeProvider) — 4개 파일교체 반경이 작다
DL 서버 탐색탐색 어댑터·답변 경로 없음(server/contentTermService.ts 만 있음)서버 경로를 새로 만든다

3. 결정이 필요한 2건 (권장안 포함) ​

  1. 상단 검색의 의미 — PF 규약(docs/EXPLORE_ANSWER_CONVENTION.md)은 입력 표면을 셸 통합 검색창 + 페이지 내 검색창 둘로 못박는다.
    • 권장: 상단 검색 = 탐색 대화창(onSearchSubmit·onExploreAsk), 게시판 필터는 페이지 안으로 이동(게시판 목록 헤더의 입력).
    • 근거: 새 셸에서 searchValue/onSearchChange 는 탐색 대화창 입력을 구동한다 — 게시판 필터를 그대로 두면 성격이 다른 두 기능이 한 입력을 공유하게 된다.
  2. 바로가기(quickLinks) 위치 — 0.6.168 셸에 슬롯이 없다.
    • 권장: sidebarFooter 또는 accountMenuItems 로 옮긴다(관리자 바로가기는 이미 adminHref·admin 셸이 있다).
    • 대안: 중앙 메뉴 공급(PortalConsole)으로 이관 — ProcessCenter 처럼 navigationItems 에 포함.

4. 작업 단계 ​

  1. ✅ 벤더·의존성 — portal-foundation 0.6.168·portal-operations 0.3.1 반입, package.json 갱신, pnpm install. vite 테스트에서 사내 file: 패키지는 server.deps.inline 으로 변환해야 한다(vite.config.ts).
  2. ✅ 셸 교체 — PortalFrame → PortalShell. 관리자 진입은 roleSwitch 가 소유하고(셸에 adminHref·quickLinks prop 이 없다), 바로가기는 그대로 두지 않는다. 커밋 9052986(동작 동일 단독 커밋).
  3. ✅ 서버 경로 — server/exploreGateway.ts(위임 토큰 캐시 + 게이트웨이 /api/explore/v1/ask) · server/explore-api.ts(GET /api/explore/capabilities, POST /api/explore/ask).
  4. ✅ 클라이언트 — client/src/features/explore/useShellExplore.ts(게시판 색인 → 셸 결과, 서버 답변 → 셸 답변 카드) + 셸 래퍼 배선(exploreResults·onExploreSelect·onExploreAsk·exploreAnswer).
  5. ✅ 게이트웨이 어댑터 노출 — server/explore-adapter.ts(POST /api/explore/v1/search, 서비스 토큰 인증). 게시글(문서)을 제목·본문 부분 일치로 찾아 kind=document 로 돌려준다. 이 포털의 읽기 규칙은 "인증 사용자 전체" 이므로 주체별로 더 좁힐 축이 없다(없는 축을 흉내 내지 않는다).
  6. ⏳ 운영 등록 — PortalConsole PORTAL_CONSOLE_TOKEN_CONSUMERS_JSON 에 document-library 소비자(delegationAudiences: ["explore-gateway"], delegationScopes: ["search:read"]), ExploreGateway PORTAL_SERVICE_TOKENS_JSON 에 EXPLORE_SERVICE_TOKEN 값.
  7. ✅ 검증 — pnpm check 0 · pnpm build 0 · pnpm test 86 passed(신규 9: 위임 발급·캐시·반쪽 구성·게이트웨이 호출, 게시판 결과 변환·인용 없는 답변 버리기).

4-1. 선확인 결과(2026-10-05) ​

  • DL 인증은 두 모드다(server/portalIntegrationConfig.ts): directory(중앙 로그인, Directory 사용자 ID 를 로컬 원장에 매핑) / local(자체 관리자). 위임 토큰의 주체는 Directory 사용자여야 하므로 연동은 directory 모드에서만 켜진다 — local 배포에는 위임할 주체가 없다. 그래서 GET /api/explore/capabilities 가 authProvider !== "directory" 면 answer: false 를 돌려주고, POST /api/explore/ask 는 503 으로 그 사실을 알린다(빈 답으로 위장하지 않는다).
  • 바로가기(quickLinks) — 0.6.168 셸에 슬롯이 없다. DL 의 유일한 바로가기(관리자)는 roleSwitch 로 흡수했다(플랫폼 표준 진입).
  • 게시판 필터 — 상단 검색창이 탐색 대화창을 열고, 그 입력값이 게시판 필터를 함께 구동한다(기존 동작 유지). 대화창은 그 값을 그대로 결과로 보여 준다 — 화면 목록과 대화창이 같은 규칙을 쓴다.

5. 하지 않는 것 ​

  • 포털 로컬 RAG 색인·검색을 게이트웨이로 위임하지 않는다 — 검색은 각 포털이 소유한다(답변만 위임).
  • 게이트웨이가 답을 만들지 않는다(오케스트레이션만).
  • PF 0.6.168 의 PortalExploreDialog 를 새로 만들지 않는다 — 셸이 이미 제공한다.