업무패키지 생성 안내 (`starj bp create`)

이 문서에서 업무패키지(Business Package) 는 포탈에 설치하는 업무 기능 단위를, Portal Shell(포탈 셸) 은 사용자가 로그인해 메뉴와 업무 화면을 쓰는 화면 애플리케이션을 뜻한다. 용어 전체는 개요와 용어에 있다.

starj bp create는 새 업무패키지 프로젝트를 만드는 명령이다. 검증·패키징·설치에 쓰는 starj CLI(@starj-portal/cli)의 한 명령이므로 도구를 따로 설치하지 않는다. 질문 여덟 개에 답하면 바로 빌드되는 프로젝트가 생기고, 그 프로젝트를 포탈에 설치하면 메뉴에서 App을 열었을 때 제목과 로그인한 사용자가 표시된다. 이 문서는 그 과정을 처음부터 끝까지 따라 하는 순서로 설명한다.

단계	하는 사람	이 문서의 위치
①~③ 프로젝트를 만들고 검증한다	개발자	§1~§4
④~⑥ 포탈에 설치하고 활성화·권한 부여를 한다	포탈 운영자. 로컬 포탈이면 개발자 자신	§5
⑦ 화면을 확인한다	개발자	§5-4

이전 도구

bp create 명령은 @starj-portal/cli 0.2.0부터 들어 있다. 예전에 개발 키트 저장소에 있던 독립 CLI @starj-portal/create-bp는 없어졌다. 게시한 적이 없는 도구이며, 질문·옵션·생성물은 starj bp create가 그대로 이어받았다.

1. 준비

1-1. 필요한 것

항목	조건	확인 명령
Node.js	22 이상	`node -v`
pnpm	11 이상. 생성 직후 설치·검증에 쓴다	`pnpm -v`
사내 npm 레지스트리	`https://npm.mdpert.com/`에 접속할 수 있어야 한다. `@starj-portal` 패키지는 계정 없이 받는다	`npm view @starj-portal/bp-backend-sdk version --registry https://npm.mdpert.com/`
npmjs 접속	React·NestJS·Prisma 같은 일반 의존성을 받는다. 폐쇄망이면 미리 확보한다
`starj` CLI	생성은 `npx`로 실행한 CLI가 맡는다(§1-2). 생성된 프로젝트는 그 CLI와 같은 버전의 `@starj-portal/cli`를 `devDependencies`로 받고, 검증의 배포 전 점검과 패키지 단계가 그것을 쓴다. 다른 CLI 파일로 검증하려면 그 경로를 환경변수 `STARJ_CLI`에 지정한다(빌드와 패키징 §7-1)	생성 뒤 프로젝트에서 `pnpm exec starj --version`
git	선택. 있으면 새 프로젝트를 git 저장소로 만든다	`git --version`

pnpm이 없으면 npm install -g pnpm 또는 corepack enable pnpm으로 설치한다.

1-2. 실행 방법

레지스트리에 게시된 CLI를 npx로 실행한다. 설치하지 않아도 되고, 계정도 필요 없다.

bash

# 프로젝트를 만들 상위 디렉터리로 이동한다
cd ~/work

npx --registry https://npm.mdpert.com/ @starj-portal/cli bp create

디렉터리 이름을 인자로 주면 그 이름이 업무패키지 id와 디렉터리의 기본값이 된다.

bash

npx --registry https://npm.mdpert.com/ @starj-portal/cli bp create purchase-req

생성된 프로젝트의 devDependencies["@starj-portal/cli"]에는 실행한 CLI의 버전이 그대로 들어간다(starj --version으로 확인한다). 생성 도구와 검증 도구가 같은 CLI이므로 두 버전을 따로 맞출 필요가 없다.

2. 질문에 답하기

실행하면 아래 순서로 질문한다. 괄호 안은 기본값이며, Enter만 누르면 기본값을 쓴다. 잘못된 값을 넣으면 이유를 표시하고 같은 질문을 다시 한다.

2-1. 실행 예

구매 요청 업무패키지를 만드는 예다. App은 목록과 상세 두 개이고, 조회자와 편집자 두 역할을 만들고, 자체 테이블을 쓴다.

text

업무패키지(Business Package) 프로젝트를 만듭니다. 괄호 안은 기본값이며 Enter를 누르면 그대로 씁니다.

