이미 만든 App 화면을 App 메뉴에 노출합니다. App 패키지 만들기를 마친 App과 동작하는 화면이 필요합니다. 메뉴 선언과 별도로 해당 API의 읽기 권한을 먼저 구현하세요.

목적지 등록

Manifest의 contribution 경로에 NavigationContribution 구현을 두고 navigationItems()에서 목적지를 반환합니다. 아래 코드는 packages/people/src/Contribution/PeopleWorkNavigation.php의 실제 온보딩 목적지만 남긴 완전한 contribution입니다.

코드 예시

PHP

<?php

namespace Amuzcorp\Nexia\PeopleCore\Contribution;

use Nexia\Navigation\Contracts\NavigationContribution;
use Nexia\Navigation\NavigationItem;

final class PeopleWorkNavigation implements NavigationContribution
{
    public static function navigationItems(): array
    {
        return [NavigationItem::make(
            id: 'people-onboarding',
            route: '/apps/people/onboarding',
            icon: 'list-checks',
            sort: 210,
            labelKey: 'people.onboarding.title',
            appKey: 'people',
            contextId: 'app',
            groupId: 'management',
            permission: 'people.onboarding_case.read',
        )];
    }
}123456789101112131415161718192021222324

labelKey에는 번역 카탈로그 키, permission에는 이미 선언한 읽기 권한을 넣습니다. 이 권한은 링크 표시 여부를 결정하므로 API에서도 권한을 검사해야 합니다. 별도 화면을 새로 만들었다면 App 화면 만들기에 따라 컴포넌트 등록과 pageElementsExtras() 연결을 완료합니다.

클래스를 추가한 뒤 discovery를 갱신합니다.

코드 예시

Shell

task artisan -- nexia-runtime:generate-app-map
task artisan -- nexia-runtime:refresh-runtime-caches12

결과 확인

App이 운영 가능한 테넌트에서 읽기 권한이 있는 계정으로 메뉴를 엽니다. 관리 그룹의 온보딩 항목을 누르면 연결한 화면이 열려야 합니다. 권한이 없는 계정에서는 메뉴가 사라지고 같은 API 요청도 거절되어야 합니다. 명령 팔레트에서 번역된 제목으로 검색하면 검색 노출도 확인할 수 있습니다.

Resource 목록과 배치

생성된 Resource는 ContributesNavigationDestination을 통해 메뉴를 제공합니다. 별도 contribution을 중복 생성하지 말고 $navigation을 조정하세요. 생성 과정은 Resource 만들기에 있습니다. visible: false는 메뉴만 숨기며 Resource 경로는 유지합니다.

설정	쓰임
`contextId: 'app'`	소유 App의 `app:{app_key}`로 해석
`groupId: null`	App 개요처럼 그룹 밖에 배치
`insights`, `management`, `operations`, `master-data`, `settings`	App에서 사용하는 그룹
`subgroupId`	그룹 안의 하위 묶음; `groupId` 필요
`permission` 배열	나열한 권한 중 하나가 있으면 노출
`searchable: false`	검색 결과에서 제외

Shell 컨텍스트와 그룹 순서는 플랫폼이 관리합니다. 설정 화면은 설정 페이지 추가, 에이전트의 화면 이동은 Command Palette 검색를 이어서 보세요. 부모 목적지, 활성 경로 패턴, 대상 집단 옵션은 packages/app-sdk/packages/laravel/src/Navigation/NavigationItem.php에 정의되어 있습니다.

항목이 나타나지 않을 때

클래스 발견 외에도 App 운영 상태, 사용자 권한, 화면 컴포넌트 등록이 필요합니다. nexia-apps:doctor-package-app은 contribution과 페이지 연결을 점검하지만 권한을 부여하지 않습니다. 빈 화면이 뜨면 경로와 컴포넌트 이름의 연결부터 살펴보세요. 패키지 단위 확인 절차는 App 테스트하기에 있습니다.

App Menu 목적지 추가

목적지 등록

결과 확인

Resource 목록과 배치

항목이 나타나지 않을 때