# INVYONE Studio · Config Panel cp 디자인 마이그레이션

날짜: 2026-04-27
작업자: gbpark
상태: 진행 중 (입력 필드 패널 + 외곽 + 사이트 preset 시스템 정리까지 완료, 추가 패널 미작업)

---

## 0. 배경 / 컨텍스트

- 디자이너 시안: `/Users/gbpark/Downloads/ui_kits/app/cli_export/standalone/`
  - `panel-input-new` (입력 필드)
  - `panel-table-new` (표)
  - `panel-lookup-new` (조회)
  - `_shared/config-panel.css` + `_shared/config-panel-fields.jsx` (CP* 프리미티브 14종)
- 시안의 핵심 컨셉:
  - **3-레벨 분류**: `kind ▸ type ▸ format`
    - kind = 행위 (입력/선택/자동/첨부)
    - type = 저장 모양 (글자/숫자/금액/날짜 등) → DB 컬럼 타입 박힘
    - format = 검증·마스킹·UI variant
  - **헤더 brumb**: `[kind ▸ type ▾]` 클릭 시 type 팝오버
  - **format trigger**: type 안에서 format 동적 변경 (자유/이메일/전화 등)
  - **카드 = 회색 라인 + 작은 폰트(0.55~0.85rem)**, 보라는 active 강조에만
  - 라이트/다크 모두 동작, v5 토큰만 사용

---

## 1. 작업 범위

| 영역 | 파일 | 처리 |
|---|---|---|
| **CP 프리미티브 신설** | `frontend/components/v2/config-panels/_shared/cp/` | 신규 5개 파일 |
| **빌더 입력 필드 본체** | `V2FieldConfigPanel.tsx` (914줄) | cp 패턴으로 재작성 |
| **빌더 외곽 패널** | `V2PropertiesPanel.tsx` (1351줄) | DIMENSIONS/OPTIONS/LABEL/조건부 표시/컴포넌트 스타일 cp 패턴화 |
| **빌더 컴포넌트 스타일 카드** | `StyleEditor.tsx` (테두리/배경/텍스트) | cp 톤 정렬 |
| **빌더 우측 패널 컨테이너** | `ScreenDesigner.tsx` 8772 라인 | 너비 드래그 핸들 + cp 톤 헤더 |
| **빌더 IDE 토큰** | `frontend/styles/builder-ide.css` | 사이트 메인 톤(`220 6%`)으로 정렬 |
| **사이트 컬러 preset** | `frontend/styles/v5-layout.css` 라인 139~167 | shadcn `--primary/--ring/--sidebar-primary/-ring` 도 preset 따라감 |
| (사용 안 됨) | `V2InputConfigPanel.tsx` (832줄) | 잘못 수정한 옛 파일. 폐기 보류 (사용처 없음) |

---

## 2. 만든 / 수정한 파일

### 2.1 신설 (CP 프리미티브)

```
frontend/components/v2/config-panels/_shared/cp/
├── cp.css                # cp 토큰 + 모든 cp-* 클래스 + 외곽 패널 override
├── icons.tsx             # CP_ICONS 12종 SVG (chevron/plus/trash/grip/reset/help/link/dot/code/close/chevRight/alert)
├── CPPrimitives.tsx      # CPSection / CPRow / CPStacked / CPText / CPSelect / CPTextarea
│                         # CPSwitch / CPNumber / CPColor / CPSegment / CPIconBtn
├── CPChrome.tsx          # CPHeader / CPTabs / CPGroup / CPBindChip / CPCrumb / CPFormatTrigger
└── index.ts              # barrel export
```

핵심 import:
```ts
import "./_shared/cp/cp.css";
import { CPSection, CPRow, CPText, CPNumber, CPSwitch, CPGroup, CPCrumb, CPFormatTrigger } from "./_shared/cp";
```

### 2.2 수정

- `frontend/components/v2/config-panels/V2FieldConfigPanel.tsx` — 거의 전부 재작성
- `frontend/components/screen/panels/V2PropertiesPanel.tsx` — 외곽 섹션들 cp 패턴화
- `frontend/components/screen/StyleEditor.tsx` — Collapsible trigger cp 박스 톤
- `frontend/components/screen/ScreenDesigner.tsx` — 우측 패널 너비 state + 드래그 핸들 + 헤더 톤
- `frontend/styles/builder-ide.css` — 빌더 토큰 → 사이트 중성 회색 톤
- `frontend/styles/v5-layout.css` — preset 분기에 shadcn `--primary` / `--ring` 추가

