호스트 슬롯에 앱 위젯 배치하기
프로필 위젯의 props·권한·컴포넌트 키를 맞춰 등록합니다.
호스트 슬롯에 앱 위젯 배치하기
App 화면 만들기를 먼저 마칩니다. 개인정보 조회 없이 배치 방법을 확인하는 정적 프로필 도움말 위젯입니다. 임의 슬롯 이름을 선언한다고 호스트에 새 자리가 생기지는 않습니다.
위젯 생성·등록
src/Descriptors/WorkshopProfileWidget.php를 만듭니다:
<?php
namespace Nexia\Apps\Acme\Workshop\Descriptors;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\SlotWidgetDescriptor;
final class WorkshopProfileWidget implements AppDescriptorContribution
{
public static function appDescriptors(): AppDescriptorSet
{
return AppDescriptorSet::of(new SlotWidgetDescriptor(
key: 'workshop.profile.help',
version: '1.0',
slot: 'profile.self.overview',
component: 'WorkshopProfileHelp',
slotApiVersion: 2,
permission: 'workshop.note.read',
labelKey: 'workshop.profile.help.title',
familyKey: 'workshop.profile',
));
}
}resources/js/profile/WorkshopProfileHelp.tsx를 만듭니다:
import type { ProfileSlotPropsV2 } from '@nexia/sdk';
import { useTranslation } from 'react-i18next';
export default function WorkshopProfileHelp(_props: ProfileSlotPropsV2) {
const { t } = useTranslation();
return <p>{t('workshop.profile.help.body')}</p>;
}기존 프런트엔드 등록의 overrides에 추가합니다. App 키·glob·기존 override는 유지하세요:
// Merge into the existing autoRegisterPackageSurfaces({ overrides: ... }).
overrides: {
WorkshopProfileHelp: () => import('./profile/WorkshopProfileHelp'),
},workshop.profile.help.title과 .body를 두 언어에 추가합니다. 프로젝트 nexia dev에서 선언·프런트엔드 준비 완료를 기다리면 됩니다. 호스트 Artisan 명령은 필요하지 않습니다.
배치·권한 확인
테스트 사용자에게 Note 조회 권한을 부여하고 내 프로필 → 개요에서 해당 언어의 안내가 나타나는지 확인합니다. 권한 없는 사용자에게는 없어야 합니다. 이후 데이터를 추가하면 인가된 App API를 사용하세요. 배치 권한이 데이터 권한을 대신하지 않습니다. 로딩·업무 문맥 없음·빈 값·오류·권한 회수를 확인합니다.
호스트 계약 선택
| 슬롯 | Props |
|---|---|
profile.self.overview, profile.self.employment, profile.self.time_leave, profile.self.pay, profile.self.projects, profile.self.growth | 신규 위젯은 ProfileSlotPropsV2; 기존 V1도 인식 |
profile.self.organization, profile.self.documents | ProfileSlotPropsV2 |
approval.composer.business_form | ApprovalBusinessFormSlotPropsV2와 별도 결재 registry |
프로필 props에는 tenant·legalEntity·visibility·descriptorKey·appKey·familyKey·workContext가 있습니다. workContext가 null이면 임의 직원으로 해석하지 마세요. 결재 controller는 앱 업무를 전자결재에 연결하기, 사용자가 배치하는 대시보드는 App 리포트 추가하기를 따릅니다. descriptor 버전과 props API 버전은 구분합니다.
탭이 표시되는 조건
내 프로필 주소는 /me/{tab}입니다. Core가 아래 탭을 정의하고, App은 해당 슬롯에 내용을 등록합니다. 개요는 항상 표시되며 나머지 탭은 현재 사용자가 볼 수 있는 위젯이 하나 이상 있을 때 표시됩니다. 같은 슬롯에 여러 App의 위젯을 등록할 수 있습니다.
| 주소 | 슬롯 |
|---|---|
/me/overview | profile.self.overview |
/me/employment | profile.self.employment |
/me/organization | profile.self.organization |
/me/time-leave | profile.self.time_leave |
/me/attendance | profile.self.attendance (V2) |
/me/leave | profile.self.leave (V2) |
/me/pay | profile.self.pay |
/me/projects | profile.self.projects |
/me/growth | profile.self.growth |
/me/documents | profile.self.documents |
앱이 독립된 프로필 탭을 제출하려면 앱 프로필 탭 제출하기를 참고하세요.
등록했는데 보이지 않으면 다음을 확인합니다.
- App이 설치되어 실행 가능하고 descriptor 상태가 Active인지 확인합니다.
key와familyKey는 해당 App 키로 시작해야 합니다. 일반 슬롯 descriptor와 달리 프로필에서는familyKey가 필수입니다. 대시보드 어댑터가 없어도 프로필에는 등록할 수 있습니다.permission을 선언하고 현재 업무 문맥에서 그 권한의 허용 결정이self대상 범위를 포함하는지 확인합니다. 권한 이름만 부여하거나 다른 대상 범위를 허용한 것으로는 충분하지 않습니다.component와 프런트엔드 등록 키, 슬롯 이름과 지원 API 버전이 일치하는지 확인합니다. 새 위젯은 V2를 사용합니다.
기존 탭에 내용을 추가하거나 ProfileTabDescriptor로 앱 소유 탭을 만들 때 Core 수정은 필요하지 않습니다. 위젯의 API 버전 변경과 탭 추가는 별개입니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
운영 조직에 직원 배치 제공하기
React SDK 0.8.10과 대응 Core에서 organization.workforce 슬롯을 지원합니다. 위의 등록 방법을 재사용하되, descriptor의 slot은 organization.workforce, slotApiVersion은 1로 지정합니다. App 소유 key·familyKey, 활성 상태, 조회 권한과 등록된 컴포넌트 키가 필요합니다. 직원 배치 데이터 조회·검색·정렬과 권한 검사는 해당 App이 구현합니다.
컴포넌트는 @nexia/sdk의 OrganizationWorkforceSlotPropsV1을 받습니다.
| 입력 | 의미 |
|---|---|
tenant, legalEntity | 현재 테넌트와 선택한 법인. 법인에는 public_id, name, code 제공 |
view | chart 또는 table |
search | 운영 조직 화면에서 입력한 검색어 |
descriptorKey, appKey, familyKey | 등록한 위젯의 식별 정보 |
여러 법인을 선택하면 호스트가 법인별로 허용된 화면을 구성합니다. Core의 enterprise.structure.read와 App의 선언된 조회 권한이 모두 필요하며, 위젯 데이터 API에서도 현재 법인과 행위자의 권한을 검사합니다. 조회 실패를 직원 0명으로 표시하지 마세요. 이 슬롯의 직원 배치는 로그인 접근용 사용자 소속을 생성하거나 수정하지 않습니다.
확인
슬롯을 포함한 App을 다시 준비한 뒤 운영 조직 화면에서 법인·조직도/표·검색어 변경이 전달되는지 확인합니다. App 조회 권한이 없는 사용자, 중지된 App, 조회 실패도 확인하세요. 제공자가 없으면 기존 사용자 소속 화면이 유지됩니다.