? 업무패키지 id(영문 소문자·숫자·하이픈, 한번 배포하면 바꾸지 않습니다): purchase-req
? 업무패키지 이름(화면과 관리 메뉴에 표시): 구매 요청
? 만들 디렉터리 (purchase-req):

App은 메뉴에서 여는 업무 화면 하나이며 권한을 부여하는 단위입니다.
? 첫 App 키(App id는 <업무패키지 id>:<App 키>가 됩니다) (main): list
?   "list" App 이름(화면 제목) (구매 요청): 요청 목록
? 다음 App 키(없으면 Enter): detail
?   "detail" App 이름(화면 제목): 요청 상세
? 다음 App 키(없으면 Enter):
? 메뉴 폴더 이름(App들이 이 아래에 놓입니다) (구매 요청):

설치할 때 기본 권한 역할이 만들어집니다. 사용자에게 부여하는 일은 관리자가 합니다.
? 기본 권한 역할 구성
  1) 조회자(읽기)와 편집자(읽기·쓰기) 두 역할 (권장)
  2) 편집자(읽기·쓰기) 한 역할
? 번호 (1):
? 조회자 역할 이름 (구매 요청 조회자):
? 편집자 역할 이름 (구매 요청 편집자):
? 자체 테이블을 쓰나요? (예시 테이블과 SQLite·PostgreSQL 마이그레이션을 함께 만듭니다) (Y/n):

다음 구성으로 만듭니다.
  업무패키지  구매 요청 (purchase-req)
  App         요청 목록 (purchase-req:list, uri purchase-req/list)
  App         요청 상세 (purchase-req:detail, uri purchase-req/detail)
  메뉴        구매 요청
  권한 역할   구매 요청 조회자 (PURCHASE_REQ_VIEWER, 읽기)
  권한 역할   구매 요청 편집자 (PURCHASE_REQ_EDITOR, 읽기·쓰기)
  자체 테이블 있음(bp_purchase_req_note)
? 이대로 만들까요? (Y/n):

마지막 확인에서 n을 입력하면 아무 파일도 만들지 않고 끝난다.

2-2. 질문별 설명

질문	규칙	정해지는 것	나중에 바꿀 수 있는가
업무패키지 id	영문 소문자로 시작, 소문자·숫자·하이픈(`-`), 32자 이내	매니페스트 `id`, API 경로 `/bp/<id>/`, 테이블 접두어 `bp_<id>_`, 모든 App id의 앞부분	배포한 뒤에는 바꾸지 않는다. 포탈은 id로 업무패키지를 식별하므로 바꾸면 다른 업무패키지로 등록된다
업무패키지 이름	따옴표(`"`)·백틱·역슬래시 제외	매니페스트 `name`. 업무패키지 관리 화면에 표시된다	바꿀 수 있다
만들 디렉터리	비어 있거나 없는 디렉터리	프로젝트 위치	프로젝트를 옮기면 된다
App 키	id와 같은 형식, 24자 이내, 중복 불가	App id `<id>:<키>`, App uri `<id>/<키>`, 메뉴 항목	배포한 뒤에는 바꾸지 않는다. 권한과 메뉴 배치가 App id에 연결된다
App 이름	업무패키지 이름과 같음	메뉴에 표시되는 이름, 화면 제목	바꿀 수 있다
메뉴 폴더 이름	업무패키지 이름과 같음	App들을 묶는 메뉴 폴더	바꿀 수 있다. 관리자가 메뉴 관리 화면에서 옮긴 배치는 유지된다
기본 권한 역할 구성	1 또는 2	설치할 때 만들어지는 권한 템플릿. 모든 App이 각 역할에 들어간다	`register.ts`에서 바꾼다
역할 이름	업무패키지 이름과 같음	권한 관리 화면에 표시되는 이름	바꿀 수 있다
자체 테이블	`y` 또는 `n`	예시 테이블 `bp_<id>_note`와 두 방언(SQLite·PostgreSQL)의 첫 마이그레이션	나중에 추가할 수 있다(§6-4)

App 키는 화면 하나를 가리키는 짧은 영문 이름이다. list, detail, dashboard, settings처럼 쓴다. App을 하나만 만들 때는 기본값 main을 써도 된다.