---

## 3. 적용된 디자인 컨셉

### 3.1 cp 토큰 (cp.css 맨 위)

```css
:root {
  --cp-surface:       hsl(var(--card));         /* 카드면 = 사이트 카드 */
  --cp-bg-subtle:     hsl(var(--background));   /* 외곽 = 사이트 background, 더 진함 */
  --cp-surface-hover: hsl(var(--accent));
  --cp-text:          hsl(var(--foreground));
  --cp-text-sec:      hsl(var(--foreground) / 0.78);  /* 라벨 — 밝음 */
  --cp-text-muted:    hsl(var(--foreground) / 0.55);  /* 캡션 — 가독 OK */
  --cp-border:        hsl(var(--border));
  --cp-border-subtle: hsl(var(--foreground) / 0.06);
  --cp-border-strong: hsl(var(--foreground) / 0.18);
}
```

**핵심**: cp 토큰을 직접 hex 가 아닌 사이트 shadcn 토큰의 **alias**.
- 라이트/다크 자동 분기 (사이트 토큰이 분기하니까)
- 메뉴/회사관리/빌더 어디서든 동일 색감
- preset 변경 시도 자동 (사이트 toplevel 토큰이 preset 따라가도록 v5-layout.css 도 손봄 — 3.5 참조)

### 3.2 V2FieldConfigPanel 분류 체계

```
kind = 입력 / 선택  (type 의 group 으로 자동 결정)
type
  입력 : 글자(text) · 숫자(number) · 여러 줄(textarea) · 채번(numbering)
  선택 : 직접 목록(select) · 카테고리(category) · 테이블 참조(entity)
format = text 안에서만 자유/이메일/전화/URL/사업자번호/통화
```

화면 구조:
```
CPCrumb (입력 | 글자 ▾)         ← 좌/우 분할 brumb, 양쪽 클릭 가능
├ CPSection "① 데이터 소속"     ← primary/reference/child + 테이블/컬럼
├ CPSection "② 유형별 설정"     ← CPFormatTrigger + 형식별 동적 옵션
├ CPSection "③ 데이터 필터"     ← entity/category 일 때만
└ CPGroup "고급 설정"           ← 접이식 (선택형: 모드/복수/검색, 입력형: autoGen/마스크)
```

데이터 모델 100% 호환 — 기존 config (`fieldType, source, dataRole, options, autoGeneration` 등) 그대로 사용. `resolveFieldType()` 로 추론 + `handleFieldTypeChange()` 로 전환 시 source/inputType 동시 갱신.

### 3.3 V2PropertiesPanel 외곽 cp 패턴

**위에서 아래로 같은 그리드** (`80px 라벨 ｜ 1fr 컨트롤`):

| 섹션 | cp 컴포넌트 |
|---|---|
| 크기 | `CPSection` + `CPRow × 3` (너비/높이/Z-Index) |
| 내용 (group/area) | `CPSection` + `CPRow × 2` (제목/설명) |
| 옵션 | `CPSection` + `CPRow + CPSwitch × 3` (필수/읽기/숨김) |
| 라벨 | `CPGroup` 접이 + `CPRow × 7` (텍스트/위치/간격/크기/색상/굵기/표시) |
| 조건부 표시 | `CPGroup` 접이 + ConditionalConfigPanel |
| 컴포넌트 스타일 | `CPGroup` 접이 + StyleEditor (안의 테두리/배경/텍스트도 cp 박스 톤) |

영문 헤더 → 한글 (DIMENSIONS→크기, OPTIONS→옵션, LABEL→라벨, CONTENT→내용).

### 3.4 빌더 토큰 정렬 (builder-ide.css)

기존 빌더는 `240 13%` 보라/파랑 tint 토큰 사용 → 메뉴·회사관리(`220 6%` 중성 회색)와 다른 톤.

