테넌트와 컨텍스트
App의 조회·저장·백그라운드 작업을 올바른 테넌트와 허용된 조직 범위 안에서 실행합니다.
테넌트와 컨텍스트
App에서 지켜야 할 조건
테넌트 컨텍스트는 어느 고객의 데이터에 접근할지 정합니다. Core가 보호된 테넌트 HTTP handler 실행 전에 이를 복원하고, App은 그 안에서 동작 권한·레코드 가시성·업무 규칙을 검사합니다. 조직이나 workspace를 선택하는 것만으로 권한이 생기지는 않습니다.
| 실행 경로 | App에서 할 일 |
|---|---|
| 생성된 Resource API | 테넌트·설치 미들웨어, 쿼리 범위, Policy 유지 |
| 레코드 생성 | Resource 권한 계약으로 소유자 속성 결정 |
| 조직 조건이 있는 목록 | 페이지가 선언한 범위와 백엔드 권한을 함께 적용 |
| 백그라운드 작업 | 신뢰된 테넌트와 해당 동작에 필요한 행위자 권한 복원 |
| 이벤트 consumer | 이미 복원한 테넌트와 envelope가 같은지 검사. 불일치를 수용하려고 테넌트를 바꾸지 않음 |
HTTP 구현은 보호된 API 추가하기, 백그라운드 실행은 이벤트와 비동기 작업 처리하기에서 이어갑니다.
테넌트·소유자·페이지 범위
| 개념 | 역할 |
|---|---|
| 테넌트 | 데이터·파일·권한·실행을 고객별로 격리 |
| 레코드 소유자 | Resource에 선언된 영속 소유권. 테넌트 또는 Legal Entity 등 |
| Legal Entity / Operating Unit | 테넌트 안의 조직 대상 |
| Access Grant | 행위자·동작·범위·대상 모집단에 대한 권한 |
| Workspace·페이지 선택 | 화면 컨텍스트 또는 요청 결과를 더 좁히는 조건 |
멤버십은 조직을 선택 가능하게 할 수 있지만 레코드 접근 권한을 주지는 않습니다.
페이지 조직 선택기는 Route Surface의 organizationScope slot에 둡니다.
표준 목록은 읽기 permission과 useOrganizationListScope를 사용하고, 커스텀 관계나
여러 permission을 다루는 페이지는 명시적 adapter를 유지합니다. 공통 기준정보
프로필에는 기본 선택기가 없습니다. 상세·수정 화면은 저장된 소유자를 표시합니다.
App 화면 만들기에서 구현을 확인하세요.
권한 계약 사용하기
아래 메서드는 SDK의 Nexia\Laravel\Access\Contracts\ResourceAuthorization에
정의되어 있습니다. 쿼리·Policy·생성 경로에서 이를 사용하고 범위 판단을 별도로
재구현하지 않습니다.
| 메서드 | 용도 |
|---|---|
scopeVisible($query, $resourceKey, $legalEntityId) | 목록을 허용된 레코드로 제한 |
scopeVisibleForLegalEntities($query, $resourceKey, $legalEntityIds) | 표준 직접 소유 모델의 여러 Legal Entity 목록 |
recordMatches($record, $resourceKey, $legalEntityId) | 저장된 레코드가 허용 경계와 맞는지 검사 |
creationAttributes($resourceKey, $legalEntityId) | 생성에 쓸 소유자 컬럼 결정 |
단일 Legal Entity 인자는 생략할 수 있습니다. 검사하지 않은 브라우저 값을 내부 ID로 전달하면 안 됩니다. 여러 조직을 받는 메서드도 커스텀 관계나 Operating Unit 가시성을 대신 구현하지 않습니다. 해당 Resource의 명시적인 쿼리·Policy에서 처리하세요. 그 밖의 권한 판단 요소는 권한과 역할에 있습니다.
백그라운드 컨텍스트 복원
신뢰된 dispatch 경계에서는 호스트 계약인
Nexia\Tenancy\Contracts\TenantRunner의 다음 진입점을 사용할 수 있습니다.
public function runFor(int|string $tenantKey, callable $callback): bool;
public function runForAll(callable $callback): int;Job 구현이 아닌 인터페이스 시그니처입니다. runFor()는 테넌트가 없으면 false,
runForAll()은 callback에 전달한 테넌트 수를 반환합니다. 두 메서드는 테넌트
컨텍스트를 복원·정리하지만 행위자는 복원하지 않습니다. 컨텍스트가 없거나 모호하면
작업을 중단하고, 기본 테넌트로 대체하지 않습니다.
이미 테넌트 안에서 실행 중인 Inbox consumer는 다른 테넌트의 envelope를 거부해야 합니다. 사용자 권한이 필요한 작업은 지원되는 delegated 경로에서 실행 시점에 행위자를 복원하고 다시 인가합니다. 시스템 consumer에 사용자 권한이 암묵적으로 부여되지는 않습니다.
범위 문제 확인하기
테넌트 도메인 → App 설치 → permission·grant → 요청한 조직 → 저장된 레코드 소유자 순서로 확인하세요. 누락된 레코드를 보이게 하려고 쿼리 범위를 넓히지 않습니다. 테넌트 컨텍스트 문제 해결에 증상별 확인 방법이 있습니다.