goldenChart/setting_save_storage.md

# GoldenChart 설정 저장소 정리

> 작성 기준: `goldenChart` 프론트엔드 + Spring Boot 백엔드 코드베이스 (2026-05-23)  
> **파일 시스템에 사용자 설정 JSON을 두는 방식은 없음.** 브라우저 **localStorage / sessionStorage** 와 **MySQL(DB)** 만 사용.

---

## 1. 저장소 종류 요약

| 저장소 | 용도 | 특징 |
|--------|------|------|
| **DB (MySQL)** | 계정·기기별 영구 설정, 전략 DSL, 워크스페이스, 체결·알림 이력 | API `PATCH/POST` 저장, Flyway 마이그레이션 |
| **localStorage** | 오프라인 미러, UI 레이아웃, 레거시 백업, 읽음/숨김 ID | 브라우저·기기별, 용량 제한 |
| **sessionStorage** | 탭 세션 동안만 유효 | 새 탭·브라우저 종료 시 소멸 |
| **메모리(React state)** | 현재 세션 UI만 | 새로고침 시 DB/localStorage에서 복원 |

### 로드 우선순위 (대표)

| 영역 | 1순위 | 2순위 | 3순위 |
|------|--------|--------|--------|
| 앱 전역 기본값 | `gc_app_settings` (DB) | `trading_chart_state` (localStorage) | 코드 하드코딩 |
| 멀티차트 레이아웃 ID | DB `default_layout_id` + `gc_chart_workspace` | localStorage `chartLayout` | `LAYOUTS[0]` |
| 동기화 옵션 | DB `sync_options_json` | localStorage `chartLayoutSync` | `DEFAULT_SYNC` |
| 전략 목록 | DB `gc_strategy` | localStorage `gc_strat_v2` | — |
| 관심종목 | DB `gc_watchlist` | localStorage `gc_favorites` | — |

---

## 2. DB — `gc_app_settings` (설정 화면 · 앱 전역)

API: `GET/POST /api/app-settings` · 프론트: `useAppSettings` → `saveAppDef()` / `loadAppSettings()`

| 필드 (API 키) | DB 컬럼 | 설명 |
|---------------|---------|------|
| `defaultSymbol` | `default_symbol` | 기본 종목 |
| `defaultTimeframe` | `default_timeframe` | 기본 타임프레임 |
| `defaultChartType` | `default_chart_type` | 기본 차트 타입 |
| `defaultTheme` | `default_theme` | 기본 테마 (`dark` / `light` / `blue`) |
| `defaultLogScale` | `default_log_scale` | 로그 스케일 기본값 |
| `defaultLayoutId` | `default_layout_id` | 멀티차트 레이아웃 ID |
| `displayTimezone` | `display_timezone` | 표시 시간대 (IANA) |
| `mainChartStyle` | `main_chart_style_json` | **캔들 색상** (상승/하락/심지/테두리) |
| `syncOptions` | `sync_options_json` | 멀티차트 동기화 (`symbol`, `interval`, `crosshair`, `time`, `dateRange`) |
| `btAutoPopup` | `bt_auto_popup` | 백테스트 완료 시 결과 팝업 |
| `btShowPrice` | `bt_show_price` | 백테스트 마커 금액 표시 |
| `chartSeriesPriceLabels` | `chart_series_price_labels` | 보조지표 우측 가격축 라벨·설명 |
| `chartVolumeVisible` | `chart_volume_visible` | 거래량 pane 표시 |
| `chartLiveReceiveHighlight` | `chart_live_receive_highlight` | 실시간 수신 카드 glow |
| `chartLegendOptions` | `chart_legend_options_json` | 상단 범례(tv-legend) 항목별 ON/OFF |
| `chartPaneSeparator` | `chart_pane_separator_json` | **pane 구분선** (`visible`, `color`, `width`, `lineStyle`) |
| `chartRealtimeSource` | `chart_realtime_source` | `BACKEND_STOMP` / `UPBIT_DIRECT` |
| `tradeAlertPopup` | `trade_alert_popup` | 매매 시그널 알림 팝업 |
| `tradeAlertSoundEnabled` | `trade_alert_sound_enabled` | 알림 사운드 ON/OFF |
| `tradeAlertSound` | `trade_alert_sound` | 알림음 ID (`bell` 등) |
| `tradeAlertPopupPosition` | `trade_alert_popup_position` | 팝업 위치 |
| `tradeAlertPopupLayout` | `trade_alert_popup_layout` | 팝업 배치 (`stack` / `grid` 등) |
| `tradeAlertPopupGridCols` | `trade_alert_popup_grid_cols` | 그리드 열 수 |
| `verificationIssueNotify` | `verification_issue_notify` | 검증 이슈 알림 |
| `liveStrategyCheck` | `live_strategy_check` | 실시간 전략 체크 마스터 |
| `liveStrategyId` | `live_strategy_id` | 관심종목 공통 전략 ID |
| `liveExecutionType` | `live_execution_type` | `CANDLE_CLOSE` / `REALTIME_TICK` |
| `livePositionMode` | `live_position_mode` | `LONG_ONLY` / `SIGNAL_ONLY` |
| `paperTradingEnabled` | `paper_trading_enabled` | 모의투자 기능 |
| `paperInitialCapital` | `paper_initial_capital` | 모의 초기 자본 |
| `paperFeeRatePct` | `paper_fee_rate_pct` | 모의 수수료율 |
| `paperSlippagePct` | `paper_slippage_pct` | 모의 슬리피지 |
| `paperMinOrderKrw` | `paper_min_order_krw` | 모의 최소 주문 금액 |
| `paperAutoTradeEnabled` | `paper_auto_trade_enabled` | 자동 모의매매 |
| `paperAutoTradeBudgetPct` | `paper_auto_trade_budget_pct` | 자동매수 예산 비율 |
| `virtualTargetMaxCount` | `virtual_target_max_count` | 가상매매 종목 수 상한 |
| `tradingMode` | `trading_mode` | `PAPER` / `LIVE` / `BOTH` |
| `liveAutoTradeEnabled` | `live_auto_trade_enabled` | 실거래 자동매매 |
| `liveAutoTradeBudgetPct` | `live_auto_trade_budget_pct` | 실거래 자동매수 비율 |
| `fcmPushEnabled` | `fcm_push_enabled` | FCM 푸시 (기능 플래그) |
| `upbitAccessKey` / `upbitSecretKey` | `upbit_access_key`, `upbit_secret_key` | 업비트 API 키 (암호화 저장) |
| `trendSearchSettings` | `trend_search_settings_json` | 추세검색 가중치·자동갱신·자동추가 등 |

