Gnuboard7/docs/cheatsheet.md

그누보드7 자주 쓰는 명령어 치트시트

TL;DR (5초 요약)

1. _bundled에서 레이아웃 JSON만 수정 → 확장 업데이트(--force)만 실행 (빌드 불필요)
2. _bundled에서 TSX/TS 수정 → build 필수 + 확장 업데이트(--force) 필요
3. 프론트엔드 테스트 → PowerShell 래퍼 필수 (powershell -Command)
4. 백엔드 테스트 → Bash 직접 실행 (php artisan test)
5. 코드 스타일 → vendor/bin/pint --dirty

---

빌드 vs 확장 업데이트

_bundled에서 레이아웃 JSON만 수정한 경우 → 빌드 불필요, 확장 업데이트(--force)만 필요
_bundled에서 TSX/TS 파일 수정한 경우    → 빌드 후 확장 업데이트(--force) 필요

수정 파일 유형	필요한 작업
*.json (레이아웃만)	{type}:update {id} --force 실행
*.tsx, *.ts + *.json	{type}:build + {type}:update {id} --force
*.tsx, *.ts만	{type}:build + {type}:update {id} --force
modules/**/resources/js/**/*.ts (핸들러)	module:build + module:update {id} --force
templates/**/src/**/*.tsx (컴포넌트)	template:build + template:update {id} --force

확장 프론트엔드 번들: 활성 모듈/플러그인 IIFE 는 서버측에서 종류별 1개 번들로 병합 서빙된다(/api/{modules,plugins}/bundle.{js,css}). {type}:update 후 확장 캐시 버전이 bump 되면 번들이 자동 재생성된다(prod 캐시, dev 매 요청 concat). 구버전 번들 파일은 ext-bundles:cleanup 또는 {type}:cache-clear 로 정리. 상세: module-assets.md.

---

확장 업데이트 (_bundled → 활성 반영)

# 템플릿 업데이트 (templates/_bundled/** → templates/**)
php artisan template:update sirsoft-admin_basic --force

# 모듈 업데이트 (modules/_bundled/** → modules/**)
php artisan module:update sirsoft-ecommerce --force

# 플러그인 업데이트 (plugins/_bundled/** → plugins/**)
php artisan plugin:update sirsoft-payment --force

---

빌드 (Artisan 명령어 사용)

기본 빌드 경로: _bundled 디렉토리. --active 옵션으로 활성 디렉토리 빌드 가능. --watch 모드는 자동으로 활성 디렉토리 사용 (실시간 브라우저 확인). 빌드 후 활성 반영: module:update / template:update / plugin:update 커맨드 사용.

# 코어 템플릿 엔진 (resources/js/core/template-engine/**)
php artisan core:build                    # 기본: 템플릿 엔진만 빌드
php artisan core:build --full             # 전체 빌드 (npm run build)
php artisan core:build --watch            # 파일 감시 모드

# 모듈 빌드 (기본: _bundled)
php artisan module:build sirsoft-ecommerce          # _bundled에서 빌드
php artisan module:build --all                      # 모든 _bundled 모듈 빌드
php artisan module:build sirsoft-ecommerce --watch   # 활성에서 watch
php artisan module:build sirsoft-ecommerce --active   # 활성에서 빌드

# 템플릿 빌드 (기본: _bundled)
php artisan template:build sirsoft-admin_basic        # _bundled에서 빌드
php artisan template:build --all                      # 모든 _bundled 템플릿 빌드
php artisan template:build sirsoft-admin_basic --watch # 활성에서 watch
php artisan template:build sirsoft-admin_basic --active # 활성에서 빌드

# 플러그인 빌드 (기본: _bundled)
php artisan plugin:build sirsoft-payment              # _bundled에서 빌드
php artisan plugin:build --all                        # 모든 _bundled 플러그인 빌드
php artisan plugin:build sirsoft-payment --watch       # 활성에서 watch
php artisan plugin:build sirsoft-payment --active       # 활성에서 빌드

---

테스트

# 프론트엔드 (PowerShell 래퍼 필수)
powershell -Command "npm run test:run"
powershell -Command "npm run test:run -- DataGrid"
powershell -Command "npm run test:run -- template-engine"

# 백엔드
php artisan test
php artisan test --filter=TestName

# _bundled 확장 테스트 (활성 디렉토리 복사 불필요)
php vendor/bin/phpunit modules/_bundled/sirsoft-ecommerce/tests
php vendor/bin/phpunit --filter=TestName modules/_bundled/sirsoft-ecommerce/tests

---

코드 스타일

vendor/bin/pint --dirty

---

