Gnuboard7/docs/frontend/actions-handlers.md

액션 핸들러 - 핸들러별 상세 사용법

메인 문서: actions.md 관련 문서: actions-g7core-api.md | layout-json.md | state-management.md

---

TL;DR (5초 요약)

1. navigate: 페이지 이동 (path, query, mergeQuery 옵션)
2. apiCall: API 호출 (method, endpoint, body, onSuccess/onError)
3. setState: 상태 변경 (_global/_local/_isolated 경로, target 옵션)
4. openModal/closeModal: 모달 열기/닫기
5. sequence/parallel: 여러 액션 순차/병렬 실행

---

하위 문서 안내

이 문서는 규모가 커서 카테고리별로 분할되었습니다. 아래 링크를 통해 각 핸들러에 대한 상세 내용을 확인하세요.

하위 문서	주요 핸들러	설명
actions-handlers-navigation.md	navigate, navigateBack, openWindow, replaceUrl, reloadExtensions, reloadRoutes, refresh	페이지 이동 및 라우트 관리
actions-handlers-state.md	apiCall, setState, setError, refetchDataSource, remount	API 호출 및 상태 관리
actions-handlers-ui.md	login/logout, openModal/closeModal, toast, switch, sequence/parallel, loadScript, callExternal	UI 인터랙션 및 외부 스크립트

---

목차

네비게이션 핸들러 → 상세 문서

1. navigate - 페이지 이동
2. navigateBack - 뒤로 가기
3. openWindow - 새 창/탭에서 열기
4. replaceUrl - URL만 변경 (refetch 없음)
5. reloadExtensions ⭐ NEW (engine-v1.38.0+) - 확장 상태 원자 재동기화
6. reloadRoutes (deprecated) - 라우트 재로드
7. refresh - 페이지 새로고침

상태 관리 핸들러 → 상세 문서

5. apiCall - API 호출
6. setState - 상태 변경
7. setError - 에러 상태 설정
8. refetchDataSource - 데이터 소스 재조회
9. appendDataSource - 데이터 소스 병합 (무한스크롤)
10. remount - 컴포넌트 리마운트
11. onSuccess/onError 후속 액션
12. API 데이터 바인딩 규칙
13. 에러 핸들링 시스템

UI 인터랙션 핸들러 → 상세 문서

14. login / logout - 인증
15. openModal / closeModal - 모달
16. showAlert / toast - 알림
17. confirm (액션 속성) - 실행 전 확인 대화상자
18. switch - 조건부 액션
19. sequence / parallel - 액션 조합
20. reloadTranslations (deprecated) - 다국어 재로드 (extension 라이프사이클은 reloadExtensions 사용)
21. showErrorPage - 에러 페이지
22. loadScript ⭐ NEW - 외부 스크립트 로드 (same-origin 경로 또는 선언된 신뢰 호스트만)
23. callExternal ⭐ NEW - 외부 라이브러리 호출
24. 실전 예시

---

핸들러 빠른 참조

자주 사용하는 핸들러

핸들러	용도	상세 문서
navigate	페이지 이동	navigation
openWindow	새 창/탭에서 열기	navigation
replaceUrl	URL만 변경 (refetch 없음)	navigation
apiCall	API 호출	state
setState	상태 변경	state
openModal	모달 열기	ui
closeModal	모달 닫기	ui
toast	토스트 알림	ui
sequence	순차 실행	ui
suppress	에러 전파 방지 (no-op)	error

핸들러별 필수 속성

핸들러	필수 속성	선택 속성
navigate	params.path	params.query, params.mergeQuery, params.replace, params.fallback (engine-v1.40.0+, 미등록 경로 fallback, 기본 openWindow)
openWindow	params.path	-
replaceUrl	-	params.path, params.query, params.mergeQuery
apiCall	target	params.method, params.body, params.contentType, auth_required, onSuccess, onError
setState	params.*	params.target (global/local/isolated)
openModal	target (모달 ID)	-
toast	params.message	params.type, params.duration
switch	cases	params.value
sequence	actions	-
parallel	actions	-
suppress	-	-

---

모듈 커스텀 핸들러 다국어 처리