키 식별: `device_id` 또는 로그인 `user_id` (백엔드 `AppSettingsService`).

---

## 3. DB — 차트·지표·전략·매매 (설정 화면 외)

### 3.1 차트 워크스페이스

| 테이블 | API | 저장 내용 |
|--------|-----|-----------|
| `gc_chart_workspace` | `GET/POST /api/chart/workspace` | `layout_id`, `sync_options_json` |
| `gc_chart_slot` | `PUT /api/chart/slot/{index}` | 슬롯별 `symbol`, `timeframe`, `chart_type`, `theme`, `mode`, `log_scale`, **`indicators_json`**, **`drawings_json`**, `drawings_locked`, `drawings_visible`, `pane_layout_json`, **`main_chart_style_json`** |

- **싱글 차트(`App.tsx`)**: `useWorkspacePersist` → 슬롯 0 위주로 워크스페이스 전체 POST (2초 debounce).
- **멀티 슬롯(`ChartSlot`)**: 슬롯마다 `saveSlot()` 개별 PUT (2초 debounce). App의 `workspaceState`는 주석대로 **슬롯 0만** 배열에 넣는 경우 있음 → 멀티는 슬롯 컴포넌트 저장이 실질적 기준.

### 3.2 보조지표 전역 기본값 (설정 → 지표 탭)

| 테이블 | API | 저장 내용 |
|--------|-----|-----------|
| `gc_indicator_settings` | `GET/POST` 지표 설정 API | `params_json` — 타입별 **계산 파라미터** (length 등) |
| ↑ 동일 | 시각 설정 API | `visual_config_json` — 타입별 **plots(색상·선굵기·선스타일)**, **hlines**, `cloudColors` |

프론트: `useIndicatorSettings` · 설정 화면 `IndicatorMainDefaultsPanel` · 차트에 지표 추가 시 DB 값이 `indicatorRegistry` 기본값을 덮어씀.

**차트에 올라간 인스턴스**(`IndicatorConfig[]`, id/plotVisibility/mergedWith 등)는 **`gc_chart_slot.indicators_json`** (또는 싱글 워크스페이스 슬롯 0).

### 3.3 투자전략 (DSL)

| 테이블 | API | 저장 내용 |
|--------|-----|-----------|
| `gc_strategy` | `/api/strategies` | `name`, `description`, `buy_condition_json`, `sell_condition_json`, `enabled` |