목록 조회 (컬럼 프루닝 · 지연 조인)

// 계속 쌓이는 목록 = 지연 조인. 정렬 컬럼이 요청 값이면 닫힌 집합으로 해석.
use App\Repositories\Concerns\{PaginatesWithDeferredJoin, ResolvesSortSpec};

return $this->paginateWithDeferredJoin(
    query: $query,                                   // 필터/where 만. orderBy·with·select 금지
    columns: self::LIST_COLUMNS,                     // ['*'] 도 위반 아님
    sort: $this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at'),
    perPage: $perPage,
    relations: ['user'],                             // 관계는 반드시 이 인자로 (with() 는 지워진다)
);

함정	결과
$query->with() 만 하고 relations: 생략	관계가 조용히 사라짐 — 예외·오류 없음
SUBSTRING(content,1,N) 을 inner 에 둠	오버플로 페이지 읽기 그대로 발생 (프루닝 아님)
정렬을 비고유 컬럼으로만 끝냄	페이지 경계에서 행 중복·누락 (trait 이 PK 자동 append)

상세: service-repository.md

---

마이그레이션

php artisan make:migration create_[table]_table
php artisan migrate
php artisan migrate:rollback

---

확장 시스템 Artisan

# 코어 업데이트
php artisan core:check-updates                                    # 코어 업데이트 확인
php artisan core:update [--force] [--no-backup] [--no-maintenance] [--vendor-mode=auto|composer|bundled]
php artisan core:execute-upgrade-steps --from=X.Y.Z --to=A.B.C [--force]   # 업그레이드 스텝 단독 실행 (HANDOFF 안내 또는 수동 복구용 — 단독 호출 시 migration·resync·.env·캐시·번들 확장 일괄 업데이트 자동 수행. CoreUpdateCommand 내부 spawn 은 --skip-* 5개 옵션 자동 전달)

# 모듈
php artisan module:list
php artisan module:install [identifier] [--vendor-mode=auto|composer|bundled] [--force]
php artisan module:activate [identifier]
php artisan module:deactivate [identifier]
php artisan module:uninstall [identifier]
php artisan module:composer-install [identifier?] [--all]
php artisan module:cache-clear [identifier?]
php artisan module:seed [identifier] [--sample] [--count=key=value]
php artisan module:check-updates [identifier?]
php artisan module:update [identifier] [--force] [--vendor-mode=auto|composer|bundled] [--layout-strategy=overwrite|keep] [--source=auto|bundled|github]

# 플러그인
php artisan plugin:list
php artisan plugin:install [identifier] [--vendor-mode=auto|composer|bundled] [--force]
php artisan plugin:activate [identifier]
php artisan plugin:deactivate [identifier]
php artisan plugin:uninstall [identifier]
php artisan plugin:composer-install [identifier?] [--all]
php artisan plugin:cache-clear [identifier?]
php artisan plugin:seed [identifier] [--sample] [--count=key=value]
php artisan plugin:check-updates [identifier?]
php artisan plugin:update [identifier] [--force] [--vendor-mode=auto|composer|bundled] [--layout-strategy=overwrite|keep] [--source=auto|bundled|github]

# 템플릿
php artisan template:list
php artisan template:install [identifier] [--force]
php artisan template:activate [identifier]
php artisan template:deactivate [identifier]
php artisan template:uninstall [identifier]
php artisan template:cache-clear [identifier?]
php artisan template:check-updates [identifier?]
php artisan template:update [identifier] [--layout-strategy=overwrite] [--force] [--source=auto|bundled|github]

# 언어팩
php artisan language-pack:list
php artisan language-pack:install [identifier] [--source=bundled|github|url] [--no-activate]
php artisan language-pack:activate [identifier] [--force]
php artisan language-pack:deactivate [identifier]
php artisan language-pack:uninstall [identifier] [--cascade] [--force]
php artisan language-pack:cache-clear
php artisan language-pack:check-updates [identifier?]
php artisan language-pack:update [identifier] [--force] [--source=auto|bundled|github]

# Composer 의존성 (모듈/플러그인별 독립 vendor/)
php artisan extension:composer-install          # 모든 모듈+플러그인

# 오토로드
php artisan extension:update-autoload            # 오토로드 캐시 + 정적 훅 매핑 캐시 함께 재생성

# 정적 훅 매핑 캐시 (부팅 비용 절감 — route:cache 동형)
php artisan hooks:cache                           # bootstrap/cache/hooks.php 생성
php artisan hooks:clear                           # 캐시 삭제 (삭제 후 스캔 폴백 — 항상 안전)

