# sirsoft-basic 핸들러

> **템플릿 식별자**: `sirsoft-basic` (type: user)
> **관련 문서**: [액션 핸들러 개요](../../actions-handlers.md) | [컴포넌트](./components.md) | [레이아웃](./layouts.md)

---

## TL;DR (5초 요약)

```text
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

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

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

### initTheme

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

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

---

## 장바구니 핸들러

**소스**: `src/handlers/cartHandlers.ts`

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

### toggleCartItemSelection

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

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

### selectAllCartItems

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

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

### setCartOption

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

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

### openCartDeleteModal

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

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

### openCartOptionModal

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

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

### recalculateCart

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

```json
{
  "handler": "recalculateCart"
}
```

### 장바구니 핸들러 요약

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

---

## 장바구니 옵션 변경 핸들러

**소스**: `src/handlers/cartOptionChange.ts`

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

### findMatchingOption

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

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

### initCartOptionSelection

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

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

---

## 상품 옵션 핸들러

**소스**: `src/handlers/productOptions.ts`

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

### addSelectedItemIfComplete (sirsoft-basic.addSelectedItemIfComplete)

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

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

### updateSelectedItemQuantity (sirsoft-basic.updateSelectedItemQuantity)

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

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

---

## 다중 통화 핸들러

### getDisplayPrice (sirsoft-basic.getDisplayPrice)

**소스**: `src/handlers/getDisplayPrice.ts`

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

```json
{
  "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`

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

```json
{
  "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`)에 설정합니다.

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

### savePreferredCurrency (sirsoft-basic.savePreferredCurrency)

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

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

---

## 스토리지 핸들러

**소스**: `src/handlers/storageHandlers.ts`

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

### initCartKey

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

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

### getCartKey / clearCartKey / regenerateCartKey

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

### saveToStorage / loadFromStorage

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

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

```json
{
  "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 로드 |

---

## 주의사항

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

---

## 관련 문서

- [액션 핸들러 개요](../../actions-handlers.md)
- [sirsoft-basic 컴포넌트](./components.md)
- [sirsoft-basic 레이아웃](./layouts.md)
- [sirsoft-admin_basic 핸들러](../sirsoft-admin_basic/handlers.md)