Gnuboard7/docs/frontend/templates/sirsoft-basic/handlers.md

sirsoft-basic 핸들러

템플릿 식별자: sirsoft-basic (type: user) 관련 문서: 액션 핸들러 개요 | 컴포넌트 | 레이아웃

---

TL;DR (5초 요약)

1. setTheme/initTheme: 다크/라이트 모드 전환 (admin과 동일 키 공유)
2. 장바구니 6종: 선택/옵션/삭제/재계산 핸들러
3. 상품 옵션 2종: 옵션 완료 시 자동 추가/수량 변경
4. 다중 통화 5종: 가격 표시/포맷/통화 기호/선호 통화 로드/저장
5. 스토리지 6종: 비회원 장바구니 키 관리 (localStorage + API 발급)

---

목차

1. 테마 핸들러
2. 장바구니 핸들러
3. 장바구니 옵션 변경 핸들러
4. 상품 옵션 핸들러
5. 다중 통화 핸들러
6. 스토리지 핸들러
7. 핸들러 등록 맵

---

테마 핸들러

소스: src/handlers/setThemeHandler.ts

sirsoft-admin_basic과 동일한 localStorage 키(g7_color_scheme)를 사용하여 테마 설정을 공유합니다.

setTheme

{
  "type": "click",
  "handler": "setTheme",
  "params": {
    "theme": "dark"
  }
}

필드	타입	필수	설명
theme	string	✅	"light", "dark", "auto" (시스템 설정 따름)

initTheme

앱 시작 시 init_actions에서 호출. params 없음.

{
  "init_actions": [
    { "handler": "initTheme" }
  ]
}

---

장바구니 핸들러

소스: src/handlers/cartHandlers.ts

장바구니 페이지에서 상품 선택, 옵션 변경, 삭제 등을 처리합니다.

toggleCartItemSelection

장바구니 아이템 선택/해제를 토글합니다.

{
  "handler": "toggleCartItemSelection",
  "params": {
    "itemId": "{{item.id}}"
  }
}

selectAllCartItems

모든 장바구니 아이템을 선택/해제합니다.

{
  "handler": "selectAllCartItems",
  "params": {
    "selected": true
  }
}

setCartOption

장바구니 아이템의 옵션을 변경합니다.

{
  "handler": "setCartOption",
  "params": {
    "itemId": "{{item.id}}",
    "optionId": "{{selectedOption.id}}"
  }
}

openCartDeleteModal

장바구니 삭제 확인 모달을 엽니다.

{
  "handler": "openCartDeleteModal",
  "params": {
    "itemId": "{{item.id}}"
  }
}

openCartOptionModal

장바구니 옵션 변경 모달을 엽니다.

{
  "handler": "openCartOptionModal",
  "params": {
    "itemId": "{{item.id}}"
  }
}

recalculateCart

장바구니 합계를 재계산합니다.

{
  "handler": "recalculateCart"
}

장바구니 핸들러 요약

핸들러	params	설명
toggleCartItemSelection	{ itemId }	아이템 선택 토글
selectAllCartItems	{ selected }	전체 선택/해제
setCartOption	{ itemId, optionId }	옵션 변경
openCartDeleteModal	{ itemId }	삭제 모달 열기
openCartOptionModal	{ itemId }	옵션 변경 모달 열기
recalculateCart	없음	합계 재계산

---

장바구니 옵션 변경 핸들러

소스: src/handlers/cartOptionChange.ts

장바구니 옵션 변경 모달에서 옵션 선택 및 매칭을 처리합니다.

findMatchingOption

선택한 옵션 값들로 매칭되는 상품 옵션을 찾습니다.

{
  "handler": "findMatchingOption",
  "params": {
    "options": "{{_local.options}}",
    "selection": "{{_local.optionSelection}}"
  }
}

initCartOptionSelection

옵션 변경 모달 초기화 시 현재 선택된 옵션을 설정합니다.

{
  "handler": "initCartOptionSelection",
  "params": {
    "currentOption": "{{item.option}}"
  }
}

---

상품 옵션 핸들러

소스: src/handlers/productOptions.ts

상품 상세 페이지에서 옵션 선택 및 수량 변경을 처리합니다.

addSelectedItemIfComplete (sirsoft-basic.addSelectedItemIfComplete)

모든 옵션 그룹 선택 완료 시 선택 아이템 목록에 자동 추가합니다.

{
  "handler": "sirsoft-basic.addSelectedItemIfComplete",
  "params": {
    "newGroupName": "{{groupName}}",
    "newValue": "{{selectedValue}}",
    "optionGroups": "{{product?.data?.option_groups}}",
    "options": "{{product?.data?.options}}"
  }
}

updateSelectedItemQuantity (sirsoft-basic.updateSelectedItemQuantity)

선택된 아이템의 수량을 변경합니다.

{
  "handler": "sirsoft-basic.updateSelectedItemQuantity",
  "params": {
    "optionId": "{{option.id}}",
    "quantity": "{{newQuantity}}"
  }
}

---

다중 통화 핸들러

getDisplayPrice (sirsoft-basic.getDisplayPrice)

소스: src/handlers/getDisplayPrice.ts

사용자 선호 통화에 맞는 가격을 반환합니다.

{
  "handler": "sirsoft-basic.getDisplayPrice",
  "params": {
    "product": "{{product.data}}",
    "priceField": "selling_price"
  }
}