훅 캐시는 확장 install/update 및 코어 업데이트(clearAllCaches → extension:update-autoload) 시 자동 재생성됩니다. 코어 리스너 코드 배포 시에만 hooks:cache 수동 실행. 상세: extension/hooks.md "정적 훅 매핑 캐시".

단발성 결함 보정 (hotfix)

hotfix:* prefix 는 특정 버전의 결함 회복을 위해 신설되는 단발성 도구를 위한 표준 prefix 다. core:* (영구 운영 도구) 와 명확히 구분되며 dev-dashboard 자동 노출 면제 대상이다.

# 코어 자동 롤백 후 활성 디렉토리에 잔존한 신 파일 진단/정리 (7.0.0-beta.6 신설)
php artisan hotfix:rollback-stale-files                              # 진단 모드 (실제 삭제 없음)
php artisan hotfix:rollback-stale-files --prune                      # 정리 (확인 프롬프트 동반)
php artisan hotfix:rollback-stale-files --backup=<경로>              # 특정 백업 디렉토리 지정

진단 결과 / 정리 로그는 storage/logs/hotfix_rollback_stale_files_<timestamp>.log 에 기록.

Vendor 번들 Artisan (공유 호스팅용 vendor/ 선탑재)

# 개별 빌드 (기존 *:build 패턴과 동일 — positional identifier + --all)
php artisan core:vendor-bundle [--check] [--force]
php artisan module:vendor-bundle [identifier] [--all] [--check] [--force]
php artisan plugin:vendor-bundle [identifier] [--all] [--check] [--force]

# 개별 무결성 검증
php artisan core:vendor-verify
php artisan module:vendor-verify [identifier] [--all]
php artisan plugin:vendor-verify [identifier] [--all]

# 일괄 알리아스 (운영/CI 전용)
php artisan vendor-bundle:build-all [--check] [--force]   # 코어 + 모든 _bundled
php artisan vendor-bundle:verify-all

# 옵션
# --check  : stale 여부만 확인 (CI 검증용, stale 시 종료 코드 1)
# --force  : 해시 체크 무시하고 강제 재빌드
# --all    : 모든 _bundled 확장 (식별자 대체, 미지정 시 명시적 에러)

상세 가이드: docs/extension/vendor-bundle.md

학습용 샘플 확장 설치

# 학습용 최소 샘플 4종 (manifest.hidden=true → 관리자 UI 기본 제외)
php artisan module:install gnuboard7-hello_module
php artisan module:activate gnuboard7-hello_module
php artisan plugin:install gnuboard7-hello_plugin
php artisan plugin:activate gnuboard7-hello_plugin
php artisan template:install gnuboard7-hello_admin_template
php artisan template:install gnuboard7-hello_user_template

# 숨김 포함 목록 조회
php artisan module:list --hidden
php artisan plugin:list --hidden
php artisan template:list --hidden

상세: extension/sample-extensions.md

SEO Artisan 커맨드

# SEO
php artisan seo:warmup              # SEO 캐시 워밍업
php artisan seo:warmup --layout=shop/show  # 특정 레이아웃만
php artisan seo:clear               # 전체 SEO 캐시 삭제
php artisan seo:clear --layout=home # 특정 레이아웃만
php artisan seo:stats               # 캐시 통계 출력
php artisan seo:generate-sitemap    # Sitemap 생성 (큐 디스패치, mode=auto)
php artisan seo:generate-sitemap --sync     # Sitemap 동기 생성
php artisan seo:generate-sitemap --rebuild  # 전체 재생성 (mode=full)
php artisan seo:generate-sitemap --mode=full|auto|incremental  # 재생성 모드 지정

성능 계측 Artisan 커맨드

# 4축(목록/화면/쓰기/배치) 성능 계측. 계측 대상은 코어 config/benchmark.php + 확장 getBenchmarkProfiles() 선언.
# 상세: docs/backend/benchmark.md
php artisan g7:bench --list-profiles                       # 등록된 프로파일 목록
php artisan g7:bench --profile=core/users_screen            # 화면 1장 응답 시간 + 쿼리 건수 + N+1 후보
php artisan g7:bench --axis=list                           # 축 단위
php artisan g7:bench --all --allow-write --report           # 전체 + 마크다운 리포트 (storage/app/benchmarks/)

# 깊은 OFFSET 계측 — 대량 합성 행을 시딩하므로 운영 데이터가 있는 환경에서 --seed/--fresh 를 쓰지 않는다.
php artisan --env=testing g7:bench --profile=sirsoft-board/board_posts --fresh --seed=200000
php artisan --env=testing g7:bench --profile=sirsoft-board/board_posts --offsets=0,20000,50000,199980 --runs=3 --explain
php artisan g7:bench --profile=sirsoft-ecommerce/orders --json   # 기계 판독용