- **정본: DB.** 저장 시 `StrategyPage` / `StrategyEditorPage`가 API 호출.
- localStorage `gc_strat_v2`는 **백업·마이그레이션·오프라인 폴백** (`saveStratsLocal`).

### 3.4 백테스트

| 테이블 | API | 저장 내용 |
|--------|-----|-----------|
| `gc_backtest_settings` | `/api/backtest-settings` | 초기자본, 수수료, 슬리피지, 진입/청산가, 손절·익절, 트레일링, 재진입 등 |
| `gc_backtest_result` (등) | `/api/backtest-results` | 실행 결과·분석 JSON (설정값 아님) |

### 3.5 실시간 전략 / 가상매매 연동

| 테이블 | API | 저장 내용 |
|--------|-----|-----------|
| `gc_live_strategy_settings` | `/api/strategy/settings` | 종목별 `strategy_id`, `is_live_check`, `execution_type`, `candle_type`, `position_mode`, `is_pinned` |

가상매매 UI의 종목 목록·세션은 **localStorage** (아래)이고, 실행·핀·분봉은 위 DB와 동기화.

### 3.6 관심종목·보유·모의·시그널·검증

| 테이블 | 용도 |
|--------|------|
| `gc_watchlist` | 관심종목 (DB 정본) |
| `gc_holdings` | 보유종목 |
| `gc_paper_account`, `gc_paper_position`, `gc_paper_trade` | 모의 계좌·포지션·체결 |
| `gc_trade_signal` | 매매 시그널 이력 (서버) |
| `gc_verification_issue` (+ comment, image) | 검증 게시판 |
| `gc_trend_search_snapshot` | 추세검색 스냅샷 |
| `gc_user`, 역할·메뉴 권한 테이블 | 로그인·`AdminSettingsPanel` |

### 3.7 지표 계산 캐시

| 테이블 | 용도 |
|--------|------|
| `gc_indicator_cache` | 서버 계산 결과 캐시 (사용자 UI 설정 아님) |

---

## 4. localStorage 전체 목록

| 키 | 파일/모듈 | 저장 내용 | DB와 관계 |
|----|-----------|-----------|-----------|
| `trading_chart_state` | `utils/storage.ts` | symbol, timeframe, chartType, theme, indicators[], watchlist[], alertPrices[], mainChartStyle (v8) | **미러·레거시**; 앱은 DB 우선 로드 후 `saveState`로 동기 갱신 |
| `chartLayout` | `App.tsx` | 멀티차트 레이아웃 ID | DB `default_layout_id` / workspace와 **이중** |
| `chartLayoutSync` | `App.tsx` | `SyncOptions` JSON | DB `sync_options_json`와 **이중** |
| `gc_app_settings` (캐시 아님) | — | (해당 없음 — DB만) | |
| `gc_favorites` | `utils/marketStorage.ts` | 관심종목 심볼 배열 | DB `gc_watchlist` **미러** |
| `upbit_market_favorites` | ↑ | 구버전 키 → `gc_favorites` 1회 이전 | — |
| `gc_holdings` | `marketStorage.ts` | 보유종목 배열 | DB `gc_holdings` **미러** |
| `gc_market_names` | `marketNameCache.ts` | 종목 한글명 캐시 | 성능용 캐시 |
| `gc_device_id` | `backendApi.ts` 등 | 기기 UUID | API 헤더·DB 행 식별 |
| `gc_user_id`, `gc_username`, `gc_display_name`, `gc_user_role` | `auth.ts` | 로그인 세션 정보 | 서버 세션 보조 |
| `gc_strat_v2` | `StrategyPage`, `strategyEditorShared`, Toolbar | 전략 목록 JSON 백업 | DB `gc_strategy` **폴백/마이그레이션** |
| `gc_strategies_v1` | `strategyTypes.ts` | 구버전 전략 DSL 배열 | 레거시 (v2와 별도) |
| `gc_indicator_settings` | — | (직접 키 없음 — DB API) | |
| `gc-indicator-custom-tabs-v1` | `indicatorCustomTabsStorage.ts` | 지표 추가 팝업 **사용자 정의 탭** (이름 + 지표 type 목록) | **localStorage만** |
| `gc_se_flow_layout_v1` | `strategyEditorLayoutStorage.ts` | 전략편집기 **그래프 노드 위치·엣지·START 메타** (전략 키별) | **localStorage만** (DSL 본문은 DB) |
| `gc_se_editor_mode` | `strategyEditorModeStorage.ts` | `graph` / `list` 편집 모드 | **localStorage만** |
| `gc_se_canvas_interaction` | `strategyCanvasInteractionStorage.ts` | 캔버스 인터랙션 모드 | **localStorage만** |
| `se-palette-auxiliary-v1` | `strategyPaletteStorage.ts` | 전략편집기 팔레트 — 보조지표 목록 커스텀 | **localStorage만** |
| `se-palette-composite-v1` | ↑ | 팔레트 — 복합지표 목록 커스텀 | **localStorage만** |
| `se-left-width` | `StrategyEditorPage` | 좌측 패널 너비(px) | **localStorage만** |
| `se-terminal-height` | ↑ | 하단 터미널 높이(px) | **localStorage만** |
| `gc_virtual_targets_v1` | `virtualTradingStorage.ts` | 가상매매 **투자대상** (market, strategyId, candleType, pinned, 이름) | DB live settings와 **동기** |
| `gc_virtual_session_v1` | ↑ | 가상매매 **세션** (globalStrategyId, executionType, positionMode, running) | 부분적으로 app settings와 중복 |
| `gc_virtual_card_view_v1` | ↑ | 카드 보기 `summary` / `detail` | **localStorage만** |
| `gc_trade_notify_read_v1` | `TradeNotificationContext.tsx` | 읽은 알림 ID 목록 | 서버 이력 + 클라이언트 읽음 |
| `gc_trade_notify_hidden_v1` | ↑ | 목록에서 숨긴 알림 ID | **localStorage만** |
| `tsd-display-mode` | `TrendSearchPage.tsx` | 추세검색 결과 `chart` / `signal` 표시 모드 | **localStorage만** |
| `btd-left-width` | `BacktestHistoryPage.tsx` | 백테스트 이력 좌측 패널 너비 | **localStorage만** |
| `btd-right-width` | ↑ | 백테스트 이력 우측 패널 너비 | **localStorage만** |

