테마
업무패키지 개발 문서
대상: starj-portal 위에 업무패키지(BP)를 만드는 개발자. 사내 개발자와 3rd-party를 구분하지 않는다 — 포탈에 내장된 관리자 업무패키지도 여기 적힌 것과 같은 계약으로 만들어져 있다.
포탈 소스를 체크아웃하거나 포탈 인스턴스를 띄울 필요는 없다. 필요한 것은 Node 22 이상과 아래 두 패키지뿐이다.
bash
# .npmrc — 설치에는 계정도 토큰도 필요 없다
@starj-portal:registry=https://npm.mdpert.com/bash
pnpm add -D @starj-portal/bp-backend-sdk # 서버 로직·API·DB가 있으면
pnpm add @starj-portal/bp-frontend-sdk # 포탈 셸 안에 화면을 그리면읽는 순서
- 시작하기 — 빈 디렉터리에서 시작해 포탈에 뜨는 BP 하나를 끝까지 만든다. 나머지 문서는 여기서 나온 개념을 깊게 파고든 것이다.
- 호스트 계약 — 포탈과 BP 사이의 경계. 무엇을 받고 무엇을 지켜야 하는가. 이 문서를 안 읽으면 조용히 깨진다.
- 그다음은 만드는 것에 따라 갈린다.
- 서버 로직·API·DB → 백엔드 가이드
- 셸 안의 화면 → 프론트엔드 가이드
- 선언 파일의 정확한 스키마 → 매니페스트 레퍼런스
- 다 만들었으면 빌드와 패키징 → 포탈에 설치하기.
- 안 되는데 오류도 안 나면 트러블슈팅. 이 플랫폼의 실패는 대부분 예외가 아니라 침묵으로 나타난다.
이 문서들이 하지 않는 것
- 포탈 내부 구현을 설명하지 않는다. 로더가 어떻게 클래스를 합성하는지, 레지스트리가 어떻게 upsert하는지는 포탈 저장소의 몫이다. 여기서는 BP 쪽에서 보이는 표면만 다룬다.
- 포탈 운영자 절차를 설명하지 않는다. 권한 부여·도메인 활성화·사용자 관리는 포탈 관리자 매뉴얼에 있다. 이 문서에서 다루는 설치(포탈에 설치하기)는 "개발자가 만든 산출물이 어떤 모양이어야 하는가"까지다.
용어
| 용어 | 뜻 |
|---|---|
| BP (업무패키지) | 포탈에 얹히는 기능 단위 하나. 화면(App) 여러 개, API, 자기 DB 스키마를 가질 수 있다 |
| App | BP가 소유한 화면 하나. 권한 부여와 메뉴 배치의 단위다 |
| 메뉴 배치 | 그 App을 메뉴 트리 어디에 걸지. App 선언과 분리돼 있고, 같은 App을 여러 곳에 걸 수 있다 |
| 도메인 | 포탈의 테넌트 경계. 같은 BP가 도메인 A에서는 활성, B에서는 비활성일 수 있다 |
| 호스트 계약 | 포탈이 BP에게 보장하는 런타임 인터페이스와 공유 모듈 집합. 버전이 있다 |
| csr-widget | BP 화면을 iframe 없이 셸 안에 직접 마운트하는 딜리버리 방식 |
버전 정책
SDK의 major 버전은 호스트 계약 버전(HOST_CONTRACT_VERSION)과 함께 움직인다. SDK 1.x로 만든 BP는 호스트 계약 1.x를 제공하는 포탈에서 동작한다. 대상 포탈이 어떤 계약 버전을 제공하는지는 그 포탈 운영자에게 확인한다.
bash
node -e "import('@starj-portal/bp-backend-sdk').then(m => console.log(m.HOST_CONTRACT_VERSION))"