Files
Gnuboard7/docs/extension
HeuJung 7b56d5f23a feat(core,board,ecommerce,page,ckeditor5,kginicis): 업로드 이미지 축소·로그인 2단계 인증 도입 + 파생 결함 수정
인터뷰에서 방향만 정하고 남겨 뒀던 후속 5건을 구현하고, 커밋 전 종합 점검에서
발견한 결함 2건을 함께 고쳤다.

기능 도입:
- 업로드 이미지 축소 — `upload.image_max_width` / `image_max_height` / `image_quality`
 는 저장·검증만 되고 리사이즈 코드가 0건이었다. 비율 유지, 상한 이내면 재인코딩하지
 않음(불필요한 화질 손실 방지), 한계 미설정이면 무동작(기존 사이트 이미지 보호).
 PNG·GIF·WebP 투명도 보존. 실패해도 업로드는 계속되고 원본이 저장된다.
- 로그인 2단계 인증 — `security.two_factor_auth` 는 설정 항목만 있고 구현도 화면
 컨트롤도 없었다. 코어 IDV 인프라를 재사용해 purpose `login` 을 추가하고, 비밀번호
 확인 통과 후 challenge 만 발행한다(토큰 미발급 + logout). `POST /api/auth/login/two-factor`
 가 코드를 확인해야 토큰이 나가며, 로그인과 같은 요청 제한을 적용한다. challenge 의
 purpose 를 대조해 다른 흐름의 challenge 로 로그인하는 것을 막는다. 코드 발송이
 실패하면 실패로 알린다 — 2단계를 건너뛰고 로그인시키면 통제가 조용히 열린다.

결함 수정:
- 게시글 수정 시 사용자 경로가 `attachment_ids` 를 Service 로 넘기지 않아, 검증과
 권한은 통과하고 200 을 받는데 첨부만 조용히 연결되지 않았다. 관리자 경로는 넘기고
 있어 같은 요청이 화면에 따라 다르게 동작했다.
- 설정 화면 라디오가 `pointer-events-none` + Label click 으로만 상태를 바꿔, 키보드
 방향키(change) 조작 시 화면 표시와 저장될 값이 어긋났다. 동일 패턴 4개 레이아웃
 12개 라디오에 change 액션을 부여하고 params 를 click 과 동일하게 고정한다.
- 주문완료 화면이 결제수단 확인보다 영수증 조회를 앞세워, PG 를 거치지 않는 주문에서도
 매번 404 요청이 나갔다.
- 개별 게시판 폼의 숫자 항목에 경계값 바인딩이 없어 환경설정 화면과 안내가 달랐다.

커밋 전 점검에서 발견:
- 2단계 인증이 반쪽으로 들어가 있었다. enum 에 case 만 추가하고 코어 purpose
 레지스트리와 ko/en 라벨을 빠뜨려, 목적 목록 API 에서 통째로 빠지고 `hasPurpose`
 가 false 였으며 라벨 대신 i18n 키 원문이 반환됐다. 관리자가 이 목적의 메시지
 템플릿·정책을 만들 수 없는 상태였다. 세 곳을 enum 기준으로 전수 대조하는 회귀
 테스트를 함께 둔다.
- 업로드 이미지 축소가 적용되지 않은 8번째 서비스(레이아웃 편집기 첨부)가 있었다.
 열거형 커버리지 테스트는 내 조사 결과를 green 으로 고정할 뿐 전수를 증명하지
 못한다 — 같은 규약을 조건으로 표현한 audit 룰이 첫 실행에서 검출했다.

재발 방지:
- audit 룰 `upload-service-image-resize` (신규 업로드 서비스의 축소 누락 검출)
- 트러블슈팅 사례 20 (코어 설정이 일부 경로에만 적용되는 증상의 진단 절차)
- `sirsoft-ckeditor5` 의 코어 최소 요구 버전을 7.0.6 으로 상향 (신설 클래스 의존)

공개 이슈: gnuboard/g7
2026-07-30 07:57:06 +09:00
..
2026-05-11 11:29:41 +09:00
2026-04-20 20:37:49 +09:00
2026-07-01 10:30:32 +09:00
2026-04-20 20:37:49 +09:00
2026-04-01 10:30:52 +09:00
2026-04-20 20:37:49 +09:00
2026-05-11 11:29:41 +09:00
2026-05-11 11:29:41 +09:00
2026-07-01 10:30:32 +09:00
2026-04-20 20:37:49 +09:00
2026-04-20 20:37:49 +09:00
2026-04-01 10:30:52 +09:00
2026-07-01 10:30:32 +09:00

그누보드7 확장 시스템 개발 가이드

이 문서는 그누보드7의 확장 시스템 전체 개요와 각 상세 문서에 대한 링크를 제공합니다.


핵심 원칙

