대시보드에 앱 리포트 추가하기
생성된 Note 건수 리포트를 실행하고 대시보드에 배치합니다.
대시보드에 앱 리포트 추가하기
표준 숫자·표·차트는 인가된 리포트를 대시보드에 배치해서 제공합니다. 첫 예제는 Note 건수입니다. 리포트마다 React 컴포넌트나 iframe을 만들 필요는 없습니다. Resource 만들기에서 Note 생성·저장을 먼저 마치세요.
생성된 리포트 확인
현재 생성기의 src/Contribution/Resources/NoteModule.php는 이미 ReportContribution을 구현하며 다음 형태의 reports()를 제공합니다. 같은 메서드나 리포트를 다시 추가하지 마세요. ReportDefinition import도 생성 파일에 있습니다.
public static function reports(): array
{
return [ReportDefinition::count(
self::resourceKey().'.count',
'workshop.note.list.title',
self::resourceKey(),
)];
}앱이 Workshop이 아니라면 생성된 키를 유지합니다. ReportDefinition::count()는 기존 Resource의 권한을 검사하는 Composition 조회와 MetricCard 표현을 만듭니다. 건수는 조회가 허용된 레코드를 대상으로 하며, 메뉴에 보이는 전체 행이나 임의 SQL로 계산하지 않습니다.
실행·배치 확인
nexia dev에서 선언 반영·준비 완료를 확인합니다.- Note 조회 권한과 필요한 법인 범위를 사용자에게 부여합니다. 리포트·대시보드 화면 자체에 필요한 접근 권한도 있어야 합니다.
- 리포트 관리 목록에서 Note 리포트를 열고 같은 사용자·조회 범위의 Note 건수와 비교합니다.
- 대시보드 편집의 리포트 탭에서 해당 리포트를 배치하고 저장합니다.
- 다시 열어 값이 유지되는지, Note를 추가한 뒤 다시 조회하면 건수가 바뀌는지 확인합니다.
- 조회 권한을 회수한 사용자에게 기존 배치가 데이터를 노출하지 않는지 확인합니다. 다른 사용자의 결과를 재사용하지 않습니다.
리포트가 없다면 앱 선언 반영 문제 해결을 확인합니다. 리포트 원본을 편집하려면 사본 저장으로 사용자 소유 리포트를 만듭니다. 공유가 데이터 접근 권한을 부여하지는 않으며 대시보드 배치는 리포트 리비전을 고정합니다.
더 복잡한 표현 선택
| 목적 | 경로 |
|---|---|
| 레코드 건수 | 생성된 ReportDefinition::count() 재사용 |
| 표·차트·피벗 | 공개 필드와 허용 집계에 맞는 CompositionSpec 및 리포트 표현 정의 |
| 생성·수정·승인 같은 업무 | App 화면 만들기의 React 업무 화면과 보호된 API |
행 목록의 필터·정렬 선언만으로 분석 필드가 공개되지는 않습니다. 별도 분석을 추가할 때는 Resource descriptor의 안전한 composition 필드·집계·단위를 맞춰야 합니다. 다른 앱 테이블 join이나 숫자 PK 노출로 우회하지 마세요. 이 가이드는 생성된 건수 리포트에 한정하며 사용자 정의 차트·슬롯 위젯의 전체 API 예제를 대신하지 않습니다.
격리 앱에서 그룹 집계·사용자 정의 Composition을 사용하기 전에 지원되는 리포트 쿼리를 확인하세요.
사용자 정의 위젯 조회
사용자 정의 위젯은 @nexia/sdk/host의 useWidgetQueryRuntime()으로 주변 런타임의 query(tool, args, signal)을 사용합니다. 위젯에서 조회 URL을 직접 호출하지 마세요. Core 화면과 별도 App 런타임의 연결 방식은 호스트가 선택하고 서버는 등록된 조회 소스와 사용자 권한을 검사합니다. queryRef와 기존 응답 형식은 유지되며 조회로 업무 데이터를 생성·수정·삭제할 수 없습니다. 이 기능을 제공하는 SDK와 Core를 함께 적용한 뒤 App을 전환합니다.
기존 앱과 적용 순서
별도 App 개요 화면은 지원 중단 예정(deprecated)입니다. 새로운 개요는 별도의 화면을 구성하기보다 SDK의 리포트와 대시보드 계약을 사용해 플랫폼 대시보드로 제공하세요. 업무 생성·수정·승인 화면은 이 기준의 대상이 아닙니다.
현재 기본 대시보드 선언은 런타임에서 선택 사항이며, 선언하지 않은 앱의 기존 개요 화면은 계속 동작합니다. 기존 일반 개요를 자동으로 삭제하거나 대시보드로 변환하지 않으며, 저장된 대시보드의 사용자 편집 내용은 유지합니다. 제거 일정은 정해지지 않았습니다. 현재 생성기는 개요 파일을 생성합니다. 생성된 경로는 현재 런타임 요구에 맞게 유지하고 별도 개요 기능을 새로 추가하지 마세요. 기존 경로를 제거하기 전에 대시보드에 필요한 정보와 동작을 제공하고 실제 호환성을 확인하세요.
기존 위젯의 법인 범위 선언이 없으면 새 대시보드의 법인 선택에 따라 조회한다고 가정할 수 없습니다. 기존 개요 화면의 법인 선택도 해당 화면의 기존 구현을 따릅니다.
아래 계약은 이를 제공하는 PHP SDK와 React SDK, Core 및 앱 런타임이 모두 적용된 환경에서 사용하세요. 배포 전에는 제공된 SDK 버전과 프로젝트의 의존성 잠금파일을 확인하고, 개발 환경과 배포 환경의 버전을 맞춥니다. 새 계약을 사용하지 않는 앱은 별도 전환 일정을 잡을 수 있습니다. 기존 위젯이나 리포트의 호환성은 실제 사용하는 쿼리와 데이터에 대해 확인하세요.
앱 기본 대시보드 선언
이미 등록한 위젯의 키를 순서대로 반환합니다. 앱당 구현은 하나만 둘 수 있고 키는 중복할 수 없습니다. 해당 앱의 위젯으로 등록하지 않은 키는 사용할 수 없습니다.
use Nexia\Dashboard\Contracts\DashboardDefaultContribution;
final class DefaultDashboard implements DashboardDefaultContribution
{
public static function dashboardDefaultWidgetKeys(): array
{
return ['workshop.note_count']; // 이미 등록한 앱 위젯 키
}
}빈 배열을 반환하면 편집 가능한 빈 기본 대시보드를 선언합니다. 선언 자체를 생략하면 기존 개요 화면을 유지합니다. 기본 대시보드가 제공되면 사용자가 편집할 수 있습니다. 기존 개요의 카드와 이동 링크를 유지하려면 각각의 위젯과 동작을 앱에서 선언해야 합니다.
위젯의 법인 범위
앱의 각 DashboardQuerySource를 실제 데이터에 맞게 분류합니다.
| 데이터 | 선언 | 동작 |
|---|---|---|
| 선택한 법인의 데이터 | legalEntityScope: 'selected', usesLegalEntitySelection: true | 선택한 법인 전체를 조회에 적용 |
| 개인 메모처럼 법인 선택과 무관한 데이터 | legalEntityScope: 'independent', usesLegalEntitySelection: false | 법인 선택이 바뀌어도 같은 범위 사용 |
기존 DashboardQuerySource 생성자에 두 인자를 추가하는 예시입니다. 키·경로·권한은 앱에 이미 등록한 값으로 바꾸세요.
use Nexia\Dashboard\DashboardQuerySource;
use Nexia\Permission\SubjectPopulation;
new DashboardQuerySource(
key: 'workshop.note_summary.read',
description: 'Note summary',
path: '/api/workshop/dashboard/note-summary',
permission: 'workshop.note.read',
subjectPopulation: SubjectPopulation::LegalEntity,
usesLegalEntitySelection: true,
legalEntityScope: 'selected',
);조회 핸들러에서는 Nexia\Laravel\Dashboard\DashboardWidgetSelection::legalEntityPublicIds($request)로 선택된 법인의 공개 ID 배열을 받습니다. 한 개와 여러 개를 모두 처리하고, 각 데이터의 실제 법인 관계에 따라 필터링하세요. 결과가 null이면 법인 범위가 전달된 대시보드 위젯 요청이 아니므로 해당 핸들러의 기존 조회 방식을 유지합니다. null을 무제한 데이터 조회 권한으로 해석하지 마세요. 선택은 권한 부여가 아니며 기존 사용자·행 단위 권한 검사도 적용해야 합니다.
리포트와 확인
리포트 정의는 위젯마다 복제하지 않습니다. 리포트를 단독으로 열면 리포트의 법인 선택을 사용하고, 대시보드에 배치하면 대시보드의 법인 선택을 사용합니다. 실제 소스가 선택한 법인에 해당하는 행을 반환해야 합니다. 테넌트 소유 리소스의 기존 리포트 필터를 대시보드 Resource 조회에도 적용하려면, 필터가 다중 법인과 현재 사용자를 올바르게 처리하는지 확인한 뒤 DashboardReportLegalEntityFilter 계약을 구현하세요. 이 선언은 권한을 부여하지 않습니다. 지원 범위와 소스별 구현은 지원되는 리포트 쿼리를 확인하세요.
전환 후 nexia check와 nexia dev로 선언을 확인하고, 리포트 단독 화면과 대시보드에서 법인 하나·여러 개를 각각 선택해 실제 건수를 비교하세요. 한 법인만 조회 가능한 사용자, 권한이 없는 법인, 법인과 무관한 개인 위젯도 확인합니다. 기존 화면과 저장된 위젯을 사용하는 앱은 그 경로도 직접 확인하세요. 새 기본 대시보드를 선언하지 않은 앱의 기존 개요가 유지되는지도 확인합니다.
useQuery에 사용하는 동일한 조회 키를 @nexia/sdk/host의 useDashboardDataSource(queryKey, runtime.supportsRealtimeInvalidation && enabled && !preview)에 등록합니다. 해당 대시보드의 새로고침 버튼과 갱신 시각에 연결되며 미리보기는 등록하지 않습니다. 두 훅 모두 기존 Core 실행 환경과 조회 등록 기능을 재사용합니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
본인 범위의 복합 조회
SubjectPopulation::Self를 선언한 사람용 DashboardQuerySource에서는 같은 App의 다른 조회 권한도 SubjectPermissionAuthorizer::allowsSubjectPopulation(..., SubjectPopulation::Self, ...)로 확인할 수 있습니다. 각 판정에는 서명된 조직 범위에서 사용자에게 실제 부여된 권한이 필요합니다. 조회 소스에 선언된 진입 권한은 여전히 필요하며, 추가 조회 권한만으로 소스에 진입할 수는 없습니다.
App의 모든 쿼리에 본인·고용관계 및 법인 조건을 명시하세요. 일반 PermissionAuthorizer 권한, 쓰기 권한, 다른 대상 범위, 다른 App의 권한이나 추가 Agent 권한은 부여하지 않습니다. 권한을 회수한 뒤에도 다시 확인하세요. 해당 Core 수정 버전의 배포가 필요하며 SDK API 변경은 없습니다.