권한 역할의 rw 값은 조회자가 1(읽기), 편집자가 3(읽기와 쓰기)이다. 편집 권한만 필요한 업무라면 2번 "편집자 한 역할"을 고른다.

2-3. 답변에서 만들어지는 이름

CLI는 업무패키지 id와 App 키에서 나머지 식별자를 모두 만든다. 직접 정할 필요가 없고, 규칙이 어긋날 일도 없다.

3. 생성 직후 자동으로 실행되는 것

확인에 답하면 CLI가 아래를 차례로 실행한다.

파일을 만든다. 자체 테이블을 쓰면 36개, 쓰지 않으면 24개다.
git이 있고 상위 디렉터리가 git 저장소가 아니면 git init을 실행한다. 커밋은 하지 않는다.
pnpm install로 의존성을 설치한다.
pnpm run verify로 빌드와 점검을 실행한다. starj CLI는 3번에서 devDependencies로 받는다. 그래도 찾지 못하면(STARJ_CLI가 없고 node_modules와 PATH에도 없으면) 검증을 건너뛰고 준비 방법을 안내한다.

verify는 다음 단계로 이뤄진다. 마지막에 아래 네 줄이 보이면 성공이다. 점검 건수는 App 수와 자체 테이블 사용 여부에 따라 다르고, 자체 테이블이 없으면 둘째 줄이 없다.

text

dist: 76건 전체 통과
산출물 배포 검증 통과
패키지 검증 통과 (16건)
단독 스모크 통과

단계	명령	확인하는 것
빌드	`pnpm run build`	호스트 제공 모듈 버전 정합, Prisma 클라이언트 생성, 매니페스트 생성, 백엔드·프론트 번들
타입체크	`pnpm run typecheck`	TypeScript 오류
배포 전 점검	`pnpm run preflight`	매니페스트·번들·App·메뉴·권한 선언, 테이블 접두어, 위젯이 App마다 제목을 렌더링하는지. `starj` CLI로 포탈 반입 검증의 V7·V8(방언별 마이그레이션 폴더, SQL 허용 목록)도 미리 판정한다
마이그레이션 적용 확인	`pnpm run verify:deploy`	`prisma migrate deploy`로 마이그레이션이 적용되는지, 적용 결과가 `schema.prisma`와 같은지. 자체 테이블을 쓸 때만 실행된다
패키지 아카이브	`pnpm run package`	`starj package pack`으로 `dist/`를 `dist-package/<id>-<version>.tgz`로 묶는다. `STARJ_SIGN_KEY`가 있으면 서명한다
아카이브 검증	`pnpm run verify:package`	아카이브가 이번 `dist/`와 같은지, `starj package verify`를 통과하는지, 거부되어야 하는 경로(신뢰 키 없음·다른 키·GNU tar 형식)가 거부되는지
단독 스모크	`pnpm run smoke`	포탈 없이 백엔드를 실행해 첫 화면 API의 권한 판정(읽기·쓰기, 읽기 전용, 권한 없음)을 확인

설치나 검증에 실패하면 CLI가 실패를 알리고 끝난다. 만든 파일은 남아 있으므로 원인을 고친 뒤 프로젝트 디렉터리에서 pnpm install이나 pnpm run verify를 다시 실행한다. 자주 생기는 원인은 §7에 있다.

마지막에는 다음 단계가 표시된다.

text

다음 단계
  1. purchase-req/dist-package/purchase-req-1.0.0.tgz 를 포탈에 설치합니다: pnpm exec starj package add <아카이브> --approve --wait
     서명하지 않은 아카이브는 개발 모드 포탈에서만 설치됩니다. 운영 포탈에는 STARJ_SIGN_KEY 로 서명해 만듭니다.
  2. 관리자 화면에서 업무패키지를 도메인에 활성화합니다: 구매 요청
  3. 관리자 화면에서 사용자에게 권한 역할을 부여합니다: 구매 요청 조회자, 구매 요청 편집자
  4. 메뉴에서 App을 엽니다: 구매 요청
     화면에 App 이름이 표시되면 연결이 끝난 것입니다.

4. 생성된 프로젝트

4-1. 디렉터리 구성

text