---

## 5. sessionStorage

| 키 | 모듈 | 내용 |
|----|------|------|
| `gc_app_entered` | `appEntry.ts` | 스플래시 통과 여부 (탭 세션) |
| `gc_admin_unlock_until` | `adminUnlock.ts` | 관리자 설정 패널 잠금 해제 만료 시각 (30분) |

---

## 6. 설정 화면 UI — 저장 여부 상세

### 6.1 DB에 저장됨 (`gc_app_settings` / API)

- 일반 · 표시 시간대 · 레이아웃 기본 · 테마
- **차트**: 실시간 데이터 소스, 수신 음영, 거래량, 지표 가격축 라벨, **pane 구분선**, 상단 범례 항목, (캔들 색은 **메인 차트 설정 모달** → `mainChartStyle`)
- **지표 탭**: `gc_indicator_settings` params + visual (색·선·hline)
- 백테스트 · 알림 · 실시간/모의/실거래 · 추세검색 · FCM 플래그
- 관리자: 사용자·역할 메뉴 권한 → **별도 DB 테이블** (`AdminSettingsPanel`)

### 6.2 DB 또는 워크스페이스에 저장 (설정 화면 밖)

| 항목 | 저장 위치 |
|------|-----------|
| 캔들 색상 (실제 적용) | `mainChartStyle` → DB + `gc_chart_slot.main_chart_style_json` |
| 차트에 붙은 보조지표 목록·개별 plot 색 | `gc_chart_slot.indicators_json` |
| 드로잉 | `gc_chart_slot.drawings_json` (싱글 App state → workspace) |
| 격자선 ON/OFF (`showGrid`) | 워크스페이스/슬롯에 **전용 필드 없음** → **미영구** (세션 state) |
| 로그 스케일 | 슬롯 `log_scale` (DB 가능, ChartSlot은 현재 `false` 고정 저장) |
| 퍼센트 스케일 | **미저장** |
| 자석 모드 (`magnetMode`) | 설정 토글은 App state만, **DB/localStorage 없음** |

### 6.3 설정 화면에만 있고 **저장되지 않음** (주의)

`SettingsPage` → `ChartPanel` 내부 **로컬 state** (`useState` 초기값 고정). 저장 API와 **연결 안 됨**:

| UI 라벨 | state | 실제 반영 |
|---------|--------|-----------|
| 상승/하락/배경 캔들 색 | `upColor`, `downColor`, `bgColor` | **없음** (진짜 색상은 메인 차트 설정 모달 → DB) |
| 격자선 표시 | `gridLines` | **없음** (툴바 `showGrid`는 App state, 미영구) |
| 크로스헤어 모드 | `crosshair` | **없음** |
| 가격축 위치 | `priceScale` | **없음** |
| 소수점 자리수 | `precision` | **없음** |