수정:
- `.ide-builder` 의 `--background / --card / --foreground / --border / --accent / --muted / --secondary / --sidebar-*` 모두 사이트 중성 톤으로 정렬
- `--primary / --ring / --sidebar-primary / --sidebar-ring` 정의 **삭제** → 사이트 `:root` 토큰 자동 상속

### 3.5 사이트 preset 시스템 확장 (v5-layout.css)

기존 — preset 변경 시 `--v5-primary-rgb` 만 바뀜. shadcn `--primary` 는 라이트/다크 보라 고정.

추가 — 6개 preset (`purple/blue/green/orange/pink/cyan`) 라이트/다크 분기에 모두 다음 토큰 같이 정의:
```css
html[data-color="orange"]{
  --v5-primary-rgb:249,115,22; ...
  --primary:25 95% 53%;
  --ring:25 95% 53%;
  --sidebar-primary:25 95% 53%;
  --sidebar-ring:25 95% 53%;
}
```

→ 이제 preset 변경 시 **사이트 전체** (메뉴/회사관리/빌더의 검색 버튼·탭·input focus·라디오·체크) 가 그 색으로 통일.

### 3.6 우측 패널 너비 드래그 핸들 (ScreenDesigner.tsx)

```
좌측 모서리 4px 핸들
├ drag → 240~600px 범위 너비 조절
├ 더블클릭 → 320px 리셋
└ localStorage `inv-right-panel-width` 자동 저장
```

---

## 4. 알려진 버그 / 함정 (다음 작업자 주의)

### 4.1 V2InputConfigPanel.tsx 는 사용 안 됨

- `frontend/components/v2/registerV2Components.ts` 에 등록되어 있지만 실제 빌더가 쓰는 registry (`lib/registry/components/v2-input/index.ts`) 는 `V2FieldConfigPanel` 을 가리킴
- 처음에 잘못 V2InputConfigPanel 을 cp 패턴으로 재작성했는데 화면 변화 없어 한참 헤맸음
- 폐기할지 보류 — 시그니처/매핑 함수 일부는 향후 단독 입력 패널에 재활용 가능

### 4.2 cp-pop 위치 — overflow:hidden 에 잘림

- `cp-crumb-split` 가 `overflow: hidden` 라 그 안에 absolute 떨어지는 팝오버는 잘림
- 해결: CPCrumb 의 jsx 에서 cp-pop 을 cp-bar 직속으로 (split 박스 밖) 이동
- 추가로 V2FieldConfigPanel wrapper 에서도 `overflow: hidden` 제거함

### 4.3 V2PropertiesPanel 안 `bg-white` 박힌 곳

- 라인 170, 1180 에 `bg-white` 가 박혀있어 다크 모드 cp 톤을 덮음
- 둘 다 제거함 (`flex h-full flex-col`)

### 4.4 빌더 외곽 톤 ≠ 패널 톤 우려

- 우측 패널 `inv-right-panel` 배경 = `cp-bg-subtle` (사이트 background, 검정)
- 안의 카드 (cp-crumb-split, input) = `cp-surface` (사이트 card, 약간 밝음)
- → 카드가 살짝 떠 보이는 입체감
- 배경 차이가 너무 약하면 사용자가 "구분 안 된다" 할 수 있으니 주의

---

## 5. 미완료 / 다음 작업 후보

### 5.1 다른 V2 패널 cp 마이그레이션 (시안의 표/조회 적용)

`components/v2/config-panels/` 에 40개 V2 패널 더 있음. 사용 빈도 높은 것부터:
- `V2TableListConfigPanel.tsx` (1497줄) — 시안 `panel-table-new` 컨셉 적용 가능
- `V2SelectConfigPanel.tsx` (847줄) — 입력에서 분리된 옛 패널 (V2FieldConfigPanel 이 이미 흡수했지만 여전히 등록되어 있을 수 있음 — 확인 필요)
- `V2DateConfigPanel.tsx` 등 type 별 패널 — 단일 패널 (V2FieldConfigPanel) 로 통합할지 결정

### 5.2 시안의 lookup (조회) 패턴 도입

시안 `panel-lookup-new` 의 핵심 = "③ 결과 매핑" (M21 다컬럼 매핑). 본 프로젝트 `V2SelectConfigPanel.tsx` 또는 새 `entity` type 안에 적용.

### 5.3 V2InputConfigPanel.tsx 처리