purchase-req/
├── package.json              의존성과 스크립트. 호스트 제공 모듈은 캐럿 없이 고정되어 있다
├── pnpm-workspace.yaml       독립 워크스페이스 선언, 네이티브 빌드 허용 목록
├── .npmrc                    @starj-portal 스코프 레지스트리
├── tsconfig.json
├── README.md                 이 프로젝트의 요약 안내
├── backend/
│   ├── src/
│   │   ├── register.ts       포탈이 부르는 진입점. App·메뉴·기본 권한 선언
│   │   ├── ids.ts            식별자 상수(App id·uri·authId·라우트)
│   │   ├── hello.controller.ts  첫 화면 API  GET /bp/purchase-req/hello
│   │   ├── runtime.ts        컨트롤러가 주입받는 실행 객체
│   │   └── db.ts             데이터 접근 (자체 테이블)
│   ├── prisma-src/schema.prisma            정본 스키마 (자체 테이블)
│   ├── prisma-src/snapshot/schema.prisma   마지막 마이그레이션 때의 정본 사본. migrate:new 가 쓴다 (자체 테이블)
│   └── prisma/{sqlite,postgresql}/migrations/  마이그레이션 SQL (자체 테이블)
├── frontend/src/
│   ├── index.tsx             위젯 등록과 mount
│   ├── apps.ts               백엔드와 맞춰야 하는 값(App uri 등)
│   ├── AppScreen.tsx         App 첫 화면. 업무 화면은 여기서부터 고친다
│   ├── api.ts                백엔드 호출
│   └── widget.css            위젯 스타일. 포탈 테마 토큰을 쓴다
├── prisma-config/            로컬 마이그레이션 생성용 설정 (자체 테이블)
├── scripts/                  build·preflight·smoke·package·verify-package 등. lib/starj-cli.mjs가 starj CLI를 찾는다
└── types/css.d.ts

"(자체 테이블)"로 표시한 파일은 자체 테이블을 쓰기로 했을 때만 생긴다. 빌드는 backend/prisma-src/schema.prisma가 있는지로 DB 단계를 실행할지 정한다.

git status로 보면 dist/, dist-package/, backend/generated/, node_modules/는 무시된다. 서명 개인 키 이름(*.key.pem, starj-signing.key.pem*)도 무시하지만, 개인 키는 처음부터 저장소 밖에 둔다. 마이그레이션 SQL은 산출물이 아니라 소스이므로 커밋한다.

4-2. 첫 화면이 그려지는 과정

메뉴에서 App을 열면 셸이 위젯 번들을 불러 mount를 호출한다. 위젯은 host.appUri로 어느 App인지 정해 제목을 먼저 그리고, 백엔드의 /hello를 불러 사용자와 권한 정보를 받아 표시한다. 권한 판정은 업무패키지가 계산하지 않고 포탈에 요청한다.

5. 포탈에 설치하고 확인하기

5-1. 패키지 아카이브를 반입하고 승인한다

verify가 통과하면 dist-package/purchase-req-1.0.0.tgz가 포탈에 설치할 패키지 아카이브다. 포탈은 아카이브를 반입해 검증하고, 패키지 관리 권한을 가진 사람이 승인하면 마이그레이션을 적용하고 코드를 적재한다.

로컬 개발 포탈에 설치하는 경우

로컬 포탈은 개발 모드(PORTAL_PACKAGE_MODE=development)로 구동한다. 개발 모드는 서명하지 않은 아카이브도 경고와 함께 받는다.

bash

STARJ_PORTAL_URL=http://localhost:<포트> STARJ_TOKEN=<패키지 관리 권한이 있는 토큰> \
  pnpm exec starj package add dist-package/purchase-req-1.0.0.tgz --approve --wait

토큰이 없으면 --approve 없이 반입하고 관리 화면의 패키지 관리에서 승인한다. 개발 서버에는 재시작 정책이 없으므로, 서버 코드가 바뀌는 적용은 "수동 재시작 필요" 상태에서 멈춘다. 그때 portal-core를 직접 재기동하면 적용이 이어진다.

개발 모드 포탈은 소스 폴더(PORTAL_BP_DIR)에 둔 dist/도 부팅 때 적재한다. 승인과 서명을 거치지 않는 개발 전용 경로이며 운영 모드 포탈은 적재하지 않는다. 같은 BP를 두 경로로 동시에 두지 않는다.

운영 포탈에 설치하는 경우

운영 포탈은 신뢰 키로 서명한 아카이브만 받는다. 서명 키를 만들고 그 키로 아카이브를 다시 만든다.