---

## 7. 차트 선색·선스타일 — 어디에 무엇이 저장되는가

| 대상 | 색상 | 선 굵기 | 선 스타일 | 저장소 |
|------|------|---------|-----------|--------|
| **캔들(메인)** | O | (캔들 형태) | — | DB `main_chart_style_json` |
| **보조지표 plot (전역 기본)** | O | O | O (`solid`/`dashed`/`dotted`) | DB `visual_config_json` |
| **보조지표 hline (전역)** | O | O | O | DB `visual_config_json` |
| **차트에 올린 지표 인스턴스** | O (plots 복사) | O | O | DB `indicators_json` (슬롯별) |
| **pane 구분선** | O | O (1–4px) | O | DB `chart_pane_separator_json` |
| **드로잉 도구 선** | Drawing 객체 필드 | width 등 | style | `drawings_json` (저장 시) |
| **격자선** | 테마 `gridColor` | — | — | 테마·`showGrid` state (격자 ON/OFF 미영구) |

일목균형 `cloudColors` → `visual_config_json` 내 Ichimoku 전용.

---

## 8. 지표 탭 · 전략편집기 · 기타 UI

| 기능 | 저장소 |
|------|--------|
| 설정 → 지표 기본값 (파라미터·스타일) | DB `gc_indicator_settings` |
| 지표 추가 팝업 **커스텀 탭** | localStorage `gc-indicator-custom-tabs-v1` only |
| 전략편집기 DSL | DB `gc_strategy` |
| 전략편집기 노드 좌표·START 분봉 메타 | localStorage `gc_se_flow_layout_v1` |
| 전략편집기 팔레트 항목 | localStorage `se-palette-*` |
| 전략편집기 패널 크기 | localStorage `se-left-width`, `se-terminal-height` |
| 전략편집기 graph/list 모드 | localStorage `gc_se_editor_mode` |

---

## 9. 이중 저장·동기화 시 주의

1. **`trading_chart_state` vs DB**  
   App이 변경마다 `saveState()` 호출. DB `useAppSettings`와 **별도**. 초기 로드는 DB → `loadState` 혼용.

2. **`chartLayout` / `chartLayoutSync` vs workspace**  
   레이아웃 변경 시 localStorage + `saveAppDef({ defaultLayoutId })` + workspace POST.

3. **전략 `gc_strat_v2` vs `gc_strategy`**  
   DB가 비면 localStorage에서 마이그레이션. Toolbar 백테스트 전략 목록은 DB 실패 시 local 폴백.

4. **가상매매**  
   - 목록/세션: localStorage  
   - 종목별 전략·live·핀·분봉: `gc_live_strategy_settings`  
   - 전역 기본 전략: `gc_app_settings.liveStrategyId` 등

5. **관심종목**  
   DB 정본 + `gc_favorites` 미러 (`marketStorage.ts`).

---

## 10. 파일 시스템

- 사용자 설정을 **로컬 디스크 파일**로 export/import 하는 공식 기능 **없음**.
- Firebase FCM: 환경변수 `VITE_FIREBASE_*` (빌드 설정, DB 아님).

---

## 11. 빠른 참조 — “이 설정 어디?”

| 사용자가 바꾸는 것 | 저장 |
|--------------------|------|
| 설정 → 차트 → 구분선/거래량/범례/실시간 소스 | **DB** `gc_app_settings` |
| 설정 → 차트 → 캔들 색 (모달) | **DB** `mainChartStyle` |
| 설정 → 지표 RSI 색/기간 | **DB** indicator settings |
| 차트에 RSI 추가 후 색만 변경 | **DB** slot `indicators_json` |
| 멀티차트 4분할 레이아웃 | **DB** workspace + localStorage `chartLayout` |
| 전략 저장 | **DB** `gc_strategy` |
| 전략 편집기에서 블록 위치 | **localStorage** flow layout |
| 가상매매 종목 추가 | **localStorage** + **DB** live settings |
| 알림 읽음/삭제 | 읽음·숨김 ID → **localStorage**; 이력 → **DB** signals |
| 백테스트 수수료·손절 | **DB** `gc_backtest_settings` |
| 추세검색 가중치 | **DB** `trendSearchSettings` |
| 추세검색 카드/시그널 보기 | **localStorage** `tsd-display-mode` |

---

*문서 위치: 프로젝트 루트 `setting_save_storage.md`*