워크스페이스 전환 가이드 (사용자용)
GenD 의 워크스페이스 는 데이터 + 작업물 격리의 기본 단위입니다. 한 사용자가 여러 워크스페이스에 동시 소속할 수 있으며 (예: 금융 인텔리전스 + 한국가스공사), 화면 상단 드롭다운 또는 CLI 명령으로 즉시 전환됩니다.
본 가이드는 Epic #1362 W2 결과를 기준으로 작성. 운영자 시드/롤아웃은 Workspace W2 Rollout 가이드 참고.
멤버십 확인
자신이 어느 워크스페이스에 속하는지 확인:
- UI: 화면 상단 좌측의 워크스페이스 이름 클릭 → 드롭다운에서 모든 멤버십 표시.
- CLI:
gend workspace list— 표 형식으로 가시. - API:
GET /api/v1/workspaces/mine—[{slug, name, status}, ...]배열 응답.
멤버십이 없다면 admin 에게 워크스페이스 할당을 요청하세요 — /admin/workspaces 가이드.
워크스페이스 전환
UI 드롭다운
- 화면 상단 좌측의 워크스페이스 트리거 클릭.
- 드롭다운 항목을 클릭 → 즉시 전환 + 토스트.
전환 즉시 다음 동작이 일어납니다:
localStorage.gend.active_workspace_slug갱신- 카탈로그 트리 캐시 invalidate → 자동 재조회 (#2718)
- 다른 화면의 캐시는 순차 편입 중 — 목록이 갱신되지 않으면 새로고침
- 다음 모든 API 요청의
X-Workspace-Slug헤더 자동 첨부 - 서버에
POST /api/v1/workspaces/switchaudit 이벤트
관리자: "전체 워크스페이스" 섹션 (#2798)
플랫폼 관리자(admin)는 드롭다운에 멤버십 목록 아래로 "전체 워크스페이스 (관리자)" 섹션이 추가로 보입니다 — 멤버가 아닌 워크스페이스도 활성 컨텍스트로 선택할 수 있습니다 (impersonation).
- 비멤버 항목은 방패 아이콘으로 구분되며, 선택 시 모든 접근이 감사에 기록됩니다 (전환 토스트에도 명시)
- 멤버십이 하나도 없는 관리자는 "워크스페이스 없음" 대신 "워크스페이스 선택" 트리거가 표시됩니다 — 쓰기 작업(데이터 마트 생성·CSV 승격·학습 데이터셋 생성) 전에 반드시 대상 워크스페이스를 선택하십시오. 선택하지 않은 쓰기는 쓰기 네임스페이스 게이트 enforce 전환 후 403 으로 거부됩니다 (쓰기 타겟 네임스페이스 게이트 참조)
- 자동 선택은 하지 않습니다 — 어느 테넌트로 쓸지는 명시적으로 고르는 것이 설계입니다
CLI
# 현재 active 확인
gend workspace current
# 전환 (영구 — ~/.gend/active_workspace 파일에 저장)
gend workspace switch finance-invest
# per-call override (영구 설정 변경 없이 1회만)
gend --workspace energy-kogas catalog list
# 환경변수 override (스크립트 안에서)
GEND_ACTIVE_WORKSPACE_SLUG=finance-invest gend query run ...
# 영구 설정 제거 (JWT 첫 멤버십 폴백)
gend workspace clear
API 직접 호출
curl -H "Authorization: Bearer $TOKEN" \
-H "X-Workspace-Slug: energy-kogas" \
https://gend.genon.ai/api/v1/...
헤더 누락 시 서버는 JWT groups claim 의 첫 /tenants/<slug> 멤버십으로 폴백합니다 — 다중 멤버십이면 결과가 결정적이지 않으니 항상 헤더 명시 권장.
우선순위 (CLI)
| 우선순위 | 출처 | 비고 |
|---|---|---|
| 1 (최상) | --workspace <slug> flag | per-call |
| 2 | GEND_ACTIVE_WORKSPACE_SLUG env | per-process |
| 3 | ~/.gend/active_workspace file | persistent |
| 4 (최하) | (헤더 미첨부 → 서버가 JWT 폴백) | 비결정적 — 비권장 |
UI 는 (2)~(3) 와 무관 — 항상 brower localStorage 가 진실의 원천.
워크스페이스 간 데이터 격리
| 데이터 그룹 | 정책 |
|---|---|
Fact 테이블 (intel_articles, intel_ohlcv_* 등, workspace_id IS NULL) | 전사 공유 — 모든 워크스페이스에서 동일 가시 |
Derived 작업물 (intel_briefings, intel_risk_reports, query_history 등, workspace_id NOT NULL) | 격리 — 현재 active 워크스페이스 행만 가시 |
| 온톨로지 instance, 데이터마트 | 격리 |
전환 후 동일 페이지 (예 /intel/briefings) 의 row 가 줄거나 빈 화면이 되면 격리 효과가 정상 동작하는 것입니다.
자주 묻는 질문
Q. 드롭다운에 한 개만 보입니다.
A. JWT groups claim 에 /tenants/<slug> 가 1개만 있는 상태입니다. admin 이 추가 멤버십을 부여 후 로그아웃 → 재로그인 하면 두 개 이상 노출됩니다.
Q. 드롭다운에 빨간 점 + "워크스페이스 사용 불가" 가 보입니다.
A. 서로 다른 두 원인이 같은 화면을 만듭니다 — 트리거에 마우스를 올리면 툴팁으로 구분할 수 있습니다 (오류 메시지 vs "워크스페이스 미할당").
- 멤버십 미설정 (일반 사용자의 정상 상태) — 빈 멤버십 응답도 이 화면입니다.
JWT 의
groups가/tenants/<slug>형식이 아닐 수도 있으니 Keycloakgroup-membershipmapper 의full.path=true여부를 운영자에게 확인 요청하십시오 (#1383 가드). - 목록 조회 실패·인증 오류 — 네트워크/서버 오류도 같은 화면입니다.
관리자 계정은 #2798 이후 정상 상태라면 이 화면 대신 "워크스페이스 선택" 트리거가 떠야 하며(위 "전체 워크스페이스" 절), 빨간 점이 계속 보이면 2번(조회 실패)입니다.
Q. 전환 후 데이터가 그대로입니다.
A. 흔한 순서대로:
- 플랫폼 관리자(admin) 계정으로 보고 있다. 관리자 역할은 워크스페이스 가시성 필터를 우회해 전사 데이터를 조회합니다 — 카탈로그 트리는 어느 워크스페이스에서도 동일하게 보입니다. 이건 버그가 아니라 현재 설계입니다. 격리를 확인하려면 일반 사용자(viewer/analyst) 계정으로 보십시오.
- 보는 데이터가 Fact 테이블 (
workspace_id IS NULL) — 전사 공유. - 격리 데이터가 양쪽 워크스페이스에서 우연히 동일 row 를 가질 때 — 매우 드뭄.
위 셋 중 어디에도 해당하지 않는데 목록이 같다면 결함일 수 있습니다. 사용 중인 계정의 역할과 멤버십 목록을 함께 운영자에게 알려 주십시오.
Q. 워크스페이스마다 보이는 카탈로그가 다른 게 맞나요?
A. 맞습니다. 카탈로그·스키마·테이블 목록은 현재 활성 워크스페이스의 데이터 권한(DataGrant) 으로 필터링됩니다. 같은 사용자라도 워크스페이스를 바꾸면 보이는 목록이 달라집니다.
권한이 없어 목록이 비면 "No catalogs available" 과 함께 데이터 액세스 요청 링크가 표시됩니다. 관리자에게 해당 워크스페이스의 권한 부여를 요청하십시오.
관련
- Workspace W2 Rollout — 운영자 시드 가이드
- /admin/workspaces UI 가이드 — admin 멤버 관리
- gend-cli 빠른 시작
- Epic #1362 — W2 다중 멤버십