bash

STARJ_SIGN_KEY=<개인 키 경로> pnpm run package
STARJ_TRUSTED_KEY=<공개 키 경로> pnpm run verify:package

아카이브와, 처음 한 번은 공개 키(starj-signing.trusted-key.json)를 운영자에게 전달한다. 개인 키는 전달하지 않는다. 키를 만들고 보관하는 방법은 빌드와 패키징 §7-2에, 운영자가 할 일은 포탈에 설치하기에 있다.

5-2. 적용이 끝나면 포탈이 하는 일

승인된 아카이브를 적용할 때와 적용한 뒤 포탈이 기동할 때 다음을 자동으로 한다.

매니페스트를 읽고 호스트 계약 버전과 DB 방언을 확인한다.
아직 적용하지 않은 마이그레이션을 적용한다. 적용한 마이그레이션의 이름과 체크섬을 기록한다.
register()를 호출해 App·메뉴·기본 권한 역할을 등록한다.

같은 버전을 내용만 바꿔 다시 반입하면 거부된다. 고쳐서 다시 설치할 때는 버전을 올린다(§6-5).

5-3. 활성화하고 권한을 부여한다

관리자 계정으로 로그인한 뒤 진행한다.

활성화: 포탈 관리 → Basis → 업무패키지 관리에서 "설치된 업무패키지" 목록의 purchase-req를 찾아, 사용할 도메인에서 활성화를 누른다. 활성화는 도메인마다 한다.
권한 부여: 아래 두 화면 중 하나를 쓴다.
- 포탈 관리 → 보안 → 권한 관리: 역할(예: "구매 요청 편집자")을 고르고 사용자 관리를 누른 뒤, 추가할 사용자를 검색해 추가한다.
- 포탈 관리 → 보안 → 사용자 관리: 사용자를 고르고 권한 부여에서 역할을 선택해 부여를 누른다.

자기 계정으로 확인하려면 자기 계정에 편집자 역할을 부여한다. 조회자 역할만 부여하면 화면에 "읽기 전용 권한으로 보고 있습니다."가 표시된다.

5-4. 화면을 확인한다

화면을 새로고침하면 메뉴에 "구매 요청" 폴더와 App이 나타난다. App을 열면 아래와 같이 표시된다.

표시	뜻
제목(요청 목록)	위젯이 적재되어 `host.appUri`로 App을 골랐다
"홍길동님, 환영합니다."	셸이 로그인 사용자 정보를 위젯에 넘겼다
업무패키지·App 줄	백엔드 `/hello`가 응답했고 포탈의 권한 판정을 통과했다
메모 0건	백엔드가 자체 테이블을 조회했다(자체 테이블을 쓸 때만)

네 가지가 모두 보이면 프론트엔드, 백엔드, 권한, DB가 모두 연결된 것이다.

6. 다음에 할 일

6-1. 화면 고치기

frontend/src/AppScreen.tsx가 App 첫 화면이다. App마다 다른 화면을 그리려면 frontend/src/index.tsx의 Root에서 app.uri로 나눈다. 화면 문구와 버튼 규칙, 테마 토큰은 프론트엔드 가이드를 따른다.

6-2. API 추가하기

backend/src/에 컨트롤러를 만든다. 경로는 ids.ts의 API_PREFIX(bp/<id>)로 시작해야 한다. 포탈은 접두어를 추가하지 않는다.
register.ts의 controllers 배열에 추가한다.
요청마다 host.checkAppAccess(req, domainId, appId, "read" | "update")로 권한을 확인한다. hello.controller.ts가 예다.
scripts/smoke.mjs에 새 API의 확인을 더한다.

자세한 규칙은 백엔드 가이드에 있다.

6-3. App 추가하기

세 곳을 함께 고친다. 하나라도 빠지면 pnpm run preflight가 실패한다.

backend/src/ids.ts에 APP_<KEY>·URI_<KEY> 상수를 더하고 APP_IDS에 넣는다.
backend/src/register.ts의 apps·menu·defaultAuthorities에 넣는다.
frontend/src/apps.ts의 APPS에 같은 App id·uri·이름을 넣는다.

6-4. 테이블 바꾸기