필드	타입	필수	설명
product	object	✅	상품 객체
priceField	string	✅	"selling_price" 또는 "list_price"
currencyCode	string	❌	통화 코드 (미지정 시 전역 설정 사용)

formatCurrency (sirsoft-basic.formatCurrency)

소스: src/handlers/formatCurrency.ts

숫자 값을 통화 형식 문자열로 변환합니다.

{
  "handler": "sirsoft-basic.formatCurrency",
  "params": {
    "value": 10000,
    "currencyCode": "KRW"
  }
}

필드	타입	필수	설명
value	number	✅	포맷팅할 숫자 값
currencyCode	string	❌	통화 코드 (KRW, USD, JPY, CNY, EUR)
locale	string	❌	로케일 (미지정 시 통화 기본 로케일 사용)

지원 통화: KRW (₩), USD ($), JPY (¥), CNY (¥), EUR (€)

getCurrencySymbol (sirsoft-basic.getCurrencySymbol)

통화 기호를 반환합니다.

loadPreferredCurrency (sirsoft-basic.loadPreferredCurrency)

소스: src/handlers/loadPreferredCurrency.ts

localStorage에서 선호 통화를 로드하여 전역 상태(_global.preferredCurrency)에 설정합니다.

{
  "init_actions": [
    {
      "handler": "sirsoft-basic.loadPreferredCurrency",
      "params": { "defaultCurrency": "KRW" }
    }
  ]
}

savePreferredCurrency (sirsoft-basic.savePreferredCurrency)

선호 통화를 localStorage에 저장합니다.

{
  "handler": "sirsoft-basic.savePreferredCurrency",
  "params": {
    "currencyCode": "{{selectedCurrency}}"
  }
}

---

스토리지 핸들러

소스: src/handlers/storageHandlers.ts

비로그인 사용자의 장바구니 키 등 클라이언트 스토리지를 관리합니다.

initCartKey

장바구니 키를 초기화합니다. localStorage에 있으면 로드, 없으면 API를 통해 발급합니다.

{
  "init_actions": [
    { "handler": "initCartKey" }
  ]
}

getCartKey / clearCartKey / regenerateCartKey

{ "handler": "getCartKey" }
{ "handler": "clearCartKey" }
{ "handler": "regenerateCartKey" }

saveToStorage / loadFromStorage

범용 localStorage 저장/로드 핸들러입니다.

{
  "handler": "saveToStorage",
  "params": {
    "key": "g7_some_setting",
    "value": "{{_local.settingValue}}"
  }
}

{
  "handler": "loadFromStorage",
  "params": {
    "key": "g7_some_setting",
    "stateKey": "savedSetting"
  }
}

스토리지 핸들러 요약

핸들러	params	설명
initCartKey	없음	장바구니 키 초기화 (localStorage + API)
getCartKey	없음	현재 장바구니 키 반환
clearCartKey	없음	장바구니 키 삭제
regenerateCartKey	없음	장바구니 키 재발급
saveToStorage	{ key, value }	localStorage 저장
loadFromStorage	{ key, stateKey }	localStorage 로드 → 상태에 설정

---

핸들러 등록 맵

소스: src/handlers/index.ts

등록 키	소스 파일	설명
setTheme	setThemeHandler.ts	테마 변경
initTheme	setThemeHandler.ts	테마 초기화
toggleCartItemSelection	cartHandlers.ts	장바구니 아이템 선택
selectAllCartItems	cartHandlers.ts	장바구니 전체 선택
setCartOption	cartHandlers.ts	장바구니 옵션 변경
openCartDeleteModal	cartHandlers.ts	삭제 모달 열기
openCartOptionModal	cartHandlers.ts	옵션 모달 열기
recalculateCart	cartHandlers.ts	장바구니 재계산
findMatchingOption	cartOptionChange.ts	매칭 옵션 검색
initCartOptionSelection	cartOptionChange.ts	옵션 선택 초기화
sirsoft-basic.addSelectedItemIfComplete	productOptions.ts	옵션 완료 시 자동 추가
sirsoft-basic.updateSelectedItemQuantity	productOptions.ts	수량 변경
sirsoft-basic.getDisplayPrice	getDisplayPrice.ts	통화별 가격 표시
sirsoft-basic.formatCurrency	formatCurrency.ts	통화 포맷팅
sirsoft-basic.getCurrencySymbol	formatCurrency.ts	통화 기호
sirsoft-basic.loadPreferredCurrency	loadPreferredCurrency.ts	선호 통화 로드
sirsoft-basic.savePreferredCurrency	loadPreferredCurrency.ts	선호 통화 저장
initCartKey	storageHandlers.ts	장바구니 키 초기화
getCartKey	storageHandlers.ts	장바구니 키 조회
clearCartKey	storageHandlers.ts	장바구니 키 삭제
regenerateCartKey	storageHandlers.ts	장바구니 키 재발급
saveToStorage	storageHandlers.ts	localStorage 저장
loadFromStorage	storageHandlers.ts	localStorage 로드

---

주의사항

이 핸들러들은 sirsoft-basic 템플릿에서만 등록됨
sirsoft-basic. 접두사 핸들러는 풀네임으로 호출해야 함
setLocale은 엔진 레벨(ActionDispatcher) 빌트인 — 별도 등록 불필요
✅ 범용 핸들러(navigate, apiCall, setState 등)는 actions-handlers.md 참조

---

관련 문서

• 액션 핸들러 개요
• sirsoft-basic 컴포넌트
• sirsoft-basic 레이아웃
• sirsoft-admin_basic 핸들러