- 옵션 A: 폐기 (rm)
- 옵션 B: 그대로 두기
- 옵션 C: registerV2Components.ts 에서 V2FieldConfigPanel 로 교체

### 5.4 입력 필드 `format` 확장

현재 V2FieldConfigPanel 의 text format 은 6개 (자유/이메일/전화/URL/사업자번호/통화). 시안의 V2InputConfigPanel 에는 7개 (+ 마스킹, 여러 줄). textarea 는 별도 type. 통합/분리 전략 재검토 가능.

### 5.5 한 번에 더 많은 검증

- 라이트/다크 둘 다 빌더 + 메뉴/회사관리에서 시각 검증
- 6개 preset (purple/blue/green/orange/pink/cyan) 모두 회사관리·빌더 검색 버튼 색이 정확히 따라가는지
- 빌더에서 입력 필드 외 컴포넌트 (버튼, 테이블, 셀렉트 등) 클릭 시 패널이 cp 톤으로 잘 그려지는지

---

## 6. 검증 방법

```bash
cd frontend && npx tsc --noEmit 2>&1 | grep -E "v2/config-panels/(_shared|V2Field|V2Input)|V2PropertiesPanel|StyleEditor"
```
- 우리 파일 에러 = 0 이어야 함
- 다른 파일 에러는 기존부터 있던 것 (test-scenarios, ddl.ts, ButtonConfigPanel-fixed 등) → 무시

브라우저 검증:
1. `https://localhost:9772/admin/builder` 또는 화면관리 → 템플릿 편집
2. 컴포넌트 (입력 필드) 클릭 → 우측 패널 cp 톤으로 뜨는지
3. brumb 좌측 "입력/선택" 클릭 → kind 팝오버
4. brumb 우측 "글자 ▾" 클릭 → type 팝오버
5. 형식 trigger 클릭 → format 팝오버 (글자 type 일 때만)
6. 데이터 소속 segment (주/참조/하위) 작동 확인
7. 우측 패널 좌측 모서리 hover → ew-resize 커서, 드래그로 너비 조절
8. 우상단 Tweaks → 컬러 preset 변경 → 전체 사이트 색 통일 확인 (검색 버튼 등)
9. 라이트/다크 토글 둘 다 자연스러운지

---

## 7. 관련 파일 맵 (다음 세션이 빠르게 컨텍스트 잡기)

```
[디자인 시안 — 읽기 전용 참고]
~/Downloads/ui_kits/app/cli_export/standalone/
├── _shared/config-panel.css
├── _shared/config-panel-fields.jsx     ← CP* 프리미티브 14종 원본
├── panel-input-new.{html,jsx}          ← 입력 패널 시안
├── panel-table-new.{html,jsx}          ← 표 패널 시안 (다음 작업)
└── panel-lookup-new.{html,jsx}         ← 조회 패널 시안 (다음 작업)

[프로젝트 — 작업 산출물]
frontend/components/v2/config-panels/
├── _shared/cp/                         ← 신설
│   ├── cp.css                          ← cp 토큰 + 외곽 패널 override
│   ├── icons.tsx
│   ├── CPPrimitives.tsx
│   ├── CPChrome.tsx
│   └── index.ts
├── V2FieldConfigPanel.tsx              ← 본체 (입력+선택 통합)
├── V2InputConfigPanel.tsx              ← 사용 안 됨, 폐기 보류
└── (V2TableListConfigPanel.tsx 등 39개 — 미작업)

frontend/components/screen/
├── panels/V2PropertiesPanel.tsx        ← 외곽 (DIMENSIONS/OPTIONS/LABEL 등)
├── StyleEditor.tsx                     ← 컴포넌트 스타일 (테두리/배경/텍스트)
└── ScreenDesigner.tsx                  ← 빌더 셸 + 우측 패널 wrap + 너비 드래그

frontend/styles/
├── builder-ide.css                     ← 빌더 토큰 (사이트 중성 톤으로 정렬)
└── v5-layout.css                       ← v5 토큰 + preset 분기 (shadcn --primary 도 preset 따라감)

frontend/lib/registry/components/v2-input/index.ts
└── config_panel: V2FieldConfigPanel    ← 빌더가 실제 쓰는 등록처 (기억해둘 것)
```