backend/prisma-src/schema.prisma를 고친다. 테이블 이름은 @@map("bp_<id>_...")으로 접두어를 붙이고 50자 이내로 둔다. 업무 데이터에는 domainId 컬럼을 둔다.
pnpm run migrate:new <이름>으로 두 방언의 마이그레이션을 만든다. 두 방언의 폴더와 스냅샷(backend/prisma-src/snapshot/schema.prisma)이 함께 생기며, 실패하면 하나도 남지 않는다. 셋 다 커밋한다.
열 이름을 바꿨다면 생성된 두 방언의 migration.sql을 ALTER TABLE "<테이블>" RENAME COLUMN "<이전>" TO "<새 이름>";으로 고친다. 생성된 SQL은 열을 지우고 새로 만들어 데이터를 버린다. 결과 상태가 스키마와 다르게 고치면 다음 migrate:new가 멈춘다.
backend/src/db.ts에 조회 함수를 더한다.

포탈은 마이그레이션마다 이름과 체크섬을 기록하고 아직 적용하지 않은 것만 적용한다. 그래서 이미 적용한 migration.sql은 고치지 않는다. 고치면 포탈이 적용을 거부한다. 바꿀 내용은 새 마이그레이션으로 만든다. 개발 DB에서 이미 고쳐 버렸다면 포탈 저장소에서 pnpm bp:dev-reset <id>로 이 업무패키지의 테이블과 이력을 지운다. 자세한 내용은 백엔드 가이드 §7-4에 있다.

자체 테이블 없이 만든 프로젝트에 테이블을 추가하려면, 같은 id로 자체 테이블을 쓰는 프로젝트를 임시로 하나 더 만들어 backend/prisma-src·backend/prisma·backend/src/db.ts·backend/src/runtime.ts·prisma-config·scripts/make-migration.mjs·scripts/lib/providers.mjs·scripts/verify-deploy.mjs와 package.json의 Prisma 의존성·스크립트를 옮긴다.

6-5. 버전 올리기

package.json과 scripts/gen-manifest.ts의 version을 함께 올린다. 포탈은 처음 보는 version일 때 설치 훅(onInstall)을 다시 실행한다.

7. 문제가 생겼을 때

증상	원인	조치
`업무패키지 id: 영문 소문자로 시작하고…`	id 형식 위반	소문자로 시작하고 소문자·숫자·하이픈만 쓴다
`디렉터리가 비어 있지 않습니다`	같은 이름의 디렉터리에 파일이 있다	다른 이름을 쓰거나 디렉터리를 비운다
`pnpm을 찾지 못해 설치를 건너뜁니다`	pnpm 미설치	pnpm을 설치하고 프로젝트에서 `pnpm install && pnpm run verify`
`pnpm install`이 `@starj-portal/...` 404로 실패	레지스트리 접속 불가	사내 레지스트리 접속을 확인한다. `.npmrc`는 생성되어 있다
`ERR_PNPM_IGNORED_BUILDS`	네이티브 빌드 허용 목록이 없다	`pnpm-workspace.yaml`의 `allowBuilds`를 지우지 않았는지 확인한다
`starj CLI를 찾지 못해 검증을 건너뜁니다` 또는 `FAIL starj CLI 를 찾았다`	`@starj-portal/cli`가 설치되지 않았거나 `STARJ_CLI`가 없는 파일을 가리킨다	프로젝트에서 `pnpm install`을 다시 실행하고 `package.json`의 `devDependencies`에 `@starj-portal/cli`가 있는지 확인한다. `STARJ_CLI`를 지정했다면 그 경로를 확인한다. 그 뒤 `pnpm run verify`를 다시 실행한다(빌드와 패키징 §7-1)
`FAIL starj package pack 이 V7·V8 을 통과한다`	마이그레이션 SQL이 허용 목록 밖이거나 방언 폴더가 없다	출력의 `SQL_NOT_ALLOWED`·`DIALECT_MIGRATIONS_MISSING` 세부 줄을 본다(빌드와 패키징 §7-6)
반입했는데 업무패키지 관리 목록에 없다	검증 실패, 승인 대기, 적용 실패 중 하나다	`starj package list --candidates`로 후보 상태를 본다. 적용되었는데 없으면 `GET /bp/runtime-info`의 `skipped[]`에서 사유를 본다(트러블슈팅)
목록에는 있는데 메뉴에 없다	도메인 활성화나 권한 부여가 안 됐다	§5-3을 다시 확인한다. 부여 뒤에는 화면을 새로고침한다
메뉴는 있는데 위젯 영역이 비어 있다	위젯 번들 적재 실패	브라우저 개발자 도구의 콘솔과 네트워크 탭을 본다. 개발 소스 폴더에서 파일만 바꿨다면 portal-core를 재기동했는지 확인한다
제목만 있고 "이 App을 볼 권한이 없습니다."	백엔드 권한 판정 실패	그 App이 들어 있는 역할이 계정에 부여됐는지 확인한다
제목만 있고 "요청이 실패했습니다(404)."	백엔드가 적재되지 않았거나 경로가 다르다	부팅 로그의 건너뜀 사유와 컨트롤러 경로(`bp/<id>`로 시작)를 확인한다