# 데이터를 변경하는 축(write/batch/비-GET screen)은 --allow-write 없이 거부된다.
php artisan g7:bench --profile=sirsoft-ecommerce/order_create --allow-write

의존성 취약점 점검 Artisan 커맨드

# 저장소의 모든 잠금파일(npm·composer) 운영 의존성 취약점 전수 점검.
# 루트만 감사하면 확장 전부가 사각이 되므로 하위 잠금파일까지 순회한다.
php artisan security:audit-dependencies                 # 전체 (npm + composer)
php artisan security:audit-dependencies --npm-only      # npm 잠금파일만
php artisan security:audit-dependencies --composer-only # composer 잠금파일만
php artisan security:audit-dependencies --json          # 기계 판독용

취약점이 발견되면 비-0 으로 종료한다. 이는 실행 실패가 아니라 조치 대상이 있다는 신호다.

출력의 "대상 없음" 은 의존성이 없는 잠금파일이고, "점검 불가" 는 감사 도구가 실행되지 않은 것이다 — 후자는 "취약점 없음" 과 다르다.

동봉(vendored) 제3자 자산은 어떤 잠금파일에도 없어 감사 도구가 원리상 볼 수 없다. 그 축은 판정하지 않고 목록으로 함께 출력하므로 사람이 확인한다.

API 문서 Artisan 커맨드

# API 레퍼런스 문서 생성/갱신 (실측 기반 스캐폴딩). 상세: docs/backend/api-documentation.md
php artisan api:docgen --scope=core                 # 코어 문서 생성 (범위: core|module:{id}|plugin:{id}|all)
php artisan api:docgen --scope=core --seed           # 실측용 완전 샘플 시드 후 생성 (개발 환경 전용)
php artisan api:docgen --scope=core --base-url=https://example.com  # 실측 기준 URL 지정
php artisan api:docgen --scope=core --examples-only  # 표·서술 불가침, 요청/응답 예시 블록만 in-place 삽입
php artisan api:docgen --scope=core --check           # 생성 없이 누락/drift 만 리포트 (하네스 소비)
php artisan api:docgen --scope=core --dry-run         # 생성 대상 파일/엔드포인트 목록만 출력

# 파라미터/응답 필드 설명 TODO 셀 in-place 백필 (재생성 없이 공통 필드 자동 서술, 멱등)
php artisan api:docgen-backfill-params               # 요청 파라미터 표 TODO 셀 백필
php artisan api:docgen-backfill-fields               # 응답 필드 표 TODO 셀 백필

---

확장 업데이트 (CLI + API)

# 코어 업데이트
php artisan core:check-updates                                    # 코어 업데이트 확인
php artisan core:update [--force] [--no-backup] [--no-maintenance] # 코어 업데이트 실행
php artisan core:execute-upgrade-steps --from=X.Y.Z --to=A.B.C [--force]   # 업그레이드 스텝 단독 실행 (HANDOFF 안내 또는 수동 복구용)

# CLI (Artisan 커맨드)
php artisan module:check-updates [identifier?]                   # 모듈 업데이트 확인
php artisan module:update [identifier] [--force] [--layout-strategy=overwrite|keep]  # 모듈 업데이트 실행
php artisan plugin:check-updates [identifier?]                   # 플러그인 업데이트 확인
php artisan plugin:update [identifier] [--force] [--layout-strategy=overwrite|keep]  # 플러그인 업데이트 실행
php artisan template:check-updates [identifier?]                 # 템플릿 업데이트 확인
php artisan template:update [identifier] [--force] [--layout-strategy=overwrite|keep]  # 템플릿 업데이트 실행

# API 엔드포인트
POST /api/admin/core-update/check                              # 코어 업데이트 확인
GET  /api/admin/core-update/changelog                          # 코어 변경 로그 조회
POST /api/admin/modules/check-updates                          # 모듈 업데이트 확인
POST /api/admin/modules/{moduleName}/update                    # 모듈 업데이트 실행
POST /api/admin/plugins/check-updates                          # 플러그인 업데이트 확인
POST /api/admin/plugins/{pluginName}/update                    # 플러그인 업데이트 실행
POST /api/admin/templates/check-updates                        # 템플릿 업데이트 확인
GET  /api/admin/templates/{templateName}/check-modified-layouts # 수정된 레이아웃 확인
POST /api/admin/templates/{templateName}/update                # 템플릿 업데이트 실행

상세: extension/extension-update-system.md

---