필수: /modules, /plugins 디렉토리 스캔으로 자동 발견 (composer.json 하드코딩 금지)
필수: 모든 확장 작업은 Artisan 커맨드로 수행
✅ 필수: 훅 시스템을 통한 코어 수정 최소화

확장 시스템 개요

G7은 동적 로딩 기반의 확장 시스템을 제공합니다:

  • 모듈: 독립적인 비즈니스 기능 단위 (예: 이커머스, 블로그)
  • 플러그인: 특정 기능 확장 (예: 결제, 배송)
  • 템플릿: UI 렌더링 및 레이아웃 정의 (Admin, User)
  • 훅 시스템: 코어 수정 없이 로직 확장

문서 구조

훅 시스템

문서 설명
hooks.md Action/Filter Hook, 리스너 구현, 우선순위

모듈 개발

문서 설명
module-basics.md AbstractModule, 디렉토리 구조, 네이밍 규칙
module-routing.md API/Web 라우트, 자동 Prefix, routes.json
module-layouts.md 레이아웃 등록, 오버라이드, 상속
module-commands.md Artisan 커맨드 (install, activate, uninstall)
module-i18n.md 백엔드/프론트엔드 다국어 분리

레이아웃 확장

문서 설명
layout-extensions.md 동적 UI 주입 (Overlay, Extension Point), 템플릿 오버라이드

플러그인 개발

문서 설명
plugin-development.md PluginInterface, 격리성, 의존성 원칙

확장 관리자

문서 설명
extension-manager.md Composer 오토로드, 서비스 등록, hidden 필터링

학습용 샘플

문서 설명
sample-extensions.md 학습용 최소 샘플 확장 4종 (gnuboard7-hello_*) — 계층 1:1 비교 레퍼런스

템플릿 시스템

문서 설명
template-basics.md Admin/User 템플릿, 메타데이터, 버전 히스토리
template-routing.md 라우트 정의, 언어 파일 경로 규칙
template-security.md API 서빙, 파일 확장자 화이트리스트
template-caching.md 캐시 계층, 무효화 전략
template-commands.md Artisan 커맨드 (install, activate)

권한 및 메뉴 시스템

문서 설명
permissions.md Role, Permission, 자동 관리
menus.md 메뉴 권한, 시더

확장 타입별 네이밍 규칙

타입 디렉토리명 네임스페이스 Composer 경로
모듈 vendor-module Modules\Vendor\Module\ modules/vendor-module
플러그인 vendor-plugin Plugins\Vendor\Plugin\ plugins/vendor-plugin
템플릿 vendor-template - templates/vendor-template

예시:

  • 모듈: sirsoft-ecommerce → Modules\Sirsoft\Ecommerce\
  • 플러그인: sirsoft-payment → Plugins\Sirsoft\Payment\
  • 템플릿: sirsoft-admin_basic

훅 네이밍 규칙

[vendor-module].[entity].[action]_[timing]

타이밍 접미사:

  • before_*: 작업 실행 전
  • after_*: 작업 실행 후
  • on_*: 특정 이벤트 발생 시
  • filter_*: 데이터 필터링

예시:

sirsoft-ecommerce.product.before_create
sirsoft-ecommerce.product.after_update
sirsoft-ecommerce.product.filter_create_data
sirsoft-ecommerce.order.on_payment_success

주요 Artisan 커맨드

모듈 관련

php artisan module:list                    # 모듈 목록 조회
php artisan module:install [identifier]    # 모듈 설치
php artisan module:activate [identifier]   # 모듈 활성화
php artisan module:deactivate [identifier] # 모듈 비활성화
php artisan module:uninstall [identifier]  # 모듈 제거
php artisan module:cache-clear             # 모듈 캐시 정리

템플릿 관련

php artisan template:list                    # 템플릿 목록 조회
php artisan template:install [identifier]    # 템플릿 설치
php artisan template:activate [identifier]   # 템플릿 활성화
php artisan template:deactivate [identifier] # 템플릿 비활성화
php artisan template:uninstall [identifier]  # 템플릿 제거
php artisan template:cache-clear             # 템플릿 캐시 정리

확장 관리자

php artisan extension:update-autoload   # Composer 오토로드 업데이트

빠른 시작 가이드

새 모듈 개발 시

  1. module-basics.md - 기본 구조 이해
  2. module-routing.md - 라우트 설정
  3. module-i18n.md - 다국어 지원
  4. module-layouts.md - 레이아웃 등록 (필요시)
  5. hooks.md - 훅 리스너 구현 (필요시)

새 플러그인 개발 시

  1. plugin-development.md - 플러그인 구조 이해
  2. hooks.md - 훅 리스너 구현

템플릿 커스터마이징 시

  1. template-basics.md - 템플릿 타입 이해
  2. template-routing.md - 라우트/언어 파일
  3. template-security.md - 보안 규칙

관련 문서