테넌트 웹 런타임
테넌트 제품이 React SPA와 CSR, API 중심 상태 모델을 선택한 이유와 서버 렌더링이 남아 있는 경계를 설명합니다.
테넌트 웹 런타임
기존 Shell에 App 진입점과 경로를 등록하고 인증된 API에서 화면 데이터를 읽으세요. React root나 router를 별도로 만들지 않습니다. App 화면 만들기를 적용하면 내비게이션과 직접 URL 진입에서 같은 화면이 열리고 API 권한 검사도 동일하게 유지되어야 합니다.
React 애플리케이션 하나로 실행
Nexia의 테넌트 제품 화면은 React SPA입니다. Laravel이 한 번 HTML Shell을
내려주면 React가 하나의 루트에 마운트되고, 그다음 화면 이동은
BrowserRouter가 브라우저 안에서 처리합니다. 화면에 필요한 데이터는
페이지를 바꿀 때마다 서버가 props로 넣어 주는 방식이 아니라, 인증된
테넌트 API에서 읽고 씁니다. React Query는 이 요청의 로딩 상태와 캐시를
관리합니다.
여기서 SPA는 브라우저에 오래 살아 있는 하나의 애플리케이션이라는 뜻이고, CSR은 Shell을 받은 뒤 React가 실제 화면을 그린다는 뜻입니다. Nexia의 모든 웹 페이지가 같은 방식이라는 말은 아닙니다. Central 운영 화면이나 관리자 영역은 각자 목적에 맞는 전달 방식을 쓸 수 있습니다. SPA·CSR 선택의 대상은 테넌트가 사용하는 제품 Shell과 그 안에 조합되는 App 화면입니다.
화면 요청 처리 순서
한 번의 화면 진입은 서버 bootstrap과 브라우저 런타임으로 나뉩니다.
| 단계 | 담당 | 결과 |
|---|---|---|
| 테넌트 도메인 요청 | Laravel 테넌시 middleware | 테넌트와 범위가 정해진 세션 확립 |
| Shell 응답 | routes/tenant.php | 제품 경로에 shell-os HTML 반환 |
| React 시작 | resources/js/app.tsx | 라우터·다국어·query state를 한 번 초기화 |
| Shell bootstrap | Core Shell runtime | 설치된 App과 사용 가능한 contribution 해석 |
| 화면 데이터 | 테넌트 API | 현재 권한으로 볼 수 있는 데이터 반환 |
| 이후 이동 | BrowserRouter | 문서를 새로 받지 않고 화면 전환 |
서버의 catch-all route는 이 구조를 위해 존재합니다. routes/tenant.php는 인증
동작과 명시적인 backend route, 관리자 경로를 먼저 등록한 뒤 마지막 GET
요청을 같은 Shell view로 보냅니다.
인증된 Shell 응답은 ShellBootstrapBuilder 결과를 포함하고 Cache-Control: no-store, private을 보냅니다. Guest는 /login으로 이동합니다. Catch-all은 관리자 경로, .well-known, 정적 asset 확장자를 제외하므로 없는 asset을 제품 경로로 취급하지 않습니다.
따라서 사용자가 깊은 URL을 주소창에서 바로 열어도 먼저 SPA Shell을 받고, 마운트가 끝난 뒤 클라이언트 라우터가 실제 화면을 찾습니다.
App이 합류하는 지점
App은 새로운 React root나 별도 router를 만들지 않습니다. App SDK가 정한 프런트엔드 엔트리와 contribution을 공개하면, Core가 설치 상태를 확인해 기존 Shell에 route와 surface를 조합합니다. 내비게이션, permission-aware action, query state, locale runtime 같은 공통 기능은 계속 호스트가 소유합니다.
API와 데이터 저장 규칙
CSR은 권한 검사가 아닙니다. 브라우저 메모리와 route guard, 숨겨진 버튼은 사용자가 우회할 수 있습니다. 보호된 변경은 반드시 Laravel에서 다시 검사합니다.
SPA라고 해서 브라우저 저장소가 업무 데이터베이스가 되는 것도 아닙니다. React Query나 로컬 store는 빠른 상호작용을 돕지만, 지속되어야 하는 제품 상태는 테넌트 저장소에 남아야 합니다. 새로고침으로 클라이언트 상태가 사라져도 API에서 다시 만들 수 있어야 합니다.
마지막으로 개발자 포털, 공개 사이트, Filament 관리자 영역은 테넌트 SPA와 소유자가 다릅니다. 저장소 안에 함께 있다는 이유로 같은 렌더링 결정을 따르지는 않습니다.
직접 URL 진입 확인
등록한 App 경로를 주소창에서 직접 연 뒤 내비게이션으로 같은 경로에 들어가세요. 두 경로 모두 호스트 안에서 App 화면이 마운트되고 테넌트 API를 사용해야 합니다. Shell 문서를 받았다고 미등록 경로가 유효해지지는 않으며 화면 표시가 백엔드 읽기 권한을 대신하지도 않습니다.
함께 읽기
- Nexia 시스템 개요 — 화면을 만들기 전에 호스트·SDK·App 소유 범위를 구분합니다.
- Shell 레이아웃 영역 — 하나의 Shell이 조합하는 영역의 이름을 확인합니다.
- App 화면 만들기 — 이 런타임에 SDK로 화면을 연결하는 절차입니다.
- 테넌트와 컨텍스트 — SPA의 API 호출 전에 서버가 확립해야 하는 실행 컨텍스트를 다룹니다.