모듈에서 커스텀 핸들러를 개발할 때, 사용자에게 표시되는 모든 문자열은 반드시 다국어 처리해야 합니다.

핵심 원칙

필수: 모든 사용자 표시 문자열은 G7Core.t() 사용
필수: 다국어 키는 moduleIdentifier로 시작
✅ 필수: 영어 폴백 메시지 제공
✅ 필수: 파라미터는 {param} 형식 사용
❌ 금지: 한글 문자열 하드코딩 (toast, 알림 메시지 등)
예외: 로케일별 콘텐츠 생성용 상수맵은 허용 (예: DETAIL_REF_TRANSLATIONS)

다국어 키 네이밍 규칙

[moduleId].admin.[section].handler.[message_key]

예시:

• sirsoft-ecommerce.admin.product.handler.category_max_5
• sirsoft-ecommerce.admin.product.handler.options_generated

키 접미사 규칙:

접미사	용도	예시
_success	성공 메시지	copy_success
_error, _failed	오류 메시지	copy_error, upload_failed
_required	필수 입력 안내	name_required
_max_N	최대 개수 제한	category_max_5

구현 패턴

기본 패턴:

// ❌ DON'T: 하드코딩
G7Core.toast?.warning?.('최대 5개까지 선택 가능합니다.');

// ✅ DO: G7Core.t() + 영어 폴백
G7Core.toast?.warning?.(
    G7Core.t?.('sirsoft-ecommerce.admin.product.handler.category_max_5')
    ?? 'You can select up to 5 categories.'
);

파라미터 패턴:

// ❌ DON'T: 템플릿 리터럴만 사용
G7Core.toast?.success?.(`${count}개의 옵션이 생성되었습니다.`);

// ✅ DO: 파라미터 전달 + 폴백
G7Core.toast?.success?.(
    G7Core.t?.('sirsoft-ecommerce.admin.product.handler.options_generated', { count })
    ?? `${count} options have been generated.`
);

다국어 파일 등록 (resources/lang/ko.json, en.json):

// ko.json
{
  "admin": {
    "product": {
      "handler": {
        "category_max_5": "최대 5개까지 선택 가능합니다.",
        "options_generated": "{count}개의 옵션이 생성되었습니다."
      }
    }
  }
}

// en.json
{
  "admin": {
    "product": {
      "handler": {
        "category_max_5": "You can select up to 5 categories.",
        "options_generated": "{count} options have been generated."
      }
    }
  }
}

예외: 로케일별 콘텐츠 생성용 상수맵

로케일별로 다른 콘텐츠를 생성해야 하는 경우, 상수맵은 허용됩니다:

// ✅ 허용: 로케일별 콘텐츠 생성용 상수맵
const DETAIL_REF_TRANSLATIONS: Record<string, Record<string, string>> = {
    ko: { goods_name: '상품명', model_name: '모델명' },
    en: { goods_name: 'Product Name', model_name: 'Model Name' },
};

// 사용: 특정 로케일의 콘텐츠 생성
const text = DETAIL_REF_TRANSLATIONS[locale]?.[key] ?? key;

핸들러 개발 체크리스트

□ 모든 toast 메시지에 G7Core.t() 적용
□ 모든 확인/알림 모달 텍스트에 G7Core.t() 적용
□ 영어 폴백 메시지 제공 (G7Core.t?.() ?? 'fallback')
□ 다국어 파일(ko.json, en.json)에 키 추가
□ 파라미터는 {param} 형식으로 정의
□ 로그 메시지는 다국어 처리 불필요 (logger.log, logger.warn 등)

---

증상별 문서 찾기

증상	관련 문서	핵심 키워드
페이지 이동 안 됨	navigation	navigate, path, replace
API 호출 실패	state	apiCall, auth_required, onError
상태 변경 안 됨	state	setState, target: global/local/isolated
모달 안 열림/안 닫힘	ui	openModal, closeModal, modalStack
토스트 안 나옴	ui	toast, params.type
외부 스크립트 로드	ui	loadScript, onLoad, src 출처 게이트
조건부 액션 분기	ui	switch, cases, default

---

관련 문서

• 액션 시스템 기초
• G7Core API
• 상태 관리
• 데이터 소스
• 레이아웃 JSON