8. 명령 옵션

옵션	효과
`[디렉터리]`	만들 디렉터리. 업무패키지 id의 기본값이 된다
`--yes`, `-y`	질문하지 않고 기본값으로 만든다. 디렉터리 이름이 id가 되고 App은 `main` 하나, 역할은 조회자와 편집자다
`--name <이름>`	`--yes`와 함께 업무패키지 이름을 지정한다
`--no-db`	자체 테이블 없이 만든다. 대화형에서는 테이블 질문의 기본값이 "아니오"가 된다
`--no-install`	`pnpm install`과 `verify`를 건너뛴다. `verify`는 `starj` CLI를 찾지 못해도 건너뛴다
`--no-git`	`git init`을 하지 않는다
`--help`, `-h`	도움말

bash

# 질문 없이 테이블 없는 프로젝트를 만든다
npx --registry https://npm.mdpert.com/ @starj-portal/cli bp create sample-bp --yes --name "샘플" --no-db

CLI 버전은 starj --version으로 확인한다. 종료 코드는 0 성공, 1 설치·검증 실패 또는 취소, 2 사용법·입력값 오류, 4 디렉터리가 비어 있지 않음이다.

함께 볼 것

시작하기: CLI가 처리한 각 설정이 왜 필요한지
매니페스트 레퍼런스: register()가 선언하는 App·메뉴·권한의 필드
포탈에 설치하기: 운영자의 설치·업그레이드·롤백 절차
트러블슈팅: 설치했는데 동작하지 않을 때

업무패키지 생성 안내 (starj bp create) ​

1. 준비 ​

1-1. 필요한 것 ​

1-2. 실행 방법 ​

2. 질문에 답하기 ​

2-1. 실행 예 ​

2-2. 질문별 설명 ​

2-3. 답변에서 만들어지는 이름 ​

3. 생성 직후 자동으로 실행되는 것 ​

4. 생성된 프로젝트 ​

4-1. 디렉터리 구성 ​

4-2. 첫 화면이 그려지는 과정 ​

5. 포탈에 설치하고 확인하기 ​

5-1. 패키지 아카이브를 반입하고 승인한다 ​

5-2. 적용이 끝나면 포탈이 하는 일 ​

5-3. 활성화하고 권한을 부여한다 ​

5-4. 화면을 확인한다 ​

6. 다음에 할 일 ​

6-1. 화면 고치기 ​

6-2. API 추가하기 ​

6-3. App 추가하기 ​

6-4. 테이블 바꾸기 ​

6-5. 버전 올리기 ​

7. 문제가 생겼을 때 ​

8. 명령 옵션 ​

함께 볼 것 ​

업무패키지 생성 안내 (`starj bp create`)

1. 준비

1-1. 필요한 것

1-2. 실행 방법

2. 질문에 답하기

2-1. 실행 예

2-2. 질문별 설명

2-3. 답변에서 만들어지는 이름

3. 생성 직후 자동으로 실행되는 것

4. 생성된 프로젝트

4-1. 디렉터리 구성

4-2. 첫 화면이 그려지는 과정

5. 포탈에 설치하고 확인하기

5-1. 패키지 아카이브를 반입하고 승인한다

5-2. 적용이 끝나면 포탈이 하는 일

5-3. 활성화하고 권한을 부여한다

5-4. 화면을 확인한다

6. 다음에 할 일

6-1. 화면 고치기

6-2. API 추가하기

6-3. App 추가하기

6-4. 테이블 바꾸기

6-5. 버전 올리기

7. 문제가 생겼을 때

8. 명령 옵션

함께 볼 것