---
description: 해외=국장 UI 최대한 동일. 꼭 다를 때만 선보고·승인. 이식 시 summary·저장·브라우저 검증.
alwaysApply: true
---

# 국내 이식·해외 UI 정합 (절대)

## A. 해외 전략 UI = 국장과 최대한 동일 (선보고)

- **기본**: 해외(`US_*`) 웹·Optuna·결과카드·버튼·표(Top5「보기」/폼/적용)·가상거래·차트는 **대응 국장 탭과 같은 UX**.
- “해외라서 단축·생략” **임의 판단 금지.**
- **꼭 다르게 해야 할 때만** (USD 표시, HTS 없음, 해외 WS 세션, 종목핀 테이블 등):
  1. **무엇을·왜** 다르게 하는지 **구현 전 짧게 보고**
  2. **사용자 승인 후** 구현
  3. UI에 차이(「전역/종목」「USD」) **문구로 명시**
- 승인 없이 Optuna Top5·보기·후보선택·PF/수익률·설정저장 흐름을 빼거나 다르게 만들면 **위반**.
- 엔진도 국장과 동일이 기본(T−1/T·freeze). 체결가·호가 등 실매 차이도 **선보고**.

---

국내 탭/API를 “그대로 가져왔다”는 **복사만으로는 완료가 아니다.**  
해외·신규 탭에서 아래를 **브라우저로 확인**하기 전에는 “정합 OK / 버그 없음”을 **단정하지 마라.**

## 0. 정신 (이 대화에서 실제로 난 사고)

- 원인 미확인 상태로 **엔진·cfg 불일치**로 넘기지 마라.  
  UI가 Optuna 폼을 **탭 재클릭/종목 리로드로 DB 핀으로 덮어쓴** 경우처럼, **표시·적용 경로**를 먼저 검증하라.
- “국내랑 같은 코드” ≠ “국내랑 같은 화면 숫자.”  
  **summary 키·저장 테이블·버튼 의미**가 하나라도 빠지면 사용자에게는 버그다.
- Optuna「보기」없이 1위 단축만 두는 것도 **국장 UI와 다름** → 선보고 없이 하면 위반.

## 1. 웹 백테 summary ↔ 렌더 키 (필수 체크리스트)

국내 `summarize_trades` / 웹 렌더는 키가 다를 수 있다. 이식 시 **응답 JSON과 DOM id를 대조**하라.

| 화면 | 흔한 버그 | 올바른 소스 |
|------|-----------|-------------|
| Profit Factor | `stats.profit_factor` 없음 → **0** | `stats["pf"]` → summary `profit_factor` |
| 총 수익률(운용한도) | summary에 미포함 → **0%** | `stats["bot_pct"]` |
| 일평균 수익률 | summary에 미포함 → **0%** | `stats["daily_avg_pct"]` |
| 누적/일별/사유 차트 | `equity`/`daily`/`reasons` 미포함 → 빈 차트 | 국내 모멘텀/스캘프 웹과 **동일 필드** |
| 피크 누적 | context 미표시 | `peak_cum_pnl` / `peak_cum_at` |

**완료 전:** 백테 1회 후 PF·bot%·일평균%·PnL·거래수가 **0이 아닌 기대값**(또는 의도적 0)인지 확인.  
`curl 200` / “거래만 나옴”만으로는 **미완료**.

## 2. 통화·절삭 (해외 USD)

- USD PnL·MDD·누적은 **`int()` 절삭 금지.** 소수(센트) 유지.
- `summarize_trades`가 `total_pnl`을 int로 돌려도, **해외 응답의 표시용 total_pnl은 거래 합산 float**을 쓸 것.
- 운용한도 분모(`total_budget_*`) 단위(USD vs KRW)를 라벨·bot_pct 계산과 **혼동하지 말 것.**

## 3. 저장 대상 분리 (버튼·테이블·문구)

| UI | 저장처 | 금지 |
|----|--------|------|
| **전역 설정 저장** | `config_us_momentum` (`US_MOMENTUM_*`) + env 스냅샷 | 종목행 테이블에 쓰는 척 |
| **종목행 적용 / 선택종목 저장** | `us_momentum_stock_config` | 전역 `US_MOMENTUM_*`만 바꾸고 종목핀 됐다고 말하기 |
| Optuna 탭(전역) | 전역만 | 종목 cfg에 몰래 쓰기 |
| 해외탭 종목 Optuna | 종목 cfg만 | 전역에 적용했다고 말하기 |

- 버튼 문구에 **「전역」/「종목」**을 명시하라. (`봇에 설정저장`처럼 모호한 이름 금지 — 이식·신규 시)
- help 문구·tooltip에 **테이블명**을 적어라.

## 4. 폼 · Optuna · 종목핀 · 백테 소스 오브 트루스

- **웹 백테 = 폼 값.** DB 종목핀을 몰래 덮어쓰지 마라 (`use_stock_cfg` 명시 시에만).
- **폼에 넣기 / 종목행 적용**은 사용자가 고른 후보(보기→선택) 또는 명시된 단축(학습1위)과 **같은 소스**.
- Optuna UI는 국장처럼 **Top5 + 보기 + 골라 적용**이 기본. 단축만 두고 보기 생략 = §A 위반.
- **폼에 넣기 직후 탭 click / 종목 select**가 폼을 DB로 덮으면 **버그**. 이미 활성 탭이면 재클릭 금지.
- upsert 시 Optuna가 안 준 컬럼을 **NULL로 지우지 마라**.

## 5. “고쳤다/같다” 보고 전 최소 검증

1. 해당 탭 **하드 새로고침** (`192.168.0.149:5050` — localhost 금지)
2. **국장 대응 탭과 UI 목록 대조** (빠진 버튼·표·카드가 있으면 미완료 또는 선보고 차이 목록)
3. Optuna → 보기/선택 → 폼/종목행 → 백테 숫자가 **한 세트**로 일치
4. summary: `profit_factor`, `bot_pct`, `daily_avg_pct` + equity/daily/reasons
5. 콘솔 `Uncaught`/`ReferenceError` 없음

하나라도 미확인이면 **안전하다/국내와 동일하다**고 말하지 마라. 잔여 위험을 명시하라.