docs: user-mail PCC 및 체크리스트 작성 (IMAP 기능 완료 반영)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
syc0123
@@ -0,0 +1,389 @@
|
||||
# [계획서] 버튼 아이콘화 - 화면 디자이너 버튼 표시 모드 확장
|
||||
|
||||
> 관련 문서: [맥락노트](./BIC[맥락]-버튼-아이콘화.md) | [체크리스트](./BIC[체크]-버튼-아이콘화.md)
|
||||
|
||||
## 개요
|
||||
|
||||
화면 디자이너에서 버튼을 텍스트 모드(현행), 아이콘 모드, 아이콘+텍스트 모드 중 선택할 수 있도록 확장한다.
|
||||
아이콘 모드 선택 시 버튼 액션에 맞는 아이콘 후보군이 제시되고, 관리자가 원하는 아이콘을 선택한다.
|
||||
아이콘 크기 비율(버튼 높이 대비 4단계 프리셋), 아이콘 색상, 텍스트 위치(4방향), 아이콘-텍스트 간격 설정을 제공한다.
|
||||
관리자가 lucide 검색 또는 외부 SVG 붙여넣기로 커스텀 아이콘을 추가/삭제할 수 있다.
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
- 버튼은 항상 **텍스트 모드**로만 표시됨
|
||||
- `ButtonConfigPanel.tsx`에서 "버튼 텍스트" 입력 → 실제 화면에서 해당 텍스트가 버튼에 표시
|
||||
- 아이콘 표시 기능 없음
|
||||
|
||||
### 현재 코드 위치
|
||||
|
||||
| 구분 | 파일 | 설명 |
|
||||
|------|------|------|
|
||||
| 설정 패널 | `frontend/components/screen/config-panels/ButtonConfigPanel.tsx` | 버튼 텍스트, 액션 설정 (784~854행) |
|
||||
| 뷰어 렌더링 | `frontend/components/screen/InteractiveScreenViewerDynamic.tsx` | 실제 버튼 렌더링 (961~983행) |
|
||||
| 뷰어 렌더링 | `frontend/components/screen/InteractiveScreenViewer.tsx` | 실제 버튼 렌더링 (2041~2059행) |
|
||||
| 위젯 렌더링 | `frontend/components/screen/widgets/types/ButtonWidget.tsx` | 위젯 기반 버튼 렌더링 (67~86행) |
|
||||
| 최적화 컴포넌트 | `frontend/components/screen/OptimizedButtonComponent.tsx` | 최적화된 버튼 컴포넌트 (643~674행) |
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 1. 표시 모드 선택 (라디오 그룹)
|
||||
|
||||
ButtonConfigPanel에 "버튼 텍스트" 입력 위에 표시 모드 선택 UI 추가:
|
||||
|
||||
- **텍스트 모드** (기본값, 현행 유지): 버튼에 텍스트만 표시
|
||||
- **아이콘 모드**: 버튼에 아이콘만 표시
|
||||
- **아이콘+텍스트 모드**: 버튼에 아이콘과 텍스트를 함께 표시
|
||||
|
||||
```
|
||||
[ 텍스트 | 아이콘 | 아이콘+텍스트 ] ← 라디오 그룹 (토글 형태)
|
||||
```
|
||||
|
||||
### 2. 텍스트 모드 선택 시
|
||||
|
||||
- 현재와 동일하게 "버튼 텍스트" 입력 필드 표시
|
||||
- 변경 사항 없음
|
||||
|
||||
### 2-1. 아이콘+텍스트 모드 선택 시
|
||||
|
||||
- 아이콘 선택 UI (3장과 동일) + 버튼 텍스트 입력 필드 **둘 다 표시**
|
||||
- 렌더링: 텍스트 위치에 따라 아이콘과 텍스트 배치 방향이 달라짐
|
||||
- 텍스트 위치 4방향: 오른쪽(기본), 왼쪽, 위쪽, 아래쪽
|
||||
- 예시: `[ ✓ 저장 ]` (오른쪽), `[ 저장 ✓ ]` (왼쪽), 세로 배치 (위쪽/아래쪽)
|
||||
- 아이콘과 텍스트 사이 간격: 기본 6px, 관리자가 0~무제한 조절 가능 (슬라이더 0~32px + 직접 입력)
|
||||
|
||||
### 3. 아이콘 모드 선택 시
|
||||
|
||||
#### 3-1. 버튼 액션별 추천 아이콘 목록
|
||||
|
||||
버튼 액션(`action.type`)에 따라 해당 액션에 어울리는 아이콘 후보군을 그리드로 표시:
|
||||
|
||||
| 버튼 액션 | 값 | 추천 아이콘 (lucide-react) |
|
||||
|-----------|-----|---------------------------|
|
||||
| 저장 | `save` | Check, Save, CheckCircle, CircleCheck, FileCheck, ShieldCheck |
|
||||
| 삭제 | `delete` | Trash2, Trash, XCircle, X, Eraser, CircleX |
|
||||
| 편집 | `edit` | Pencil, PenLine, Edit, SquarePen, FilePen, PenTool |
|
||||
| 페이지 이동 | `navigate` | ArrowRight, ExternalLink, MoveRight, Navigation, CornerUpRight, Link |
|
||||
| 모달 열기 | `modal` | Maximize2, PanelTop, AppWindow, LayoutGrid, Layers, FolderOpen |
|
||||
| 데이터 전달 | `transferData` | SendHorizontal, ArrowRightLeft, Repeat, PackageCheck, Upload, Share2 |
|
||||
| 엑셀 다운로드 | `excel_download` | Download, FileDown, FileSpreadsheet, Sheet, Table, FileOutput |
|
||||
| 엑셀 업로드 | `excel_upload` | Upload, FileUp, FileSpreadsheet, Sheet, ImportIcon, FileInput |
|
||||
| 즉시 저장 | `quickInsert` | Zap, Plus, PlusCircle, SquarePlus, FilePlus, BadgePlus |
|
||||
| 제어 흐름 | `control` | Settings, SlidersHorizontal, ToggleLeft, Workflow, GitBranch, Cog |
|
||||
| 바코드 스캔 | `barcode_scan` | ScanLine, QrCode, Camera, Scan, ScanBarcode, Focus |
|
||||
| 운행알림 및 종료 | `operation_control` | Truck, Car, MapPin, Navigation2, Route, Bell |
|
||||
| 이벤트 발송 | `event` | Send, Bell, Radio, Megaphone, Podcast, BellRing |
|
||||
| 복사 | `copy` | Copy, ClipboardCopy, Files, CopyPlus, Duplicate, ClipboardList |
|
||||
|
||||
**적절한 아이콘이 없는 액션 (숨김 처리된 deprecated 액션들):**
|
||||
|
||||
| 버튼 액션 | 값 | 안내 문구 |
|
||||
|-----------|-----|----------|
|
||||
| 연관 데이터 버튼 모달 열기 | `openRelatedModal` | 안내 문구 표시 + 커스텀 아이콘 추가 가능 |
|
||||
| (deprecated) 데이터 전달 + 모달 | `openModalWithData` | 안내 문구 표시 + 커스텀 아이콘 추가 가능 |
|
||||
| 테이블 이력 보기 | `view_table_history` | 안내 문구 표시 + 커스텀 아이콘 추가 가능 |
|
||||
| 코드 병합 | `code_merge` | 안내 문구 표시 + 커스텀 아이콘 추가 가능 |
|
||||
| 공차등록 | `empty_vehicle` | 안내 문구 표시 + 커스텀 아이콘 추가 가능 |
|
||||
|
||||
> 안내 문구: "적절한 추천 아이콘이 없습니다. 텍스트 모드를 사용하거나 아래에서 아이콘을 직접 추가하세요."
|
||||
> 안내 문구 아래에 커스텀 아이콘 목록 + lucide 검색/SVG 붙여넣기 버튼이 표시됨
|
||||
|
||||
#### 3-2. 아이콘 선택 UI
|
||||
|
||||
- 액션별 추천 아이콘을 4~6열 그리드로 표시
|
||||
- 각 아이콘은 32x32 크기, 호버 시 하이라이트, 선택 시 ring 표시
|
||||
- 아이콘 아래에 이름 표시 (`text-[10px]`)
|
||||
- 관리자가 추가한 커스텀 아이콘이 있으면 "커스텀 아이콘" 구분선 아래 함께 표시
|
||||
|
||||
#### 3-3. 아이콘 크기 비율 설정
|
||||
|
||||
버튼 높이 대비 비율로 아이콘 크기를 설정 (정사각형 유지):
|
||||
|
||||
**프리셋 (ToggleGroup, 4단계):**
|
||||
|
||||
| 이름 | 버튼 높이 대비 | 설명 |
|
||||
|------|--------------|------|
|
||||
| 작게 | 40% | 컴팩트한 아이콘 |
|
||||
| 보통 | 55% | 기본값, 대부분의 버튼에 적합 |
|
||||
| 크게 | 70% | 존재감 있는 크기 |
|
||||
| 매우 크게 | 85% | 아이콘 강조, 버튼에 꽉 차는 느낌 |
|
||||
|
||||
- px 직접 입력은 제거 (비율 기반이므로 버튼 크기 변경 시 아이콘도 자동 비례)
|
||||
- 저장: `icon.size`에 프리셋 문자열(`"보통"`) 저장
|
||||
- 렌더링: `height: N%` + `aspect-ratio: 1/1`로 정사각형 유지
|
||||
|
||||
#### 3-4. 아이콘 색상 설정
|
||||
|
||||
아이콘 크기 아래에 아이콘 전용 색상 설정:
|
||||
|
||||
- **컬러 피커**: 기존 버튼 색상 설정과 동일한 UI 사용
|
||||
- **기본값**: 미설정 (= `textColor` 상속, 기존 동작과 동일)
|
||||
- **설정 시**: lucide 아이콘은 지정한 색상으로 덮어쓰기
|
||||
- **외부 SVG**: 고유 색상이 하드코딩된 SVG는 이 설정의 영향을 받지 않음 (원본 유지)
|
||||
- **초기화 버튼**: "텍스트 색상과 동일" 버튼으로 별도 색상 해제 가능
|
||||
|
||||
| 상황 | iconColor 설정 | 결과 |
|
||||
|------|---------------|------|
|
||||
| lucide 아이콘, iconColor 미설정 | 없음 | textColor 상속 (기존 동작) |
|
||||
| lucide 아이콘, iconColor 설정 | `#22c55e` | 초록색 아이콘 |
|
||||
| 외부 SVG (고유 색상), iconColor 설정 | `#22c55e` | SVG 원본 색상 유지 (무시) |
|
||||
| 외부 SVG (currentColor), iconColor 설정 | `#22c55e` | 초록색 아이콘 |
|
||||
|
||||
#### 3-5. 텍스트 위치 설정 (아이콘+텍스트 모드 전용)
|
||||
|
||||
아이콘 대비 텍스트의 배치 방향을 4방향으로 설정:
|
||||
|
||||
| 위치 | 값 | 레이아웃 | 설명 |
|
||||
|------|-----|---------|------|
|
||||
| 왼쪽 | `left` | `텍스트 ← 아이콘` | 텍스트가 아이콘 왼쪽 (가로) |
|
||||
| 오른쪽 | `right` | `아이콘 → 텍스트` | 기본값, 아이콘 뒤에 텍스트 (가로) |
|
||||
| 위쪽 | `top` | 텍스트 위, 아이콘 아래 | 세로 배치 |
|
||||
| 아래쪽 | `bottom` | 아이콘 위, 텍스트 아래 | 세로 배치 |
|
||||
|
||||
- 기본값: `"right"` (아이콘 오른쪽에 텍스트)
|
||||
- 저장: `componentConfig.iconTextPosition`
|
||||
- 아이콘 모드에서는 이 옵션이 숨겨짐 (텍스트가 없으므로 불필요)
|
||||
|
||||
#### 3-6. 아이콘-텍스트 간격 설정 (아이콘+텍스트 모드 전용)
|
||||
|
||||
아이콘+텍스트 모드에서 아이콘과 텍스트 사이 간격을 조절:
|
||||
|
||||
- **슬라이더**: 0~32px 범위 시각적 조절
|
||||
- **직접 입력**: px 수치 직접 입력 (최솟값 0, 최댓값 제한 없음)
|
||||
- **기본값**: 6px
|
||||
- 아이콘 모드에서는 이 옵션이 숨겨짐 (텍스트가 없으므로 불필요)
|
||||
|
||||
#### 3-7. 아이콘 모드 레이아웃 안내
|
||||
|
||||
아이콘만 표시하면 텍스트보다 좁은 공간으로 충분하므로 안내 문구 표시:
|
||||
|
||||
```
|
||||
ℹ 아이콘만 표시할 때는 버튼 영역의 가로 폭을 줄여 정사각형에 가깝게 만들면 더 깔끔합니다.
|
||||
```
|
||||
|
||||
- `bg-blue-50 dark:bg-blue-950/20` 배경의 안내 박스
|
||||
- 아이콘 모드(`"icon"`)에서만 표시, 아이콘+텍스트 모드에서는 숨김
|
||||
|
||||
#### 3-8. 디폴트 아이콘 자동 부여
|
||||
|
||||
아이콘/아이콘+텍스트 모드 전환 시 아이콘이 미선택 상태이면 **디폴트 아이콘을 자동으로 부여**한다.
|
||||
|
||||
| 상황 | 디폴트 아이콘 |
|
||||
|------|-------------|
|
||||
| 추천 아이콘이 있는 액션 (save, delete 등) | 해당 액션의 **첫 번째 추천 아이콘** (예: save → Check) |
|
||||
| 추천 아이콘이 없는 액션 (deprecated 등) | 범용 폴백 아이콘: `SquareMousePointer` |
|
||||
|
||||
**커스텀 아이콘 삭제 시:**
|
||||
- 현재 선택된 커스텀 아이콘을 삭제하면 **디폴트 아이콘으로 자동 복귀** (텍스트 모드로 빠지지 않음)
|
||||
- 아이콘 모드를 유지한 채 디폴트 아이콘이 캔버스에 즉시 반영됨
|
||||
|
||||
#### 3-9. 커스텀 아이콘 추가/삭제
|
||||
|
||||
**방법 1: lucide 아이콘 검색으로 추가**
|
||||
- "아이콘 추가" 버튼 클릭 시 lucide 아이콘 전체 검색 가능한 모달/팝오버 표시
|
||||
- 검색 입력 → 아이콘 이름으로 필터링 → 선택하면 커스텀 목록에 추가
|
||||
|
||||
**방법 2: 외부 SVG 붙여넣기로 추가**
|
||||
- "SVG 붙여넣기" 버튼 클릭 시 텍스트 입력 영역(textarea) 표시
|
||||
- 외부에서 복사한 SVG 코드를 붙여넣기 → 미리보기로 확인 → "추가" 버튼으로 등록
|
||||
- SVG 유효성 검사: `<svg` 태그가 포함된 올바른 SVG인지 확인, 아니면 에러 메시지
|
||||
- 추가 시 관리자가 아이콘 이름을 직접 입력 (목록에서 구분용)
|
||||
- 저장 형태: SVG 문자열을 `customSvgIcons` 배열에 `{ name, svg }` 객체로 저장
|
||||
|
||||
**공통 규칙:**
|
||||
- 추가된 커스텀 아이콘(lucide/SVG 모두)은 **모든 버튼 액션의 아이콘 후보에 공통으로 노출**
|
||||
- 커스텀 아이콘에 X 버튼으로 삭제 가능
|
||||
|
||||
---
|
||||
|
||||
## 데이터 구조
|
||||
|
||||
### componentConfig 확장
|
||||
|
||||
```typescript
|
||||
interface ButtonComponentConfig {
|
||||
text: string; // 기존: 버튼 텍스트
|
||||
displayMode: "text" | "icon" | "icon-text"; // 신규: 표시 모드 (기본값: "text")
|
||||
icon?: {
|
||||
name: string; // lucide 아이콘 이름 또는 커스텀 SVG 아이콘 이름
|
||||
type: "lucide" | "svg"; // 아이콘 출처 구분 (기본값: "lucide")
|
||||
size: "작게" | "보통" | "크게" | "매우 크게"; // 버튼 높이 대비 비율 프리셋 (기본값: "보통")
|
||||
color?: string; // 아이콘 색상 (미설정 시 textColor 상속)
|
||||
};
|
||||
iconGap?: number; // 아이콘-텍스트 간격 px (기본값: 6, 아이콘+텍스트 모드 전용)
|
||||
iconTextPosition?: "right" | "left" | "top" | "bottom"; // 텍스트 위치 (기본값: "right", 아이콘+텍스트 모드 전용)
|
||||
customIcons?: string[]; // 관리자가 추가한 lucide 커스텀 아이콘 이름 목록
|
||||
customSvgIcons?: Array<{ // 관리자가 붙여넣기한 외부 SVG 아이콘 목록
|
||||
name: string; // 관리자가 지정한 아이콘 이름
|
||||
svg: string; // SVG 문자열 원본
|
||||
}>;
|
||||
action: {
|
||||
type: string; // 기존: 버튼 액션 타입
|
||||
// ...기존 action 속성들 유지
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 저장 예시
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "저장",
|
||||
"displayMode": "icon",
|
||||
"icon": {
|
||||
"name": "Check",
|
||||
"type": "lucide",
|
||||
"size": "보통",
|
||||
"color": "#22c55e"
|
||||
},
|
||||
"customIcons": ["Rocket", "Star"],
|
||||
"customSvgIcons": [
|
||||
{
|
||||
"name": "회사로고",
|
||||
"svg": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'>...</svg>"
|
||||
}
|
||||
],
|
||||
"action": {
|
||||
"type": "save"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 시각적 동작 예시
|
||||
|
||||
### ButtonConfigPanel (디자이너 편집 모드)
|
||||
|
||||
```
|
||||
표시 모드: [ 텍스트 | (아이콘) | 아이콘+텍스트 ] ← 아이콘 선택됨
|
||||
|
||||
아이콘 선택:
|
||||
┌──────────────────────────────────┐
|
||||
│ 추천 아이콘 (저장) │
|
||||
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
|
||||
│ │ ✓ │ │ 💾 │ │ ✓○ │ │ ○✓ │ │
|
||||
│ │Check│ │Save│ │Chk○│ │○Chk│ │
|
||||
│ └────┘ └────┘ └────┘ └────┘ │
|
||||
│ ┌────┐ ┌────┐ │
|
||||
│ │📄✓│ │🛡✓│ │
|
||||
│ │FChk│ │ShCk│ │
|
||||
│ └────┘ └────┘ │
|
||||
│ │
|
||||
│ ── 커스텀 아이콘 ── │
|
||||
│ ┌────┐ ┌────┐ ┌────┐ │
|
||||
│ │ 🚀 │ │ ⭐ │ │[로고]│ │
|
||||
│ │Rckt │ │Star│ │회사 │ │
|
||||
│ │ ✕ │ │ ✕│ │ ✕ │ │
|
||||
│ └────┘ └────┘ └────┘ │
|
||||
│ [+ lucide 검색] [+ SVG 붙여넣기]│
|
||||
└──────────────────────────────────┘
|
||||
|
||||
아이콘 크기 비율: [ 작게 | (보통) | 크게 | 매우 크게 ]
|
||||
텍스트 위치: [ 왼쪽 | (오른쪽) | 위쪽 | 아래쪽 ] ← 아이콘+텍스트 모드에서만 표시
|
||||
아이콘-텍스트 간격: [━━━━━○━━] [6] px ← 아이콘+텍스트 모드에서만 표시
|
||||
아이콘 색상: [■ #22c55e] [텍스트 색상과 동일]
|
||||
|
||||
ℹ 아이콘만 표시할 때는 버튼 영역의 가로 폭을 줄여 정사각형에 가깝게 만들면 더 깔끔합니다.
|
||||
```
|
||||
|
||||
### 실제 화면 렌더링
|
||||
|
||||
| 모드 | 표시 |
|
||||
|------|------|
|
||||
| 텍스트 모드 | `[ 저장 ]` |
|
||||
| 아이콘 모드 (보통, 55%) | `[ ✓ ]` |
|
||||
| 아이콘 모드 (매우 크게, 85%) | `[ ✓ ]` |
|
||||
| 아이콘+텍스트 (텍스트 오른쪽) | `[ ✓ 저장 ]` (간격 6px) |
|
||||
| 아이콘+텍스트 (텍스트 왼쪽) | `[ 저장 ✓ ]` |
|
||||
| 아이콘+텍스트 (텍스트 아래쪽) | 아이콘 위, 텍스트 아래 (세로) |
|
||||
| 아이콘+텍스트 (색상 분리) | `[ 초록✓ 검정저장 ]` |
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상
|
||||
|
||||
### 수정 파일
|
||||
|
||||
| 파일 | 변경 내용 |
|
||||
|------|----------|
|
||||
| `ButtonConfigPanel.tsx` | 표시 모드 3종 라디오, 아이콘 그리드, 크기, 색상, 간격 설정, 레이아웃 안내, 커스텀 아이콘 UI |
|
||||
| `InteractiveScreenViewerDynamic.tsx` | `displayMode` 3종 분기 → 아이콘/아이콘+텍스트/텍스트 렌더링 |
|
||||
| `InteractiveScreenViewer.tsx` | 동일 분기 추가 |
|
||||
| `ButtonWidget.tsx` | 동일 분기 추가 |
|
||||
| `OptimizedButtonComponent.tsx` | 동일 분기 추가 |
|
||||
| `ScreenDesigner.tsx` | 입력 필드 포커스 시 키보드 단축키 기본 동작 허용 (Ctrl+A/C/V/Z) |
|
||||
| `RealtimePreviewDynamic.tsx` | 버튼 컴포넌트 position wrapper에서 border 속성 분리 (이중 테두리 방지) |
|
||||
|
||||
### 신규 파일
|
||||
|
||||
| 파일 | 내용 |
|
||||
|------|------|
|
||||
| `frontend/lib/button-icon-map.tsx` | 버튼 액션별 추천 아이콘 매핑 + 아이콘 동적 렌더링 유틸 |
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- 기본값은 `"text"` 모드 → 기존 모든 버튼은 변경 없이 동작
|
||||
- `displayMode`가 없거나 `"text"`이면 현행 텍스트 렌더링 유지
|
||||
- 아이콘/아이콘+텍스트 모드 전환 시 아이콘 미선택이면 **디폴트 아이콘 자동 부여** (빈 상태 방지)
|
||||
- 커스텀 아이콘 삭제 시 텍스트 모드로 빠지지 않고 **디폴트 아이콘으로 자동 복귀**
|
||||
- 아이콘 모드에서도 `text` 값은 유지 (접근성 aria-label로 활용)
|
||||
- 기본 아이콘은 lucide-react 사용 (프로젝트 일관성)
|
||||
- 외부 SVG 붙여넣기도 지원 → 관리자가 회사 로고 등 자체 아이콘을 등록 가능
|
||||
- lucide 커스텀 아이콘은 `componentConfig.customIcons`에, SVG 아이콘은 `componentConfig.customSvgIcons`에 저장
|
||||
- lucide 아이콘 렌더링: 아이콘 이름 → 컴포넌트 매핑, SVG 아이콘 렌더링: `dangerouslySetInnerHTML` + DOMPurify 정화
|
||||
- **동적 아이콘 로딩**: `iconMap`에 명시적으로 import되지 않은 lucide 아이콘도 `getLucideIcon()` 호출 시 `lucide-react`의 전체 아이콘(`icons`)에서 자동 조회 후 캐싱 → 화면 관리에서 선택한 모든 lucide 아이콘이 실제 화면에서도 렌더링됨
|
||||
- **커스텀 아이콘 전역 관리 (미구현)**: 커스텀 아이콘을 버튼별(`componentConfig`)이 아닌 시스템 전역(`custom_icon_registry` 테이블)으로 관리하여, 한번 추가한 커스텀 아이콘이 모든 화면의 모든 버튼에서 사용 가능하도록 확장 예정
|
||||
|
||||
---
|
||||
|
||||
## [미구현] 커스텀 아이콘 전역 관리
|
||||
|
||||
### 현재 문제
|
||||
|
||||
- 커스텀 아이콘이 `componentConfig.customIcons`에 저장 → **해당 버튼에서만** 보임
|
||||
- 저장1 버튼에 추가한 커스텀 아이콘이 저장2 버튼, 다른 화면에서는 안 보임
|
||||
- 같은 아이콘을 쓰려면 매번 검색해서 다시 추가해야 함
|
||||
|
||||
### 변경 후 동작
|
||||
|
||||
- 커스텀 아이콘을 **회사(company_code) 단위 전역**으로 관리
|
||||
- 어떤 화면의 어떤 버튼에서든 커스텀 아이콘 추가 → 모든 화면의 모든 버튼에서 커스텀란에 표시
|
||||
- 버튼 액션 종류와 무관하게 모든 커스텀 아이콘이 노출
|
||||
|
||||
### DB 테이블 (신규)
|
||||
|
||||
```sql
|
||||
CREATE TABLE custom_icon_registry (
|
||||
id VARCHAR(500) PRIMARY KEY DEFAULT gen_random_uuid()::text,
|
||||
company_code VARCHAR(500) NOT NULL,
|
||||
icon_name VARCHAR(500) NOT NULL,
|
||||
icon_type VARCHAR(500) DEFAULT 'lucide', -- 'lucide' | 'svg'
|
||||
svg_data TEXT, -- SVG일 경우 원본 데이터
|
||||
created_date TIMESTAMP DEFAULT now(),
|
||||
updated_date TIMESTAMP DEFAULT now(),
|
||||
writer VARCHAR(500)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_custom_icon_registry_company ON custom_icon_registry(company_code);
|
||||
```
|
||||
|
||||
### 백엔드 API (신규)
|
||||
|
||||
| 메서드 | 경로 | 설명 |
|
||||
|--------|------|------|
|
||||
| GET | `/api/custom-icons` | 커스텀 아이콘 목록 조회 (company_code 필터) |
|
||||
| POST | `/api/custom-icons` | 커스텀 아이콘 추가 |
|
||||
| DELETE | `/api/custom-icons/:id` | 커스텀 아이콘 삭제 |
|
||||
|
||||
### 프론트엔드 변경
|
||||
|
||||
- `ButtonConfigPanel` — 커스텀 아이콘 조회/추가/삭제를 API 호출로 변경
|
||||
- 기존 `componentConfig.customIcons` 데이터는 하위 호환으로 병합 표시 (점진적 마이그레이션)
|
||||
- `componentConfig.customSvgIcons`도 동일하게 전역 테이블로 이관
|
||||
@@ -0,0 +1,283 @@
|
||||
# [맥락노트] 버튼 아이콘화 - 화면 디자이너 버튼 표시 모드 확장
|
||||
|
||||
> 관련 문서: [계획서](./BIC[계획]-버튼-아이콘화.md) | [체크리스트](./BIC[체크]-버튼-아이콘화.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 현재 모든 버튼은 텍스트로만 표시 → 버튼 영역이 넓어야 하고, 모바일/태블릿에서 공간 효율이 낮음
|
||||
- "저장", "삭제", "추가" 같은 자주 쓰는 버튼은 아이콘만으로 충분히 인식 가능
|
||||
- 관리자가 화면 레이아웃을 더 컴팩트하게 구성할 수 있도록 선택권 제공
|
||||
- 단, "출하 계획" 같이 아이콘화가 어려운 특수 버튼이 존재하므로 텍스트 모드도 반드시 유지
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 표시 모드는 3종 라디오 그룹(토글 형태)으로 구현
|
||||
|
||||
- **결정**: `ToggleGroup` 형태의 세 개 옵션 (텍스트 / 아이콘 / 아이콘+텍스트)
|
||||
- **근거**: 세 모드는 상호 배타적. 아이콘+텍스트 병합 모드가 있어야 `[ + 추가 ]`, `[ 💾 저장 ]` 같은 실무 패턴을 지원. 아이콘만으로 의미 전달이 부족한 경우 텍스트를 병기하면 사용자 인식 속도가 빨라짐
|
||||
- **대안 검토**: Switch(토글) → 기각 ("무엇이 켜지는지" 직관적이지 않음, 3종 불가)
|
||||
|
||||
### 2. 기본값은 텍스트 모드
|
||||
|
||||
- **결정**: `displayMode` 기본값 = `"text"`
|
||||
- **근거**: 기존 모든 버튼은 텍스트로 동작 중. 아이콘 모드는 명시적으로 선택해야만 적용되어야 하위 호환성이 보장됨
|
||||
- **중요**: `displayMode`가 `undefined`이거나 `"text"`이면 현행 동작 그대로 유지
|
||||
|
||||
### 3. 아이콘은 버튼 액션(action.type)에 연동
|
||||
|
||||
- **결정**: 버튼 액션을 변경하면 해당 액션에 맞는 추천 아이콘 목록이 자동으로 갱신됨
|
||||
- **근거**: 관리자가 "저장" 아이콘을 고른 뒤 액션을 "삭제"로 바꾸면 혼란 발생. 액션별로 적절한 아이콘 후보를 보여주는 것이 자연스러움
|
||||
- **주의**: 액션 변경 시 이전에 선택한 아이콘이 새 액션의 추천 목록에 없으면 선택 초기화
|
||||
|
||||
### 4. 액션별 아이콘은 6개씩 제공, 적절한 아이콘이 없으면 안내 문구
|
||||
|
||||
- **결정**: 활성 액션 14개 각각에 6개의 lucide-react 아이콘 후보 제공
|
||||
- **근거**: 너무 적으면 선택지 부족, 너무 많으면 선택 피로. 6개가 2행 그리드로 깔끔하게 표시됨
|
||||
- **deprecated/숨김 액션**: UI에서 숨김 처리된 액션은 추천 아이콘 없이 안내 문구만 표시
|
||||
|
||||
### 5. 커스텀 아이콘 추가는 2가지 방법 제공
|
||||
|
||||
- **결정**: (1) lucide 아이콘 검색 + (2) 외부 SVG 붙여넣기 두 가지 경로 제공
|
||||
- **근거**: lucide 내장 아이콘만으로는 부족한 경우 존재 (회사 로고, 업종별 특수 아이콘 등). 외부에서 가져온 SVG를 직접 붙여넣기로 등록할 수 있어야 실무 유연성 확보
|
||||
- **lucide 추가**: "lucide 검색" 버튼 → 팝오버에서 검색 → 선택 → `customIcons` 배열에 이름 추가
|
||||
- **SVG 추가**: "SVG 붙여넣기" 버튼 → textarea에 SVG 코드 붙여넣기 → 미리보기 확인 → 이름 입력 → `customSvgIcons` 배열에 `{ name, svg }` 저장
|
||||
- **SVG 유효성**: `<svg` 태그 포함 여부로 기본 검증, XSS 방지를 위해 DOMPurify로 정화 후 저장
|
||||
- **범위**: 모든 커스텀 아이콘은 **해당 버튼 컴포넌트에 저장** (lucide: `customIcons`, SVG: `customSvgIcons`)
|
||||
- **노출**: 커스텀 아이콘(lucide/SVG 모두)은 어떤 버튼 액션에서도 추천 아이콘 아래에 함께 노출됨
|
||||
- **삭제**: 커스텀 아이콘 위에 X 버튼으로 개별 삭제 가능
|
||||
|
||||
### 5-1. 외부 SVG 붙여넣기의 보안 고려
|
||||
|
||||
- **결정**: SVG 문자열을 DOMPurify로 정화(sanitize)한 뒤 저장
|
||||
- **근거**: SVG에 `<script>`, `onload` 같은 악성 코드가 포함될 수 있으므로 XSS 방지 필수
|
||||
- **렌더링**: 정화된 SVG를 `dangerouslySetInnerHTML`로 렌더링 (정화 후이므로 안전)
|
||||
- **대안 검토**: SVG를 이미지 파일로 업로드 → 기각 (관리자 입장에서 복사-붙여넣기가 훨씬 간편)
|
||||
|
||||
### 6. 아이콘 색상은 별도 설정, 기본값은 textColor 상속
|
||||
|
||||
- **결정**: `icon.color` 옵션 추가. 미설정 시 `textColor`를 상속, 설정하면 아이콘만 해당 색상 적용
|
||||
- **근거**: 아이콘+텍스트 모드에서 `[ 초록✓ 검정저장 ]` 같이 아이콘과 텍스트 색을 분리하고 싶은 경우 존재. 삭제 버튼에 빨간 아이콘 + 흰 텍스트 같은 세밀한 디자인도 가능
|
||||
- **기본값**: 미설정 (= `textColor` 상속) → 설정하지 않으면 기존 동작과 100% 동일
|
||||
- **외부 SVG**: `fill`이 하드코딩된 SVG는 이 설정 무시 (SVG 원본 색상 유지가 의도). `currentColor`를 사용하는 SVG만 영향받음
|
||||
- **구현**: 아이콘을 `<span style={{ color: icon.color }}>`으로 감싸서 아이콘만 색상 분리
|
||||
- **초기화**: "텍스트 색상과 동일" 버튼으로 별도 색상 해제 → `icon.color` 삭제
|
||||
|
||||
### 7. 아이콘 크기는 버튼 높이 대비 비율(%) 프리셋 4단계
|
||||
|
||||
- **결정**: 작게(40%) / 보통(55%) / 크게(70%) / 매우 크게(85%) — 버튼 높이 대비 비율
|
||||
- **근거**: 절대 px 값은 버튼 크기가 바뀌면 비율이 깨짐. 비율 기반이면 버튼 크기를 조정해도 아이콘이 자동으로 비례하여 일관된 시각적 균형 유지
|
||||
- **기본값**: `"보통"` (55%) — 대부분의 버튼 크기에 적합
|
||||
- **px 직접 입력 제거**: 관리자에게 과도한 선택지를 주면 오히려 일관성이 깨짐. 4단계 프리셋만으로 충분
|
||||
- **구현**: CSS `height: N%` + `aspect-ratio: 1/1`로 정사각형 유지, lucide 아이콘은 래핑 span으로 크기 제어
|
||||
- **레거시 호환**: 기존 `"sm"`, `"md"` 등 레거시 값은 55%(보통)로 자동 폴백
|
||||
|
||||
### 8. 아이콘 동적 렌더링은 매핑 객체 방식
|
||||
|
||||
- **결정**: lucide-react 아이콘 이름(string) → 실제 컴포넌트 매핑 객체를 별도 파일로 관리
|
||||
- **근거**: `import * from 'lucide-react'`는 번들 크기에 영향. 사용하는 아이콘만 명시적으로 매핑
|
||||
- **파일**: `frontend/lib/button-icon-map.ts`
|
||||
- **구현**: `Record<string, React.ComponentType>` 형태의 매핑 + `renderIcon(name, size)` 유틸 함수
|
||||
|
||||
### 9. 아이콘 모드에서도 text 값은 유지
|
||||
|
||||
- **결정**: `displayMode === "icon"`이어도 `text` 필드는 삭제하지 않음
|
||||
- **근거**: 접근성(`aria-label`), 검색/필터링 등에 텍스트가 필요할 수 있음
|
||||
- **렌더링**: 아이콘 모드에서는 `text`를 `aria-label` 용도로만 보존
|
||||
- **아이콘+텍스트 모드**: `text`가 아이콘 오른쪽에 함께 렌더링됨
|
||||
|
||||
### 10. 아이콘-텍스트 간격 설정 추가
|
||||
|
||||
- **결정**: 아이콘+텍스트 모드에서 아이콘과 텍스트 사이 간격을 관리자가 조절 가능 (`iconGap`)
|
||||
- **근거**: 고정 `gap-1.5`(6px)로는 다양한 버튼 크기/디자인에 대응 불가. 간격이 좁으면 답답하고, 넓으면 분리되어 보이는 경우가 있어 관리자에게 조절 권한 제공
|
||||
- **기본값**: 6px (기존 `gap-1.5`와 동일)
|
||||
- **UI**: 슬라이더(0~32px) + 숫자 직접 입력(최댓값 제한 없음)
|
||||
- **저장**: `componentConfig.iconGap` (숫자)
|
||||
|
||||
### 11. 키보드 단축키 입력 필드 충돌 해결
|
||||
|
||||
- **결정**: `ScreenDesigner`의 글로벌 키보드 핸들러에서 입력 필드 포커스 시 앱 단축키를 무시하도록 수정
|
||||
- **근거**: SVG 붙여넣기 textarea에서 Ctrl+V/A/C/Z가 작동하지 않는 치명적 UX 문제 발견. 글로벌 `keydown` 핸들러가 `{ capture: true }`로 모든 키보드 이벤트를 가로채고 있었음
|
||||
- **수정**: `browserShortcuts` 일괄 차단과 앱 전용 단축키 처리 앞에 `e.target`/`document.activeElement` 기반 입력 필드 감지 가드 추가
|
||||
- **영향**: input, textarea, select, contentEditable 요소에서 텍스트 편집 단축키가 정상 동작
|
||||
|
||||
### 12. noIconAction에서 커스텀 아이콘 추가 허용
|
||||
|
||||
- **결정**: 추천 아이콘이 없는 deprecated 액션에서도 커스텀 아이콘(lucide 검색, SVG 붙여넣기) 추가 가능
|
||||
- **근거**: "적절한 아이콘이 없습니다" 문구만 표시하고 아이콘 추가를 완전 차단하면 관리자가 필요한 아이콘을 직접 등록할 방법이 없음. 추천은 없지만 직접 추가는 허용해야 유연성 확보
|
||||
- **안내 문구**: "적절한 추천 아이콘이 없습니다. 텍스트 모드를 사용하거나 아래에서 아이콘을 직접 추가하세요."
|
||||
|
||||
### 13. 아이콘 모드 레이아웃 안내 문구
|
||||
|
||||
- **결정**: 아이콘 모드(`"icon"`) 선택 시 "버튼 영역의 가로 폭을 줄여 정사각형에 가깝게 만들면 더 깔끔합니다" 안내 표시
|
||||
- **근거**: 아이콘 자체는 항상 정사각형(24x24 viewBox)이지만, 디자이너에서 버튼 컨테이너는 가로로 넓은 직사각형이 기본. 아이콘만 넣으면 좌우 여백이 과다해 보이므로 버튼 영역을 줄이라는 안내가 필요. 자동 크기 조정은 기존 레이아웃을 깨뜨릴 위험이 있어 도입하지 않되, 관리자에게 팁을 제공하면 스스로 최적화할 수 있음
|
||||
- **표시 조건**: `displayMode === "icon"`일 때만 (아이콘+텍스트 모드는 가로 공간이 필요하므로 해당 안내 불필요)
|
||||
- **대안 검토**: 자동 정사각형 조정 → 기각 (관리자 수동 레이아웃 파괴 위험)
|
||||
|
||||
### 14. 디폴트 아이콘 자동 부여
|
||||
|
||||
- **결정**: 아이콘/아이콘+텍스트 모드 전환 시 아이콘이 미선택이면 디폴트 아이콘을 자동으로 부여. 커스텀 아이콘 삭제 시에도 텍스트 모드로 빠지지 않고 디폴트 아이콘으로 복귀
|
||||
- **근거**: 아이콘 모드로 전환했는데 아무것도 안 보이면 "기능이 작동하지 않는다"는 착각을 유발. 또한 커스텀 아이콘을 삭제했을 때 갑자기 텍스트로 빠지면 관리자가 의도치 않은 모드 변경을 경험하게 됨
|
||||
- **디폴트 선택 기준**: 해당 액션의 첫 번째 추천 아이콘 (예: save → Check). 추천 아이콘이 없는 액션은 범용 폴백 `SquareMousePointer` 사용
|
||||
- **구현**: `getDefaultIconForAction(actionType)` 유틸 함수로 중앙화 (`button-icon-map.tsx`)
|
||||
- **폴백 아이콘**: `SquareMousePointer` — 마우스 포인터 + 사각형 형태로 "버튼 클릭 동작"을 범용적으로 표현
|
||||
|
||||
### 15. 아이콘+텍스트 모드에서 텍스트 위치 4방향 지원
|
||||
|
||||
- **결정**: 아이콘 대비 텍스트 위치를 왼쪽/오른쪽/위쪽/아래쪽 4방향으로 설정 가능
|
||||
- **근거**: 기존에는 아이콘 오른쪽에 텍스트 고정이었으나, 세로 배치(위/아래)가 필요한 경우도 존재 (좁고 높은 버튼, 툴바 스타일). 4방향을 제공하면 관리자가 버튼 모양에 맞게 레이아웃 선택 가능
|
||||
- **기본값**: `"right"` (아이콘 오른쪽에 텍스트) — 가장 자연스러운 좌→우 읽기 방향
|
||||
- **구현**: `flexDirection` (row/column) + 요소 순서 (textFirst) 조합으로 4방향 구현
|
||||
- **저장**: `componentConfig.iconTextPosition`
|
||||
- **표시 조건**: 아이콘+텍스트 모드에서만 표시 (아이콘 모드, 텍스트 모드에서는 숨김)
|
||||
|
||||
### 16. 버튼 컴포넌트 테두리 이중 적용 문제 해결
|
||||
|
||||
- **결정**: `RealtimePreviewDynamic`의 position wrapper에서 버튼 컴포넌트의 border 속성을 분리(strip)
|
||||
- **근거**: StyleEditor에서 설정한 border가 (1) position wrapper와 (2) 내부 버튼 요소 두 곳에 모두 적용되어 이중 테두리 발생. border는 내부 버튼(`buttonElementStyle`)에서만 렌더링해야 함
|
||||
- **수정 파일**: `RealtimePreviewDynamic.tsx` — `isButtonComponent` 조건에 `v2-button-primary` 추가하여 border strip 대상에 포함
|
||||
- **수정 파일**: `ButtonPrimaryComponent.tsx` — 외부 wrapper(`componentStyle`)에서 border 속성 destructure로 제거, `border: "none"` shorthand 대신 개별 longhand 속성으로 변경 (borderStyle 미설정 시 기본 `"solid"` 적용)
|
||||
|
||||
### 17. 커스텀 아이콘 검색은 lucide 전체 목록 기반
|
||||
|
||||
- **결정**: lucide-react에서 export되는 전체 아이콘 이름 목록을 검색 가능
|
||||
- **근거**: 관리자가 "어떤 아이콘이 있는지" 모르므로 검색 기능이 필수
|
||||
- **구현**: `lucide-react`의 `icons` 객체에서 `Object.keys()`로 전체 이름 목록을 가져오고, CommandInput으로 필터링
|
||||
- **주의**: `allLucideIcons`는 `button-icon-map.tsx`에서 re-export하여 import를 중앙화
|
||||
|
||||
### 18. 커스텀 아이콘 전역 관리 (미구현)
|
||||
|
||||
- **결정**: 커스텀 아이콘을 버튼별(`componentConfig`) → 시스템 전역(`custom_icon_registry` 테이블)으로 변경
|
||||
- **근거**: 현재는 버튼 A에서 추가한 커스텀 아이콘이 버튼 B, 다른 화면에서 안 보여 매번 재등록 필요. 아이콘은 시각적 자원이므로 액션이나 화면에 종속될 이유가 없음
|
||||
- **범위 검토**: 버튼별 < 화면 단위 < **시스템 전역(채택)** — 같은 아이콘을 여러 화면에서 재사용하는 ERP 특성에 시스템 전역이 가장 적합
|
||||
- **저장**: `custom_icon_registry` 테이블 (company_code 멀티테넌시), lucide 이름 또는 SVG 데이터 저장
|
||||
- **하위 호환**: 기존 `componentConfig.customIcons` 데이터는 병합 표시 후 점진적 마이그레이션
|
||||
|
||||
### 19. 동적 아이콘 로딩 (getLucideIcon fallback)
|
||||
|
||||
- **결정**: `getLucideIcon(name)`이 `iconMap`에 없는 아이콘을 `lucide-react`의 `icons` 전체 객체에서 동적으로 조회 후 캐싱
|
||||
- **근거**: 화면 관리에서 커스텀 lucide 아이콘을 선택하면 `componentConfig.customIcons`에 이름만 저장됨. 디자이너 세션에서는 `addToIconMap()`으로 런타임에 등록되지만, 실제 화면(뷰어) 로드 시에는 `iconMap`에 해당 아이콘이 없어 렌더링 실패. `icons` fallback을 추가하면 **어떤 lucide 아이콘이든 이름만으로 자동 렌더링**
|
||||
- **구현**: `button-icon-map.tsx`에 `import { icons as allLucideIcons } from "lucide-react"` 추가, `getLucideIcon()`에서 `iconMap` miss 시 `allLucideIcons[name]` 조회 후 `iconMap`에 캐싱
|
||||
- **번들 영향**: `icons` 전체 객체 import로 번들 크기 증가 (~100-200KB). ERP 애플리케이션 특성상 수용 가능한 수준이며, 관리자가 선택한 모든 아이콘이 실제 화면에서 동작하는 것이 더 중요
|
||||
- **대안 검토**: 뷰어 로드 시 `customIcons`를 순회하여 개별 등록 → 기각 (모든 뷰어 컴포넌트에 로직 추가 필요, 누락 위험)
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 설정 패널 (수정) | `frontend/components/screen/config-panels/ButtonConfigPanel.tsx` | 버튼 텍스트/액션 설정 (784~854행에 모드 선택 추가) |
|
||||
| 뷰어 렌더링 (수정) | `frontend/components/screen/InteractiveScreenViewerDynamic.tsx` | 버튼 렌더링 분기 (961~983행) |
|
||||
| 뷰어 렌더링 (수정) | `frontend/components/screen/InteractiveScreenViewer.tsx` | 버튼 렌더링 분기 (2041~2059행) |
|
||||
| 위젯 (수정) | `frontend/components/screen/widgets/types/ButtonWidget.tsx` | 위젯 기반 버튼 렌더링 (67~86행) |
|
||||
| 최적화 버튼 (수정) | `frontend/components/screen/OptimizedButtonComponent.tsx` | 최적화된 버튼 렌더링 (643~674행) |
|
||||
| 아이콘 매핑 (신규) | `frontend/lib/button-icon-map.tsx` | 액션별 추천 아이콘 + 동적 렌더링 유틸 + allLucideIcons fallback |
|
||||
| 타입 정의 (참고) | `frontend/types/screen.ts` | ComponentData, componentConfig 타입 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### lucide-react 아이콘 동적 렌더링
|
||||
|
||||
```typescript
|
||||
// button-icon-map.tsx
|
||||
import { Check, Save, ..., icons as allLucideIcons, type LucideIcon } from "lucide-react";
|
||||
|
||||
// 추천 아이콘은 명시적 import, 나머지는 동적 조회
|
||||
const iconMap: Record<string, LucideIcon> = { Check, Save, ... };
|
||||
|
||||
export function getLucideIcon(name: string): LucideIcon | undefined {
|
||||
if (iconMap[name]) return iconMap[name];
|
||||
// iconMap에 없으면 lucide-react 전체에서 동적 조회 후 캐싱
|
||||
const found = allLucideIcons[name as keyof typeof allLucideIcons];
|
||||
if (found) {
|
||||
iconMap[name] = found;
|
||||
return found;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
```
|
||||
|
||||
### 아이콘 크기 비율 매핑 (버튼 높이 대비 %)
|
||||
|
||||
```typescript
|
||||
const iconSizePresets: Record<string, number> = {
|
||||
"작게": 40,
|
||||
"보통": 55,
|
||||
"크게": 70,
|
||||
"매우 크게": 85,
|
||||
};
|
||||
|
||||
// 프리셋 문자열 → 비율(%) 반환. 레거시 값은 55(보통)로 폴백
|
||||
export function getIconPercent(size: string | number): number {
|
||||
if (typeof size === "number") return size;
|
||||
return iconSizePresets[size] ?? 55;
|
||||
}
|
||||
|
||||
// 버튼 높이 대비 비율 + 정사각형 유지
|
||||
export function getIconSizeStyle(size: string | number): React.CSSProperties {
|
||||
const pct = getIconPercent(size);
|
||||
return { height: `${pct}%`, width: "auto", aspectRatio: "1 / 1" };
|
||||
}
|
||||
```
|
||||
|
||||
### 외부 SVG 아이콘 렌더링
|
||||
|
||||
```typescript
|
||||
import DOMPurify from "dompurify";
|
||||
|
||||
export function renderSvgIcon(svgString: string, size: string | number) {
|
||||
const clean = DOMPurify.sanitize(svgString, { USE_PROFILES: { svg: true } });
|
||||
return (
|
||||
<span
|
||||
className="inline-flex items-center justify-center"
|
||||
style={getIconSizeStyle(size)}
|
||||
dangerouslySetInnerHTML={{ __html: clean }}
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 버튼 액션별 추천 아이콘 구조
|
||||
|
||||
```typescript
|
||||
const actionIconMap: Record<string, string[]> = {
|
||||
save: ["Check", "Save", "CheckCircle", "CircleCheck", "FileCheck", "ShieldCheck"],
|
||||
delete: ["Trash2", "Trash", "XCircle", "X", "Eraser", "CircleX"],
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
### 현재 버튼 액션 목록 (활성)
|
||||
|
||||
| 값 | 표시명 | 아이콘화 가능 |
|
||||
|-----|--------|-------------|
|
||||
| `save` | 저장 | O |
|
||||
| `delete` | 삭제 | O |
|
||||
| `edit` | 편집 | O |
|
||||
| `navigate` | 페이지 이동 | O |
|
||||
| `modal` | 모달 열기 | O |
|
||||
| `transferData` | 데이터 전달 | O |
|
||||
| `excel_download` | 엑셀 다운로드 | O |
|
||||
| `excel_upload` | 엑셀 업로드 | O |
|
||||
| `quickInsert` | 즉시 저장 | O |
|
||||
| `control` | 제어 흐름 | O |
|
||||
| `barcode_scan` | 바코드 스캔 | O |
|
||||
| `operation_control` | 운행알림 및 종료 | O |
|
||||
| `event` | 이벤트 발송 | O |
|
||||
| `copy` | 복사 (품목코드 초기화) | O |
|
||||
|
||||
### 현재 버튼 액션 목록 (숨김/deprecated)
|
||||
|
||||
| 값 | 표시명 | 아이콘화 가능 |
|
||||
|-----|--------|-------------|
|
||||
| `openRelatedModal` | 연관 데이터 버튼 모달 열기 | X (적절한 아이콘 없음) |
|
||||
| `openModalWithData` | (deprecated) 데이터 전달 + 모달 | X |
|
||||
| `view_table_history` | 테이블 이력 보기 | X |
|
||||
| `code_merge` | 코드 병합 | X |
|
||||
| `empty_vehicle` | 공차등록 | X |
|
||||
@@ -0,0 +1,179 @@
|
||||
# [체크리스트] 버튼 아이콘화 - 화면 디자이너 버튼 표시 모드 확장
|
||||
|
||||
> 관련 문서: [계획서](./BIC[계획]-버튼-아이콘화.md) | [맥락노트](./BIC[맥락]-버튼-아이콘화.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (전 단계 구현 및 검증 완료)
|
||||
- 현재 단계: 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 아이콘 매핑 파일 생성
|
||||
|
||||
- [x] `frontend/lib/button-icon-map.tsx` 생성
|
||||
- [x] 버튼 액션별 추천 아이콘 매핑 (`actionIconMap`) 정의 (14개 액션 x 6개 아이콘)
|
||||
- [x] 아이콘 크기 비율 매핑 (`iconSizePresets`) 정의 (작게/보통/크게/매우 크게, 버튼 높이 대비 %) + `getIconSizeStyle()` 유틸
|
||||
- [x] lucide 아이콘 동적 렌더링 포함 `getButtonDisplayContent()` 구현
|
||||
- [x] SVG 아이콘 렌더링 (DOMPurify 정화 via `isomorphic-dompurify`)
|
||||
- [x] 아이콘 이름 → 컴포넌트 매핑 객체 (`iconMap`) + `addToIconMap()` 동적 추가
|
||||
- [x] deprecated 액션용 안내 문구 상수 (`NO_ICON_MESSAGE`) 정의
|
||||
- [x] `isomorphic-dompurify` 기존 설치 확인 (추가 설치 불필요)
|
||||
- [x] `ButtonIconRenderer` 공용 컴포넌트 추가 (모든 렌더러에서 재사용)
|
||||
- [x] `getDefaultIconForAction()` 디폴트 아이콘 유틸 함수 추가 (액션별 첫 번째 추천 / 범용 폴백)
|
||||
- [x] `FALLBACK_ICON_NAME` 상수 + `SquareMousePointer` import/매핑 추가
|
||||
|
||||
### 2단계: ButtonConfigPanel 수정
|
||||
|
||||
- [x] 표시 모드 버튼 그룹 UI 추가 (텍스트 / 아이콘 / 아이콘+텍스트)
|
||||
- [x] `displayMode` 상태 관리 및 `onUpdateProperty` 연동
|
||||
- [x] 아이콘 모드 선택 시 조건부 UI 분기 (텍스트 입력 숨김 → 아이콘 선택 표시)
|
||||
- [x] 아이콘+텍스트 모드 선택 시 아이콘 선택 + 텍스트 입력 **동시** 표시
|
||||
- [x] 버튼 액션별 추천 아이콘 그리드 렌더링 (4열 그리드)
|
||||
- [x] 선택된 아이콘 하이라이트 (`ring-2 ring-primary/30 border-primary`)
|
||||
- [x] 아이콘 크기 비율 프리셋 버튼 그룹 (작게/보통/크게/매우 크게, 한글 라벨)
|
||||
- [x] px 직접 입력 필드 제거 (비율 프리셋만 제공)
|
||||
- [x] `icon.name`, `icon.size` 를 `onUpdateProperty`로 저장
|
||||
- [x] 아이콘 색상 컬러 피커 구현 (`ColorPickerWithTransparent` 재사용)
|
||||
- [x] "텍스트 색상과 동일" 초기화 버튼 구현
|
||||
- [x] 텍스트 위치 4방향 설정 추가 (`iconTextPosition`, 왼쪽/오른쪽/위쪽/아래쪽)
|
||||
- [x] 아이콘-텍스트 간격 설정 추가 (`iconGap`, 슬라이더 + 직접 입력, 아이콘+텍스트 모드 전용)
|
||||
- [x] 아이콘 모드 레이아웃 안내 문구 표시 (Info 아이콘 + bg-blue-50 박스)
|
||||
- [x] 액션 변경 시 선택 아이콘 자동 초기화 로직 (추천 목록에 없으면 해제)
|
||||
- [x] deprecated 액션에서 안내 문구 + 커스텀 아이콘 추가 버튼 표시
|
||||
- [x] 아이콘/아이콘+텍스트 모드 전환 시 아이콘 미선택이면 디폴트 아이콘 자동 부여
|
||||
- [x] 커스텀 아이콘 삭제 시 디폴트 아이콘으로 자동 복귀 (텍스트 모드 전환 방지)
|
||||
|
||||
### 3단계: 커스텀 아이콘 추가/삭제 (lucide 검색)
|
||||
|
||||
- [x] "lucide 검색" 버튼 UI
|
||||
- [x] lucide 아이콘 검색 팝오버 (Popover + Command + CommandInput)
|
||||
- [x] `import { icons } from "lucide-react"` 기반 전체 아이콘 검색/필터링
|
||||
- [x] 선택 시 `componentConfig.customIcons` 배열 추가 + `addToIconMap` 동적 등록
|
||||
- [x] lucide 커스텀 아이콘 그리드 렌더링 (추천 아이콘 아래, 구분선 포함)
|
||||
- [x] lucide 커스텀 아이콘 X 버튼으로 개별 삭제
|
||||
|
||||
### 3-1단계: 커스텀 아이콘 추가/삭제 (SVG 붙여넣기)
|
||||
|
||||
- [x] "SVG 붙여넣기" 버튼 UI (Popover)
|
||||
- [x] SVG 입력 textarea + DOMPurify 실시간 미리보기
|
||||
- [x] SVG 유효성 검사 (`<svg` 태그 포함 여부)
|
||||
- [x] 아이콘 이름 입력 필드 (관리자가 구분용 이름 지정)
|
||||
- [x] DOMPurify로 SVG 정화(sanitize) 후 저장
|
||||
- [x] `componentConfig.customSvgIcons` 배열에 `{ name, svg }` 추가
|
||||
- [x] SVG 커스텀 아이콘 그리드 렌더링 (lucide 커스텀 아이콘과 함께 표시)
|
||||
- [x] SVG 커스텀 아이콘 X 버튼으로 개별 삭제
|
||||
- [x] 커스텀 아이콘(lucide + SVG 모두)이 모든 버튼 액션에서 공통 노출
|
||||
|
||||
### 4단계: 버튼 렌더링 수정 (뷰어/위젯)
|
||||
|
||||
- [x] `InteractiveScreenViewerDynamic.tsx` - `ButtonIconRenderer` 적용
|
||||
- [x] `InteractiveScreenViewer.tsx` - `ButtonIconRenderer` 적용
|
||||
- [x] `ButtonWidget.tsx` - `ButtonIconRenderer` 적용 (디자인/실행 모드 모두)
|
||||
- [x] `OptimizedButtonComponent.tsx` - `ButtonIconRenderer` 적용 (실행 중 "처리 중..." 유지)
|
||||
- [x] `ButtonPrimaryComponent.tsx` - `ButtonIconRenderer` 적용 (v2-button-primary 캔버스 렌더링)
|
||||
- [x] lucide 아이콘 렌더링 (`icon.type === "lucide"`, `getLucideIcon` 조회)
|
||||
- [x] SVG 아이콘 렌더링 (`icon.type === "svg"`, DOMPurify 정화 후 innerHTML)
|
||||
- [x] 아이콘+텍스트 모드: `inline-flex items-center` + 동적 `gap` (iconGap px)
|
||||
- [x] `icon.color` 설정 시 아이콘만 별도 색상 적용 (inline style)
|
||||
- [x] `icon.color` 미설정 시 textColor 상속 (currentColor 기본)
|
||||
- [x] 아이콘 크기 비율 프리셋 `getIconSizeStyle()` 처리 (버튼 높이 대비 %)
|
||||
- [x] 텍스트 위치 4방향 렌더링 (`flexDirection` + 요소 순서 조합)
|
||||
|
||||
### 4-2단계: 버튼 테두리 이중 적용 수정
|
||||
|
||||
- [x] `RealtimePreviewDynamic.tsx` — position wrapper에서 버튼 컴포넌트 border strip 추가
|
||||
- [x] `ButtonPrimaryComponent.tsx` — 외부 wrapper에서 border 속성 destructure 제거
|
||||
- [x] `ButtonPrimaryComponent.tsx` — `border: "none"` shorthand 제거, 개별 longhand 속성으로 변경
|
||||
- [x] `isButtonComponent` 조건에 `"v2-button-primary"` 추가
|
||||
|
||||
### 4-1단계: 키보드 단축키 충돌 수정
|
||||
|
||||
- [x] `ScreenDesigner.tsx` 글로벌 keydown 핸들러에 입력 필드 감지 가드 추가
|
||||
- [x] `browserShortcuts` 배열에서 `Ctrl+V` 제거
|
||||
- [x] 입력 필드(input/textarea/select/contentEditable) 포커스 시 Ctrl+A/C/V/Z 기본 동작 허용
|
||||
- [x] SVG 붙여넣기 textarea에 `onPaste`/`onKeyDown` stopPropagation 핸들러 추가
|
||||
|
||||
### 5단계: 검증
|
||||
|
||||
- [x] 텍스트 모드: 기존 동작 변화 없음 확인 (하위 호환성)
|
||||
- [x] `displayMode` 없는 기존 버튼: 텍스트 모드로 정상 동작
|
||||
- [x] 아이콘 모드 선택 → 추천 아이콘 6개 그리드 표시
|
||||
- [x] 아이콘 선택 → 캔버스(오른쪽 프리뷰) 및 실제 화면에서 아이콘 렌더링 확인
|
||||
- [x] 아이콘 크기 비율 프리셋 변경 → 버튼 높이 대비 비율 반영 확인
|
||||
- [x] 텍스트 위치 4방향(왼/오른/위/아래) 변경 → 레이아웃 방향 반영 확인
|
||||
- [x] 버튼 테두리 설정 → 내부 버튼에만 적용, 외부 wrapper에 이중 적용 없음 확인
|
||||
- [x] 버튼 액션 변경 → 추천 아이콘 목록 갱신 확인
|
||||
- [x] lucide 커스텀 아이콘 추가 → 모든 액션에서 노출 확인
|
||||
- [x] SVG 커스텀 아이콘 붙여넣기 → 미리보기 → 추가 → 모든 액션에서 노출 확인
|
||||
- [x] SVG에 악성 코드 삽입 시도 → DOMPurify 정화 후 안전 렌더링 확인
|
||||
- [x] 커스텀 아이콘 삭제 → 목록에서 제거 확인
|
||||
- [x] deprecated 액션에서 안내 문구 + 커스텀 아이콘 추가 가능 확인
|
||||
- [x] 아이콘+텍스트 모드: 아이콘 + 텍스트 나란히 렌더링 확인
|
||||
- [x] 아이콘+텍스트 간격 조절: 슬라이더/직접 입력으로 간격 변경 → 실시간 반영 확인
|
||||
- [x] 아이콘 색상 미설정 → textColor와 동일한 색상 확인
|
||||
- [x] 아이콘 색상 설정 → 아이콘만 해당 색상, 텍스트는 textColor 유지 확인
|
||||
- [x] 외부 SVG (고유 색상) → icon.color 설정해도 SVG 원본 색상 유지 확인
|
||||
- [x] "텍스트 색상과 동일" 버튼 → icon.color 해제되고 textColor 상속 복원 확인
|
||||
- [x] 레이아웃 안내 문구: 아이콘 모드에서만 표시, 다른 모드에서 숨김 확인
|
||||
- [x] 입력 필드에서 Ctrl+A/C/V/Z 단축키 정상 동작 확인
|
||||
- [x] 아이콘 모드 전환 시 디폴트 아이콘 자동 선택 → 캔버스에 즉시 반영 확인
|
||||
- [x] 커스텀 아이콘 삭제 시 디폴트 아이콘으로 복귀 → 아이콘 모드 유지 확인
|
||||
- [x] deprecated 액션에서 디폴트 폴백 아이콘(SquareMousePointer) 표시 확인
|
||||
|
||||
### 6단계: 동적 아이콘 로딩 (뷰어 렌더링 누락 수정)
|
||||
|
||||
- [x] `button-icon-map.tsx`에 `icons as allLucideIcons` import 추가
|
||||
- [x] `getLucideIcon()` — `iconMap` miss 시 `allLucideIcons` fallback 조회 + 캐싱
|
||||
- [x] `allLucideIcons`를 `button-icon-map.tsx`에서 re-export (import 중앙화)
|
||||
- [x] `ButtonConfigPanel.tsx` — `lucide-react` 직접 import 제거, `button-icon-map`에서 import로 통합
|
||||
- [x] 화면 관리에서 선택한 커스텀 lucide 아이콘이 실제 화면(뷰어)에서도 렌더링됨 확인
|
||||
|
||||
### 7단계: 정리
|
||||
|
||||
- [x] TypeScript 컴파일 에러 없음 확인
|
||||
- [x] 불필요한 import 없음 확인
|
||||
- [x] 문서 3개 최신화 (동적 로딩 반영)
|
||||
- [x] 이 체크리스트 완료 표시 업데이트
|
||||
|
||||
### 8단계: 커스텀 아이콘 전역 관리 (미구현)
|
||||
|
||||
- [ ] `custom_icon_registry` 테이블 마이그레이션 SQL 작성 및 실행 (개발섭 + 본섭)
|
||||
- [ ] 백엔드 API 구현 (GET/POST/DELETE `/api/custom-icons`)
|
||||
- [ ] 프론트엔드 API 클라이언트 함수 추가 (`lib/api/`)
|
||||
- [ ] `ButtonConfigPanel` — 커스텀 아이콘 조회/추가/삭제를 전역 API로 변경
|
||||
- [ ] 기존 `componentConfig.customIcons` 하위 호환 병합 처리
|
||||
- [ ] 검증: 화면 A에서 추가한 커스텀 아이콘이 화면 B에서도 보이는지 확인
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-04 | 계획서, 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-04 | 외부 SVG 붙여넣기 기능 추가 (3개 문서 모두 반영) |
|
||||
| 2026-03-04 | 아이콘+텍스트 모드, 레이아웃 안내 추가 |
|
||||
| 2026-03-04 | 설정 패널 내 미리보기 제거 (오른쪽 캔버스 프리뷰로 대체) |
|
||||
| 2026-03-04 | 아이콘 색상 설정 추가 (icon.color, 기본값 textColor 상속) |
|
||||
| 2026-03-04 | 3개 문서 교차 검토 — 개요 누락 보완, 시각 예시 문구 통일, 렌더 함수 px 대응, 용어 명확화 |
|
||||
| 2026-03-04 | 구현 완료 — 1~4단계 코드 작성, 6단계 린트/타입 검증 통과 |
|
||||
| 2026-03-04 | 아이콘-텍스트 간격 설정 추가 (iconGap, 슬라이더+직접 입력) |
|
||||
| 2026-03-04 | noIconAction에서 커스텀 아이콘 추가 허용 + 안내 문구 변경 |
|
||||
| 2026-03-04 | ScreenDesigner 키보드 단축키 수정 — 입력 필드에서 텍스트 편집 단축키 허용 |
|
||||
| 2026-03-04 | SVG 붙여넣기 textarea에 onPaste/onKeyDown 핸들러 추가 |
|
||||
| 2026-03-04 | SVG 커스텀 아이콘 이름 중복 방지 (자동 넘버링) |
|
||||
| 2026-03-04 | 디폴트 아이콘 자동 부여 — 모드 전환 시 자동 선택, 커스텀 삭제 시 디폴트 복귀 |
|
||||
| 2026-03-04 | `getDefaultIconForAction()` 유틸 + `SquareMousePointer` 폴백 아이콘 추가 |
|
||||
| 2026-03-04 | 3개 문서 변경사항 동기화 및 코드 정리 |
|
||||
| 2026-03-04 | 아이콘 크기: 절대 px → 버튼 높이 대비 비율(%) 4단계 프리셋으로 변경, px 직접 입력 제거 |
|
||||
| 2026-03-04 | 텍스트 위치 4방향 설정 추가 (왼쪽/오른쪽/위쪽/아래쪽) |
|
||||
| 2026-03-04 | 버튼 테두리 이중 적용 수정 — position wrapper에서 border strip, border shorthand 제거 |
|
||||
| 2026-03-04 | 프리셋 라벨 한글화 (작게/보통/크게/매우 크게), 라벨 "아이콘 크기 비율"로 변경 |
|
||||
| 2026-03-13 | 동적 아이콘 로딩 — `getLucideIcon()` fallback으로 `allLucideIcons` 조회+캐싱, import 중앙화 |
|
||||
| 2026-03-13 | 문서 3개 최신화 (계획서 설계 원칙, 맥락노트 결정사항 #18, 체크리스트 6-7단계) |
|
||||
| 2026-03-13 | 커스텀 아이콘 전역 관리 계획 추가 (8단계, 미구현) — DB 테이블 + API + 프론트 변경 예정 |
|
||||
@@ -0,0 +1,171 @@
|
||||
# BTN - 버튼 UI 스타일 기준정보
|
||||
|
||||
## 1. 스타일 기준
|
||||
|
||||
### 공통 스타일
|
||||
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| 높이 | 40px |
|
||||
| 표시모드 | 아이콘 + 텍스트 (icon-text) |
|
||||
| 아이콘 | 액션별 첫 번째 기본 아이콘 (자동 선택) |
|
||||
| 아이콘 크기 비율 | 보통 |
|
||||
| 아이콘-텍스트 간격 | 6px |
|
||||
| 텍스트 위치 | 오른쪽 (아이콘 왼쪽, 텍스트 오른쪽) |
|
||||
| 테두리 모서리 | 8px |
|
||||
| 테두리 색상/두께 | 없음 (투명, borderWidth: 0) |
|
||||
| 텍스트 색상 | #FFFFFF (흰색) |
|
||||
| 텍스트 크기 | 12px |
|
||||
| 텍스트 굵기 | normal (보통) |
|
||||
| 텍스트 정렬 | 왼쪽 |
|
||||
|
||||
### 배경색 (액션별)
|
||||
|
||||
| 액션 타입 | 배경색 | 비고 |
|
||||
|---|---|---|
|
||||
| `delete` | `#F04544` | 빨간색 |
|
||||
| `excel_download`, `excel_upload`, `multi_table_excel_upload` | `#212121` | 검정색 |
|
||||
| 그 외 모든 액션 | `#3B83F6` | 파란색 (기본값) |
|
||||
|
||||
배경색은 디자이너에서 액션을 변경하면 자동으로 바뀐다.
|
||||
|
||||
### 너비 (텍스트 글자수별)
|
||||
|
||||
| 글자수 | 너비 |
|
||||
|---|---|
|
||||
| 6글자 이하 | 140px |
|
||||
| 7글자 이상 | 160px |
|
||||
|
||||
### 액션별 기본 아이콘
|
||||
|
||||
디자이너에서 표시모드를 "아이콘" 또는 "아이콘+텍스트"로 변경하면 액션에 맞는 첫 번째 아이콘이 자동 선택된다.
|
||||
|
||||
소스: `frontend/lib/button-icon-map.tsx` > `actionIconMap`
|
||||
|
||||
| action.type | 기본 아이콘 |
|
||||
|---|---|
|
||||
| `save` | Check |
|
||||
| `delete` | Trash2 |
|
||||
| `edit` | Pencil |
|
||||
| `navigate` | ArrowRight |
|
||||
| `modal` | Maximize2 |
|
||||
| `transferData` | SendHorizontal |
|
||||
| `excel_download` | Download |
|
||||
| `excel_upload` | Upload |
|
||||
| `quickInsert` | Zap |
|
||||
| `control` | Settings |
|
||||
| `barcode_scan` | ScanLine |
|
||||
| `operation_control` | Truck |
|
||||
| `event` | Send |
|
||||
| `copy` | Copy |
|
||||
| (그 외/없음) | SquareMousePointer |
|
||||
|
||||
---
|
||||
|
||||
## 2. 코드 반영 현황
|
||||
|
||||
### 컴포넌트 기본값 (신규 버튼 생성 시 적용)
|
||||
|
||||
| 파일 | 내용 |
|
||||
|---|---|
|
||||
| `frontend/lib/registry/components/v2-button-primary/index.ts` | defaultConfig, defaultSize (140x40) |
|
||||
| `frontend/lib/registry/components/v2-button-primary/config.ts` | ButtonPrimaryDefaultConfig |
|
||||
|
||||
### 액션 변경 시 배경색 자동 변경
|
||||
|
||||
| 파일 | 내용 |
|
||||
|---|---|
|
||||
| `frontend/components/screen/config-panels/ButtonConfigPanel.tsx` | 액션 변경 시 배경색/텍스트색 자동 설정 |
|
||||
|
||||
### 렌더링 배경색 우선순위
|
||||
|
||||
| 파일 | 내용 |
|
||||
|---|---|
|
||||
| `frontend/lib/registry/components/v2-button-primary/ButtonPrimaryComponent.tsx` | 배경색 결정 우선순위 개선 |
|
||||
|
||||
배경색 결정 순서:
|
||||
1. `webTypeConfig.backgroundColor`
|
||||
2. `componentConfig.backgroundColor`
|
||||
3. `component.style.backgroundColor`
|
||||
4. `componentConfig.style.backgroundColor`
|
||||
5. `component.style.labelColor` (레거시 호환)
|
||||
6. 액션별 기본 배경색 (`#F04544` / `#212121` / `#3B83F6`)
|
||||
|
||||
### 미반영 (추후 작업)
|
||||
|
||||
- split-panel 내부 버튼의 코드 기본값 (split-panel 컴포넌트가 자체 생성하는 버튼)
|
||||
|
||||
---
|
||||
|
||||
## 3. DB 데이터 매핑 (layout_data JSON)
|
||||
|
||||
버튼은 `layout_data.components[]` 배열 안에 `url`이 `v2-button-primary`인 컴포넌트로 저장된다.
|
||||
|
||||
| 항목 | JSON 위치 | 값 |
|
||||
|---|---|---|
|
||||
| 높이 | `size.height` | `40` |
|
||||
| 너비 | `size.width` | `140` 또는 `160` |
|
||||
| 표시모드 | `overrides.displayMode` | `"icon-text"` |
|
||||
| 아이콘 이름 | `overrides.icon.name` | 액션별 영문 이름 |
|
||||
| 아이콘 타입 | `overrides.icon.type` | `"lucide"` |
|
||||
| 아이콘 크기 | `overrides.icon.size` | `"보통"` |
|
||||
| 텍스트 위치 | `overrides.iconTextPosition` | `"right"` |
|
||||
| 아이콘-텍스트 간격 | `overrides.iconGap` | `6` |
|
||||
| 테두리 모서리 | `overrides.style.borderRadius` | `"8px"` |
|
||||
| 텍스트 색상 | `overrides.style.labelColor` | `"#FFFFFF"` |
|
||||
| 텍스트 크기 | `overrides.style.fontSize` | `"12px"` |
|
||||
| 텍스트 굵기 | `overrides.style.fontWeight` | `"normal"` |
|
||||
| 텍스트 정렬 | `overrides.style.labelTextAlign` | `"left"` |
|
||||
| 배경색 | `overrides.style.backgroundColor` | 액션별 색상 |
|
||||
|
||||
버튼이 위치하는 구조별 경로:
|
||||
- 일반 버튼: `layout_data.components[]`
|
||||
- 탭 위젯 내부: `layout_data.components[].overrides.tabs[].components[]`
|
||||
- split-panel 내부: `layout_data.components[].overrides.rightPanel.components[]`
|
||||
|
||||
---
|
||||
|
||||
## 4. 탑씰(COMPANY_7) 일괄 변경 작업 기록
|
||||
|
||||
### 대상
|
||||
- **회사**: 탑씰 (company_code = 'COMPANY_7')
|
||||
- **테이블**: screen_layouts_v2 (배포서버)
|
||||
- **스크립트**: `backend-node/scripts/btn-bulk-update-company7.ts`
|
||||
- **백업 테이블**: `screen_layouts_v2_backup_company7`
|
||||
|
||||
### 작업 이력
|
||||
|
||||
| 날짜 | 작업 내용 | 비고 |
|
||||
|---|---|---|
|
||||
| 2026-03-13 | 백업 테이블 생성 | |
|
||||
| 2026-03-13 | 전체 버튼 공통 스타일 일괄 적용 | 높이, 아이콘, 텍스트 스타일, 배경색, 모서리 |
|
||||
| 2026-03-13 | 탭 위젯 내부 버튼 스타일 보정 | componentConfig + root style 양쪽 적용 |
|
||||
| 2026-03-13 | fontWeight "400" → "normal" 보정 | |
|
||||
| 2026-03-13 | overrides.style.width 제거 | size.width와 충돌 방지 |
|
||||
| 2026-03-13 | save 액션 55개에 "저장" 텍스트 명시 | |
|
||||
| 2026-03-13 | "엑셀다운로드" → "Excel" 텍스트 통일 | |
|
||||
| 2026-03-13 | Excel 버튼 배경색 #212121 통일 | |
|
||||
| 2026-03-13 | 전체 버튼 너비 140px 통일 | |
|
||||
| 2026-03-13 | 7글자 이상 버튼 너비 160px 재조정 | |
|
||||
| 2026-03-13 | split-panel 내부 버튼 스타일 적용 | BOM관리 등 7개 버튼 |
|
||||
|
||||
### 스킵 항목
|
||||
- `transferData` 액션의 텍스트 없는 버튼 1개 (screen=5976)
|
||||
|
||||
### 알려진 이슈
|
||||
- **반응형 너비 불일치**: 디자이너에서 설정한 `size.width`가 실제 화면(`ResponsiveGridRenderer`)에서 반영되지 않을 수 있음. 버튼 wrapper에 `width` 속성이 누락되어 flex shrink-to-fit 동작으로 너비가 줄어드는 현상. 세로(height)는 정상 반영됨.
|
||||
|
||||
### 원복 (필요 시)
|
||||
|
||||
```sql
|
||||
UPDATE screen_layouts_v2 AS target
|
||||
SET layout_data = backup.layout_data
|
||||
FROM screen_layouts_v2_backup_company7 AS backup
|
||||
WHERE target.layout_id = backup.layout_id;
|
||||
```
|
||||
|
||||
### 백업 테이블 정리
|
||||
|
||||
```sql
|
||||
DROP TABLE screen_layouts_v2_backup_company7;
|
||||
```
|
||||
@@ -0,0 +1,199 @@
|
||||
# [계획서] 카테고리 트리 대분류 추가 모달 - 연속 등록 모드 수정
|
||||
|
||||
> 관련 문서: [맥락노트](./CCA[맥락]-카테고리-연속등록모드.md) | [체크리스트](./CCA[체크]-카테고리-연속등록모드.md)
|
||||
|
||||
## 개요
|
||||
|
||||
기준정보 - 옵션설정 화면에서 트리 구조 카테고리(예: 품목정보 > 재고단위)의 "대분류 추가" 모달이 저장 후 닫히지 않는 버그를 수정합니다.
|
||||
평면 목록용 추가 모달(`CategoryValueAddDialog.tsx`)과 동일한 연속 입력 패턴을 적용합니다.
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
- 대분류 추가 모달에서 값 입력 후 "추가" 클릭 시 **값은 정상 저장됨**
|
||||
- 저장 후 **모달이 닫히지 않고** 폼만 초기화됨 (항상 연속 입력 상태)
|
||||
- "연속 입력" 체크박스 UI가 **없음** → 사용자가 모드를 끌 수 없음
|
||||
- 모달을 닫으려면 "닫기" 버튼 또는 외부 클릭을 해야 함
|
||||
|
||||
### 현재 코드 (CategoryValueManagerTree.tsx - handleAdd, 512~530행)
|
||||
|
||||
```tsx
|
||||
if (response.success) {
|
||||
toast.success("카테고리가 추가되었습니다");
|
||||
// 폼 초기화 (모달은 닫지 않고 연속 입력)
|
||||
setFormData((prev) => ({
|
||||
...prev,
|
||||
valueCode: "",
|
||||
valueLabel: "",
|
||||
description: "",
|
||||
color: "",
|
||||
}));
|
||||
setTimeout(() => addNameRef.current?.focus(), 50);
|
||||
await loadTree(true);
|
||||
if (parentValue) {
|
||||
setExpandedNodes((prev) => new Set([...prev, parentValue.valueId]));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 현재 DialogFooter (809~821행)
|
||||
|
||||
```tsx
|
||||
<DialogFooter className="gap-2 sm:gap-0">
|
||||
<Button variant="outline" onClick={() => setIsAddModalOpen(false)} ...>
|
||||
닫기
|
||||
</Button>
|
||||
<Button onClick={handleAdd} ...>
|
||||
추가
|
||||
</Button>
|
||||
</DialogFooter>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 1. 기본 동작: 저장 후 모달 닫힘
|
||||
|
||||
- "추가" 클릭 → 저장 성공 → 모달 닫힘 + 트리 새로고침
|
||||
- `CategoryValueAddDialog.tsx`(평면 목록 추가 모달)와 동일한 기본 동작
|
||||
|
||||
### 2. 연속 입력 체크박스 추가
|
||||
|
||||
- DialogFooter 좌측에 "연속 입력" 체크박스 표시
|
||||
- 기본값: 체크 해제 (OFF)
|
||||
- 체크 시: 저장 후 폼만 초기화, 모달 유지, 이름 필드에 포커스
|
||||
- 체크 해제 시: 저장 후 모달 닫힘
|
||||
|
||||
---
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
| 상태 | 연속 입력 체크 | 추가 버튼 클릭 후 |
|
||||
|------|---------------|-----------------|
|
||||
| 기본 (체크 해제) | [ ] 연속 입력 | 저장 → 모달 닫힘 → 트리 갱신 |
|
||||
| 연속 모드 (체크) | [x] 연속 입력 | 저장 → 폼 초기화 → 모달 유지 → 이름 필드 포커스 |
|
||||
|
||||
### 모달 하단 레이아웃 (ScreenModal.tsx 패턴)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ [닫기] [추가] │ ← DialogFooter (버튼만)
|
||||
├─────────────────────────────────────────┤
|
||||
│ [x] 저장 후 계속 입력 (연속 등록 모드) │ ← border-t 구분선 아래 별도 영역
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["사용자: '추가' 클릭"] --> B["handleAdd()"]
|
||||
B --> C{"API 호출 성공?"}
|
||||
C -- 실패 --> D["toast.error → 모달 유지"]
|
||||
C -- 성공 --> E["toast.success + loadTree"]
|
||||
E --> F{"continuousAdd?"}
|
||||
F -- true --> G["폼 초기화 + 이름 필드 포커스\n모달 유지"]
|
||||
F -- false --> H["폼 초기화 + 모달 닫힘"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 파일 | 역할 | 변경 내용 |
|
||||
|------|------|----------|
|
||||
| `frontend/components/table-category/CategoryValueManagerTree.tsx` | 트리형 카테고리 값 관리 | 상태 추가, handleAdd 분기, DialogFooter UI |
|
||||
|
||||
- **변경 규모**: 약 20줄 내외 소규모 변경
|
||||
- **참고 파일**: `frontend/components/table-category/CategoryValueAddDialog.tsx` (동일 패턴)
|
||||
|
||||
---
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### 1. 상태 추가 (286행 근처, 모달 상태 선언부)
|
||||
|
||||
```tsx
|
||||
const [continuousAdd, setContinuousAdd] = useState(false);
|
||||
```
|
||||
|
||||
### 2. handleAdd 성공 분기 수정 (512~530행 대체)
|
||||
|
||||
```tsx
|
||||
if (response.success) {
|
||||
toast.success("카테고리가 추가되었습니다");
|
||||
await loadTree(true);
|
||||
if (parentValue) {
|
||||
setExpandedNodes((prev) => new Set([...prev, parentValue.valueId]));
|
||||
}
|
||||
|
||||
if (continuousAdd) {
|
||||
setFormData((prev) => ({
|
||||
...prev,
|
||||
valueCode: "",
|
||||
valueLabel: "",
|
||||
description: "",
|
||||
color: "",
|
||||
}));
|
||||
setTimeout(() => addNameRef.current?.focus(), 50);
|
||||
} else {
|
||||
setFormData({ valueCode: "", valueLabel: "", description: "", color: "", isActive: true });
|
||||
setIsAddModalOpen(false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. DialogFooter + 연속 등록 체크박스 수정 (809~821행 대체)
|
||||
|
||||
DialogFooter는 버튼만 유지하고, 그 아래에 `border-t` 구분선과 체크박스를 별도 영역으로 배치합니다.
|
||||
`ScreenModal.tsx` (1287~1303행) 패턴 그대로입니다.
|
||||
|
||||
```tsx
|
||||
<DialogFooter className="gap-2 sm:gap-0">
|
||||
<Button
|
||||
variant="outline"
|
||||
onClick={() => setIsAddModalOpen(false)}
|
||||
className="h-9 flex-1 text-sm sm:flex-none"
|
||||
>
|
||||
닫기
|
||||
</Button>
|
||||
<Button onClick={handleAdd} className="h-9 flex-1 text-sm sm:flex-none">
|
||||
추가
|
||||
</Button>
|
||||
</DialogFooter>
|
||||
|
||||
{/* 연속 등록 모드 체크박스 - ScreenModal.tsx 패턴 */}
|
||||
<div className="border-t px-4 py-3">
|
||||
<div className="flex items-center gap-2">
|
||||
<Checkbox
|
||||
id="tree-continuous-add"
|
||||
checked={continuousAdd}
|
||||
onCheckedChange={(checked) => setContinuousAdd(checked as boolean)}
|
||||
/>
|
||||
<Label htmlFor="tree-continuous-add" className="cursor-pointer text-sm font-normal select-none">
|
||||
저장 후 계속 입력 (연속 등록 모드)
|
||||
</Label>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 예상 문제 및 대응
|
||||
|
||||
`CategoryValueAddDialog.tsx`와 동일한 패턴이므로 별도 예상 문제 없음.
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- `CategoryValueAddDialog.tsx`(같은 폴더, 같은 목적)의 패턴을 그대로 따름
|
||||
- 기존 수정/삭제 모달 동작은 변경하지 않음
|
||||
- 하위 추가(중분류/소분류) 모달도 동일한 `handleAdd`를 사용하므로 자동 적용
|
||||
- `Checkbox` import는 이미 존재 (24행)하므로 추가 import 불필요
|
||||
- `Label` import는 이미 존재 (53행)하므로 추가 import 불필요
|
||||
- 체크박스 위치/라벨/className 모두 `ScreenModal.tsx` (1287~1303행)과 동일
|
||||
@@ -0,0 +1,84 @@
|
||||
# [맥락노트] 카테고리 트리 대분류 추가 모달 - 연속 등록 모드 수정
|
||||
|
||||
> 관련 문서: [계획서](./CCA[계획]-카테고리-연속등록모드.md) | [체크리스트](./CCA[체크]-카테고리-연속등록모드.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 기준정보 - 옵션설정에서 트리 구조 카테고리(품목정보 > 재고단위 등)의 "대분류 추가" 모달이 저장 후 닫히지 않음
|
||||
- 연속 등록 모드가 하드코딩되어 항상 ON 상태이고, 끌 수 있는 UI가 없음
|
||||
- 같은 폴더의 평면 목록 모달(`CategoryValueAddDialog.tsx`)은 이미 올바르게 구현되어 있음
|
||||
- 동일 패턴을 적용하여 일관성 확보
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 기본값: 연속 등록 OFF (모달 닫힘)
|
||||
|
||||
- **결정**: `continuousAdd` 초기값을 `false`로 설정
|
||||
- **근거**: 대부분의 사용자는 한 건 추가 후 결과를 확인하려 함. 연속 입력은 선택적 기능
|
||||
|
||||
### 2. 체크박스 위치: DialogFooter 아래, border-t 구분선 별도 영역
|
||||
|
||||
- **결정**: `ScreenModal.tsx` (1287~1303행) 패턴 그대로 적용
|
||||
- **근거**: "기준정보 - 부서관리" 추가 모달과 동일한 디자인. 프로젝트 관행 준수
|
||||
- **대안 검토**: `CategoryValueAddDialog.tsx`는 DialogFooter 안에 체크박스 배치 → 부서 모달과 다른 디자인이므로 기각
|
||||
|
||||
### 3. 라벨: "저장 후 계속 입력 (연속 등록 모드)"
|
||||
|
||||
- **결정**: `ScreenModal.tsx`와 동일한 라벨 텍스트 사용
|
||||
- **근거**: 부서 추가 모달과 동일한 문구로 사용자 혼란 방지
|
||||
|
||||
### 4. localStorage 미사용
|
||||
|
||||
- **결정**: 컴포넌트 state만 사용, localStorage 영속화 안 함
|
||||
- **근거**: `CategoryValueAddDialog.tsx`(같은 폴더 형제 컴포넌트)가 localStorage를 쓰지 않음. `ScreenModal.tsx`는 사용하지만 동적 화면 모달 전용 기능이므로 범위가 다름
|
||||
|
||||
### 5. 수정 대상: handleAdd 함수만
|
||||
|
||||
- **결정**: 저장 성공 분기에서만 `continuousAdd` 체크
|
||||
- **근거**: 실패 시에는 원래대로 모달 유지 + 에러 표시. 분기가 필요한 건 성공 시뿐
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 대상 | `frontend/components/table-category/CategoryValueManagerTree.tsx` | 트리형 카테고리 값 관리 (대분류/중분류/소분류) |
|
||||
| 참고 패턴 (로직) | `frontend/components/table-category/CategoryValueAddDialog.tsx` | 평면 목록 추가 모달 - continuousAdd 분기 로직 |
|
||||
| 참고 패턴 (UI) | `frontend/components/common/ScreenModal.tsx` | 동적 화면 모달 - 체크박스 위치/라벨/스타일 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### 현재 handleAdd 흐름
|
||||
|
||||
```
|
||||
handleAdd() → API 호출 → 성공 시:
|
||||
1. toast.success
|
||||
2. 폼 초기화 (모달 유지 - 하드코딩)
|
||||
3. addNameRef 포커스
|
||||
4. loadTree(true) - 펼침 상태 유지
|
||||
5. parentValue 있으면 해당 노드 펼침
|
||||
```
|
||||
|
||||
### 변경 후 handleAdd 흐름
|
||||
|
||||
```
|
||||
handleAdd() → API 호출 → 성공 시:
|
||||
1. toast.success
|
||||
2. loadTree(true) + parentValue 펼침
|
||||
3. continuousAdd 체크:
|
||||
- true: 폼 초기화 + addNameRef 포커스 (모달 유지)
|
||||
- false: 폼 초기화 + setIsAddModalOpen(false) (모달 닫힘)
|
||||
```
|
||||
|
||||
### import 현황
|
||||
|
||||
- `Checkbox`: 24행에서 이미 import (`@/components/ui/checkbox`)
|
||||
- `Label`: 53행에서 이미 import (`@/components/ui/label`)
|
||||
- 추가 import 불필요
|
||||
@@ -0,0 +1,52 @@
|
||||
# [체크리스트] 카테고리 트리 대분류 추가 모달 - 연속 등록 모드 수정
|
||||
|
||||
> 관련 문서: [계획서](./CCA[계획]-카테고리-연속등록모드.md) | [맥락노트](./CCA[맥락]-카테고리-연속등록모드.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (구현 완료)
|
||||
- 현재 단계: 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 상태 추가
|
||||
|
||||
- [x] `CategoryValueManagerTree.tsx` 모달 상태 선언부(286행 근처)에 `continuousAdd` 상태 추가
|
||||
|
||||
### 2단계: handleAdd 분기 수정
|
||||
|
||||
- [x] `handleAdd` 성공 분기(512~530행)에서 `continuousAdd` 체크 분기 추가
|
||||
- [x] `continuousAdd === true`: 폼 초기화 + addNameRef 포커스 (모달 유지)
|
||||
- [x] `continuousAdd === false`: 폼 초기화 + `setIsAddModalOpen(false)` (모달 닫힘)
|
||||
|
||||
### 3단계: DialogFooter UI 수정
|
||||
|
||||
- [x] DialogFooter(809~821행)는 버튼만 유지
|
||||
- [x] DialogFooter 아래에 `border-t px-4 py-3` 영역 추가
|
||||
- [x] "저장 후 계속 입력 (연속 등록 모드)" 체크박스 배치
|
||||
- [x] ScreenModal.tsx (1287~1303행) 패턴과 동일한 className/라벨 사용
|
||||
|
||||
### 4단계: 검증
|
||||
|
||||
- [ ] 대분류 추가: 체크 해제 상태에서 추가 → 모달 닫힘 확인
|
||||
- [ ] 대분류 추가: 체크 상태에서 추가 → 모달 유지 + 폼 초기화 + 포커스 확인
|
||||
- [ ] 하위 추가(중분류/소분류): 동일하게 동작하는지 확인
|
||||
- [ ] 수정/삭제 모달: 기존 동작 변화 없음 확인
|
||||
|
||||
### 5단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인
|
||||
- [x] 이 체크리스트 완료 표시 업데이트
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-11 | 계획서, 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-11 | 구현 완료 (1~3단계, 5단계 정리). 4단계 검증은 수동 테스트 필요 |
|
||||
@@ -0,0 +1,122 @@
|
||||
# [계획서] 카테고리 드롭다운 - 3단계 깊이 구분 표시
|
||||
|
||||
> 관련 문서: [맥락노트](./CTI[맥락]-카테고리-깊이구분.md) | [체크리스트](./CTI[체크]-카테고리-깊이구분.md)
|
||||
>
|
||||
> 상태: **완료** (2026-03-11)
|
||||
|
||||
## 개요
|
||||
|
||||
카테고리 타입(`source="category"`) 드롭다운에서 3단계 계층(대분류 > 중분류 > 소분류)의 들여쓰기가 시각적으로 구분되지 않는 문제를 수정합니다.
|
||||
|
||||
---
|
||||
|
||||
## 변경 전 동작
|
||||
|
||||
- `category_values` 테이블은 `parent_value_id`, `depth` 컬럼으로 3단계 계층 구조를 지원
|
||||
- 백엔드 `buildHierarchy()`가 트리 구조를 정상적으로 반환
|
||||
- 프론트엔드 `flattenTree()`가 트리를 평탄화하면서 **일반 ASCII 공백(`" "`)** 으로 들여쓰기 생성
|
||||
- HTML이 연속 공백을 하나로 축소(collapse)하여 depth 1과 depth 2가 동일하게 렌더링됨
|
||||
|
||||
### 변경 전 코드 (flattenTree)
|
||||
|
||||
```tsx
|
||||
const prefix = depth > 0 ? " ".repeat(depth) + "└ " : "";
|
||||
```
|
||||
|
||||
### 변경 전 렌더링 결과
|
||||
|
||||
```
|
||||
신예철
|
||||
└ 신2
|
||||
└ 신22 ← depth 2인데 depth 1과 구분 불가
|
||||
└ 신3
|
||||
└ 신4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 일반 공백을 Non-Breaking Space(`\u00A0`)로 교체
|
||||
|
||||
- `\u00A0`는 HTML에서 축소되지 않으므로 depth별 들여쓰기가 정확히 유지됨
|
||||
- depth당 3칸(`\u00A0\u00A0\u00A0`)으로 시각적 계층 구분을 명확히 함
|
||||
- 백엔드 변경 없음 (트리 구조는 이미 정상)
|
||||
|
||||
### 변경 후 코드 (flattenTree)
|
||||
|
||||
```tsx
|
||||
const prefix = depth > 0 ? "\u00A0\u00A0\u00A0".repeat(depth) + "└ " : "";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
| depth | prefix | 드롭다운 표시 |
|
||||
|-------|--------|-------------|
|
||||
| 0 (대분류) | `""` | `신예철` |
|
||||
| 1 (중분류) | `"\u00A0\u00A0\u00A0└ "` | `···└ 신2` |
|
||||
| 2 (소분류) | `"\u00A0\u00A0\u00A0\u00A0\u00A0\u00A0└ "` | `······└ 신22` |
|
||||
|
||||
### 변경 전후 비교
|
||||
|
||||
```
|
||||
변경 전: 변경 후:
|
||||
신예철 신예철
|
||||
└ 신2 └ 신2
|
||||
└ 신22 ← 구분 불가 └ 신22 ← 명확히 구분
|
||||
└ 신3 └ 신3
|
||||
└ 신4 └ 신4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[category_values 테이블] -->|parent_value_id, depth| B[백엔드 buildHierarchy]
|
||||
B -->|트리 JSON 응답| C[프론트엔드 API 호출]
|
||||
C --> D[flattenTree 함수]
|
||||
D -->|"depth별 \u00A0 prefix 생성"| E[SelectOption 배열]
|
||||
E --> F{렌더링 모드}
|
||||
F -->|비검색| G[SelectItem - label 표시]
|
||||
F -->|검색| H[CommandItem - displayLabel 표시]
|
||||
|
||||
style D fill:#f96,stroke:#333,color:#000
|
||||
```
|
||||
|
||||
**변경 지점**: `flattenTree` 함수 내 prefix 생성 로직 (주황색 표시)
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 파일 경로 | 변경 내용 | 변경 규모 |
|
||||
|-----------|----------|----------|
|
||||
| `frontend/components/v2/V2Select.tsx` (904행) | `flattenTree` prefix를 `\u00A0` 기반으로 변경 | 1줄 |
|
||||
| `frontend/components/unified/UnifiedSelect.tsx` (632행) | 동일한 `flattenTree` prefix 변경 | 1줄 |
|
||||
|
||||
---
|
||||
|
||||
## 영향받는 기존 로직
|
||||
|
||||
V2Select.tsx의 `resolvedValue`(979행)에서 prefix를 제거하는 정규식:
|
||||
|
||||
```tsx
|
||||
const cleanLabel = o.label.replace(/^[\s└]+/, "").trim();
|
||||
```
|
||||
|
||||
- JavaScript `\s`는 `\u00A0`를 포함하므로 기존 정규식이 정상 동작함
|
||||
- 추가 수정 불필요
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- 백엔드 변경 없이 프론트엔드 표시 로직만 수정
|
||||
- `flattenTree` 공통 함수 수정이므로 카테고리 타입 드롭다운 전체에 자동 적용
|
||||
- DB 저장값(`valueCode`)에는 영향 없음 — `label`만 변경
|
||||
- 기존 prefix strip 정규식(`/^[\s└]+/`)과 호환 유지
|
||||
- `V2Select`와 `UnifiedSelect` 두 곳의 동일 패턴을 일관되게 수정
|
||||
@@ -0,0 +1,105 @@
|
||||
# [맥락노트] 카테고리 드롭다운 - 3단계 깊이 구분 표시
|
||||
|
||||
> 관련 문서: [계획서](./CTI[계획]-카테고리-깊이구분.md) | [체크리스트](./CTI[체크]-카테고리-깊이구분.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 품목정보 등록 모달의 "재고단위" 등 카테고리 드롭다운에서 3단계 계층이 시각적으로 구분되지 않음
|
||||
- 예: "신22"가 "신2"의 하위인데, "신3", "신4"와 같은 레벨로 보임
|
||||
- 사용자가 대분류/중분류/소분류 관계를 파악할 수 없어 잘못된 항목을 선택할 위험
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 원인: HTML 공백 축소(collapse)
|
||||
|
||||
- **현상**: `flattenTree`에서 `" ".repeat(depth)`로 들여쓰기를 만들지만, HTML이 연속 공백을 하나로 합침
|
||||
- **결과**: depth 1(`" └ "`)과 depth 2(`" └ "`)가 동일하게 렌더링됨
|
||||
- **확인**: `SelectItem`, `CommandItem` 모두 `white-space: pre` 미적용 상태
|
||||
|
||||
### 2. 해결: Non-Breaking Space(`\u00A0`) 사용
|
||||
|
||||
- **결정**: 일반 공백 `" "`를 `"\u00A0"`로 교체
|
||||
- **근거**: `\u00A0`는 HTML에서 축소되지 않아 depth별 들여쓰기가 정확히 유지됨
|
||||
- **대안 검토**:
|
||||
- `white-space: pre` CSS 적용 → 기각 (SelectItem, CommandItem 양쪽 모두 수정 필요, shadcn 기본 스타일 오버라이드 부담)
|
||||
- CSS `padding-left` 사용 → 기각 (label 문자열 기반 옵션 구조에서 개별 아이템에 스타일 전달 어려움)
|
||||
- 트리 문자(`│`, `├`, `└`) 조합 → 기각 (과도한 시각 정보, 단순 들여쓰기면 충분)
|
||||
|
||||
### 3. depth당 3칸 `\u00A0`
|
||||
|
||||
- **결정**: `"\u00A0\u00A0\u00A0".repeat(depth)` (depth당 3칸)
|
||||
- **근거**: 기존 2칸은 `\u00A0`로 바꿔도 depth간 차이가 작음. 3칸이 시각적 구분에 적절
|
||||
|
||||
### 4. 두 파일 동시 수정
|
||||
|
||||
- **결정**: `V2Select.tsx`와 `UnifiedSelect.tsx` 모두 수정
|
||||
- **근거**: 동일한 `flattenTree` 패턴이 두 컴포넌트에 존재. 하나만 수정하면 불일치 발생
|
||||
|
||||
### 5. 기존 prefix strip 정규식 호환
|
||||
|
||||
- **확인**: V2Select.tsx 979행의 `o.label.replace(/^[\s└]+/, "").trim()`
|
||||
- **근거**: JavaScript `\s`는 `\u00A0`를 포함하므로 추가 수정 불필요
|
||||
|
||||
---
|
||||
|
||||
## 구현 중 발견한 사항
|
||||
|
||||
### CAT_ vs CATEGORY_ 접두사 불일치
|
||||
|
||||
테스트 과정에서 최고 관리자 계정으로 리스트 조회 시 `CAT_MMLL6U02_QH2V` 같은 코드가 그대로 표시되는 현상 발견.
|
||||
|
||||
- **원인**: 카테고리 값 생성 함수가 두 곳에 존재하며 접두사가 다름
|
||||
- `CategoryValueAddDialog.tsx`: `CATEGORY_` 접두사
|
||||
- `CategoryValueManagerTree.tsx`: `CAT_` 접두사
|
||||
- **영향**: 리스트 해석 로직(`V2Repeater`, `InteractiveDataTable`, `UnifiedRepeater`)이 `CATEGORY_` 접두사만 인식하여 `CAT_` 코드는 라벨 변환 실패
|
||||
- **판단**: 일반 회사 계정에서는 정상 동작 확인. 본 작업(들여쓰기 표시) 범위 외로 별도 이슈로 분리
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 완료 | `frontend/components/v2/V2Select.tsx` | flattenTree 함수 (904행) |
|
||||
| 수정 완료 | `frontend/components/unified/UnifiedSelect.tsx` | flattenTree 함수 (632행) |
|
||||
| 백엔드 (변경 없음) | `backend-node/src/services/tableCategoryValueService.ts` | buildHierarchy 메서드 |
|
||||
| UI 컴포넌트 (변경 없음) | `frontend/components/ui/select.tsx` | SelectItem 렌더링 |
|
||||
| UI 컴포넌트 (변경 없음) | `frontend/components/ui/command.tsx` | CommandItem 렌더링 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### flattenTree 동작 흐름
|
||||
|
||||
```
|
||||
백엔드 API 응답 (트리 구조):
|
||||
{
|
||||
valueCode: "CAT_001", valueLabel: "신예철", children: [
|
||||
{ valueCode: "CAT_002", valueLabel: "신2", children: [
|
||||
{ valueCode: "CAT_003", valueLabel: "신22", children: [] }
|
||||
]},
|
||||
{ valueCode: "CAT_004", valueLabel: "신3", children: [] },
|
||||
{ valueCode: "CAT_005", valueLabel: "신4", children: [] }
|
||||
]
|
||||
}
|
||||
|
||||
→ flattenTree 변환 후 (SelectOption 배열):
|
||||
[
|
||||
{ value: "CAT_001", label: "신예철" },
|
||||
{ value: "CAT_002", label: "\u00A0\u00A0\u00A0└ 신2" },
|
||||
{ value: "CAT_003", label: "\u00A0\u00A0\u00A0\u00A0\u00A0\u00A0└ 신22" },
|
||||
{ value: "CAT_004", label: "\u00A0\u00A0\u00A0└ 신3" },
|
||||
{ value: "CAT_005", label: "\u00A0\u00A0\u00A0└ 신4" }
|
||||
]
|
||||
```
|
||||
|
||||
### value vs label 분리
|
||||
|
||||
- `value` (저장값): `valueCode` — DB에 저장되는 값, 들여쓰기 없음
|
||||
- `label` (표시값): prefix + `valueLabel` — 화면에만 보이는 값, 들여쓰기 포함
|
||||
- 데이터 무결성에 영향 없음
|
||||
@@ -0,0 +1,53 @@
|
||||
# [체크리스트] 카테고리 드롭다운 - 3단계 깊이 구분 표시
|
||||
|
||||
> 관련 문서: [계획서](./CTI[계획]-카테고리-깊이구분.md) | [맥락노트](./CTI[맥락]-카테고리-깊이구분.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (완료)
|
||||
- 현재 단계: 전체 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 코드 수정
|
||||
|
||||
- [x] `V2Select.tsx` 904행 — `flattenTree` prefix를 `\u00A0` 기반으로 변경
|
||||
- [x] `UnifiedSelect.tsx` 632행 — 동일한 `flattenTree` prefix 변경
|
||||
|
||||
### 2단계: 검증
|
||||
|
||||
- [x] depth 1 항목: 3칸 들여쓰기 + `└` 표시 확인
|
||||
- [x] depth 2 항목: 6칸 들여쓰기 + `└` 표시, depth 1과 명확히 구분됨 확인
|
||||
- [x] depth 0 항목: 들여쓰기 없이 원래대로 표시 확인
|
||||
- [x] 항목 선택 후 값이 정상 저장되는지 확인 (valueCode 기준)
|
||||
- [x] 기존 prefix strip 로직 정상 동작 확인 — JS `\s`가 `\u00A0` 포함하므로 호환
|
||||
- [x] 검색 가능 모드(Combobox): 정상 동작 확인
|
||||
- [x] 비검색 모드(Select): 렌더링 정상 확인
|
||||
|
||||
### 3단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인 (기존 에러 제외)
|
||||
- [x] 계맥체 문서 최신화
|
||||
|
||||
---
|
||||
|
||||
## 참고: 최고 관리자 계정 표시 이슈
|
||||
|
||||
- 최고 관리자(`company_code = "*"`)로 리스트 조회 시 `CAT_MMLL6U02_QH2V` 같은 코드값이 그대로 노출되는 현상 발견
|
||||
- 원인: `CategoryValueManagerTree.tsx`의 `generateCode()`가 `CAT_` 접두사를 사용하나, 리스트 해석 로직은 `CATEGORY_` 접두사만 인식
|
||||
- 일반 회사 계정에서는 정상 표시됨을 확인
|
||||
- 본 작업 범위 외로 판단하여 별도 이슈로 분리
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-11 | 계획서, 맥락노트, 체크리스트 작성 |
|
||||
| 2026-03-11 | 1단계 코드 수정 완료 (V2Select.tsx, UnifiedSelect.tsx) |
|
||||
| 2026-03-11 | 2단계 검증 완료, 3단계 문서 정리 완료 |
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: IMX[계획] IMAP 메일 기능 확장
|
||||
description: 메일 삭제, SMTP 발송, 폴더 전환, 첨부파일 다운로드, 이동, 답장/전달 구현
|
||||
type: plan
|
||||
---
|
||||
|
||||
# IMX 계획 — IMAP 메일 기능 확장
|
||||
|
||||
## 개요
|
||||
|
||||
기존 메일 조회/읽음처리만 되던 IMAP 페이지에 전체 메일 클라이언트 기능 추가.
|
||||
nodemailer(이미 설치), imapflow(이미 설치), TipTap v2(신규 설치) 기반.
|
||||
|
||||
## 현재 동작
|
||||
|
||||
- 계정 목록 조회
|
||||
- 메일 스트리밍 목록
|
||||
- 메일 상세 보기
|
||||
- 읽음 처리
|
||||
- 메일 삭제 (백엔드만, UI 버튼 있으나 실제 연동 확인 필요)
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
- 좌측 패널: 폴더 목록 (INBOX, Sent, Trash, Spam 등) + 미읽음 수
|
||||
- 메일 상세 우측 버튼: 답장 / 전달 / 이동 / 삭제(→Trash)
|
||||
- 하단 첨부파일 목록 + 다운로드 버튼
|
||||
- 우상단 `작성` 버튼 → Dialog (TipTap 에디터, to/cc/subject)
|
||||
- 답장/전달 시 원문 인용 자동 삽입
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 메일 관리 (IMAP) [작성] [계정추가] │
|
||||
├──────────────┬───────────────────┬───────────────────────────────┤
|
||||
│ [계정목록] │ [검색창] │ 제목: 보안 알림 │
|
||||
│ │ │ From: Google │
|
||||
│ Gmail │ ● Google 오후1:51 │ To: yechul@gmail.com │
|
||||
│ Wace │ 보안 알림 │ Date: 2026-03-27 │
|
||||
│ │ ● GitHub 오전9:48 │ [답장][전달][이동▼][삭제] │
|
||||
│ ───────── │ Sudo code │ ───────────────────────────── │
|
||||
│ [폴더목록] │ │ <HTML 본문> │
|
||||
│ INBOX (3) │ │ │
|
||||
│ Sent │ │ 📎 첨부파일 │
|
||||
│ Trash │ │ file.pdf (120KB) [다운로드] │
|
||||
│ Spam │ │ │
|
||||
└──────────────┴───────────────────┴───────────────────────────────┘
|
||||
```
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
FE[page.tsx] -->|GET /folders| BE_CTRL[userMailController]
|
||||
FE -->|POST /send| BE_CTRL
|
||||
FE -->|POST /move| BE_CTRL
|
||||
FE -->|GET /attachment| BE_CTRL
|
||||
BE_CTRL --> IMAP[userMailImapService]
|
||||
BE_CTRL --> SMTP[userMailSmtpService - 신규]
|
||||
IMAP --> Pool[imapConnectionPool]
|
||||
SMTP --> Nodemailer[nodemailer]
|
||||
```
|
||||
|
||||
## 변경 파일
|
||||
|
||||
### 신규
|
||||
- `backend-node/src/services/userMailSmtpService.ts` — SMTP 발송 전용
|
||||
|
||||
### 수정
|
||||
- `backend-node/src/services/userMailImapService.ts` — 폴더목록, 이동, 첨부파일 추가
|
||||
- `backend-node/src/controllers/userMailController.ts` — 신규 엔드포인트 핸들러
|
||||
- `backend-node/src/routes/userMailRoutes.ts` — 신규 라우트 등록
|
||||
- `frontend/lib/api/userMail.ts` — 신규 API 함수
|
||||
- `frontend/app/(main)/mail/imap/page.tsx` — UI 전면 확장
|
||||
|
||||
## 신규 API 엔드포인트
|
||||
|
||||
| Method | Path | 설명 |
|
||||
|--------|------|------|
|
||||
| GET | `/user-mail/accounts/:id/folders` | 폴더 목록 + 미읽음 수 |
|
||||
| GET | `/user-mail/accounts/:id/folders/:folder/mails/stream` | 폴더별 메일 스트리밍 |
|
||||
| POST | `/user-mail/accounts/:id/mails/:seqno/move` | 메일 이동 `{ targetFolder }` |
|
||||
| GET | `/user-mail/accounts/:id/mails/:seqno/attachment/:partId` | 첨부파일 다운로드 (스트리밍) |
|
||||
| POST | `/user-mail/accounts/:id/send` | 메일 발송 `{ to, cc, subject, html, text, inReplyTo?, references? }` |
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### userMailSmtpService.ts
|
||||
```typescript
|
||||
// SMTP 포트 추론: useTls true → 465, false → 587
|
||||
// Gmail: smtp.gmail.com, wace.me: mail.wace.me 또는 host 에서 도메인 추출
|
||||
// nodemailer createTransport + sendMail
|
||||
// 답장: inReplyTo, references 헤더 설정
|
||||
```
|
||||
|
||||
### userMailImapService.ts 추가 메서드
|
||||
```typescript
|
||||
listFolders(account): Promise<{ path, name, unseen }[]> // client.list({ statusQuery })
|
||||
moveMail(account, seqno, targetFolder): Promise<Result> // messageMove
|
||||
downloadAttachment(account, seqno, partId, res): Promise<void> // download() + pipeline(res)
|
||||
```
|
||||
|
||||
### page.tsx 추가 UI
|
||||
- `folders` state: 폴더 목록
|
||||
- `currentFolder` state: 현재 폴더 (기본 INBOX)
|
||||
- `ComposeDialog`: TipTap 에디터 + to/cc/subject 필드
|
||||
- `composeMode`: 'new' | 'reply' | 'forward'
|
||||
- 메일 상세 버튼: 답장, 전달, 이동(DropdownMenu), 삭제
|
||||
|
||||
## 예상 문제
|
||||
|
||||
1. **Gmail SMTP 포트**: Gmail은 587(STARTTLS) 또는 465(SSL). host에서 자동 추론.
|
||||
2. **폴더명 인코딩**: 한글 폴더 등 UTF-7/UTF-8 혼용 → imapflow가 자동 처리
|
||||
3. **첨부파일 partId**: bodyStructure 파싱이 복잡 → `client.download(seqno, partId)` 직접 사용
|
||||
4. **TipTap SSR**: Next.js에서 dynamic import 필요 (`ssr: false`)
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- SMTP 서비스는 IMAP 서비스와 완전 분리 (파일 분리)
|
||||
- 첨부파일은 서버에 저장하지 않고 스트리밍으로 직접 응답
|
||||
- 답장/전달 인용: `<blockquote>` + RFC 2822 헤더 표준 준수
|
||||
- TipTap은 dynamic import로 SSR 방지
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: IMX[맥락] IMAP 메일 기능 확장
|
||||
description: 왜 이 기능들을 추가하는가, 핵심 결정 근거
|
||||
type: context
|
||||
---
|
||||
|
||||
# IMX 맥락 — IMAP 메일 기능 확장
|
||||
|
||||
## 왜 하는가
|
||||
|
||||
ERP 시스템에서 메일 확인만 되면 의미가 없음. 거래처 메일 수신 후 바로 답장, 견적서 첨부파일 저장, 담당자 전달까지 워크플로우가 연결되어야 실용적.
|
||||
|
||||
## 핵심 결정 + 근거
|
||||
|
||||
### SMTP 서비스 분리 (`userMailSmtpService.ts`)
|
||||
- IMAP(수신)과 SMTP(송신)은 프로토콜 자체가 다름
|
||||
- 파일 분리로 각각 독립적으로 교체/테스트 가능
|
||||
- nodemailer는 이미 설치됨 (추가 의존성 없음)
|
||||
|
||||
### TipTap v2 선택 (메일 에디터)
|
||||
- ProseMirror 기반 → 안정적, 확장 용이
|
||||
- `@tiptap/react` 공식 패키지 → Next.js 15 호환
|
||||
- Quill보다 번들 크기 작음 (~100KB vs ~200KB)
|
||||
- dynamic import (`ssr: false`)로 SSR 문제 회피
|
||||
|
||||
### 첨부파일 스트리밍
|
||||
- 서버에 임시 저장하지 않음 → 디스크 절약, 보안
|
||||
- `imapflow client.download()` → `stream/promises pipeline()` → HTTP 응답
|
||||
- 대용량 파일도 메모리 부담 없음
|
||||
|
||||
### 메일 삭제 = Trash 이동
|
||||
- 즉시 삭제(`messageDelete`) 대신 Trash 폴더 이동
|
||||
- 실수로 삭제 시 복구 가능
|
||||
- Gmail/wace.me 모두 Trash 폴더 표준 지원
|
||||
|
||||
### 폴더 구조 표시
|
||||
- `client.list({ statusQuery: { unseen: true } })` 로 미읽음 수 포함
|
||||
- 폴더 클릭 시 기존 스트리밍 로직 재활용 (folder 파라미터 추가)
|
||||
|
||||
### 답장/전달 RFC 준수
|
||||
- `inReplyTo`, `references` 헤더 → 메일 클라이언트에서 스레드로 묶임
|
||||
- `<blockquote>` 인용 → Gmail/Outlook 모두 올바르게 렌더링
|
||||
|
||||
## 관련 파일
|
||||
|
||||
- `backend-node/src/services/userMailImapService.ts` — IMAP 수신 로직
|
||||
- `backend-node/src/services/imapConnectionPool.ts` — 커넥션 풀 (건드리지 않음)
|
||||
- `backend-node/src/services/mailCache.ts` — TTL 캐시 (건드리지 않음)
|
||||
- `frontend/app/(main)/mail/imap/page.tsx` — 메인 UI
|
||||
|
||||
## 기술 참고
|
||||
|
||||
- imapflow `client.list()` → statusQuery 옵션으로 unseen 포함
|
||||
- imapflow `client.messageMove(seqno, folder)` → UID 기반 이동
|
||||
- imapflow `client.download(seqno, partId)` → ReadableStream 반환
|
||||
- nodemailer `createTransport({ host, port, secure, auth })` → `sendMail()`
|
||||
- RFC 2822 §3.6.4: `In-Reply-To`, `References` 헤더
|
||||
- W3C HTML Threading: `<blockquote cite="mid:...">` 권장
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: IMX[체크] IMAP 메일 기능 확장
|
||||
description: 구현 및 검증 체크리스트
|
||||
type: checklist
|
||||
---
|
||||
|
||||
# IMX 체크리스트 — IMAP 메일 기능 확장
|
||||
|
||||
## 공정 상태: 0%
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### Unit A — 백엔드 서비스
|
||||
- [ ] `userMailImapService.ts`: `listFolders()` 추가
|
||||
- [ ] `userMailImapService.ts`: `streamMailsByFolder()` 추가
|
||||
- [ ] `userMailImapService.ts`: `moveMail()` 추가
|
||||
- [ ] `userMailImapService.ts`: `downloadAttachment()` 추가
|
||||
- [ ] `userMailSmtpService.ts` 신규 생성 (nodemailer 기반)
|
||||
- [ ] TypeScript 에러 없음
|
||||
|
||||
### Unit B — 백엔드 컨트롤러/라우트
|
||||
- [ ] `userMailController.ts`: `listFolders`, `streamFolderMails`, `moveMail`, `downloadAttachment`, `sendMail` 핸들러
|
||||
- [ ] `userMailRoutes.ts`: 5개 신규 라우트 등록
|
||||
- [ ] TypeScript 에러 없음
|
||||
|
||||
### Unit C — 프론트엔드 API
|
||||
- [ ] `userMail.ts`: `getUserMailFolders()` 추가
|
||||
- [ ] `userMail.ts`: `streamFolderMails()` 추가
|
||||
- [ ] `userMail.ts`: `moveUserMail()` 추가
|
||||
- [ ] `userMail.ts`: `sendUserMail()` 추가
|
||||
- [ ] `userMail.ts`: 첨부파일 다운로드 URL 헬퍼 추가
|
||||
|
||||
### Unit D — 프론트엔드 UI (TipTap 설치 포함)
|
||||
- [ ] TipTap 패키지 설치 (`@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-link`)
|
||||
- [ ] 좌측 패널: 폴더 목록 + 미읽음 수
|
||||
- [ ] 폴더 클릭 → 해당 폴더 메일 스트리밍
|
||||
- [ ] 메일 상세: 답장/전달/이동/삭제 버튼
|
||||
- [ ] ComposeDialog: TipTap 에디터 + to/cc/subject
|
||||
- [ ] 답장/전달 시 원문 인용 자동 삽입
|
||||
- [ ] 첨부파일 목록 + 다운로드 링크
|
||||
- [ ] TypeScript 에러 없음
|
||||
|
||||
## 검증 체크리스트
|
||||
|
||||
- [ ] 폴더 목록이 좌측 패널에 표시됨 (INBOX, Sent, Trash 등)
|
||||
- [ ] 폴더 클릭 시 해당 폴더 메일이 로드됨
|
||||
- [ ] 메일 삭제 버튼 클릭 → Trash로 이동됨
|
||||
- [ ] 메일 이동 드롭다운 → 다른 폴더로 이동됨
|
||||
- [ ] 첨부파일 있는 메일에서 다운로드 버튼 동작
|
||||
- [ ] 새 메일 작성 → 발송 성공
|
||||
- [ ] 답장 → To 자동 입력, 원문 인용 포함
|
||||
- [ ] 전달 → 원문 전체 포함
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 일자 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-27 | PCC 작성, 구현 시작 |
|
||||
@@ -0,0 +1,374 @@
|
||||
# [계획서] 렉 구조 위치코드/위치명 포맷 사용자 설정
|
||||
|
||||
> 관련 문서: [맥락노트](./LFC[맥락]-위치포맷-사용자설정.md) | [체크리스트](./LFC[체크]-위치포맷-사용자설정.md)
|
||||
|
||||
## 개요
|
||||
|
||||
물류관리 > 창고정보 관리 > 렉 구조 등록 모달에서 생성되는 **위치코드(`location_code`)와 위치명(`location_name`)의 포맷을 관리자가 화면 디자이너에서 자유롭게 설정**할 수 있도록 합니다.
|
||||
|
||||
현재 위치코드/위치명 생성 로직은 하드코딩되어 있어, 구분자("-"), 세그먼트 순서(창고코드-층-구역-열-단), 한글 접미사("구역", "열", "단") 등을 변경할 수 없습니다.
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
### 1. 타입/설정에 패턴 필드가 정의되어 있지만 사용하지 않음
|
||||
|
||||
`types.ts`(57~58행)에 `codePattern`/`namePattern`이 정의되어 있고, `config.ts`(14~15행)에 기본값도 있으나, 실제 컴포넌트에서는 **전혀 참조하지 않음**:
|
||||
|
||||
```typescript
|
||||
// types.ts:57~58 - 정의만 있음
|
||||
codePattern?: string; // 코드 패턴 (예: "{warehouse}-{floor}{zone}-{row:02d}-{level}")
|
||||
namePattern?: string; // 이름 패턴 (예: "{zone}구역-{row:02d}열-{level}단")
|
||||
|
||||
// config.ts:14~15 - 기본값만 있음
|
||||
codePattern: "{warehouseCode}-{floor}{zone}-{row:02d}-{level}",
|
||||
namePattern: "{zone}구역-{row:02d}열-{level}단",
|
||||
```
|
||||
|
||||
### 2. 위치 코드 생성 하드코딩 (RackStructureComponent.tsx:494~510)
|
||||
|
||||
```tsx
|
||||
const generateLocationCode = useCallback(
|
||||
(row: number, level: number): { code: string; name: string } => {
|
||||
const warehouseCode = context?.warehouseCode || "WH001";
|
||||
const floor = context?.floor;
|
||||
const zone = context?.zone || "A";
|
||||
|
||||
const floorPrefix = floor ? `${floor}` : "";
|
||||
const code = `${warehouseCode}-${floorPrefix}${zone}-${row.toString().padStart(2, "0")}-${level}`;
|
||||
|
||||
const zoneName = zone.includes("구역") ? zone : `${zone}구역`;
|
||||
const floorNamePrefix = floor ? `${floor}-` : "";
|
||||
const name = `${floorNamePrefix}${zoneName}-${row.toString().padStart(2, "0")}열-${level}단`;
|
||||
|
||||
return { code, name };
|
||||
},
|
||||
[context],
|
||||
);
|
||||
```
|
||||
|
||||
### 3. ConfigPanel에 포맷 관련 설정 UI 없음
|
||||
|
||||
`RackStructureConfigPanel.tsx`에는 필드 매핑, 제한 설정, UI 설정만 있고, `codePattern`/`namePattern`을 편집하는 UI가 없음.
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 1. ConfigPanel에 "포맷 설정" 섹션 추가
|
||||
|
||||
화면 디자이너 좌측 속성 패널의 v2-rack-structure ConfigPanel에 새 섹션이 추가됨:
|
||||
|
||||
- 위치코드/위치명 각각의 세그먼트 목록
|
||||
- 최상단에 컬럼 헤더(`라벨` / `구분` / `자릿수`) 표시
|
||||
- 세그먼트별로 **드래그 순서변경**, **체크박스로 한글 라벨 표시/숨김**, **라벨 텍스트 입력**, **구분자 입력**, **자릿수 입력**
|
||||
- 자릿수 필드는 숫자 타입(열, 단)만 활성화, 나머지(창고코드, 층, 구역)는 비활성화
|
||||
- 변경 시 실시간 미리보기로 결과 확인
|
||||
|
||||
### 2. 컴포넌트에서 config 기반 코드 생성
|
||||
|
||||
`RackStructureComponent`의 `generateLocationCode`가 하드코딩 대신 `config.formatConfig`의 세그먼트 배열을 순회하며 동적으로 코드/이름 생성.
|
||||
|
||||
### 3. 기본값은 현재 하드코딩과 동일
|
||||
|
||||
`formatConfig`가 설정되지 않으면 기본 세그먼트가 적용되어 현재와 완전히 동일한 결과 생성 (하위 호환).
|
||||
|
||||
---
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
### ConfigPanel UI (화면 디자이너 좌측 속성 패널)
|
||||
|
||||
```
|
||||
┌─ 포맷 설정 ──────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ 위치코드 포맷 │
|
||||
│ 라벨 구분 자릿수 │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ ☰ 창고코드 [✓] [ ] [ - ] [ 0 ] (비활성) │ │
|
||||
│ │ ☰ 층 [✓] [ 층 ] [ ] [ 0 ] (비활성) │ │
|
||||
│ │ ☰ 구역 [✓] [구역 ] [ - ] [ 0 ] (비활성) │ │
|
||||
│ │ ☰ 열 [✓] [ ] [ - ] [ 2 ] │ │
|
||||
│ │ ☰ 단 [✓] [ ] [ ] [ 0 ] │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ 미리보기: WH001-1층A구역-01-1 │
|
||||
│ │
|
||||
│ 위치명 포맷 │
|
||||
│ 라벨 구분 자릿수 │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ ☰ 구역 [✓] [구역 ] [ - ] [ 0 ] (비활성) │ │
|
||||
│ │ ☰ 열 [✓] [ 열 ] [ - ] [ 2 ] │ │
|
||||
│ │ ☰ 단 [✓] [ 단 ] [ ] [ 0 ] │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ 미리보기: A구역-01열-1단 │
|
||||
│ │
|
||||
└───────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 사용자 커스터마이징 예시
|
||||
|
||||
| 설정 변경 | 위치코드 결과 | 위치명 결과 |
|
||||
|-----------|-------------|------------|
|
||||
| 기본값 (변경 없음) | `WH001-1층A구역-01-1` | `A구역-01열-1단` |
|
||||
| 구분자를 "/" 로 변경 | `WH001/1층A구역/01/1` | `A구역/01열/1단` |
|
||||
| 층 라벨 해제 | `WH001-1A구역-01-1` | `A구역-01열-1단` |
|
||||
| 구역+열 라벨 해제 | `WH001-1층A-01-1` | `A-01-1단` |
|
||||
| 순서를 구역→층→열→단 으로 변경 | `WH001-A구역1층-01-1` | `A구역-1층-01열-1단` |
|
||||
| 한글 라벨 모두 해제 | `WH001-1A-01-1` | `A-01-1` |
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
### 데이터 흐름
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["관리자: 화면 디자이너 열기"] --> B["RackStructureConfigPanel\n포맷 세그먼트 편집"]
|
||||
B --> C["componentConfig.formatConfig\n에 세그먼트 배열 저장"]
|
||||
C --> D["screen_layouts_v2.layout_data\nDB JSONB에 영구 저장"]
|
||||
D --> E["엔드유저: 렉 구조 모달 열기"]
|
||||
E --> F["RackStructureComponent\nconfig.formatConfig 읽기"]
|
||||
F --> G["generateLocationCode\n세그먼트 배열 순회하며 동적 생성"]
|
||||
G --> H["미리보기 테이블에 표시\nlocation_code / location_name"]
|
||||
```
|
||||
|
||||
### 컴포넌트 관계
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph designer ["화면 디자이너 (관리자)"]
|
||||
CP["RackStructureConfigPanel"]
|
||||
FE["FormatSegmentEditor\n(신규 서브컴포넌트)"]
|
||||
CP --> FE
|
||||
end
|
||||
subgraph runtime ["렉 구조 모달 (엔드유저)"]
|
||||
RC["RackStructureComponent"]
|
||||
GL["generateLocationCode\n(세그먼트 기반으로 교체)"]
|
||||
RC --> GL
|
||||
end
|
||||
subgraph storage ["저장소"]
|
||||
DB["screen_layouts_v2\nlayout_data.overrides.formatConfig"]
|
||||
end
|
||||
|
||||
FE -->|"onChange → componentConfig"| DB
|
||||
DB -->|"config prop 전달"| RC
|
||||
```
|
||||
|
||||
> 노란색 영역은 없음. 기존 설정-저장-전달 파이프라인을 그대로 활용.
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 파일 | 수정 내용 | 수정 규모 |
|
||||
|------|----------|----------|
|
||||
| `frontend/lib/registry/components/v2-rack-structure/types.ts` | `FormatSegment`, `LocationFormatConfig` 타입 추가, `RackStructureComponentConfig`에 `formatConfig` 필드 추가 | ~25줄 |
|
||||
| `frontend/lib/registry/components/v2-rack-structure/config.ts` | 기본 코드/이름 세그먼트 상수 정의 | ~40줄 |
|
||||
| `frontend/lib/registry/components/v2-rack-structure/FormatSegmentEditor.tsx` | **신규** - grid 레이아웃 + 컬럼 헤더 + 드래그 순서변경 + showLabel 체크박스 + 라벨/구분/자릿수 고정 필드 + 자릿수 비숫자 타입 비활성화 + 미리보기 | ~200줄 |
|
||||
| `frontend/lib/registry/components/v2-rack-structure/RackStructureConfigPanel.tsx` | "포맷 설정" 섹션 추가, FormatSegmentEditor 배치 | ~30줄 |
|
||||
| `frontend/lib/registry/components/v2-rack-structure/RackStructureComponent.tsx` | `generateLocationCode`를 세그먼트 기반으로 교체 | ~20줄 |
|
||||
|
||||
### 변경하지 않는 파일
|
||||
|
||||
- `buttonActions.ts` - 생성된 `location_code`/`location_name`을 그대로 저장하므로 변경 불필요
|
||||
- 백엔드 전체 - 포맷은 프론트엔드에서만 처리
|
||||
- DB 스키마 - `screen_layouts_v2.layout_data` JSONB에 자동 포함
|
||||
|
||||
---
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### 1. 타입 추가 (types.ts)
|
||||
|
||||
```typescript
|
||||
// 포맷 세그먼트 (위치코드/위치명의 각 구성요소)
|
||||
export interface FormatSegment {
|
||||
type: 'warehouseCode' | 'floor' | 'zone' | 'row' | 'level';
|
||||
enabled: boolean; // 이 세그먼트를 포함할지 여부
|
||||
showLabel: boolean; // 한글 라벨 표시 여부 (false면 값에서 라벨 제거)
|
||||
label: string; // 한글 라벨 (예: "층", "구역", "열", "단")
|
||||
separatorAfter: string; // 이 세그먼트 뒤의 구분자 (예: "-", "/", "")
|
||||
pad: number; // 최소 자릿수 (0 = 그대로, 2 = "01"처럼 2자리 맞춤)
|
||||
}
|
||||
|
||||
// 위치코드 + 위치명 포맷 설정
|
||||
export interface LocationFormatConfig {
|
||||
codeSegments: FormatSegment[];
|
||||
nameSegments: FormatSegment[];
|
||||
}
|
||||
```
|
||||
|
||||
`RackStructureComponentConfig`에 필드 추가:
|
||||
|
||||
```typescript
|
||||
export interface RackStructureComponentConfig {
|
||||
// ... 기존 필드 유지 ...
|
||||
codePattern?: string; // (기존, 하위 호환용 유지)
|
||||
namePattern?: string; // (기존, 하위 호환용 유지)
|
||||
formatConfig?: LocationFormatConfig; // 신규: 구조화된 포맷 설정
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 기본 세그먼트 상수 (config.ts)
|
||||
|
||||
```typescript
|
||||
import { FormatSegment, LocationFormatConfig } from "./types";
|
||||
|
||||
// 위치코드 기본 세그먼트 (현재 하드코딩과 동일한 결과)
|
||||
export const defaultCodeSegments: FormatSegment[] = [
|
||||
{ type: "warehouseCode", enabled: true, showLabel: false, label: "", separatorAfter: "-", pad: 0 },
|
||||
{ type: "floor", enabled: true, showLabel: true, label: "층", separatorAfter: "", pad: 0 },
|
||||
{ type: "zone", enabled: true, showLabel: true, label: "구역", separatorAfter: "-", pad: 0 },
|
||||
{ type: "row", enabled: true, showLabel: false, label: "", separatorAfter: "-", pad: 2 },
|
||||
{ type: "level", enabled: true, showLabel: false, label: "", separatorAfter: "", pad: 0 },
|
||||
];
|
||||
|
||||
// 위치명 기본 세그먼트 (현재 하드코딩과 동일한 결과)
|
||||
export const defaultNameSegments: FormatSegment[] = [
|
||||
{ type: "zone", enabled: true, showLabel: true, label: "구역", separatorAfter: "-", pad: 0 },
|
||||
{ type: "row", enabled: true, showLabel: true, label: "열", separatorAfter: "-", pad: 2 },
|
||||
{ type: "level", enabled: true, showLabel: true, label: "단", separatorAfter: "", pad: 0 },
|
||||
];
|
||||
|
||||
export const defaultFormatConfig: LocationFormatConfig = {
|
||||
codeSegments: defaultCodeSegments,
|
||||
nameSegments: defaultNameSegments,
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 세그먼트 기반 문자열 생성 함수 (config.ts)
|
||||
|
||||
```typescript
|
||||
// context 값에 포함된 한글 접미사 ("1층", "A구역")
|
||||
const KNOWN_SUFFIXES: Partial<Record<FormatSegmentType, string>> = {
|
||||
floor: "층",
|
||||
zone: "구역",
|
||||
};
|
||||
|
||||
function stripKnownSuffix(type: FormatSegmentType, val: string): string {
|
||||
const suffix = KNOWN_SUFFIXES[type];
|
||||
if (suffix && val.endsWith(suffix)) {
|
||||
return val.slice(0, -suffix.length);
|
||||
}
|
||||
return val;
|
||||
}
|
||||
|
||||
export function buildFormattedString(
|
||||
segments: FormatSegment[],
|
||||
values: Record<string, string>,
|
||||
): string {
|
||||
const activeSegments = segments.filter(
|
||||
(seg) => seg.enabled && values[seg.type],
|
||||
);
|
||||
|
||||
return activeSegments
|
||||
.map((seg, idx) => {
|
||||
// 1) 원본 값에서 한글 접미사를 먼저 벗겨냄 ("A구역" → "A", "1층" → "1")
|
||||
let val = stripKnownSuffix(seg.type, values[seg.type]);
|
||||
|
||||
// 2) showLabel이 켜져 있고 label이 있으면 붙임
|
||||
if (seg.showLabel && seg.label) {
|
||||
val += seg.label;
|
||||
}
|
||||
|
||||
if (seg.pad > 0 && !isNaN(Number(val))) {
|
||||
val = val.padStart(seg.pad, "0");
|
||||
}
|
||||
|
||||
if (idx < activeSegments.length - 1) {
|
||||
val += seg.separatorAfter;
|
||||
}
|
||||
return val;
|
||||
})
|
||||
.join("");
|
||||
}
|
||||
```
|
||||
|
||||
### 4. generateLocationCode 교체 (RackStructureComponent.tsx:494~510)
|
||||
|
||||
```typescript
|
||||
// 변경 전 (하드코딩)
|
||||
const generateLocationCode = useCallback(
|
||||
(row: number, level: number): { code: string; name: string } => {
|
||||
const warehouseCode = context?.warehouseCode || "WH001";
|
||||
const floor = context?.floor;
|
||||
const zone = context?.zone || "A";
|
||||
const floorPrefix = floor ? `${floor}` : "";
|
||||
const code = `${warehouseCode}-${floorPrefix}${zone}-...`;
|
||||
// ...
|
||||
},
|
||||
[context],
|
||||
);
|
||||
|
||||
// 변경 후 (세그먼트 기반)
|
||||
const formatConfig = config.formatConfig || defaultFormatConfig;
|
||||
|
||||
const generateLocationCode = useCallback(
|
||||
(row: number, level: number): { code: string; name: string } => {
|
||||
const values: Record<string, string> = {
|
||||
warehouseCode: context?.warehouseCode || "WH001",
|
||||
floor: context?.floor || "",
|
||||
zone: context?.zone || "A",
|
||||
row: row.toString(),
|
||||
level: level.toString(),
|
||||
};
|
||||
|
||||
const code = buildFormattedString(formatConfig.codeSegments, values);
|
||||
const name = buildFormattedString(formatConfig.nameSegments, values);
|
||||
|
||||
return { code, name };
|
||||
},
|
||||
[context, formatConfig],
|
||||
);
|
||||
```
|
||||
|
||||
### 5. ConfigPanel에 포맷 설정 섹션 추가 (RackStructureConfigPanel.tsx:284행 위)
|
||||
|
||||
```tsx
|
||||
{/* 포맷 설정 - UI 설정 섹션 아래에 추가 */}
|
||||
<div className="space-y-3 border-t pt-3">
|
||||
<div className="text-sm font-medium text-gray-700">포맷 설정</div>
|
||||
<p className="text-xs text-gray-500">
|
||||
위치코드와 위치명의 구성 요소를 드래그로 순서 변경하고,
|
||||
구분자/라벨을 편집할 수 있습니다
|
||||
</p>
|
||||
|
||||
<FormatSegmentEditor
|
||||
label="위치코드 포맷"
|
||||
segments={formatConfig.codeSegments}
|
||||
onChange={(segs) => handleFormatChange("codeSegments", segs)}
|
||||
sampleValues={sampleValues}
|
||||
/>
|
||||
|
||||
<FormatSegmentEditor
|
||||
label="위치명 포맷"
|
||||
segments={formatConfig.nameSegments}
|
||||
onChange={(segs) => handleFormatChange("nameSegments", segs)}
|
||||
sampleValues={sampleValues}
|
||||
/>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 6. FormatSegmentEditor 서브컴포넌트 (신규 파일)
|
||||
|
||||
- `@dnd-kit/core` + `@dnd-kit/sortable`로 드래그 순서변경
|
||||
- 프로젝트 표준 패턴: `useSortable`, `DndContext`, `SortableContext` 사용
|
||||
- **grid 레이아웃** (`grid-cols-[16px_56px_18px_1fr_1fr_1fr]`): 드래그핸들 / 타입명 / 체크박스 / 라벨 / 구분 / 자릿수
|
||||
- 최상단에 **컬럼 헤더** (`라벨` / `구분` / `자릿수`) 표시 — 각 행에서 텍스트 라벨 제거하여 공간 절약
|
||||
- 라벨/구분/자릿수 3개 필드는 **항상 고정 표시** (빈 값이어도 입력 필드가 사라지지 않음)
|
||||
- 자릿수 필드는 숫자 타입(열, 단)만 활성화, 비숫자 타입은 `disabled` + 회색 배경
|
||||
- 하단에 `buildFormattedString`으로 실시간 미리보기 표시
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- `formatConfig` 미설정 시 `defaultFormatConfig` 적용으로 **기존 동작 100% 유지** (하위 호환)
|
||||
- 포맷 설정은 **화면 디자이너 ConfigPanel에서만** 편집 (프로젝트의 설정-사용 분리 관행 준수)
|
||||
- `componentConfig` → `screen_layouts_v2.layout_data` 저장 파이프라인을 **그대로 활용** (추가 인프라 불필요)
|
||||
- 기존 `codePattern`/`namePattern` 문자열 필드는 삭제하지 않고 유지 (하위 호환)
|
||||
- v2-pivot-grid의 `format` 설정 패턴과 동일한 구조: ConfigPanel에서 설정 → 런타임에서 읽어 사용
|
||||
- `@dnd-kit` 드래그 구현은 `SortableCodeItem.tsx`, `useDragAndDrop.ts`의 기존 패턴 재사용
|
||||
- 백엔드 변경 없음, DB 스키마 변경 없음
|
||||
@@ -0,0 +1,123 @@
|
||||
# [맥락노트] 렉 구조 위치코드/위치명 포맷 사용자 설정
|
||||
|
||||
> 관련 문서: [계획서](./LFC[계획]-위치포맷-사용자설정.md) | [체크리스트](./LFC[체크]-위치포맷-사용자설정.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 위치코드(`WH001-1층A구역-01-1`)와 위치명(`A구역-01열-1단`)의 포맷이 하드코딩되어 있음
|
||||
- 회사마다 구분자("-" vs "/"), 세그먼트 순서, 한글 라벨 유무 등 요구사항이 다름
|
||||
- 현재는 코드를 직접 수정하지 않으면 포맷 변경 불가 → 관리자가 화면 디자이너에서 설정할 수 있어야 함
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 엔드유저 모달이 아닌 화면 디자이너 ConfigPanel에 설정 UI 배치
|
||||
|
||||
- **결정**: 포맷 편집 UI를 렉 구조 등록 모달이 아닌 화면 디자이너 좌측 속성 패널(ConfigPanel)에 배치
|
||||
- **근거**: 프로젝트의 설정-사용 분리 패턴 준수. 모든 v2 컴포넌트가 ConfigPanel에서 설정하고 런타임에서 읽기만 하는 구조를 따름
|
||||
- **대안 검토**: 모달 안에 포맷 편집 UI 배치(방법 B) → 기각 (프로젝트 관행에 맞지 않음, 매번 설정해야 함, 설정이 휘발됨)
|
||||
|
||||
### 2. 패턴 문자열이 아닌 구조화된 세그먼트 배열 사용
|
||||
|
||||
- **결정**: `"{warehouseCode}-{floor}{zone}-{row:02d}-{level}"` 같은 문자열 대신 `FormatSegment[]` 배열로 포맷 정의
|
||||
- **근거**: 관리자가 패턴 문법을 알 필요 없이 드래그/토글/Input으로 직관적 편집 가능
|
||||
- **대안 검토**: 기존 `codePattern`/`namePattern` 문자열 활용 → 기각 (관리자가 패턴 문법을 모를 수 있고, 오타 가능성 높음)
|
||||
|
||||
### 2-1. 체크박스는 한글 라벨 표시/숨김 제어 (showLabel)
|
||||
|
||||
- **결정**: 세그먼트의 체크박스는 `showLabel` 속성을 토글하며, 세그먼트 자체를 제거하지 않음
|
||||
- **근거**: "A구역-01열-1단"에서 "구역", "열" 체크 해제 시 → "A-01-1단"이 되어야 함 (값은 유지, 한글만 제거)
|
||||
- **주의**: `enabled`는 세그먼트 자체의 포함 여부, `showLabel`은 한글 라벨만 표시/숨김. 혼동하지 않도록 분리
|
||||
|
||||
### 2-2. 라벨/구분/자릿수 3개 필드 항상 고정 표시
|
||||
|
||||
- **결정**: 라벨 필드를 비워도 입력 필드가 사라지지 않고, 3개 필드(라벨, 구분, 자릿수)가 모든 세그먼트에 항상 표시
|
||||
- **근거**: 라벨을 지웠을 때 "라벨 없음"이 뜨면서 입력 필드가 사라지면 다시 라벨을 추가할 수 없는 문제 발생
|
||||
- **UI 개선**: 컬럼 헤더를 최상단에 배치하고, 각 행에서는 "구분", "자릿수" 텍스트를 제거하여 공간 확보
|
||||
|
||||
### 2-3. stripKnownSuffix로 원본 값의 한글 접미사를 먼저 벗긴 뒤 라벨 붙임
|
||||
|
||||
- **결정**: `buildFormattedString`에서 값을 처리할 때, 먼저 `KNOWN_SUFFIXES`(층, 구역)를 벗겨내고 순수 값만 남긴 뒤, `showLabel && label`일 때만 라벨을 붙이는 구조
|
||||
- **근거**: context 값이 "1층", "A구역"처럼 한글이 이미 포함된 상태로 들어옴. 이전 방식(`if (seg.label)`)은 라벨 필드가 빈 문자열이면 조건을 건너뛰어서 한글이 제거되지 않는 버그 발생
|
||||
- **핵심 흐름**: 원본 값 → `stripKnownSuffix` → 순수 값 → `showLabel && label`이면 라벨 붙임
|
||||
|
||||
### 2-4. 자릿수 필드는 숫자 타입만 활성화
|
||||
|
||||
- **결정**: 자릿수(pad) 필드는 열(row), 단(level)만 편집 가능, 나머지(창고코드, 층, 구역)는 disabled + 회색 배경
|
||||
- **근거**: 자릿수(zero-padding)는 숫자 값에만 의미가 있음. 비숫자 타입에 자릿수를 설정하면 혼란을 줄 수 있음
|
||||
|
||||
### 3. 기존 codePattern/namePattern 필드는 삭제하지 않고 유지
|
||||
|
||||
- **결정**: `types.ts`의 `codePattern`, `namePattern` 필드를 삭제하지 않음
|
||||
- **근거**: 하위 호환. 기존에 이 필드를 참조하는 코드가 없지만, 향후 다른 용도로 활용될 수 있음
|
||||
|
||||
### 4. formatConfig 미설정 시 기본값으로 현재 동작 유지
|
||||
|
||||
- **결정**: `config.formatConfig`가 없으면 `defaultFormatConfig` 사용
|
||||
- **근거**: 기존 화면 설정을 수정하지 않아도 현재와 동일한 위치코드/위치명이 생성됨 (무중단 배포 가능)
|
||||
|
||||
### 5. UI 라벨에서 "패딩" 대신 "자릿수" 사용
|
||||
|
||||
- **결정**: ConfigPanel UI에서 숫자 제로패딩 설정을 "자릿수"로 표시
|
||||
- **근거**: 관리자급 사용자가 "패딩"이라는 개발 용어를 모를 수 있음. "자릿수: 2 → 01, 02, ... 99"가 직관적
|
||||
- **코드 내부**: 변수명은 `pad` 유지 (개발자 영역)
|
||||
|
||||
### 6. @dnd-kit으로 드래그 구현
|
||||
|
||||
- **결정**: `@dnd-kit/core` + `@dnd-kit/sortable` 사용
|
||||
- **근거**: 프로젝트에 이미 설치되어 있고(`package.json`), `SortableCodeItem.tsx`, `useDragAndDrop.ts` 등 표준 패턴이 확립되어 있음
|
||||
- **대안 검토**: 위/아래 화살표 버튼으로 순서 변경 → 기각 (프로젝트에 이미 DnD 패턴이 있으므로 일관성 유지)
|
||||
|
||||
### 7. v2-pivot-grid의 format 설정 패턴을 참고
|
||||
|
||||
- **결정**: ConfigPanel에서 설정 → componentConfig에 저장 → 런타임에서 읽어 사용하는 흐름
|
||||
- **근거**: v2-pivot-grid가 필드별 `format`(type, precision, thousandSeparator 등)을 동일한 패턴으로 구현하고 있음. 가장 유사한 선례
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 타입 정의 | `frontend/lib/registry/components/v2-rack-structure/types.ts` | FormatSegment, LocationFormatConfig 타입 |
|
||||
| 기본 설정 | `frontend/lib/registry/components/v2-rack-structure/config.ts` | 기본 세그먼트 상수, buildFormattedString 함수 |
|
||||
| 신규 컴포넌트 | `frontend/lib/registry/components/v2-rack-structure/FormatSegmentEditor.tsx` | 포맷 편집 UI 서브컴포넌트 |
|
||||
| 설정 패널 | `frontend/lib/registry/components/v2-rack-structure/RackStructureConfigPanel.tsx` | FormatSegmentEditor 배치 |
|
||||
| 런타임 컴포넌트 | `frontend/lib/registry/components/v2-rack-structure/RackStructureComponent.tsx` | generateLocationCode 세그먼트 기반 교체 |
|
||||
| DnD 참고 | `frontend/hooks/useDragAndDrop.ts` | 프로젝트 표준 DnD 패턴 |
|
||||
| DnD 참고 | `frontend/components/admin/SortableCodeItem.tsx` | useSortable 사용 예시 |
|
||||
| 선례 참고 | `frontend/lib/registry/components/v2-pivot-grid/` | ConfigPanel에서 format 설정하는 패턴 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### 세그먼트 기반 문자열 생성 흐름
|
||||
|
||||
```
|
||||
FormatSegment[] → filter(enabled && 값 있음) → map(stripKnownSuffix → showLabel && label이면 라벨 붙임 → 자릿수 → 구분자) → join("") → 최종 문자열
|
||||
```
|
||||
|
||||
### componentConfig 저장/로드 흐름
|
||||
|
||||
```
|
||||
ConfigPanel onChange
|
||||
→ V2PropertiesPanel.onUpdateProperty("componentConfig", mergedConfig)
|
||||
→ layout.components[i].componentConfig.formatConfig
|
||||
→ convertLegacyToV2 → screen_layouts_v2.layout_data.overrides.formatConfig (DB)
|
||||
→ convertV2ToLegacy → componentConfig.formatConfig (런타임)
|
||||
→ RackStructureComponent config.formatConfig (prop)
|
||||
```
|
||||
|
||||
### context 값 참고
|
||||
|
||||
```
|
||||
context.warehouseCode = "WH001" (창고 코드)
|
||||
context.floor = "1층" (층 라벨 - 값 자체에 "층" 포함)
|
||||
context.zone = "A구역" 또는 "A" (구역 라벨 - "구역" 포함 여부 불확실)
|
||||
row = 1, 2, 3, ... (열 번호 - 숫자)
|
||||
level = 1, 2, 3, ... (단 번호 - 숫자)
|
||||
```
|
||||
@@ -0,0 +1,84 @@
|
||||
# [체크리스트] 렉 구조 위치코드/위치명 포맷 사용자 설정
|
||||
|
||||
> 관련 문서: [계획서](./LFC[계획]-위치포맷-사용자설정.md) | [맥락노트](./LFC[맥락]-위치포맷-사용자설정.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (완료)
|
||||
- 현재 단계: 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 타입 및 기본값 정의
|
||||
|
||||
- [x] `types.ts`에 `FormatSegment` 인터페이스 추가
|
||||
- [x] `types.ts`에 `LocationFormatConfig` 인터페이스 추가
|
||||
- [x] `types.ts`의 `RackStructureComponentConfig`에 `formatConfig?: LocationFormatConfig` 필드 추가
|
||||
- [x] `config.ts`에 `defaultCodeSegments` 상수 정의 (현재 하드코딩과 동일한 결과)
|
||||
- [x] `config.ts`에 `defaultNameSegments` 상수 정의 (현재 하드코딩과 동일한 결과)
|
||||
- [x] `config.ts`에 `defaultFormatConfig` 상수 정의
|
||||
- [x] `config.ts`에 `buildFormattedString()` 함수 구현 (stripKnownSuffix 방식)
|
||||
|
||||
### 2단계: FormatSegmentEditor 서브컴포넌트 생성
|
||||
|
||||
- [x] `FormatSegmentEditor.tsx` 신규 파일 생성
|
||||
- [x] `@dnd-kit/sortable` 기반 드래그 순서변경 구현
|
||||
- [x] 세그먼트별 체크박스로 한글 라벨 표시/숨김 토글 (showLabel)
|
||||
- [x] 라벨/구분/자릿수 3개 필드 항상 고정 표시 (빈 값이어도 입력 필드 유지)
|
||||
- [x] 최상단 컬럼 헤더 추가 (라벨 / 구분 / 자릿수), 각 행에서 텍스트 라벨 제거
|
||||
- [x] grid 레이아웃으로 정렬 (`grid-cols-[16px_56px_18px_1fr_1fr_1fr]`)
|
||||
- [x] 자릿수 필드: 숫자 타입(열, 단)만 활성화, 비숫자 타입은 disabled + 회색 배경
|
||||
- [x] `buildFormattedString`으로 실시간 미리보기 표시
|
||||
|
||||
### 3단계: ConfigPanel에 포맷 설정 섹션 추가
|
||||
|
||||
- [x] `RackStructureConfigPanel.tsx`에 FormatSegmentEditor import
|
||||
- [x] UI 설정 섹션 아래에 "포맷 설정" 섹션 추가
|
||||
- [x] 위치코드 포맷용 FormatSegmentEditor 배치
|
||||
- [x] 위치명 포맷용 FormatSegmentEditor 배치
|
||||
- [x] `onChange`로 `formatConfig` 업데이트 연결
|
||||
|
||||
### 4단계: 컴포넌트에서 세그먼트 기반 코드 생성
|
||||
|
||||
- [x] `RackStructureComponent.tsx`에서 `defaultFormatConfig` import
|
||||
- [x] `generateLocationCode` 함수를 세그먼트 기반으로 교체
|
||||
- [x] `config.formatConfig || defaultFormatConfig` 폴백 적용
|
||||
|
||||
### 5단계: 검증
|
||||
|
||||
- [x] formatConfig 미설정 시: 기존과 동일한 위치코드/위치명 생성 확인
|
||||
- [x] ConfigPanel에서 구분자 변경: 미리보기에 즉시 반영 확인
|
||||
- [x] ConfigPanel에서 라벨 체크 해제: 한글만 사라지고 값은 유지 확인 (예: "A구역" → "A")
|
||||
- [x] ConfigPanel에서 순서 드래그 변경: 미리보기에 반영 확인
|
||||
- [x] ConfigPanel에서 라벨 텍스트 변경: 미리보기에 반영 확인
|
||||
- [x] 설정 저장 후 화면 재로드: 설정 유지 확인
|
||||
- [x] 렉 구조 모달에서 미리보기 생성: 설정된 포맷으로 생성 확인
|
||||
- [x] 렉 구조 저장: DB에 설정된 포맷의 코드/이름 저장 확인
|
||||
|
||||
### 6단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인
|
||||
- [x] 미사용 import 제거 (FormatSegmentEditor.tsx: useState)
|
||||
- [x] 파일 끝 불필요한 빈 줄 제거 (types.ts, config.ts)
|
||||
- [x] 계획서/맥락노트/체크리스트 최종 반영
|
||||
- [x] 이 체크리스트 완료 표시 업데이트
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-10 | 계획서, 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-10 | 1~4단계 구현 완료 (types, config, FormatSegmentEditor, ConfigPanel, Component) |
|
||||
| 2026-03-10 | showLabel 로직 수정: 체크박스가 세그먼트 제거가 아닌 한글 라벨만 표시/숨김 처리 |
|
||||
| 2026-03-10 | 계획서, 맥락노트, 체크리스트에 showLabel 변경사항 반영 |
|
||||
| 2026-03-10 | UI 개선: 3필드 고정표시 + 컬럼 헤더 + grid 레이아웃 + 자릿수 비숫자 비활성화 |
|
||||
| 2026-03-10 | 계획서, 맥락노트, 체크리스트에 UI 개선사항 반영 |
|
||||
| 2026-03-10 | 라벨 필드 비움 시 한글 미제거 버그 수정 (stripKnownSuffix 도입) |
|
||||
| 2026-03-10 | 코드 정리 (미사용 import, 빈 줄) + 문서 최종 반영 |
|
||||
| 2026-03-10 | 5단계 검증 완료, 전체 작업 완료 |
|
||||
@@ -0,0 +1,420 @@
|
||||
# [계획서] 품번 수동 접두어 채번 - 접두어별 독립 순번 생성
|
||||
|
||||
> 관련 문서: [맥락노트](./MPN[맥락]-품번-수동접두어채번.md) | [체크리스트](./MPN[체크]-품번-수동접두어채번.md)
|
||||
|
||||
## 개요
|
||||
|
||||
기준정보 - 품목 정보 등록 모달에서 품번(`item_number`) 채번의 세 가지 문제를 해결합니다.
|
||||
|
||||
1. **BULK1 덮어쓰기 문제**: 사용자가 "ㅁㅁㅁ"을 입력해도 수동 값 추출이 실패하여 DB 숨은 값 `manualConfig.value = "BULK1"`로 덮어씌워짐
|
||||
2. **순번 공유 문제**: `buildPrefixKey`가 수동 파트를 건너뛰어 모든 접두어가 같은 시퀀스 카운터를 공유함
|
||||
3. **연속 구분자(--) 문제**: 카테고리가 비었을 때 `joinPartsWithSeparators`가 빈 파트에도 구분자를 붙여 `--` 발생 + 템플릿 불일치로 수동 값 추출 실패 → `userInputCode` 전체(구분자 포함)가 수동 값이 됨
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
### 채번 규칙 구성 (옵션설정 > 코드설정)
|
||||
|
||||
```
|
||||
규칙1(카테고리/재질, 자동) → "-" → 규칙2(문자, 직접입력) → "-" → 규칙3(순번, 자동, 3자리, 시작=5)
|
||||
```
|
||||
|
||||
### 실제 저장 흐름 (사용자가 "ㅁㅁㅁ" 입력 시)
|
||||
|
||||
1. 모달 열림 → `_numberingRuleId` 설정됨 (TextInputComponent L117-128)
|
||||
2. 사용자가 "ㅁㅁㅁ" 입력 → `formData.item_number = "ㅁㅁㅁ"`
|
||||
3. 저장 클릭 → `buttonActions.ts`가 `_numberingRuleId` 확인 → `allocateCode(ruleId, "ㅁㅁㅁ", formData)` 호출
|
||||
4. 백엔드: 템플릿 기반 수동 값 추출 시도 → **실패** (입력 "ㅁㅁㅁ"이 템플릿 "CATEGORY-____-XXX"와 불일치)
|
||||
5. 폴백: `manualConfig.value = "BULK1"` 사용 → **사용자 입력 "ㅁㅁㅁ" 완전 무시됨**
|
||||
6. `buildPrefixKey`가 수동 파트를 건너뜀 → prefix_key에 접두어 미포함 → 공유 카운터 사용
|
||||
7. 결과: **-BULK1-015** (사용자가 뭘 입력하든 항상 BULK1, 항상 공유 카운터)
|
||||
|
||||
### 문제 1: 순번 공유 (buildPrefixKey)
|
||||
|
||||
**위치**: `numberingRuleService.ts` L85-88
|
||||
|
||||
```typescript
|
||||
if (part.generationMethod === "manual") {
|
||||
// 수동 입력 파트는 prefix에서 제외 (값이 매번 달라질 수 있으므로)
|
||||
continue; // ← 접두어별 순번 분리를 막는 원인
|
||||
}
|
||||
```
|
||||
|
||||
이 `continue` 때문에 수동 입력값이 prefix_key에 포함되지 않습니다.
|
||||
"ㅁㅁㅁ", "ㅇㅇㅇ", "BULK1" 전부 **같은 시퀀스 카운터를 공유**합니다.
|
||||
|
||||
### 문제 2: BULK1 덮어쓰기 (추출 실패 + manualConfig.value 폴백)
|
||||
|
||||
**발생 흐름**:
|
||||
|
||||
1. 사용자가 "ㅁㅁㅁ" 입력 → `userInputCode = "ㅁㅁㅁ"` 으로 `allocateCode` 호출
|
||||
2. `allocateCode` 내부에서 **prefix_key를 먼저 빌드** (L1306) → 수동 값 추출은 그 이후 (L1332-1442)
|
||||
3. 템플릿 기반 수동 값 추출 시도 (L1411-1436):
|
||||
```
|
||||
템플릿: "카테고리값-____-XXX" (카테고리값-수동입력위치-순번)
|
||||
사용자 입력: "ㅁㅁㅁ"
|
||||
```
|
||||
4. "ㅁㅁㅁ"은 "카테고리값-"으로 시작하지 않음 → `startsWith` 불일치 → **추출 실패** → `extractedManualValues = []`
|
||||
5. 코드 조합 단계 (L1448-1454)에서 폴백 체인 동작:
|
||||
```typescript
|
||||
const manualValue =
|
||||
extractedManualValues[0] || // undefined (추출 실패)
|
||||
part.manualConfig?.value || // "BULK1" (DB 숨은 값) ← 여기서 덮어씌워짐
|
||||
"";
|
||||
```
|
||||
6. 결과: `-BULK1-015` (사용자 입력 "ㅁㅁㅁ"이 완전히 무시됨)
|
||||
|
||||
**DB 숨은 값 원인**:
|
||||
- DB `numbering_rule_parts.manual_config` 컬럼에 `{"value": "BULK1", "placeholder": "..."}` 저장됨
|
||||
- `ManualConfigPanel.tsx`에는 `placeholder` 입력란만 있고 **`value` 입력란이 없음**
|
||||
- 플레이스홀더 수정 시 `{ ...config, placeholder: ... }` 스프레드로 기존 `value: "BULK1"`이 계속 보존됨
|
||||
|
||||
### 문제 3: 연속 구분자(--) 문제
|
||||
|
||||
**발생 흐름**:
|
||||
|
||||
1. 카테고리 미선택 → 카테고리 파트 값 = `""` (빈 문자열)
|
||||
2. `joinPartsWithSeparators`가 빈 파트에도 구분자 `-`를 추가 → 연속 빈 파트 시 `--` 발생
|
||||
3. 사용자 입력 필드에 `-제발-015` 형태로 표시 (선행 `-`)
|
||||
4. `extractManualValuesFromInput`에서 템플릿이 `CATEGORY-____-XXX`로 생성됨 (실제 값 `""` 대신 플레이스홀더 `"CATEGORY"` 사용)
|
||||
5. 입력 `-제발-015`이 `CATEGORY-`로 시작하지 않음 → 추출 실패
|
||||
6. 폴백: `userInputCode` 전체 `-제발-015`가 수동 값이 됨
|
||||
7. 코드 조합: `""` + `-` + `-제발-015` + `-` + `003` = `--제발-015-003`
|
||||
|
||||
### 정상 동작 확인된 부분
|
||||
|
||||
| 항목 | 상태 | 근거 |
|
||||
|------|------|------|
|
||||
| `_numberingRuleId` 유지 | 정상 | 사용자 입력해도 allocateCode가 호출됨 |
|
||||
| 시퀀스 증가 | 정상 | 순번이 증가하고 있음 (015 등) |
|
||||
| 코드 조합 | 정상 | 구분자, 파트 순서 등 올바르게 결합됨 |
|
||||
|
||||
### 비정상 확인된 부분
|
||||
|
||||
| 항목 | 상태 | 근거 |
|
||||
|------|------|------|
|
||||
| 수동 값 추출 | **실패** | 사용자 입력 "ㅁㅁㅁ"이 템플릿과 불일치 → 추출 실패 → BULK1 폴백 |
|
||||
| prefix_key 분리 | **실패** | `buildPrefixKey`가 수동 파트 skip → 모든 접두어가 같은 시퀀스 공유 |
|
||||
| 연속 구분자 | **실패** | 빈 파트에 구분자 추가 + 템플릿 플레이스홀더 불일치 → `--` 발생 |
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### prefix_key에 수동 파트 값 포함
|
||||
|
||||
```
|
||||
현재: prefix_key = 카테고리값만 (수동 파트 무시)
|
||||
변경: prefix_key = 카테고리값 + "|" + 수동입력값
|
||||
```
|
||||
|
||||
### allocateCode 실행 순서 변경
|
||||
|
||||
```
|
||||
현재: buildPrefixKey → 시퀀스 할당 → 수동 값 추출 → 코드 조합
|
||||
변경: 수동 값 추출 → buildPrefixKey(수동 값 포함) → 시퀀스 할당 → 코드 조합
|
||||
```
|
||||
|
||||
### 순번 동작
|
||||
|
||||
```
|
||||
"ㅁㅁㅁ" 첫 등록 → prefix_key="카테고리|ㅁㅁㅁ", sequence=1 → -ㅁㅁㅁ-001
|
||||
"ㅁㅁㅁ" 두번째 → prefix_key="카테고리|ㅁㅁㅁ", sequence=2 → -ㅁㅁㅁ-002
|
||||
"ㅇㅇㅇ" 첫 등록 → prefix_key="카테고리|ㅇㅇㅇ", sequence=1 → -ㅇㅇㅇ-001
|
||||
"ㅁㅁㅁ" 세번째 → prefix_key="카테고리|ㅁㅁㅁ", sequence=3 → -ㅁㅁㅁ-003
|
||||
```
|
||||
|
||||
### BULK1 폴백 제거 (코드 + DB 이중 조치)
|
||||
|
||||
```
|
||||
코드: 폴백 체인에서 manualConfig.value 제거 → extractedManualValues만 사용
|
||||
DB: manual_config에서 "value": "BULK1" 키 제거 → 유령 기본값 정리
|
||||
```
|
||||
|
||||
### 연속 구분자 방지 + 템플릿 정합성 복원
|
||||
|
||||
```
|
||||
joinPartsWithSeparators: 빈 파트 뒤에 이미 구분자가 있으면 중복 추가하지 않음
|
||||
extractManualValuesFromInput: 카테고리/참조 빈 값 시 "" 반환 (플레이스홀더 "CATEGORY"/"REF" 대신)
|
||||
→ 템플릿이 실제 코드 구조와 일치 → 추출 성공 → -- 방지
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
| 사용자 입력 | 현재 동작 | 원인 | 변경 후 동작 |
|
||||
|------------|----------|------|-------------|
|
||||
| `ㅁㅁㅁ` (첫번째) | `-BULK1-015` | 추출 실패 → BULK1 폴백 + 공유 카운터 | `카테고리값-ㅁㅁㅁ-001` |
|
||||
| `ㅁㅁㅁ` (두번째) | `-BULK1-016` | 동일 | `카테고리값-ㅁㅁㅁ-002` |
|
||||
| `ㅇㅇㅇ` (첫번째) | `-BULK1-017` | 동일 | `카테고리값-ㅇㅇㅇ-001` |
|
||||
| (입력 안 함) | `-BULK1-018` | manualConfig.value 폴백 | 에러 반환 (수동 파트 필수 입력) |
|
||||
| 카테고리 비었을 때 | `--제발-015-003` | 빈 파트 구분자 중복 + 템플릿 불일치 | `-제발-001` |
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 사용자
|
||||
participant BA as buttonActions.ts
|
||||
participant API as allocateNumberingCode API
|
||||
participant NRS as numberingRuleService
|
||||
participant DB as numbering_rule_sequences
|
||||
|
||||
User->>BA: 저장 클릭 (item_number = "ㅁㅁㅁ")
|
||||
BA->>API: allocateCode(ruleId, "ㅁㅁㅁ", formData)
|
||||
API->>NRS: allocateCode()
|
||||
|
||||
Note over NRS: 1단계: 수동 값 추출 (buildPrefixKey 전에 수행)
|
||||
NRS->>NRS: extractManualValuesFromInput("ㅁㅁㅁ")
|
||||
Note over NRS: 템플릿 파싱 실패 → 폴백: userInputCode 전체 사용
|
||||
NRS->>NRS: extractedManualValues = ["ㅁㅁㅁ"]
|
||||
|
||||
Note over NRS: 2단계: prefix_key 빌드 (수동 값 포함)
|
||||
NRS->>NRS: buildPrefixKey(rule, formData, ["ㅁㅁㅁ"])
|
||||
Note over NRS: prefix_key = "카테고리값|ㅁㅁㅁ"
|
||||
|
||||
Note over NRS: 3단계: 시퀀스 할당
|
||||
NRS->>DB: UPSERT sequences (prefix_key="카테고리값|ㅁㅁㅁ")
|
||||
DB-->>NRS: current_sequence = 1
|
||||
|
||||
Note over NRS: 4단계: 코드 조합
|
||||
NRS->>NRS: 카테고리값 + "-" + "ㅁㅁㅁ" + "-" + "001"
|
||||
NRS-->>API: "카테고리값-ㅁㅁㅁ-001"
|
||||
API-->>BA: generatedCode
|
||||
BA->>BA: formData.item_number = "카테고리값-ㅁㅁㅁ-001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 파일 | 변경 내용 | 규모 |
|
||||
|------|----------|------|
|
||||
| `backend-node/src/services/numberingRuleService.ts` | `buildPrefixKey`에 `manualValues` 파라미터 추가, `allocateCode`에서 수동 값 추출 순서 변경 + 폴백 체인 정리, `extractManualValuesFromInput` 헬퍼 분리, `joinPartsWithSeparators` 연속 구분자 방지, 템플릿 카테고리/참조 플레이스홀더를 실제값으로 변경, `previewCode`에 `manualInputValue` 파라미터 추가 + `startFrom` 적용 | ~80줄 |
|
||||
| `backend-node/src/controllers/numberingRuleController.ts` | preview 엔드포인트에 `manualInputValue` body 파라미터 수신 추가 | ~2줄 |
|
||||
| `frontend/lib/api/numberingRule.ts` | `previewNumberingCode`에 `manualInputValue` 파라미터 추가 | ~3줄 |
|
||||
| `frontend/components/v2/V2Input.tsx` | 수동 입력값 변경 시 디바운스(300ms) preview API 호출 + suffix(순번) 실시간 갱신 | ~35줄 |
|
||||
| `db/migrations/1053_remove_bulk1_manual_config_value.sql` | `numbering_rule_parts.manual_config`에서 `value: "BULK1"` 제거 | SQL 1건 |
|
||||
|
||||
### buildPrefixKey 호출부 영향 분석
|
||||
|
||||
| 호출부 | 위치 | `manualValues` 전달 | 영향 |
|
||||
|--------|------|---------------------|------|
|
||||
| `previewCode` | L1091 | `manualInputValue` 전달 시 포함 | 접두어별 정확한 순번 조회 |
|
||||
| `allocateCode` | L1332 | 전달 | prefix_key에 수동 값 포함됨 |
|
||||
|
||||
### 멀티테넌시 체크
|
||||
|
||||
| 항목 | 상태 | 근거 |
|
||||
|------|------|------|
|
||||
| `buildPrefixKey` | 영향 없음 | 시그니처만 확장, company_code 관련 변경 없음 |
|
||||
| `allocateCode` | 이미 준수 | L1302에서 `companyCode`로 규칙 조회, L1313에서 시퀀스 할당 시 `companyCode` 전달 |
|
||||
| `joinPartsWithSeparators` | 영향 없음 | 순수 문자열 조합 함수, company_code 무관 |
|
||||
| DB 마이그레이션 | 해당 없음 | JSONB 내부 값 정리, company_code 무관 |
|
||||
|
||||
---
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### 1. `joinPartsWithSeparators` 수정 - 연속 구분자 방지
|
||||
|
||||
**위치**: L36-48
|
||||
**변경**: 빈 파트 뒤에 이미 구분자가 있으면 중복 추가하지 않음
|
||||
|
||||
```typescript
|
||||
function joinPartsWithSeparators(partValues: string[], sortedParts: any[], globalSeparator: string): string {
|
||||
let result = "";
|
||||
partValues.forEach((val, idx) => {
|
||||
result += val;
|
||||
if (idx < partValues.length - 1) {
|
||||
const sep = sortedParts[idx].separatorAfter ?? sortedParts[idx].autoConfig?.separatorAfter ?? globalSeparator;
|
||||
if (val || !result.endsWith(sep)) {
|
||||
result += sep;
|
||||
}
|
||||
}
|
||||
});
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. `buildPrefixKey` 수정 - 수동 파트 값을 prefix에 포함
|
||||
|
||||
**위치**: L75-88
|
||||
**변경**: 세 번째 파라미터 `manualValues` 추가. 전달되면 prefix_key에 포함.
|
||||
|
||||
```typescript
|
||||
private async buildPrefixKey(
|
||||
rule: NumberingRuleConfig,
|
||||
formData?: Record<string, any>,
|
||||
manualValues?: string[]
|
||||
): Promise<string> {
|
||||
const sortedParts = [...rule.parts].sort((a: any, b: any) => a.order - b.order);
|
||||
const prefixParts: string[] = [];
|
||||
let manualIndex = 0;
|
||||
|
||||
for (const part of sortedParts) {
|
||||
if (part.partType === "sequence") continue;
|
||||
|
||||
if (part.generationMethod === "manual") {
|
||||
const manualValue = manualValues?.[manualIndex] || "";
|
||||
manualIndex++;
|
||||
if (manualValue) {
|
||||
prefixParts.push(manualValue);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// ... 나머지 기존 로직 (text, date, category, reference 등) 그대로 유지 ...
|
||||
}
|
||||
|
||||
return prefixParts.join("|");
|
||||
}
|
||||
```
|
||||
|
||||
**하위 호환성**: `manualValues`는 optional. `previewCode`(L1091)는 전달하지 않으므로 동작 변화 없음.
|
||||
|
||||
### 3. `allocateCode` 수정 - 수동 값 추출 순서 변경 + 폴백 정리
|
||||
|
||||
**위치**: L1290-1584
|
||||
**핵심 변경 2가지**:
|
||||
|
||||
(A) 기존에는 `buildPrefixKey`(L1306) → 수동 값 추출(L1332) 순서였으나, **수동 값 추출 → `buildPrefixKey`** 순서로 변경.
|
||||
|
||||
(B) 코드 조합 단계(L1448-1454)에서 `manualConfig.value` 폴백 제거.
|
||||
|
||||
```typescript
|
||||
async allocateCode(ruleId, companyCode, formData?, userInputCode?) {
|
||||
// ... 규칙 조회 ...
|
||||
|
||||
// 1단계: 수동 파트 값 추출 (buildPrefixKey 호출 전에 수행)
|
||||
const manualParts = rule.parts.filter(p => p.generationMethod === "manual");
|
||||
let extractedManualValues: string[] = [];
|
||||
|
||||
if (manualParts.length > 0 && userInputCode) {
|
||||
extractedManualValues = await this.extractManualValuesFromInput(
|
||||
rule, userInputCode, formData
|
||||
);
|
||||
|
||||
// 폴백: 추출 실패 시 userInputCode 전체를 수동 값으로 사용
|
||||
if (extractedManualValues.length === 0 && manualParts.length === 1) {
|
||||
extractedManualValues = [userInputCode];
|
||||
}
|
||||
}
|
||||
|
||||
// 2단계: 수동 값을 포함하여 prefix_key 빌드
|
||||
const prefixKey = await this.buildPrefixKey(rule, formData, extractedManualValues);
|
||||
|
||||
// 3단계: 시퀀스 할당 (기존 로직 그대로)
|
||||
|
||||
// 4단계: 코드 조합 (manualConfig.value 폴백 제거)
|
||||
// 기존: extractedManualValues[i] || part.manualConfig?.value || ""
|
||||
// 변경: extractedManualValues[i] || ""
|
||||
}
|
||||
```
|
||||
|
||||
### 4. `extractManualValuesFromInput` 헬퍼 분리 + 템플릿 정합성 복원
|
||||
|
||||
기존 `allocateCode` 내부의 수동 값 추출 로직(L1332-1442)을 별도 private 메서드로 추출.
|
||||
로직 자체는 변경 없음, 위치만 이동.
|
||||
카테고리/참조 파트의 빈 값 처리를 실제 코드 생성과 일치시킴.
|
||||
|
||||
```typescript
|
||||
private async extractManualValuesFromInput(
|
||||
rule: NumberingRuleConfig,
|
||||
userInputCode: string,
|
||||
formData?: Record<string, any>
|
||||
): Promise<string[]> {
|
||||
// 기존 L1332-1442의 로직을 그대로 이동
|
||||
// 변경: 카테고리/참조 빈 값 시 "CATEGORY"/"REF" 대신 "" 반환
|
||||
// → 템플릿이 실제 코드 구조와 일치 → 추출 성공률 향상
|
||||
}
|
||||
```
|
||||
|
||||
### 5. DB 마이그레이션 - BULK1 유령 기본값 제거
|
||||
|
||||
**파일**: `db/migrations/1053_remove_bulk1_manual_config_value.sql`
|
||||
|
||||
`numbering_rule_parts.manual_config` 컬럼에서 `value` 키를 제거합니다.
|
||||
|
||||
```sql
|
||||
-- manual_config에서 "value" 키 제거 (BULK1 유령 기본값 정리)
|
||||
UPDATE numbering_rule_parts
|
||||
SET manual_config = manual_config - 'value'
|
||||
WHERE generation_method = 'manual'
|
||||
AND manual_config ? 'value'
|
||||
AND manual_config->>'value' = 'BULK1';
|
||||
```
|
||||
|
||||
> PostgreSQL JSONB 연산자 `-`를 사용하여 특정 키만 제거.
|
||||
> `manual_config`의 나머지 필드(`placeholder` 등)는 유지됨.
|
||||
> "BULK1" 값을 가진 레코드만 대상으로 하여 안전성 확보.
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- **변경 범위 최소화**: `numberingRuleService.ts` 코드 변경 + DB 마이그레이션 1건
|
||||
- **이중 조치**: 코드에서 `manualConfig.value` 폴백 제거 + DB에서 유령 값 정리
|
||||
- `buildPrefixKey`의 `manualValues`는 optional → 기존 호출부(`previewCode` 등)에 영향 없음
|
||||
- `allocateCode` 내부 로직 순서만 변경 (추출 → prefix_key 빌드), 새 로직 추가 아님
|
||||
- 수동 값 추출 로직은 기존 코드를 헬퍼로 분리할 뿐, 로직 자체는 변경 없음
|
||||
- DB 마이그레이션은 "BULK1" 값만 정확히 타겟팅하여 부작용 방지
|
||||
- `TextInputComponent.tsx` 변경 불필요 (현재 동작이 올바름)
|
||||
- 프론트엔드 변경 없음 → 프론트엔드 테스트 불필요
|
||||
- `joinPartsWithSeparators`는 연속 구분자만 방지, 기존 구분자 구조 유지
|
||||
- 템플릿 카테고리/참조 빈 값을 실제 코드와 일치시켜 추출 성공률 향상
|
||||
|
||||
---
|
||||
|
||||
## 실시간 순번 미리보기 (추가 기능)
|
||||
|
||||
### 배경
|
||||
|
||||
품목 등록 모달에서 수동 입력 세그먼트 우측에 표시되는 순번(suffix)이 입력값과 무관하게 고정되어 있었음. 사용자가 "ㅇㅇ"을 입력하면 해당 접두어로 이미 몇 개가 등록되었는지에 따라 순번이 달라져야 함.
|
||||
|
||||
### 목표 동작
|
||||
|
||||
```
|
||||
모달 열림 : -[입력하시오]-005 (startFrom=5 기반 기본 순번)
|
||||
"ㅇㅇ" 입력 : -[ㅇㅇ]-005 (기존 "ㅇㅇ" 등록 0건)
|
||||
저장 후 재입력 "ㅇㅇ": -[ㅇㅇ]-006 (기존 "ㅇㅇ" 등록 1건)
|
||||
```
|
||||
|
||||
### 아키텍처
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 사용자
|
||||
participant V2 as V2Input
|
||||
participant API as previewNumberingCode
|
||||
participant BE as numberingRuleService.previewCode
|
||||
participant DB as numbering_rule_sequences
|
||||
|
||||
User->>V2: 수동 입력 "ㅇㅇ"
|
||||
Note over V2: 디바운스 300ms
|
||||
V2->>API: preview(ruleId, formData, "ㅇㅇ")
|
||||
API->>BE: previewCode(ruleId, companyCode, formData, "ㅇㅇ")
|
||||
BE->>BE: buildPrefixKey(rule, formData, ["ㅇㅇ"])
|
||||
Note over BE: prefix_key = "카테고리|ㅇㅇ"
|
||||
BE->>DB: getSequenceForPrefix(prefix_key)
|
||||
DB-->>BE: currentSeq = 0
|
||||
Note over BE: nextSequence = 0 + startFrom(5) = 5
|
||||
BE-->>API: "-____-005"
|
||||
API-->>V2: generatedCode
|
||||
V2->>V2: suffix = "-005" 갱신
|
||||
Note over V2: 화면 표시: -[ㅇㅇ]-005
|
||||
```
|
||||
|
||||
### 변경 내용
|
||||
|
||||
1. **백엔드 컨트롤러**: preview 엔드포인트가 `req.body.manualInputValue` 수신
|
||||
2. **백엔드 서비스**: `previewCode`가 `manualInputValue`를 받아 `buildPrefixKey`에 전달 → 접두어별 정확한 시퀀스 조회
|
||||
3. **백엔드 서비스**: 수동 파트가 있는데 `manualInputValue`가 없는 초기 상태 → 레거시 공용 시퀀스 조회 건너뜀, `currentSeq = 0` 사용 → `startFrom` 기본값 표시
|
||||
4. **프론트엔드 API**: `previewNumberingCode`에 `manualInputValue` 파라미터 추가
|
||||
5. **V2Input**: `manualInputValue` 변경 시 디바운스(300ms) preview API 재호출 → `numberingTemplateRef` 갱신 → suffix 실시간 업데이트
|
||||
6. **V2Input**: 카테고리 변경 시 초기 useEffect에서도 현재 `manualInputValue`를 preview에 전달 → 카테고리 변경/삭제 시 순번 즉시 반영
|
||||
7. **코드 정리**: 카테고리 해석 로직 3곳 중복 → `resolveCategoryFormat` 헬퍼로 통합 (약 100줄 감소)
|
||||
@@ -0,0 +1,161 @@
|
||||
# [맥락노트] 품번 수동 접두어 채번 - 접두어별 독립 순번 생성
|
||||
|
||||
> 관련 문서: [계획서](./MPN[계획]-품번-수동접두어채번.md) | [체크리스트](./MPN[체크]-품번-수동접두어채번.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 기준정보 - 품목정보 등록 모달에서 품번 인풋에 사용자가 값을 입력해도 무시되고 "BULK1"로 저장됨
|
||||
- 서로 다른 접두어("ㅁㅁㅁ", "ㅇㅇㅇ")를 입력해도 전부 같은 시퀀스 카운터를 공유함
|
||||
- 카테고리 미선택 시 `--제발-015-003` 처럼 연속 구분자가 발생함
|
||||
- 사용자 입력이 반영되고, 접두어별로 독립된 순번이 부여되어야 함
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 수동 값 추출을 buildPrefixKey 전으로 이동
|
||||
|
||||
- **결정**: `allocateCode` 내부에서 수동 값 추출 → buildPrefixKey 순서로 변경
|
||||
- **근거**: 기존에는 buildPrefixKey(L1306)가 먼저 실행된 후 수동 값 추출(L1332)이 진행됨. 수동 값이 prefix_key에 포함되려면 추출이 먼저 되어야 함
|
||||
- **대안 검토**: buildPrefixKey 내부에서 직접 추출 → 기각 (역할 분리 위반, previewCode 호출에도 영향)
|
||||
|
||||
### 2. buildPrefixKey에 수동 파트 값 포함
|
||||
|
||||
- **결정**: `manualValues` optional 파라미터 추가, 전달되면 prefix_key에 포함
|
||||
- **근거**: 기존 `continue`(L85-87)로 수동 파트가 prefix_key에서 제외되어 모든 접두어가 같은 시퀀스를 공유함
|
||||
- **하위호환**: optional 파라미터이므로 `previewCode`(L1091) 등 기존 호출부는 영향 없음
|
||||
|
||||
### 3. 템플릿 파싱 실패 시 userInputCode 전체를 수동 값으로 사용
|
||||
|
||||
- **결정**: 수동 파트가 1개이고 템플릿 기반 추출이 실패하면 `userInputCode` 전체를 수동 값으로 사용
|
||||
- **근거**: 사용자가 "ㅁㅁㅁ"처럼 접두어 부분만 입력하면 템플릿 "카테고리값-____-XXX"와 불일치. `startsWith` 조건 실패로 추출이 안 됨. 이 경우 입력 전체가 수동 값임
|
||||
- **제한**: 수동 파트가 2개 이상이면 이 폴백 불가 (어디서 분리할지 알 수 없음)
|
||||
|
||||
### 4. 코드 조합에서 manualConfig.value 폴백 제거
|
||||
|
||||
- **결정**: `extractedManualValues[i] || part.manualConfig?.value || ""` → `extractedManualValues[i] || ""`
|
||||
- **근거**: `manualConfig.value`는 UI에서 입력/편집할 수 없는 유령 필드. `ManualConfigPanel.tsx`에 `value` 입력란이 없어 DB에 한번 저장되면 스프레드 연산자로 계속 보존됨
|
||||
- **이중 조치**: 코드에서 폴백 제거 + DB 마이그레이션으로 기존 "BULK1" 값 정리
|
||||
|
||||
### 5. DB 마이그레이션은 BULK1만 타겟팅
|
||||
|
||||
- **결정**: `manual_config->>'value' = 'BULK1'` 조건으로 한정
|
||||
- **근거**: 다른 value가 의도적으로 설정된 경우가 있을 수 있음. 확인된 문제("BULK1")만 정리하여 부작용 방지
|
||||
- **대안 검토**: 전체 `manual_config.value` 키 제거 → 보류 (운영 판단 필요)
|
||||
|
||||
### 6. extractManualValuesFromInput 헬퍼 분리
|
||||
|
||||
- **결정**: 기존 `allocateCode` 내부의 수동 값 추출 로직(L1332-1442)을 별도 private 메서드로 추출
|
||||
- **근거**: 추출 로직이 약 110줄로 `allocateCode`가 과도하게 비대함. 헬퍼로 분리하면 순서 변경도 자연스러움
|
||||
- **원칙**: 로직 자체는 변경 없음, 위치만 이동 (구조적 변경과 행위적 변경 분리)
|
||||
|
||||
### 7. 프론트엔드 변경 불필요
|
||||
|
||||
- **결정**: 프론트엔드 코드 수정 없음
|
||||
- **근거**: `_numberingRuleId`가 사용자 입력 시에도 유지되고 있음 확인. `buttonActions.ts`가 정상적으로 `allocateCode`를 호출함. 문제는 백엔드 로직에만 있음
|
||||
|
||||
### 8. joinPartsWithSeparators 연속 구분자 방지
|
||||
|
||||
- **결정**: 빈 파트 뒤에 이미 같은 구분자가 있으면 중복 추가하지 않음
|
||||
- **근거**: 카테고리가 비면 파트 값 `""` + 구분자 `-`가 반복되어 `--` 발생. 구분자 구조(`-ㅁㅁㅁ-001`)는 유지하되 연속(`--`)만 방지
|
||||
- **조건**: `if (val || !result.endsWith(sep))` — 값이 있으면 항상 추가, 값이 없으면 이미 같은 구분자로 끝나면 스킵
|
||||
|
||||
### 9. 템플릿 카테고리/참조 플레이스홀더를 실제값으로 변경
|
||||
|
||||
- **결정**: `extractManualValuesFromInput` 내부의 카테고리/참조 빈 값 반환을 `"CATEGORY"`/`"REF"` → `""`로 변경
|
||||
- **근거**: 실제 코드 생성에서 빈 카테고리는 `""`인데 템플릿에서 `"CATEGORY"`를 쓰면 구조 불일치로 추출 실패. 로그로 확인: `userInputCode=-제발-015, previewTemplate=CATEGORY-____-XXX, extractedManualValues=[]`
|
||||
- **카테고리 있을 때**: `catMapping2?.format` 반환은 수정 전후 동일하여 영향 없음
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 대상 | `backend-node/src/services/numberingRuleService.ts` | joinPartsWithSeparators(L36), buildPrefixKey(L75), extractManualValuesFromInput(신규), allocateCode(L1296) |
|
||||
| 신규 생성 | `db/migrations/1053_remove_bulk1_manual_config_value.sql` | BULK1 유령 값 정리 마이그레이션 |
|
||||
| 변경 없음 | `frontend/components/screen/widgets/TextInputComponent.tsx` | _numberingRuleId 유지 확인 완료 |
|
||||
| 변경 없음 | `frontend/lib/registry/components/numbering-rule/config.ts` | 채번 설정 레지스트리 |
|
||||
| 변경 없음 | `frontend/components/screen/config-panels/NumberConfigPanel.tsx` | 채번 규칙 설정 패널 |
|
||||
| 참고 | `backend-node/src/controllers/numberingRuleController.ts` | allocateNumberingCode 컨트롤러 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### allocateCode 실행 순서 (변경 전 → 후)
|
||||
|
||||
```
|
||||
변경 전: buildPrefixKey(L1306) → 시퀀스 할당 → 수동 값 추출(L1332) → 코드 조합
|
||||
변경 후: 수동 값 추출 → buildPrefixKey(수동 값 포함) → 시퀀스 할당 → 코드 조합
|
||||
```
|
||||
|
||||
### prefix_key 구성 (변경 전 → 후)
|
||||
|
||||
```
|
||||
변경 전: "카테고리값" (수동 파트 무시, 모든 접두어가 같은 키)
|
||||
변경 후: "카테고리값|ㅁㅁㅁ" (수동 파트 포함, 접두어별 독립 키)
|
||||
```
|
||||
|
||||
### 폴백 체인 (변경 전 → 후)
|
||||
|
||||
```
|
||||
변경 전: extractedManualValues[i] || manualConfig.value || ""
|
||||
변경 후: extractedManualValues[i] || ""
|
||||
```
|
||||
|
||||
### joinPartsWithSeparators 연속 구분자 방지 (변경 전 → 후)
|
||||
|
||||
```
|
||||
변경 전: "" + "-" + "" + "-" + "ㅁㅁㅁ" → "--ㅁㅁㅁ"
|
||||
변경 후: "" + "-" (이미 "-"로 끝남, 스킵) + "ㅁㅁㅁ" → "-ㅁㅁㅁ"
|
||||
```
|
||||
|
||||
### 템플릿 정합성 (변경 전 → 후)
|
||||
|
||||
```
|
||||
변경 전: 카테고리 비었을 때 템플릿 = "CATEGORY-____-XXX" / 입력 = "-제발-015" → 불일치 → 추출 실패
|
||||
변경 후: 카테고리 비었을 때 템플릿 = "-____-XXX" / 입력 = "-제발-015" → 일치 → 추출 성공
|
||||
```
|
||||
|
||||
### 10. 실시간 순번 미리보기 구현 방식
|
||||
|
||||
- **결정**: V2Input에서 `manualInputValue` 변경 시 디바운스(300ms)로 preview API를 재호출하여 suffix(순번)를 갱신
|
||||
- **근거**: 기존 preview API는 `manualInputValue` 없이 호출되어 모든 접두어가 같은 기본 순번을 표시함. 접두어별 정확한 순번을 보여주려면 preview 시점에도 수동 값을 전달하여 해당 prefix_key의 시퀀스를 조회해야 함
|
||||
- **대안 검토**: 프론트엔드에서 카운트 API를 별도 호출 → 기각 (기존 `previewCode` 흐름 재사용이 프로젝트 관행에 부합)
|
||||
- **디바운스 300ms**: 사용자 타이핑 중 과도한 API 호출 방지. 프로젝트 기존 패턴(검색 디바운스 등)과 동일
|
||||
|
||||
### 11. previewCode에 manualInputValue 전달
|
||||
|
||||
- **결정**: `previewCode` 시그니처에 `manualInputValue?: string` 추가, `buildPrefixKey`에 `[manualInputValue]`로 전달
|
||||
- **근거**: `buildPrefixKey`가 이미 `manualValues` optional 파라미터를 지원하므로 자연스럽게 확장 가능. 순번 조회 시 접두어별 독립 시퀀스를 정확히 반영함
|
||||
- **하위호환**: optional 파라미터이므로 기존 호출(`formData`만 전달)에 영향 없음
|
||||
|
||||
### 12. 초기 상태에서 레거시 시퀀스 조회 방지
|
||||
|
||||
- **결정**: `previewCode`에서 수동 파트가 있는데 `manualInputValue`가 없으면 시퀀스 조회를 건너뛰고 `currentSeq = 0` 사용
|
||||
- **근거**: 수정 전에는 모든 할당이 수동 파트 없는 공용 prefix_key를 사용했으므로 레거시 시퀀스가 누적되어 있음(예: 16). 모달 초기 상태에서 이 공용 키를 조회하면 `-016`이 표시됨. 아직 어떤 접두어인지 모르는 상태이므로 `startFrom` 기본값을 보여주는 것이 정확함
|
||||
- **`currentSeq = 0` + `startFrom`**: `nextSequence = 0 + startFrom(5) = 5` → `-005` 표시. 사용자가 입력하면 디바운스 preview가 해당 접두어의 실제 시퀀스를 조회
|
||||
|
||||
### 13. 카테고리 변경 시 수동 입력값 포함하여 순번 재조회
|
||||
|
||||
- **결정**: 초기 useEffect(카테고리 변경 트리거)에서 `previewNumberingCode` 호출 시 현재 `manualInputValue`도 함께 전달
|
||||
- **근거**: 카테고리를 바꾸거나 삭제하면 prefix_key가 달라지므로 순번도 달라져야 함. 기존에는 입력값 변경과 카테고리 변경이 별도 트리거여서 카테고리 변경 시 수동 값이 누락됨
|
||||
- **빈 입력값 처리**: `manualInputValue || undefined`로 처리하여 빈 문자열일 때는 기존처럼 `skipSequenceLookup` 작동
|
||||
|
||||
### 14. 카테고리 해석 로직 resolveCategoryFormat 헬퍼 통합
|
||||
|
||||
- **결정**: `previewCode`, `allocateCode`, `extractManualValuesFromInput` 3곳에 복붙된 카테고리 매핑 해석 로직을 `resolveCategoryFormat` private 메서드로 추출
|
||||
- **근거**: 동일 로직 약 50줄이 3곳에 복사되어 있었음 (변수명만 pool2/ct2/cc2 등으로 다름). 한 곳을 수정하면 나머지도 동일하게 수정해야 하는 유지보수 위험
|
||||
- **원칙**: 구조적 변경만 수행 (로직 변경 없음)
|
||||
|
||||
### BULK1이 DB에 남아있는 이유
|
||||
|
||||
```
|
||||
ManualConfigPanel.tsx: placeholder 입력란만 존재 (value 입력란 없음)
|
||||
플레이스홀더 수정 시: { ...existingConfig, placeholder: newValue }
|
||||
→ 기존 config에 value: "BULK1"이 있으면 스프레드로 계속 보존됨
|
||||
→ UI에서 제거 불가능한 유령 값
|
||||
```
|
||||
@@ -0,0 +1,100 @@
|
||||
# [체크리스트] 품번 수동 접두어 채번 - 접두어별 독립 순번 생성
|
||||
|
||||
> 관련 문서: [계획서](./MPN[계획]-품번-수동접두어채번.md) | [맥락노트](./MPN[맥락]-품번-수동접두어채번.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (전체 완료)
|
||||
- 현재 단계: 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 구조적 변경 (행위 변경 없음)
|
||||
|
||||
- [x] `numberingRuleService.ts`에서 수동 값 추출 로직을 `extractManualValuesFromInput` private 메서드로 분리
|
||||
- [x] 기존 `allocateCode` 내부에서 분리한 메서드 호출로 교체
|
||||
- [x] 기존 동작과 동일한지 확인 (구조적 변경만, 행위 변경 없음)
|
||||
|
||||
### 2단계: buildPrefixKey 수정
|
||||
|
||||
- [x] `buildPrefixKey` 시그니처에 `manualValues?: string[]` 파라미터 추가
|
||||
- [x] 수동 파트 처리 로직 변경: `continue` → `manualValues`에서 값 꺼내 `prefixParts`에 추가
|
||||
- [x] `previewCode` 호출부에 영향 없음 확인 (optional 파라미터)
|
||||
|
||||
### 3단계: allocateCode 순서 변경 + 폴백 정리
|
||||
|
||||
- [x] 수동 값 추출 로직을 `buildPrefixKey` 호출 전으로 이동
|
||||
- [x] 수동 파트 1개 + 추출 실패 시 `userInputCode` 전체를 수동 값으로 사용하는 폴백 추가
|
||||
- [x] `buildPrefixKey` 호출 시 `extractedManualValues`를 세 번째 인자로 전달
|
||||
- [x] 코드 조합 단계에서 `part.manualConfig?.value` 폴백 제거
|
||||
|
||||
### 4단계: DB 마이그레이션
|
||||
|
||||
- [x] `db/migrations/1053_remove_bulk1_manual_config_value.sql` 작성
|
||||
- [x] `manual_config->>'value' = 'BULK1'` 조건으로 JSONB에서 `value` 키 제거
|
||||
- [x] 마이그레이션 실행 (9건 정리 완료)
|
||||
|
||||
### 5단계: 연속 구분자(--) 방지
|
||||
|
||||
- [x] `joinPartsWithSeparators`에서 빈 파트 뒤 연속 구분자 방지 로직 추가
|
||||
- [x] `extractManualValuesFromInput`에서 카테고리/참조 빈 값 시 `""` 반환 (템플릿 정합성)
|
||||
|
||||
### 6단계: 검증
|
||||
|
||||
- [x] 카테고리 선택 + 수동입력 "ㅁㅁㅁ" → 카테고리값-ㅁㅁㅁ-001 생성 확인
|
||||
- [x] 카테고리 미선택 + 수동입력 "ㅁㅁㅁ" → -ㅁㅁㅁ-001 생성 확인 (-- 아님)
|
||||
- [x] 같은 접두어 "ㅁㅁㅁ" 재등록 → -ㅁㅁㅁ-002 순번 증가 확인
|
||||
- [x] 다른 접두어 "ㅇㅇㅇ" 등록 → -ㅇㅇㅇ-001 독립 시퀀스 확인
|
||||
- [x] 수동 파트 없는 채번 규칙 동작 영향 없음 확인
|
||||
- [x] previewCode (미리보기) 동작 영향 없음 확인
|
||||
- [x] BULK1이 더 이상 생성되지 않음 확인
|
||||
|
||||
### 7단계: 실시간 순번 미리보기
|
||||
|
||||
- [x] 백엔드 컨트롤러: preview 엔드포인트에 `manualInputValue` body 파라미터 수신 추가
|
||||
- [x] 백엔드 서비스: `previewCode`에 `manualInputValue` 파라미터 추가, `buildPrefixKey`에 전달
|
||||
- [x] 프론트엔드 API: `previewNumberingCode`에 `manualInputValue` 파라미터 추가
|
||||
- [x] V2Input: `manualInputValue` 변경 시 디바운스(300ms) preview API 호출 + suffix 갱신
|
||||
- [x] 백엔드 서비스: 초기 상태(수동 입력 없음) 시 레거시 공용 시퀀스 조회 건너뜀 → startFrom 기본값 표시
|
||||
- [x] V2Input: 카테고리 변경 시 초기 useEffect에서도 `manualInputValue` 전달 → 순번 즉시 반영
|
||||
- [x] 린트 에러 없음 확인
|
||||
|
||||
### 8단계: 코드 정리
|
||||
|
||||
- [x] 카테고리 해석 로직 3곳 중복 → `resolveCategoryFormat` 헬퍼 추출 (약 100줄 감소)
|
||||
- [x] 임시 변수명 정리 (pool2/ct2/cc2 등 복붙 흔적 제거)
|
||||
- [x] 린트 에러 없음 확인
|
||||
|
||||
### 9단계: 정리
|
||||
|
||||
- [x] 계획서/맥락노트/체크리스트 최신화
|
||||
|
||||
---
|
||||
|
||||
## 알려진 이슈 (보류)
|
||||
|
||||
| 이슈 | 설명 | 상태 |
|
||||
|------|------|------|
|
||||
| 저장 실패 시 순번 갭 | allocateCode와 saveFormData가 별도 트랜잭션이라 저장 실패해도 순번 소비됨 | 보류 |
|
||||
| 유령 데이터 | 중복 품명으로 간헐적 저장 성공 + 리스트 미노출 | 보류 |
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-11 | 계획서, 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-11 | 1-4단계 구현 완료 |
|
||||
| 2026-03-11 | 5단계 추가 구현 (연속 구분자 방지 + 템플릿 정합성 복원) |
|
||||
| 2026-03-11 | 계맥체 최신화 완료. 문제 4-5 보류 |
|
||||
| 2026-03-12 | 7단계 실시간 순번 미리보기 구현 완료 (백엔드/프론트엔드 4파일) |
|
||||
| 2026-03-12 | 계맥체 최신화 완료 |
|
||||
| 2026-03-12 | 초기 상태 레거시 시퀀스 조회 방지 수정 + 계맥체 반영 |
|
||||
| 2026-03-12 | 카테고리 변경 시 수동 입력값 포함 순번 재조회 수정 |
|
||||
| 2026-03-12 | resolveCategoryFormat 헬퍼 추출 코드 정리 + 계맥체 최신화 |
|
||||
| 2026-03-12 | 6단계 검증 완료. 전체 완료 |
|
||||
@@ -0,0 +1,146 @@
|
||||
# [계획서] V2Select 다중 선택 드롭다운 - 선택 항목 표시 개선
|
||||
|
||||
> 관련 문서: [맥락노트](./MST[맥락노트]-v2select-multiselect-tooltip.md) | [체크리스트](./MST[체크리스트]-v2select-multiselect-tooltip.md)
|
||||
|
||||
## 개요
|
||||
|
||||
모든 화면에서 다중 선택 가능한 드롭다운(`V2Select` - `DropdownSelect`)의 선택 항목 표시 방식을 개선합니다.
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
- 다중 선택 시 `"3개 선택됨"` 같은 텍스트만 표시
|
||||
- 어떤 항목이 선택되었는지 드롭다운을 열어야만 확인 가능
|
||||
|
||||
### 현재 코드 (V2Select.tsx - DropdownSelect, 174~178행)
|
||||
|
||||
```tsx
|
||||
{selectedLabels.length > 0
|
||||
? multiple
|
||||
? `${selectedLabels.length}개 선택됨`
|
||||
: selectedLabels[0]
|
||||
: placeholder}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 1. 선택된 항목 라벨을 쉼표로 연결하여 한 줄로 표시
|
||||
|
||||
- 예: `"구매품, 판매품, 재고품"`
|
||||
- `truncate` (text-overflow: ellipsis)로 필드 너비를 넘으면 말줄임(`...`) 처리
|
||||
- 무조건 한 줄 표시, 넘치면 `...`으로 숨김
|
||||
|
||||
### 2. 텍스트가 말줄임(`...`) 처리될 때만 호버 툴팁 표시
|
||||
|
||||
- 필드 너비를 넘어서 `...`으로 잘릴 때만 툴팁 활성화
|
||||
- 필드 내에 전부 보이면 툴팁 불필요
|
||||
- 툴팁 내용은 세로 나열로 각 항목을 한눈에 확인 가능
|
||||
- 툴팁은 딜레이 없이 즉시 표시
|
||||
|
||||
---
|
||||
|
||||
## 시각적 동작 예시
|
||||
|
||||
| 상태 | 필드 내 표시 | 호버 시 툴팁 |
|
||||
|------|-------------|-------------|
|
||||
| 미선택 | `선택` (placeholder) | 없음 |
|
||||
| 1개 선택 | `구매품` | 없음 |
|
||||
| 3개 선택 (필드 내 수용) | `구매품, 판매품, 재고품` | 없음 (잘리지 않으므로) |
|
||||
| 5개 선택 (필드 넘침) | `구매품, 판매품, 재고품, 외...` | 구매품 / 판매품 / 재고품 / 외주품 / 반제품 (세로 나열) |
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상
|
||||
|
||||
- **파일**: `frontend/components/v2/V2Select.tsx`
|
||||
- **컴포넌트**: `DropdownSelect` 내부 표시 텍스트 부분 (170~178행)
|
||||
- **적용 범위**: `DropdownSelect`를 사용하는 모든 화면 (품목정보, 기타 모든 모달 포함)
|
||||
- **변경 규모**: 약 30줄 내외 소규모 변경
|
||||
|
||||
---
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### 추가 import
|
||||
|
||||
```tsx
|
||||
import { useRef, useEffect, useState } from "react";
|
||||
import {
|
||||
Tooltip,
|
||||
TooltipContent,
|
||||
TooltipProvider,
|
||||
TooltipTrigger,
|
||||
} from "@/components/ui/tooltip";
|
||||
```
|
||||
|
||||
### 말줄임 감지 로직
|
||||
|
||||
```tsx
|
||||
// 텍스트가 잘리는지(truncated) 감지
|
||||
const textRef = useRef<HTMLSpanElement>(null);
|
||||
const [isTruncated, setIsTruncated] = useState(false);
|
||||
|
||||
useEffect(() => {
|
||||
const el = textRef.current;
|
||||
if (el) {
|
||||
setIsTruncated(el.scrollWidth > el.clientWidth);
|
||||
}
|
||||
}, [selectedLabels]);
|
||||
```
|
||||
|
||||
### 수정 코드 (DropdownSelect 내부, 170~178행 대체)
|
||||
|
||||
```tsx
|
||||
const displayText = selectedLabels.length > 0
|
||||
? (multiple ? selectedLabels.join(", ") : selectedLabels[0])
|
||||
: placeholder;
|
||||
|
||||
const isPlaceholder = selectedLabels.length === 0;
|
||||
|
||||
// 렌더링 부분
|
||||
{isTruncated && multiple ? (
|
||||
<TooltipProvider delayDuration={0}>
|
||||
<Tooltip>
|
||||
<TooltipTrigger asChild>
|
||||
<span
|
||||
ref={textRef}
|
||||
className={cn("truncate flex-1 text-left", isPlaceholder && "text-muted-foreground")}
|
||||
{...(isPlaceholder ? { "data-placeholder": placeholder } : {})}
|
||||
>
|
||||
{displayText}
|
||||
</span>
|
||||
</TooltipTrigger>
|
||||
<TooltipContent side="top" className="max-w-[300px]">
|
||||
<div className="space-y-0.5 text-xs">
|
||||
{selectedLabels.map((label, i) => (
|
||||
<div key={i}>{label}</div>
|
||||
))}
|
||||
</div>
|
||||
</TooltipContent>
|
||||
</Tooltip>
|
||||
</TooltipProvider>
|
||||
) : (
|
||||
<span
|
||||
ref={textRef}
|
||||
className={cn("truncate flex-1 text-left", isPlaceholder && "text-muted-foreground")}
|
||||
{...(isPlaceholder ? { "data-placeholder": placeholder } : {})}
|
||||
>
|
||||
{displayText}
|
||||
</span>
|
||||
)}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- 기존 단일 선택 동작은 변경하지 않음
|
||||
- `DropdownSelect` 공통 컴포넌트 수정이므로 모든 화면에 자동 적용
|
||||
- 무조건 한 줄 표시, 넘치면 `...`으로 말줄임
|
||||
- 툴팁은 텍스트가 실제로 잘릴 때(`scrollWidth > clientWidth`)만 표시
|
||||
- 툴팁 내용은 세로 나열로 각 항목 확인 용이
|
||||
- 툴팁 딜레이 없음 (`delayDuration={0}`)
|
||||
- shadcn 표준 Tooltip 컴포넌트 사용으로 프로젝트 일관성 유지
|
||||
@@ -0,0 +1,95 @@
|
||||
# [맥락노트] V2Select 다중 선택 드롭다운 - 선택 항목 표시 개선
|
||||
|
||||
> 관련 문서: [계획서](./MST[계획서]-v2select-multiselect-tooltip.md) | [체크리스트](./MST[체크리스트]-v2select-multiselect-tooltip.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 사용자가 수정 모달에서 다중 선택 드롭다운을 사용할 때 `"3개 선택됨"` 만 보임
|
||||
- 드롭다운을 다시 열어봐야만 무엇이 선택됐는지 확인 가능 → UX 불편
|
||||
- 선택 항목을 직접 보여주고, 넘치면 툴팁으로 확인할 수 있게 개선
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. "n개 선택됨" → 라벨 쉼표 나열
|
||||
|
||||
- **결정**: `"구매품, 판매품, 재고품"` 형태로 표시
|
||||
- **근거**: 사용자가 드롭다운을 열지 않아도 선택 내용을 바로 확인 가능
|
||||
|
||||
### 2. 무조건 한 줄, 넘치면 말줄임(`...`)
|
||||
|
||||
- **결정**: 여러 줄 줄바꿈 없이 한 줄 고정, `truncate`로 오버플로우 처리
|
||||
- **근거**: 드롭다운 필드 높이가 고정되어 있어 여러 줄 표시 시 레이아웃이 깨짐
|
||||
|
||||
### 3. 텍스트가 잘릴 때만 툴팁 표시
|
||||
|
||||
- **결정**: `scrollWidth > clientWidth` 비교로 실제 잘림 여부 감지 후 툴팁 활성화
|
||||
- **근거**: 전부 보이는데 툴팁이 뜨면 오히려 방해. 필요할 때만 보여야 함
|
||||
- **대안 검토**: "2개 이상이면 항상 툴팁" → 기각 (불필요한 툴팁 발생)
|
||||
|
||||
### 4. 툴팁 내용은 세로 나열
|
||||
|
||||
- **결정**: 툴팁 안에서 항목을 줄바꿈으로 세로 나열
|
||||
- **근거**: 가로 나열 시 툴팁도 길어져서 읽기 어려움. 세로가 한눈에 파악하기 좋음
|
||||
|
||||
### 5. 툴팁 딜레이 0ms
|
||||
|
||||
- **결정**: `delayDuration={0}` 즉시 표시
|
||||
- **근거**: 사용자가 "무엇을 선택했는지" 확인하려는 의도적 행동이므로 즉시 응답해야 함
|
||||
|
||||
### 6. Radix Tooltip 대신 커스텀 호버 툴팁 사용
|
||||
|
||||
- **결정**: Radix Tooltip을 사용하지 않고 `onMouseEnter`/`onMouseLeave`로 직접 제어
|
||||
- **근거**: Radix Tooltip + Popover 조합은 이벤트 충돌 발생. 내부 배치든 외부 래핑이든 Popover가 호버를 가로챔
|
||||
- **시도 1**: Tooltip을 Button 안에 배치 → Popover가 이벤트 가로챔 (실패)
|
||||
- **시도 2**: Radix 공식 패턴 (TooltipTrigger > PopoverTrigger > Button 체이닝) → 여전히 동작 안 함 (실패)
|
||||
- **최종**: wrapper div에 마우스 이벤트 + 절대 위치 div로 툴팁 렌더링 (성공)
|
||||
- **추가**: Popover 열릴 때 `setHoverTooltip(false)`로 툴팁 자동 숨김
|
||||
|
||||
### 8. 선택 항목 표시 순서는 드롭다운 옵션 순서 기준
|
||||
|
||||
- **결정**: 사용자가 클릭한 순서가 아닌 드롭다운 옵션 목록 순서대로 표시
|
||||
- **근거**: 선택 순서대로 보여주면 매번 순서가 달라져서 혼란. 옵션 순서 기준이 일관적이고 예측 가능
|
||||
- **구현**: `selectedValues.map(...)` → `safeOptions.filter(...).map(...)` 으로 변경
|
||||
|
||||
### 9. DropdownSelect 공통 컴포넌트 수정
|
||||
|
||||
- **결정**: 특정 화면이 아닌 `DropdownSelect` 자체를 수정
|
||||
- **근거**: 품목정보뿐 아니라 모든 화면에서 동일한 문제가 있으므로 공통 해결
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 대상 | `frontend/components/v2/V2Select.tsx` | DropdownSelect 컴포넌트 (170~178행) |
|
||||
| 타입 정의 | `frontend/types/v2-components.ts` | V2SelectProps, SelectOption 타입 |
|
||||
| UI 컴포넌트 | `frontend/components/ui/tooltip.tsx` | shadcn Tooltip 컴포넌트 |
|
||||
| 렌더러 | `frontend/lib/registry/components/v2-select/V2SelectRenderer.tsx` | V2Select를 레지스트리에 연결 |
|
||||
| 수정 모달 | `frontend/components/screen/EditModal.tsx` | 공통 편집 모달 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### truncate 감지 방식
|
||||
|
||||
```
|
||||
scrollWidth: 텍스트의 실제 전체 너비 (보이지 않는 부분 포함)
|
||||
clientWidth: 요소의 보이는 너비
|
||||
|
||||
scrollWidth > clientWidth → 텍스트가 잘리고 있음 (... 표시 중)
|
||||
```
|
||||
|
||||
### selectedLabels 계산 흐름
|
||||
|
||||
```
|
||||
value (string[]) → selectedValues → safeOptions에서 label 매칭 → selectedLabels (string[])
|
||||
```
|
||||
|
||||
- `selectedLabels`는 이미 `DropdownSelect` 내부에서 `useMemo`로 계산됨 (126~130행)
|
||||
- 추가 데이터 fetching 불필요, 기존 값을 `.join(", ")`로 결합하면 됨
|
||||
@@ -0,0 +1,54 @@
|
||||
# [체크리스트] V2Select 다중 선택 드롭다운 - 선택 항목 표시 개선
|
||||
|
||||
> 관련 문서: [계획서](./MST[계획서]-v2select-multiselect-tooltip.md) | [맥락노트](./MST[맥락노트]-v2select-multiselect-tooltip.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (완료)
|
||||
- 현재 단계: 전체 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 코드 수정
|
||||
|
||||
- [x] `V2Select.tsx`에 Tooltip 관련 import 추가
|
||||
- [x] `DropdownSelect` 내부에 `textRef`, `isTruncated` 상태 추가
|
||||
- [x] `useEffect`로 `scrollWidth > clientWidth` 감지 로직 추가
|
||||
- [x] 표시 텍스트를 `selectedLabels.join(", ")`로 변경
|
||||
- [x] `isTruncated && multiple` 조건으로 Tooltip 래핑
|
||||
- [x] 툴팁 내용을 세로 나열 (`space-y-0.5`)로 구성
|
||||
- [x] `delayDuration={0}` 설정
|
||||
- [x] Radix Tooltip → 커스텀 호버 툴팁으로 변경 (onMouseEnter/onMouseLeave + 절대 위치 div)
|
||||
- [x] 선택 항목 표시 순서를 드롭다운 옵션 순서 기준으로 변경
|
||||
|
||||
### 2단계: 검증
|
||||
|
||||
- [x] 단일 선택 모드: 기존 동작 변화 없음 확인
|
||||
- [x] 다중 선택 1개: 라벨 정상 표시, 툴팁 없음
|
||||
- [x] 다중 선택 3개 (필드 내 수용): 쉼표 나열 표시, 툴팁 없음
|
||||
- [x] 다중 선택 5개+ (필드 넘침): 말줄임 표시, 호버 시 툴팁 세로 나열
|
||||
- [x] 품목정보 수정 모달에서 동작 확인
|
||||
- [x] 다른 화면의 다중 선택 드롭다운에서도 동작 확인
|
||||
|
||||
### 3단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인
|
||||
- [x] 이 체크리스트 완료 표시 업데이트
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-04 | 설계 문서 작성 완료 |
|
||||
| 2026-03-04 | 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-04 | 파일명 MST 접두사 적용 |
|
||||
| 2026-03-04 | 1단계 코드 수정 완료 (V2Select.tsx) |
|
||||
| 2026-03-04 | Radix Tooltip이 Popover와 충돌 → 커스텀 호버 툴팁으로 변경 |
|
||||
| 2026-03-04 | 사용자 검증 완료, 전체 작업 완료 |
|
||||
| 2026-03-04 | 선택 항목 표시 순서를 옵션 순서 기준으로 변경 |
|
||||
@@ -0,0 +1,128 @@
|
||||
# [계획서] 페이징 - 페이지 번호 직접 입력 네비게이션
|
||||
|
||||
> 관련 문서: [맥락노트](./PGN[맥락]-페이징-직접입력.md) | [체크리스트](./PGN[체크]-페이징-직접입력.md)
|
||||
|
||||
## 개요
|
||||
|
||||
v2-table-list 컴포넌트의 하단 페이지네이션 중앙 영역에서, 현재 페이지 번호를 **읽기 전용 텍스트**에서 **입력 가능한 필드**로 변경합니다.
|
||||
사용자가 원하는 페이지 번호를 키보드로 직접 입력하여 빠르게 이동할 수 있게 합니다.
|
||||
|
||||
### 이전 설계(10개 번호 버튼 그룹) 폐기 사유
|
||||
|
||||
- 10개 버튼은 공간을 많이 차지하고, 모바일에서 렌더링이 어려움
|
||||
- 고정 슬롯/고정 너비 등 복잡한 레이아웃 제약이 발생
|
||||
- 입력 필드 방식이 더 직관적이고 공간 효율적
|
||||
|
||||
---
|
||||
|
||||
## 변경 전 → 변경 후
|
||||
|
||||
### 페이지네이션 UI
|
||||
|
||||
```
|
||||
변경 전: [<<] [<] 1 / 38 [>] [>>] ← 읽기 전용 텍스트
|
||||
변경 후: [<<] [<] [ 15 ] / 49 [>] [>>] ← 입력 가능 필드
|
||||
```
|
||||
|
||||
| 버튼 | 동작 (변경 없음) |
|
||||
|------|-----------------|
|
||||
| `<<` | 첫 페이지(1)로 이동 |
|
||||
| `<` | 이전 페이지(`currentPage - 1`)로 이동 |
|
||||
| 중앙 | **입력 필드** `/` **총 페이지** — 사용자가 원하는 페이지 번호를 직접 입력 |
|
||||
| `>` | 다음 페이지(`currentPage + 1`)로 이동 |
|
||||
| `>>` | 마지막 페이지(`totalPages`)로 이동 |
|
||||
|
||||
### 입력 필드 동작 규칙
|
||||
|
||||
| 동작 | 설명 |
|
||||
|------|------|
|
||||
| 클릭 | 입력 필드에 포커스, 기존 숫자 전체 선택(select all) |
|
||||
| 숫자 입력 | 자유롭게 타이핑 가능 (입력 중에는 페이지 이동 안 함) |
|
||||
| Enter | 입력한 페이지로 이동 + 포커스 해제 |
|
||||
| 포커스 아웃 (blur) | 입력한 페이지로 이동 |
|
||||
| 유효 범위 보정 | 1 미만 → 1, totalPages 초과 → totalPages, 빈 값/비숫자 → 현재 페이지 유지 |
|
||||
| `< >` 클릭 | 기존대로 한 페이지씩 이동 (입력 필드 값도 갱신) |
|
||||
| `<< >>` 클릭 | 기존대로 첫/끝 페이지 이동 (입력 필드 값도 갱신) |
|
||||
|
||||
### 비활성화 조건 (기존과 동일)
|
||||
|
||||
- `<<` `<` : `currentPage === 1`
|
||||
- `>` `>>` : `currentPage >= totalPages`
|
||||
|
||||
---
|
||||
|
||||
## 시각적 동작 예시
|
||||
|
||||
총 49페이지 기준:
|
||||
|
||||
| 사용자 동작 | 입력 필드 표시 | 결과 |
|
||||
|------------|---------------|------|
|
||||
| 초기 상태 | `1 / 49` | 1페이지 표시 |
|
||||
| 입력 필드 클릭 | `[1]` 전체 선택됨 | 타이핑 대기 |
|
||||
| `28` 입력 후 Enter | `28 / 49` | 28페이지로 이동 |
|
||||
| `0` 입력 후 Enter | `1 / 49` | 1로 보정 |
|
||||
| `999` 입력 후 Enter | `49 / 49` | 49로 보정 |
|
||||
| 빈 값으로 blur | `28 / 49` | 이전 페이지(28) 유지 |
|
||||
| `abc` 입력 후 Enter | `28 / 49` | 이전 페이지(28) 유지 |
|
||||
| `>` 클릭 | `29 / 49` | 29페이지로 이동 |
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
### 데이터 흐름
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["currentPage (state, 단일 소스)"] --> B["입력 필드 표시값 (pageInputValue)"]
|
||||
B -->|"사용자 타이핑"| C["pageInputValue 갱신 (표시만)"]
|
||||
C -->|"Enter 또는 blur"| D["유효 범위 보정 (1~totalPages)"]
|
||||
D -->|"보정된 값"| E[handlePageChange]
|
||||
E --> F["setCurrentPage → useEffect → fetchTableDataDebounced"]
|
||||
F --> G[백엔드 API 호출]
|
||||
G --> H[데이터 갱신]
|
||||
H --> A
|
||||
|
||||
I["<< < > >> 클릭"] --> E
|
||||
J["페이지크기 변경"] --> K["setCurrentPage(1) + setLocalPageSize + onConfigChange"]
|
||||
K --> F
|
||||
```
|
||||
|
||||
### 페이징 바 레이아웃
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ [페이지크기 입력] │ << < [__입력__] / n > >> │ [내보내기][새로고침] │
|
||||
│ 좌측(유지) │ 중앙(입력필드 교체) │ 우측(유지) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 구분 | 파일 | 변경 내용 |
|
||||
|------|------|----------|
|
||||
| 수정 | `TableListComponent.tsx` | (1) `pageInputValue` 상태 + `useEffect` 동기화 + `commitPageInput` 핸들러 추가 |
|
||||
| | | (2) paginationJSX 중앙 `<span>` → `<input>` + `/` + `<span>` 교체 |
|
||||
| | | (3) `handlePageSizeChange`에 `onConfigChange` 호출 추가 |
|
||||
| | | (4) `fetchTableDataInternal`에서 `currentPage`를 단일 소스로 사용 |
|
||||
| | | (5) `useMemo` 의존성에 `pageInputValue` 추가 |
|
||||
| 삭제 | `PageGroupNav.tsx` | 이전 설계 산출물 삭제 (이미 삭제됨) |
|
||||
|
||||
- 신규 파일 생성 없음
|
||||
- 백엔드 변경 없음, DB 변경 없음
|
||||
- v2-table-list를 사용하는 **모든 동적 화면**에 자동 적용
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- **최소 변경**: `<span>` 1개를 `<input>` + 유효성 검증으로 교체. 나머지 전부 유지
|
||||
- **기존 버튼 동작 무변경**: `<< < > >>` 4개 버튼의 onClick/disabled 로직은 그대로
|
||||
- **`handlePageChange` 재사용**: 기존 함수를 그대로 호출
|
||||
- **입력 중 페이지 이동 안 함**: onChange는 표시만 변경, Enter/blur로 실제 적용
|
||||
- **유효 범위 자동 보정**: 1 미만 → 1, totalPages 초과 → totalPages, 비숫자 → 현재 값 유지
|
||||
- **포커스 시 전체 선택**: 클릭하면 바로 타이핑 가능
|
||||
- **`currentPage`가 단일 소스**: fetch 시 `tableConfig.pagination?.currentPage` 대신 로컬 `currentPage`만 사용 (비동기 전파 문제 방지)
|
||||
- **페이지크기 변경 시 1페이지로 리셋**: `handlePageSizeChange`가 `onConfigChange`를 호출하여 부모/백엔드 동기화
|
||||
@@ -0,0 +1,115 @@
|
||||
# [맥락노트] 페이징 - 페이지 번호 직접 입력 네비게이션
|
||||
|
||||
> 관련 문서: [계획서](./PGN[계획]-페이징-직접입력.md) | [체크리스트](./PGN[체크]-페이징-직접입력.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 현재 페이지네이션은 `1 / 38` 읽기 전용 텍스트만 표시
|
||||
- 수십 페이지가 있을 때 원하는 페이지로 빠르게 이동할 수 없음 (`>` 연타 필요)
|
||||
- 페이지 번호를 직접 입력하여 즉시 이동할 수 있어야 UX가 개선됨
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 10개 번호 버튼 그룹 → 입력 필드로 설계 변경
|
||||
|
||||
- **결정**: 이전 설계(10개 페이지 번호 버튼 나열)를 폐기하고, 기존 `현재/총` 텍스트에서 현재 부분을 입력 필드로 교체
|
||||
- **근거**: 10개 버튼은 공간을 많이 차지하고 고정 슬롯/고정 너비 등 복잡한 레이아웃 제약이 발생. 입력 필드 방식이 더 직관적이고 공간 효율적
|
||||
- **이전 산출물**: `PageGroupNav.tsx` → 삭제 완료
|
||||
|
||||
### 2. `<< < > >>` 버튼 동작 유지
|
||||
|
||||
- **결정**: 4개 화살표 버튼의 동작은 기존과 완전히 동일하게 유지
|
||||
- **근거**: 입력 필드가 "원하는 페이지로 점프" 역할을 하므로, 버튼은 기존의 순차 이동(+1/-1, 첫/끝) 그대로 유지하는 것이 자연스러움
|
||||
|
||||
### 3. 입력 중에는 페이지 이동 안 함
|
||||
|
||||
- **결정**: onChange는 입력 필드 표시만 변경. Enter 또는 blur로 실제 페이지 이동
|
||||
- **근거**: `28`을 입력하려면 `2`를 먼저 치는데, `2`에서 바로 이동하면 안 됨
|
||||
|
||||
### 4. 포커스 시 전체 선택 (select all)
|
||||
|
||||
- **결정**: 입력 필드 클릭 시 기존 숫자를 전체 선택
|
||||
- **근거**: 사용자가 "15페이지로 가고 싶다" → 클릭 → 바로 `15` 타이핑. 기존 값을 지우는 추가 동작 불필요
|
||||
|
||||
### 5. 유효 범위 자동 보정
|
||||
|
||||
- **결정**: 1 미만 → 1, totalPages 초과 → totalPages, 빈 값/비숫자 → 현재 페이지 유지
|
||||
- **근거**: 에러 메시지보다 자동 보정이 UX에 유리
|
||||
- **대안 검토**: 입력 자체를 숫자만 허용 → 기각 (백스페이스로 비울 때 불편)
|
||||
|
||||
### 6. `inputMode="numeric"` 사용
|
||||
|
||||
- **결정**: `type="text"` + `inputMode="numeric"`
|
||||
- **근거**: `type="number"`는 브라우저별 스피너 UI가 추가되고, 빈 값 처리가 어려움. `inputMode="numeric"`은 모바일에서 숫자 키보드를 띄우면서 text 입력의 유연성 유지
|
||||
|
||||
### 7. 신규 컴포넌트 분리 안 함
|
||||
|
||||
- **결정**: v2-table-list의 paginationJSX 내부에 인라인으로 구현
|
||||
- **근거**: 변경이 `<span>` → `<input>` + 핸들러 약 30줄 수준으로 매우 작음
|
||||
|
||||
### 8. `currentPage`를 fetch의 단일 소스로 사용
|
||||
|
||||
- **결정**: `fetchTableDataInternal`에서 `tableConfig.pagination?.currentPage || currentPage` 대신 `currentPage`만 사용
|
||||
- **근거**: `handlePageSizeChange`에서 `setCurrentPage(1)` + `onConfigChange(...)` 호출 시, `onConfigChange`를 통한 부모의 `tableConfig` 갱신은 다음 렌더 사이클에서 전파됨. fetch가 실행되는 시점에 `tableConfig.pagination?.currentPage`가 아직 이전 값(예: 4)이고 truthy이므로 로컬 `currentPage`(1) 대신 4를 사용하게 되는 문제 발생. 로컬 `currentPage`는 `setCurrentPage`로 즉시 갱신되므로 이 문제가 없음
|
||||
- **발견 과정**: 페이지 크기를 20→40으로 변경하면 1페이지로 설정되지만 리스트가 빈 상태로 표시되는 버그로 발견
|
||||
|
||||
### 9. `handlePageSizeChange`에서 `onConfigChange` 호출 필수
|
||||
|
||||
- **결정**: 페이지 크기 변경 시 `onConfigChange`로 `{ pageSize, currentPage: 1 }`을 부모에게 전달
|
||||
- **근거**: 기존 코드는 `setLocalPageSize` + `setCurrentPage(1)`만 호출하고 `onConfigChange`를 호출하지 않았음. 이로 인해 부모 컴포넌트의 `tableConfig.pagination`이 갱신되지 않아 후속 동작에서 stale 값 참조 가능
|
||||
- **발견 과정**: 위 8번과 같은 맥락에서 발견
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 | `frontend/lib/registry/components/v2-table-list/TableListComponent.tsx` | paginationJSX 중앙 입력 필드 + fetch 소스 수정 |
|
||||
| 삭제 | `frontend/components/common/PageGroupNav.tsx` | 이전 설계 산출물 (삭제 완료) |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### 로컬 입력 상태와 실제 페이지 상태 분리
|
||||
|
||||
```
|
||||
pageInputValue (string) — 입력 필드에 표시되는 값 (사용자가 타이핑 중일 수 있음)
|
||||
currentPage (number) — 실제 현재 페이지 (API 호출의 단일 소스)
|
||||
|
||||
동기화:
|
||||
- currentPage 변경 시 → useEffect → setPageInputValue(String(currentPage))
|
||||
- Enter/blur 시 → commitPageInput → parseInt + clamp → handlePageChange(보정된 값)
|
||||
```
|
||||
|
||||
### handlePageChange 호출 흐름
|
||||
|
||||
```
|
||||
입력 필드 Enter/blur
|
||||
→ commitPageInput()
|
||||
→ parseInt + clamp(1, totalPages)
|
||||
→ handlePageChange(clampedPage)
|
||||
→ setCurrentPage(clampedPage) + onConfigChange
|
||||
→ useEffect 트리거 → fetchTableDataDebounced
|
||||
→ fetchTableDataInternal(page = currentPage)
|
||||
→ 백엔드 API 호출
|
||||
```
|
||||
|
||||
### handlePageSizeChange 호출 흐름
|
||||
|
||||
```
|
||||
좌측 페이지크기 입력 onChange/onBlur
|
||||
→ handlePageSizeChange(newSize)
|
||||
→ setLocalPageSize(newSize)
|
||||
→ setCurrentPage(1)
|
||||
→ sessionStorage 저장
|
||||
→ onConfigChange({ pageSize: newSize, currentPage: 1 })
|
||||
→ useEffect 트리거 → fetchTableDataDebounced
|
||||
→ fetchTableDataInternal(page = 1, pageSize = newSize)
|
||||
→ 백엔드 API 호출
|
||||
```
|
||||
@@ -0,0 +1,73 @@
|
||||
# [체크리스트] 페이징 - 페이지 번호 직접 입력 네비게이션
|
||||
|
||||
> 관련 문서: [계획서](./PGN[계획]-페이징-직접입력.md) | [맥락노트](./PGN[맥락]-페이징-직접입력.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (완료)
|
||||
- 현재 단계: 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 1단계: 이전 설계 산출물 정리
|
||||
|
||||
- [x] `frontend/components/common/PageGroupNav.tsx` 삭제
|
||||
- [x] `TableListComponent.tsx`에서 `PageGroupNav` import 제거 (있으면) — 이미 없음
|
||||
|
||||
### 2단계: 입력 필드 구현
|
||||
|
||||
- [x] `pageInputValue` 로컬 상태 추가 (`useState<string>`)
|
||||
- [x] `currentPage` 변경 시 `pageInputValue` 동기화 (`useEffect`)
|
||||
- [x] `commitPageInput` 핸들러 구현 (parseInt + clamp + handlePageChange)
|
||||
- [x] paginationJSX 중앙의 `<span>` → `<input>` + `/` + `<span>` 교체
|
||||
- [x] `inputMode="numeric"` 적용
|
||||
- [x] `onFocus`에 전체 선택 (`e.target.select()`)
|
||||
- [x] `onChange`에 `setPageInputValue` (표시만 변경)
|
||||
- [x] `onKeyDown` Enter에 `commitPageInput` + `blur()`
|
||||
- [x] `onBlur`에 `commitPageInput`
|
||||
- [x] `disabled={loading}` 적용
|
||||
- [x] 기존 좌측 페이지크기 입력과 일관된 스타일 적용
|
||||
|
||||
### 3단계: 버그 수정
|
||||
|
||||
- [x] `handlePageSizeChange`에 `onConfigChange` 호출 추가 (`pageSize` + `currentPage: 1` 전달)
|
||||
- [x] `fetchTableDataInternal`에서 `currentPage`를 단일 소스로 변경 (stale `tableConfig.pagination?.currentPage` 문제 해결)
|
||||
- [x] `useCallback` 의존성에서 `tableConfig.pagination?.currentPage` 제거
|
||||
- [x] `useMemo` 의존성에 `pageInputValue` 추가
|
||||
|
||||
### 4단계: 검증
|
||||
|
||||
- [x] 입력 필드에 숫자 입력 후 Enter → 해당 페이지로 이동
|
||||
- [x] 입력 필드에 숫자 입력 후 포커스 아웃 → 해당 페이지로 이동
|
||||
- [x] 0 입력 → 1로 보정
|
||||
- [x] totalPages 초과 입력 → totalPages로 보정
|
||||
- [x] 빈 값으로 blur → 현재 페이지 유지
|
||||
- [x] 비숫자(abc) 입력 후 Enter → 현재 페이지 유지
|
||||
- [x] 입력 필드 클릭 시 기존 숫자 전체 선택 확인
|
||||
- [x] `< >` 버튼 클릭 시 입력 필드 값도 갱신 확인
|
||||
- [x] `<< >>` 버튼 클릭 시 입력 필드 값도 갱신 확인
|
||||
- [x] 로딩 중 입력 필드 비활성화 확인
|
||||
- [x] 좌측 페이지크기 입력과 스타일 일관성 확인
|
||||
- [x] 기존 `<< < > >>` 버튼 동작 변화 없음 확인
|
||||
- [x] 페이지크기 변경 시 1페이지로 리셋 + 데이터 정상 로딩 확인
|
||||
|
||||
### 5단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인 (기존 에러만 존재, 신규 없음)
|
||||
- [x] 문서(계획서/맥락노트/체크리스트) 최신화 완료
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-11 | 최초 설계: 10개 번호 버튼 그룹 (PageGroupNav) |
|
||||
| 2026-03-11 | 설계 변경: 입력 필드 방식으로 전면 재작성 |
|
||||
| 2026-03-11 | 구현 완료: 입력 필드 + 유효성 검증 |
|
||||
| 2026-03-11 | 버그 수정: 페이지크기 변경 시 빈 데이터 문제 (onConfigChange 누락 + stale currentPage) |
|
||||
| 2026-03-11 | 문서 최신화: 버그 수정 내역 반영, 코드 설계 섹션 제거 (구현 완료) |
|
||||
@@ -0,0 +1,350 @@
|
||||
# [계획서] 렉 구조 등록 - 층(floor) 필수 입력 해제
|
||||
|
||||
> 관련 문서: [맥락노트](./RFO[맥락]-렉구조-층필수해제.md) | [체크리스트](./RFO[체크]-렉구조-층필수해제.md)
|
||||
|
||||
## 개요
|
||||
|
||||
탑씰 회사의 물류관리 > 창고정보 관리 > 렉 구조 등록 모달에서, "층" 필드를 필수 입력에서 선택 입력으로 변경합니다. 현재 "창고 코드 / 층 / 구역" 3개가 모두 필수로 하드코딩되어 있어, 층을 선택하지 않으면 미리보기 생성과 저장이 불가능합니다.
|
||||
|
||||
---
|
||||
|
||||
## 현재 동작
|
||||
|
||||
### 1. 필수 필드 경고 (RackStructureComponent.tsx:291~298)
|
||||
|
||||
층을 선택하지 않으면 빨간 경고가 표시됨:
|
||||
|
||||
```tsx
|
||||
const missingFields = useMemo(() => {
|
||||
const missing: string[] = [];
|
||||
if (!context.warehouseCode) missing.push("창고 코드");
|
||||
if (!context.floor) missing.push("층"); // ← 하드코딩 필수
|
||||
if (!context.zone) missing.push("구역");
|
||||
return missing;
|
||||
}, [context]);
|
||||
```
|
||||
|
||||
> "다음 필드를 먼저 입력해주세요: **층**"
|
||||
|
||||
### 2. 미리보기 생성 차단 (RackStructureComponent.tsx:517~521)
|
||||
|
||||
`missingFields`에 "층"이 포함되어 있으면 `generatePreview()` 실행이 차단됨:
|
||||
|
||||
```tsx
|
||||
if (missingFields.length > 0) {
|
||||
alert(`다음 필드를 먼저 입력해주세요: ${missingFields.join(", ")}`);
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 위치 코드 생성 (RackStructureComponent.tsx:497~513)
|
||||
|
||||
floor가 없으면 기본값 `"1"`을 사용하여 위치 코드를 생성:
|
||||
|
||||
```tsx
|
||||
const floor = context?.floor || "1";
|
||||
const code = `${warehouseCode}-${floor}${zone}-${row.toString().padStart(2, "0")}-${level}`;
|
||||
// 예: WH001-1층A구역-01-1
|
||||
```
|
||||
|
||||
### 4. 기존 데이터 조회 (RackStructureComponent.tsx:378~432)
|
||||
|
||||
floor가 비어있으면 기존 데이터 조회 자체를 건너뜀 → 중복 체크 불가:
|
||||
|
||||
```tsx
|
||||
if (!warehouseCodeForQuery || !floorForQuery || !zoneForQuery) {
|
||||
setExistingLocations([]);
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 렉 구조 화면 감지 (buttonActions.ts:692~698)
|
||||
|
||||
floor가 비어있으면 렉 구조 화면으로 인식하지 않음 → 일반 저장으로 빠짐:
|
||||
|
||||
```tsx
|
||||
const isRackStructureScreen =
|
||||
context.tableName === "warehouse_location" &&
|
||||
context.formData?.floor && // ← floor 없으면 false
|
||||
context.formData?.zone &&
|
||||
!rackStructureLocations;
|
||||
```
|
||||
|
||||
### 6. 저장 전 중복 체크 (buttonActions.ts:2085~2131)
|
||||
|
||||
floor가 없으면 중복 체크 전체를 건너뜀:
|
||||
|
||||
```tsx
|
||||
if (warehouseCode && floor && zone) {
|
||||
// 중복 체크 로직
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 후 동작
|
||||
|
||||
### 1. 필수 필드에서 "층" 제거
|
||||
|
||||
- "창고 코드"와 "구역"만 필수
|
||||
- 층을 선택하지 않아도 경고가 뜨지 않음
|
||||
|
||||
### 2. 미리보기 생성 정상 동작
|
||||
|
||||
- 층 없이도 미리보기 생성 가능
|
||||
- 위치 코드에서 층 부분을 생략하여 깔끔하게 생성
|
||||
|
||||
### 3. 위치 코드 생성 규칙 변경
|
||||
|
||||
- 층 있을 때: `WH001-1층A구역-01-1` (기존과 동일)
|
||||
- 층 없을 때: `WH001-A구역-01-1` (층 부분 생략)
|
||||
|
||||
### 4. 기존 데이터 조회 (중복 체크)
|
||||
|
||||
- 층 있을 때: `warehouse_code + floor + zone`으로 조회 (기존과 동일)
|
||||
- 층 없을 때: `warehouse_code + zone`으로 조회 (floor 조건 제외)
|
||||
|
||||
### 5. 렉 구조 화면 감지
|
||||
|
||||
- floor 유무와 관계없이 `warehouse_location` 테이블 + zone 필드가 있으면 렉 구조 화면으로 인식
|
||||
|
||||
### 6. 저장 시 floor 값
|
||||
|
||||
- 층 선택함: `floor = "1층"` 등 선택한 값 저장
|
||||
- 층 미선택: `floor = NULL`로 저장
|
||||
|
||||
---
|
||||
|
||||
## 시각적 예시
|
||||
|
||||
| 상태 | 경고 메시지 | 미리보기 | 위치 코드 | DB floor 값 |
|
||||
|------|------------|---------|-----------|------------|
|
||||
| 창고+층+구역 모두 선택 | 없음 | 생성 가능 | `WH001-1층A구역-01-1` | `"1층"` |
|
||||
| 창고+구역만 선택 (층 미선택) | 없음 | 생성 가능 | `WH001-A구역-01-1` | `NULL` |
|
||||
| 창고만 선택 | "구역을 먼저 입력해주세요" | 차단 | - | - |
|
||||
| 아무것도 미선택 | "창고 코드, 구역을 먼저 입력해주세요" | 차단 | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
### 데이터 흐름 (변경 전)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[사용자: 창고/층/구역 입력] --> B{필수 필드 검증}
|
||||
B -->|층 없음| C[경고: 층을 입력하세요]
|
||||
B -->|3개 다 있음| D[기존 데이터 조회<br/>warehouse_code + floor + zone]
|
||||
D --> E[미리보기 생성]
|
||||
E --> F{저장 버튼}
|
||||
F --> G[렉 구조 화면 감지<br/>floor && zone 필수]
|
||||
G --> H[중복 체크<br/>warehouse_code + floor + zone]
|
||||
H --> I[일괄 INSERT<br/>floor = 선택값]
|
||||
```
|
||||
|
||||
### 데이터 흐름 (변경 후)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[사용자: 창고/구역 입력<br/>층은 선택사항] --> B{필수 필드 검증}
|
||||
B -->|창고 or 구역 없음| C[경고: 해당 필드를 입력하세요]
|
||||
B -->|창고+구역 있음| D{floor 값 존재?}
|
||||
D -->|있음| E1[기존 데이터 조회<br/>warehouse_code + floor + zone]
|
||||
D -->|없음| E2[기존 데이터 조회<br/>warehouse_code + zone]
|
||||
E1 --> F[미리보기 생성]
|
||||
E2 --> F
|
||||
F --> G{저장 버튼}
|
||||
G --> H[렉 구조 화면 감지<br/>zone만 필수]
|
||||
H --> I{floor 값 존재?}
|
||||
I -->|있음| J1[중복 체크<br/>warehouse_code + floor + zone]
|
||||
I -->|없음| J2[중복 체크<br/>warehouse_code + zone]
|
||||
J1 --> K[일괄 INSERT<br/>floor = 선택값]
|
||||
J2 --> K2[일괄 INSERT<br/>floor = NULL]
|
||||
```
|
||||
|
||||
### 컴포넌트 관계
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph 프론트엔드
|
||||
A[폼 필드<br/>창고/층/구역] -->|formData| B[RackStructureComponent<br/>필수 검증 + 미리보기]
|
||||
B -->|locations 배열| C[buttonActions.ts<br/>화면 감지 + 중복 체크 + 저장]
|
||||
end
|
||||
subgraph 백엔드
|
||||
C -->|POST /dynamic-form/save| D[DynamicFormApi<br/>데이터 저장]
|
||||
D --> E[(warehouse_location<br/>floor: nullable)]
|
||||
end
|
||||
|
||||
style B fill:#fff3cd,stroke:#ffc107
|
||||
style C fill:#fff3cd,stroke:#ffc107
|
||||
```
|
||||
|
||||
> 노란색 = 이번에 수정하는 부분
|
||||
|
||||
---
|
||||
|
||||
## 변경 대상 파일
|
||||
|
||||
| 파일 | 수정 내용 | 수정 규모 |
|
||||
|------|----------|----------|
|
||||
| `frontend/lib/registry/components/v2-rack-structure/RackStructureComponent.tsx` | 필수 검증에서 floor 제거, 위치 코드 생성 로직 수정, 기존 데이터 조회 로직 수정 | ~20줄 |
|
||||
| `frontend/lib/utils/buttonActions.ts` | 렉 구조 화면 감지 조건 수정, 중복 체크 조건 수정 | ~10줄 |
|
||||
|
||||
### 사전 확인 필요
|
||||
|
||||
| 확인 항목 | 내용 |
|
||||
|----------|------|
|
||||
| DB 스키마 | `warehouse_location.floor` 컬럼이 `NULL` 허용인지 확인. NOT NULL이면 `ALTER TABLE` 필요 |
|
||||
|
||||
---
|
||||
|
||||
## 코드 설계
|
||||
|
||||
### 1. 필수 필드 검증 수정 (RackStructureComponent.tsx:291~298)
|
||||
|
||||
```tsx
|
||||
// 변경 전
|
||||
const missingFields = useMemo(() => {
|
||||
const missing: string[] = [];
|
||||
if (!context.warehouseCode) missing.push("창고 코드");
|
||||
if (!context.floor) missing.push("층");
|
||||
if (!context.zone) missing.push("구역");
|
||||
return missing;
|
||||
}, [context]);
|
||||
|
||||
// 변경 후
|
||||
const missingFields = useMemo(() => {
|
||||
const missing: string[] = [];
|
||||
if (!context.warehouseCode) missing.push("창고 코드");
|
||||
if (!context.zone) missing.push("구역");
|
||||
return missing;
|
||||
}, [context]);
|
||||
```
|
||||
|
||||
### 2. 위치 코드 생성 수정 (RackStructureComponent.tsx:497~513)
|
||||
|
||||
```tsx
|
||||
// 변경 전
|
||||
const floor = context?.floor || "1";
|
||||
const code = `${warehouseCode}-${floor}${zone}-${row.toString().padStart(2, "0")}-${level}`;
|
||||
|
||||
// 변경 후
|
||||
const floor = context?.floor;
|
||||
const floorPrefix = floor ? `${floor}` : "";
|
||||
const code = `${warehouseCode}-${floorPrefix}${zone}-${row.toString().padStart(2, "0")}-${level}`;
|
||||
// 층 있을 때: WH001-1층A구역-01-1
|
||||
// 층 없을 때: WH001-A구역-01-1
|
||||
```
|
||||
|
||||
### 3. 기존 데이터 조회 수정 (RackStructureComponent.tsx:378~432)
|
||||
|
||||
```tsx
|
||||
// 변경 전
|
||||
if (!warehouseCodeForQuery || !floorForQuery || !zoneForQuery) {
|
||||
setExistingLocations([]);
|
||||
return;
|
||||
}
|
||||
|
||||
const searchParams = {
|
||||
warehouse_code: { value: warehouseCodeForQuery, operator: "equals" },
|
||||
floor: { value: floorForQuery, operator: "equals" },
|
||||
zone: { value: zoneForQuery, operator: "equals" },
|
||||
};
|
||||
|
||||
// 변경 후
|
||||
if (!warehouseCodeForQuery || !zoneForQuery) {
|
||||
setExistingLocations([]);
|
||||
return;
|
||||
}
|
||||
|
||||
const searchParams: Record<string, any> = {
|
||||
warehouse_code: { value: warehouseCodeForQuery, operator: "equals" },
|
||||
zone: { value: zoneForQuery, operator: "equals" },
|
||||
};
|
||||
if (floorForQuery) {
|
||||
searchParams.floor = { value: floorForQuery, operator: "equals" };
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 렉 구조 화면 감지 수정 (buttonActions.ts:692~698)
|
||||
|
||||
```tsx
|
||||
// 변경 전
|
||||
const isRackStructureScreen =
|
||||
context.tableName === "warehouse_location" &&
|
||||
context.formData?.floor &&
|
||||
context.formData?.zone &&
|
||||
!rackStructureLocations;
|
||||
|
||||
// 변경 후
|
||||
const isRackStructureScreen =
|
||||
context.tableName === "warehouse_location" &&
|
||||
context.formData?.zone &&
|
||||
!rackStructureLocations;
|
||||
```
|
||||
|
||||
### 5. 저장 전 중복 체크 수정 (buttonActions.ts:2085~2131)
|
||||
|
||||
```tsx
|
||||
// 변경 전
|
||||
if (warehouseCode && floor && zone) {
|
||||
const existingResponse = await DynamicFormApi.getTableData(tableName, {
|
||||
search: {
|
||||
warehouse_code: { value: warehouseCode, operator: "equals" },
|
||||
floor: { value: floor, operator: "equals" },
|
||||
zone: { value: zone, operator: "equals" },
|
||||
},
|
||||
// ...
|
||||
});
|
||||
}
|
||||
|
||||
// 변경 후
|
||||
if (warehouseCode && zone) {
|
||||
const searchParams: Record<string, any> = {
|
||||
warehouse_code: { value: warehouseCode, operator: "equals" },
|
||||
zone: { value: zone, operator: "equals" },
|
||||
};
|
||||
if (floor) {
|
||||
searchParams.floor = { value: floor, operator: "equals" };
|
||||
}
|
||||
|
||||
const existingResponse = await DynamicFormApi.getTableData(tableName, {
|
||||
search: searchParams,
|
||||
// ...
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 적용 범위 및 영향도
|
||||
|
||||
### 이번 변경은 전역 설정
|
||||
|
||||
방법 B는 렉 구조 컴포넌트 코드에서 직접 "층 필수"를 제거하는 방식이므로, 이 컴포넌트를 사용하는 **모든 회사**에 동일하게 적용됩니다.
|
||||
|
||||
| 회사 | 변경 후 |
|
||||
|------|--------|
|
||||
| 탑씰 | 층 안 골라도 됨 (요청 사항) |
|
||||
| 다른 회사 | 층 안 골라도 됨 (동일하게 적용) |
|
||||
|
||||
### 기존 사용자에 대한 영향
|
||||
|
||||
- 층을 안 골라도 **되는** 것이지, 안 골라야 **하는** 것이 아님
|
||||
- 기존처럼 층을 선택하면 **완전히 동일하게** 동작함 (하위 호환 보장)
|
||||
- 즉, 기존 사용 패턴을 유지하는 회사에는 아무런 차이가 없음
|
||||
|
||||
### 회사별 독립 제어가 필요한 경우
|
||||
|
||||
만약 특정 회사는 층을 필수로 유지하고, 다른 회사는 선택으로 해야 하는 상황이 발생하면, 방법 A(설정 기능 추가)로 업그레이드가 필요합니다. 이번 방법 B의 변경은 향후 방법 A로 전환할 때 충돌 없이 확장 가능합니다.
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
- "창고 코드"와 "구역"의 필수 검증은 기존과 동일하게 유지
|
||||
- 층을 선택한 경우의 동작은 기존과 완전히 동일 (하위 호환)
|
||||
- 층 미선택 시 위치 코드에서 층 부분을 깔끔하게 생략 (폴백값 "1" 사용하지 않음)
|
||||
- 중복 체크는 가용한 필드 기준으로 수행 (floor 없으면 warehouse_code + zone 기준)
|
||||
- DB에는 NULL로 저장하여 "미입력"을 정확하게 표현 (프로젝트 표준 패턴)
|
||||
- 특수 문자열("상관없음" 등) 사용하지 않음 (프로젝트 관행에 맞지 않으므로)
|
||||
@@ -0,0 +1,92 @@
|
||||
# [맥락노트] 렉 구조 등록 - 층(floor) 필수 입력 해제
|
||||
|
||||
> 관련 문서: [계획서](./RFO[계획]-렉구조-층필수해제.md) | [체크리스트](./RFO[체크]-렉구조-층필수해제.md)
|
||||
|
||||
---
|
||||
|
||||
## 왜 이 작업을 하는가
|
||||
|
||||
- 탑씰 회사에서 창고 렉 구조 등록 시 "층"을 선택하지 않아도 되게 해달라는 요청
|
||||
- 현재 코드에 창고 코드 / 층 / 구역 3개가 필수로 하드코딩되어 있어, 층 미선택 시 미리보기 생성과 저장이 모두 차단됨
|
||||
- 층 필수 검증이 6곳에 분산되어 있어 한 곳만 고치면 다른 곳에서 오류 발생
|
||||
|
||||
---
|
||||
|
||||
## 핵심 결정 사항과 근거
|
||||
|
||||
### 1. 방법 B(하드코딩 제거) 채택, 방법 A(설정 기능) 미채택
|
||||
|
||||
- **결정**: 코드에서 floor 필수 조건을 직접 제거
|
||||
- **근거**: 이 프로젝트의 다른 모달/컴포넌트들은 모두 코드에서 직접 "필수/선택"을 정해놓는 방식을 사용. 설정으로 필수 여부를 바꿀 수 있게 만든 패턴은 기존에 없음
|
||||
- **대안 검토**:
|
||||
- 방법 A(ConfigPanel에 requiredFields 설정 추가): 유연하지만 4파일 수정 + 프로젝트에 없던 새 패턴 도입 → 기각
|
||||
- "상관없음" 값 추가 후 null 변환: 프로젝트 어디에서도 magic value → null 변환 패턴을 쓰지 않음 → 기각
|
||||
- "상관없음" 값만 추가 (코드 무변경): DB에 "상관없음" 텍스트가 저장되어 데이터가 지저분함 → 기각
|
||||
- **향후**: 회사별 독립 제어가 필요해지면 방법 A로 확장 가능 (충돌 없음)
|
||||
|
||||
### 2. 전역 적용 (회사별 독립 설정 아님)
|
||||
|
||||
- **결정**: 렉 구조 컴포넌트를 사용하는 모든 회사에 동일 적용
|
||||
- **근거**: 방법 B는 코드 직접 수정이므로 회사별 분기 불가. 단, 기존처럼 층을 선택하면 완전히 동일하게 동작하므로 다른 회사에 실질적 영향 없음 (선택 안 해도 "되는" 것이지, 안 해야 "하는" 것이 아님)
|
||||
|
||||
### 3. floor 미선택 시 NULL 저장 (특수값 아님)
|
||||
|
||||
- **결정**: floor를 선택하지 않으면 DB에 `NULL` 저장
|
||||
- **근거**: 프로젝트 표준 패턴. `UserFormModal`의 `email: formData.email || null`, `EnhancedFormService`의 빈 문자열 → null 자동 변환 등과 동일한 방식
|
||||
- **대안 검토**: "상관없음" 저장 후 null 변환 → 프로젝트에서 미사용 패턴이므로 기각
|
||||
|
||||
### 4. 위치 코드에서 층 부분 생략 (폴백값 "1" 사용 안 함)
|
||||
|
||||
- **결정**: floor 없을 때 위치 코드에서 층 부분을 아예 빼버림
|
||||
- **근거**: 기존 코드는 `context?.floor || "1"`로 폴백하여 1층을 선택한 것처럼 위장됨. 이는 잘못된 데이터를 만들 수 있음
|
||||
- **결과**:
|
||||
- 층 있을 때: `WH001-1층A구역-01-1` (기존과 동일)
|
||||
- 층 없을 때: `WH001-A구역-01-1` (층 부분 없이 깔끔)
|
||||
|
||||
### 5. 중복 체크는 가용 필드 기준으로 수행
|
||||
|
||||
- **결정**: floor 없으면 `warehouse_code + zone`으로 중복 체크, floor 있으면 `warehouse_code + floor + zone`으로 중복 체크
|
||||
- **근거**: 기존 코드는 floor 없으면 중복 체크 전체를 건너뜀 → 중복 데이터 발생 위험. 가용 필드 기준으로 체크하면 floor 유무와 관계없이 안전
|
||||
|
||||
### 6. 렉 구조 화면 감지에서 floor 조건 제거
|
||||
|
||||
- **결정**: `buttonActions.ts`의 `isRackStructureScreen` 조건에서 `context.formData?.floor` 제거
|
||||
- **근거**: floor 없으면 렉 구조 화면으로 인식되지 않아 일반 단건 저장으로 빠짐 → 예기치 않은 동작. zone만으로 감지해야 floor 미선택 시에도 렉 구조 일괄 저장이 정상 동작
|
||||
|
||||
---
|
||||
|
||||
## 관련 파일 위치
|
||||
|
||||
| 구분 | 파일 경로 | 설명 |
|
||||
|------|----------|------|
|
||||
| 수정 대상 | `frontend/lib/registry/components/v2-rack-structure/RackStructureComponent.tsx` | 필수 검증, 위치 코드 생성, 기존 데이터 조회 |
|
||||
| 수정 대상 | `frontend/lib/utils/buttonActions.ts` | 화면 감지, 중복 체크 |
|
||||
| 타입 정의 | `frontend/lib/registry/components/v2-rack-structure/types.ts` | RackStructureContext, FieldMapping 등 |
|
||||
| 설정 패널 | `frontend/lib/registry/components/v2-rack-structure/RackStructureConfigPanel.tsx` | 필드 매핑 설정 (이번에 수정 안 함) |
|
||||
| 저장 모달 | `frontend/components/screen/SaveModal.tsx` | 필수 검증 (DB NOT NULL 기반, 별도 확인 필요) |
|
||||
| 사전 확인 | DB `warehouse_location.floor` 컬럼 | NULL 허용 여부 확인, NOT NULL이면 ALTER TABLE 필요 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 참고
|
||||
|
||||
### 수정 포인트 6곳 요약
|
||||
|
||||
| # | 파일 | 행 | 내용 | 수정 방향 |
|
||||
|---|------|-----|------|----------|
|
||||
| 1 | RackStructureComponent.tsx | 291~298 | missingFields에서 floor 체크 | floor 체크 제거 |
|
||||
| 2 | RackStructureComponent.tsx | 517~521 | 미리보기 생성 차단 | 1번 수정으로 자동 해결 |
|
||||
| 3 | RackStructureComponent.tsx | 497~513 | 위치 코드 생성 `floor \|\| "1"` | 폴백값 제거, 없으면 생략 |
|
||||
| 4 | RackStructureComponent.tsx | 378~432 | 기존 데이터 조회 조건 | floor 없어도 조회 가능하게 |
|
||||
| 5 | buttonActions.ts | 692~698 | 렉 구조 화면 감지 | floor 조건 제거 |
|
||||
| 6 | buttonActions.ts | 2085~2131 | 저장 전 중복 체크 | floor 조건부로 포함 |
|
||||
|
||||
### 프로젝트 표준 optional 필드 처리 패턴
|
||||
|
||||
```
|
||||
빈 값 → null 변환: value || null (UserFormModal)
|
||||
nullable 자동 변환: value === "" && isNullable === "Y" → null (EnhancedFormService)
|
||||
Select placeholder: "__none__" → "" 또는 undefined (여러 ConfigPanel)
|
||||
```
|
||||
|
||||
이번 변경은 위 패턴들과 일관성을 유지합니다.
|
||||
@@ -0,0 +1,57 @@
|
||||
# [체크리스트] 렉 구조 등록 - 층(floor) 필수 입력 해제
|
||||
|
||||
> 관련 문서: [계획서](./RFO[계획]-렉구조-층필수해제.md) | [맥락노트](./RFO[맥락]-렉구조-층필수해제.md)
|
||||
|
||||
---
|
||||
|
||||
## 공정 상태
|
||||
|
||||
- 전체 진행률: **100%** (완료)
|
||||
- 현재 단계: 전체 완료
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 0단계: 사전 확인
|
||||
|
||||
- [x] DB `warehouse_location.floor` 컬럼 nullable 여부 확인 → 이미 NULL 허용 상태, 변경 불필요
|
||||
|
||||
### 1단계: RackStructureComponent.tsx 수정
|
||||
|
||||
- [x] `missingFields`에서 `if (!context.floor) missing.push("층")` 제거 (291~298행)
|
||||
- [x] `generateLocationCode`에서 `context?.floor || "1"` 폴백 제거, floor 없으면 위치 코드에서 생략 (497~513행)
|
||||
- [x] `loadExistingLocations`에서 floor 없어도 조회 가능하도록 조건 수정 (378~432행)
|
||||
- [x] `searchParams`에 floor를 조건부로 포함하도록 변경
|
||||
|
||||
### 2단계: buttonActions.ts 수정
|
||||
|
||||
- [x] `isRackStructureScreen` 조건에서 `context.formData?.floor` 제거 (692~698행)
|
||||
- [x] `handleRackStructureBatchSave` 중복 체크에서 floor를 조건부로 포함 (2085~2131행)
|
||||
|
||||
### 3단계: 검증
|
||||
|
||||
- [x] 층 선택 + 구역 선택: 기존과 동일하게 동작 확인
|
||||
- [x] 층 미선택 + 구역 선택: 경고 없이 미리보기 생성 가능 확인
|
||||
- [x] 층 미선택 시 위치 코드에 층 부분이 빠져있는지 확인
|
||||
- [x] 층 미선택 시 저장 정상 동작 확인
|
||||
- [x] 층 미선택 시 기존 데이터 중복 체크 정상 동작 확인
|
||||
- [x] 창고 코드 미입력 시 여전히 경고 표시되는지 확인
|
||||
- [x] 구역 미입력 시 여전히 경고 표시되는지 확인
|
||||
|
||||
### 4단계: 정리
|
||||
|
||||
- [x] 린트 에러 없음 확인 (기존 WARNING 1개만 존재, 이번 변경과 무관)
|
||||
- [x] 이 체크리스트 완료 표시 업데이트
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-10 | 계획서, 맥락노트, 체크리스트 작성 완료 |
|
||||
| 2026-03-10 | 1단계 코드 수정 완료 (RackStructureComponent.tsx) |
|
||||
| 2026-03-10 | 2단계 코드 수정 완료 (buttonActions.ts) |
|
||||
| 2026-03-10 | 린트 에러 확인 완료 |
|
||||
| 2026-03-10 | 사용자 검증 완료, 전체 작업 완료 |
|
||||
@@ -0,0 +1,169 @@
|
||||
# UML[계획] - 사용자 메일 관리 시스템
|
||||
|
||||
## 개요
|
||||
|
||||
벡스플로우(Vexflow) 사용자 메일 관리 페이지 구현 프로젝트입니다. 외부 메일 서버(POP3/IMAP)와 연동하여 사용자가 본인의 메일 계정을 등록하고 벡스플로우 내에서 메일을 조회할 수 있는 기능을 제공합니다.
|
||||
|
||||
### 현재 동작
|
||||
- Admin 메일 시스템만 존재
|
||||
- JSON 파일 기반 저장소
|
||||
- 사용자 구분 없음
|
||||
|
||||
### 변경 후 동작
|
||||
- 사용자가 외부 메일 계정(IMAP 또는 POP3) 등록
|
||||
- 벡스플로우에서 해당 계정의 메일 조회
|
||||
- PostgreSQL 기반 계정 저장 및 관리
|
||||
- 사용자별 격리(user_id 기반)
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ 사용자 │
|
||||
│ (Frontend) │
|
||||
└──────┬──────┘
|
||||
│
|
||||
├─→ /mail/imap 페이지
|
||||
└─→ /mail/pop3 페이지
|
||||
│
|
||||
↓
|
||||
┌──────────────────┐
|
||||
│ userMail.ts │ (API 클라이언트)
|
||||
│ (lib/api/) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
↓
|
||||
┌────────────────────────────┐
|
||||
│ /api/user-mail/* 라우트 │
|
||||
│ (userMailController) │
|
||||
└────────┬───────────────────┘
|
||||
│
|
||||
┌───────┴────────┐
|
||||
│ │
|
||||
↓ ↓
|
||||
┌────────────────┐ ┌──────────────┐
|
||||
│ userMailAccount│ │ userMailImap │
|
||||
│ Service │ │ Service │
|
||||
│ (PostgreSQL) │ │ (IMAP) │
|
||||
└────────────────┘ │ │
|
||||
└──────────────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────────┐
|
||||
│ 외부 IMAP 서버 │
|
||||
└──────────────────┘
|
||||
|
||||
또는
|
||||
|
||||
┌──────────────────┐
|
||||
│ userMailPop3 │
|
||||
│ Service │
|
||||
│ (POP3) │
|
||||
└──────────────────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────────┐
|
||||
│ 외부 POP3 서버 │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 신규 파일 목록
|
||||
|
||||
### 백엔드 (Node.js/Express)
|
||||
|
||||
| 파일 경로 | 역할 |
|
||||
|----------|------|
|
||||
| `src/services/userMailAccountService.ts` | DB 계정 관리 (생성, 조회, 삭제, 수정) |
|
||||
| `src/services/userMailImapService.ts` | IMAP 프로토콜 연결 및 메일 조회 |
|
||||
| `src/services/userMailPop3Service.ts` | POP3 프로토콜 연결 및 메일 조회 |
|
||||
| `src/controllers/userMailController.ts` | API 엔드포인트 처리 |
|
||||
| `src/routes/userMailRoutes.ts` | 라우트 정의 |
|
||||
|
||||
### 프론트엔드 (React/TypeScript)
|
||||
|
||||
| 파일 경로 | 역할 |
|
||||
|----------|------|
|
||||
| `frontend/lib/api/userMail.ts` | API 클라이언트 |
|
||||
| `frontend/app/(main)/mail/imap/page.tsx` | IMAP 메일 관리 페이지 |
|
||||
| `frontend/app/(main)/mail/pop3/page.tsx` | POP3 메일 관리 페이지 |
|
||||
|
||||
---
|
||||
|
||||
## 수정 파일 목록
|
||||
|
||||
| 파일 경로 | 변경 사항 |
|
||||
|----------|---------|
|
||||
| `src/runMigration.ts` | 마이그레이션 스크립트에 user_mail_accounts 테이블 추가 |
|
||||
| `src/app.ts` | userMailRoutes 등록 |
|
||||
| `src/components/AdminPageRenderer.tsx` | /mail/imap, /mail/pop3 페이지 하드코딩 등록 (2줄) |
|
||||
|
||||
---
|
||||
|
||||
## 데이터베이스 스키마
|
||||
|
||||
### user_mail_accounts 테이블
|
||||
|
||||
```sql
|
||||
CREATE TABLE user_mail_accounts (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
protocol VARCHAR(10) NOT NULL CHECK (protocol IN ('imap', 'pop3')),
|
||||
host VARCHAR(255) NOT NULL,
|
||||
port INT NOT NULL DEFAULT 993,
|
||||
use_tls BOOLEAN DEFAULT TRUE,
|
||||
username VARCHAR(255) NOT NULL,
|
||||
password TEXT NOT NULL, -- 암호화됨 (encryptionService 사용)
|
||||
status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'inactive')),
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(user_id, protocol, host, username)
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 설계 원칙
|
||||
|
||||
### 1. 사용자 격리
|
||||
- 모든 API 요청에서 현재 사용자의 user_id 검증
|
||||
- 다른 사용자의 계정/메일 접근 불가
|
||||
|
||||
### 2. 프로토콜별 서비스 분리
|
||||
- userMailImapService.ts: IMAP 전용
|
||||
- userMailPop3Service.ts: POP3 전용
|
||||
- 각 서비스는 독립적으로 동작
|
||||
|
||||
### 3. 기존 기능 재활용
|
||||
- `encryptionService`: 비밀번호 암호화/복호화
|
||||
- `mailparser`: 메일 본문 파싱
|
||||
- `imap` 패키지: IMAP 연결(기존 mailReceiveBasicService 참조)
|
||||
|
||||
### 4. 기존 Admin 메일 시스템과 분리
|
||||
- 새로운 테이블, 서비스, 라우트로 완전 독립
|
||||
- JSON 파일 기반 방식 미사용
|
||||
|
||||
---
|
||||
|
||||
## 주요 API 엔드포인트
|
||||
|
||||
| 메서드 | 경로 | 설명 |
|
||||
|--------|------|------|
|
||||
| POST | `/api/user-mail/accounts` | 새 계정 등록 |
|
||||
| GET | `/api/user-mail/accounts` | 사용자 계정 목록 |
|
||||
| GET | `/api/user-mail/accounts/:id` | 계정 상세 조회 |
|
||||
| PUT | `/api/user-mail/accounts/:id` | 계정 수정 |
|
||||
| DELETE | `/api/user-mail/accounts/:id` | 계정 삭제 |
|
||||
| POST | `/api/user-mail/accounts/:id/test` | 연결 테스트 |
|
||||
| GET | `/api/user-mail/accounts/:id/mails` | 메일 목록 조회 |
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 버전 | 내용 |
|
||||
|------|------|------|
|
||||
| 2026-03-27 | v1.0 | 초안 작성 |
|
||||
@@ -0,0 +1,147 @@
|
||||
# UML[맥락] - 사용자 메일 관리 시스템
|
||||
|
||||
## 프로젝트 배경
|
||||
|
||||
### 추진 이유
|
||||
- 팀장 지시로 POP3 구현 필요
|
||||
- IMAP 허용 여부 확인 대기 중
|
||||
- 두 프로토콜 모두 구현 후 비교하여 최적 솔루션 채택
|
||||
|
||||
---
|
||||
|
||||
## 핵심 기술 결정 사항
|
||||
|
||||
### 1. 페이지 등록 방식: 하드코딩
|
||||
**선택**: 하드코딩 (AdminPageRenderer.tsx에 직접 등록)
|
||||
|
||||
**사유**:
|
||||
- 컴포넌트 레지스트리에 추가할 권한 없음
|
||||
- 간단한 추가 작업으로 빠른 구현 가능
|
||||
|
||||
**구현**:
|
||||
```typescript
|
||||
// AdminPageRenderer.tsx에 2줄 추가
|
||||
{path: '/mail/imap', label: '메일(IMAP)', component: () => <IMapPage /> },
|
||||
{path: '/mail/pop3', label: '메일(POP3)', component: () => <Pop3Page /> },
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 저장소: PostgreSQL (Admin 메일과 완전 분리)
|
||||
|
||||
**선택**: PostgreSQL `user_mail_accounts` 테이블
|
||||
|
||||
**사유**:
|
||||
- Admin 메일 시스템(JSON 파일 기반)과 완전 독립
|
||||
- 사용자별 격리 용이 (user_id 기반)
|
||||
- 확장성 및 성능 이점
|
||||
|
||||
**결과**:
|
||||
- 기존 Admin 메일: JSON 파일 유지
|
||||
- 신규 사용자 메일: PostgreSQL 관리
|
||||
|
||||
---
|
||||
|
||||
### 3. POP3 메일 삭제 정책: 서버 유지
|
||||
|
||||
**선택**: DELE 명령 미호출 (서버 메일 유지)
|
||||
|
||||
**사유**:
|
||||
- 데이터 손실 방지
|
||||
- 사용자 실수로 인한 피해 최소화
|
||||
- 벡스플로우는 조회만 수행
|
||||
|
||||
**구현**:
|
||||
- `userMailPop3Service.ts`에서 RETR 후 DELE 호출 안 함
|
||||
- 서버의 자동 정리 정책에 의존
|
||||
|
||||
---
|
||||
|
||||
### 4. 페이지별 프로토콜 고정
|
||||
|
||||
**선택**: 페이지당 프로토콜 1개로 제한
|
||||
|
||||
**구현**:
|
||||
- `/mail/imap` → IMAP 계정만 표시/관리
|
||||
- `/mail/pop3` → POP3 계정만 표시/관리
|
||||
|
||||
**사유**:
|
||||
- UI 단순화
|
||||
- 프로토콜별 메일 구조 차이 처리 용이
|
||||
- 사용자 혼동 최소화
|
||||
|
||||
---
|
||||
|
||||
## 관련 기존 코드 참조
|
||||
|
||||
### mailReceiveBasicService.ts
|
||||
- IMAP 연결 및 메일 조회 로직
|
||||
- 메일 파싱 및 저장 방식
|
||||
- Error handling 패턴
|
||||
|
||||
**참조 사항**:
|
||||
```typescript
|
||||
// IMAP 연결 구조, 메일 검색 쿼리, 메일 수신 처리 방식
|
||||
```
|
||||
|
||||
### encryptionService.ts
|
||||
- 비밀번호 암호화/복호화
|
||||
- DB 저장 시 암호화, 조회 시 복호화
|
||||
|
||||
**사용 방식**:
|
||||
```typescript
|
||||
// 저장: encryptionService.encrypt(password)
|
||||
// 조회: encryptionService.decrypt(encrypted_password)
|
||||
```
|
||||
|
||||
### AdminPageRenderer.tsx
|
||||
- 기존 페이지 하드코딩 구조
|
||||
- 페이지 등록 형식 및 라벨 지정 방식
|
||||
|
||||
**추가 위치**:
|
||||
```typescript
|
||||
// 기존 페이지 목록에 /mail/imap, /mail/pop3 추가
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 기술 스택 및 패키지
|
||||
|
||||
### 기존 패키지 (재활용)
|
||||
| 패키지 | 버전 | 용도 |
|
||||
|--------|------|------|
|
||||
| `imap` | - | IMAP 연결 |
|
||||
| `mailparser` | - | 메일 파싱 |
|
||||
| `pg` | - | PostgreSQL 클라이언트 |
|
||||
|
||||
### 신규 패키지
|
||||
| 패키지 | 버전 | 용도 |
|
||||
|--------|------|------|
|
||||
| `node-pop3` | latest | POP3 연결 |
|
||||
|
||||
---
|
||||
|
||||
## 핵심 고려 사항
|
||||
|
||||
### 보안
|
||||
1. 메일 계정 비밀번호는 항상 암호화 상태로 저장
|
||||
2. 사용자 격리: user_id 기반 접근 제어
|
||||
3. 외부 서버 연결 정보는 민감: 환경변수 활용
|
||||
|
||||
### 성능
|
||||
1. 메일 조회는 페이지네이션 처리
|
||||
2. 연결 테스트는 별도 API (현재 메일 검색과 분리)
|
||||
3. 대량 메일 처리 시 비동기 처리
|
||||
|
||||
### 에러 처리
|
||||
1. 네트워크 오류: 재시도 로직
|
||||
2. 인증 실패: 명확한 에러 메시지 제공
|
||||
3. DB 오류: 트랜잭션 롤백
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 내용 |
|
||||
|------|------|
|
||||
| 2026-03-27 | 초안 작성 |
|
||||
@@ -0,0 +1,161 @@
|
||||
# UML[체크] - 사용자 메일 관리 시스템
|
||||
|
||||
## 공정 상태
|
||||
**진행률: 90%** (IMAP 완성, POP3 미구현)
|
||||
|
||||
---
|
||||
|
||||
## 구현 체크리스트
|
||||
|
||||
### 데이터베이스
|
||||
- [x] DB 마이그레이션 작성 (user_mail_accounts 테이블 생성)
|
||||
|
||||
### 패키지 설치
|
||||
- [ ] npm install node-pop3 (설치됨, 서비스 미구현)
|
||||
|
||||
### 백엔드 서비스 계층
|
||||
- [x] userMailAccountService.ts (DB CRUD)
|
||||
- [x] userMailImapService.ts (IMAP 프로토콜)
|
||||
- [x] userMailSmtpService.ts (SMTP 발송)
|
||||
- [x] imapConnectionPool.ts (IMAP 연결 풀)
|
||||
- [x] mailCache.ts (메일 캐시)
|
||||
- [ ] userMailPop3Service.ts (POP3 프로토콜 - 미구현)
|
||||
|
||||
### 백엔드 API 계층
|
||||
- [x] userMailController.ts (요청 처리)
|
||||
- [x] userMailRoutes.ts (라우트 정의)
|
||||
- [x] app.ts에 userMailRoutes 등록 (`/api/user-mail`)
|
||||
|
||||
### 프론트엔드 API 클라이언트
|
||||
- [x] frontend/lib/api/userMail.ts
|
||||
|
||||
### 프론트엔드 페이지
|
||||
- [x] frontend/app/(main)/mail/imap/page.tsx
|
||||
- [x] frontend/app/(main)/mail/imap/ComposeDialog.tsx (메일 작성)
|
||||
- [ ] frontend/app/(main)/mail/pop3/page.tsx (미구현)
|
||||
|
||||
### 페이지 등록
|
||||
- [x] AdminPageRenderer.tsx에 /mail/imap 등록
|
||||
- [ ] AdminPageRenderer.tsx에 /mail/pop3 등록 (미구현)
|
||||
|
||||
---
|
||||
|
||||
## 구현된 IMAP 기능
|
||||
|
||||
### 계정 관리
|
||||
- [x] 계정 추가 (연결 테스트 후 저장)
|
||||
- [x] 계정 수정
|
||||
- [x] 계정 삭제
|
||||
- [x] 연결 테스트 (저장 전 자동 + 수동)
|
||||
|
||||
### 메일 조회
|
||||
- [x] SSE 스트리밍으로 메일 목록 로드 (20개씩)
|
||||
- [x] 이전 메일 더 보기 (무한 스크롤 방식)
|
||||
- [x] 메일 상세 조회 (HTML/텍스트 본문)
|
||||
- [x] 폴더별 메일 조회 (INBOX, 휴지통, 스팸 등)
|
||||
- [x] 새로고침 버튼
|
||||
|
||||
### 메일 관리
|
||||
- [x] 읽음 처리 (클릭 시 자동, IMAP \Seen 플래그)
|
||||
- [x] 메일 삭제 (\Trash 특수 폴더로 이동 - Gmail 호환)
|
||||
- [x] 메일 이동 (폴더 간 이동)
|
||||
|
||||
### 첨부파일
|
||||
- [x] 첨부파일 목록 표시 (pill 형태)
|
||||
- [x] 첨부파일 다운로드 (ReadableStream 진행바 표시)
|
||||
- [x] Content-Length 헤더 지원 (정확한 진행률)
|
||||
|
||||
### 발신
|
||||
- [x] 메일 작성 / 발송 (SMTP)
|
||||
- [x] 답장 (Re: 제목, inReplyTo 헤더)
|
||||
- [x] 전달 (Fwd: 제목, 원본 본문 인용)
|
||||
|
||||
### UI
|
||||
- [x] 3단 패널 레이아웃 (계정 / 메일 목록 / 상세)
|
||||
- [x] 폴더 목록 (unseen 카운트 표시)
|
||||
- [x] 읽음/삭제 후 unseen 카운트 자동 갱신
|
||||
- [x] 검색 (제목/발신자 클라이언트 필터)
|
||||
|
||||
---
|
||||
|
||||
## 검증 체크리스트
|
||||
|
||||
### 데이터베이스
|
||||
- [x] `user_mail_accounts` 테이블 존재 확인
|
||||
- [x] 테이블 스키마 정확성 확인
|
||||
|
||||
### 계정 관리 API
|
||||
- [x] POST `/api/user-mail/accounts` - 계정 생성
|
||||
- [x] GET `/api/user-mail/accounts` - 사용자 계정 목록
|
||||
- [x] PUT `/api/user-mail/accounts/:id` - 계정 수정
|
||||
- [x] DELETE `/api/user-mail/accounts/:id` - 계정 삭제
|
||||
- [x] POST `/api/user-mail/accounts/:id/test` - 연결 테스트
|
||||
- [x] POST `/api/user-mail/test-connection` - 직접 연결 테스트
|
||||
|
||||
### 메일 API
|
||||
- [x] GET `/api/user-mail/accounts/:id/mails/stream` - 스트리밍 목록
|
||||
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno` - 상세 조회
|
||||
- [x] POST `/api/user-mail/accounts/:id/mails/:seqno/mark-read` - 읽음 처리
|
||||
- [x] DELETE `/api/user-mail/accounts/:id/mails/:seqno` - 삭제 (휴지통 이동)
|
||||
- [x] POST `/api/user-mail/accounts/:id/mails/:seqno/move` - 이동
|
||||
- [x] GET `/api/user-mail/accounts/:id/folders` - 폴더 목록
|
||||
- [x] GET `/api/user-mail/accounts/:id/folders/:folder/mails/stream` - 폴더별 스트리밍
|
||||
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno/attachments` - 첨부파일 목록
|
||||
- [x] GET `/api/user-mail/accounts/:id/mails/:seqno/attachment/:partId` - 첨부파일 다운로드
|
||||
- [x] POST `/api/user-mail/accounts/:id/send` - 메일 발송
|
||||
|
||||
### 사용자 격리 검증
|
||||
- [x] 모든 쿼리에 WHERE user_id = $n 포함 (DB 레벨 강제)
|
||||
- [x] 다른 user_id로 계정 접근 시 404 반환
|
||||
|
||||
### 프론트엔드 페이지
|
||||
- [x] `/mail/imap` 페이지 접속 및 동작
|
||||
- [x] Gmail IMAP 연동 확인
|
||||
- [x] 메일 목록 → 상세 → 읽음 처리
|
||||
- [x] 첨부파일 다운로드 진행바
|
||||
- [x] 메일 삭제 → Gmail 휴지통 이동 확인
|
||||
- [x] 답장/전달 발송 확인
|
||||
|
||||
---
|
||||
|
||||
## 알려진 이슈 및 주의사항
|
||||
|
||||
### 1. 메일 삭제 방식
|
||||
- `\Trash` 특수 폴더로 이동 (EXPUNGE 아님)
|
||||
- Gmail 호환: `[Gmail]/휴지통`으로 자동 라우팅
|
||||
- 폴더 없으면 `messageDelete` fallback (영구 삭제 주의)
|
||||
|
||||
### 2. 첨부파일 진행바
|
||||
- Content-Length 헤더 기반 진행률 계산
|
||||
- imapflow `meta.size`로 헤더 설정
|
||||
- totalSize fallback: `getUserMailAttachments`의 size 필드 사용
|
||||
|
||||
### 3. IMAP 연결 풀
|
||||
- 계정당 1개 연결 유지 (maxIdleMs: 5분)
|
||||
- busy 상태 시 큐잉 처리
|
||||
- 연결 끊김 시 자동 재연결
|
||||
|
||||
### 4. 캐시
|
||||
- 메일 목록: 60초 TTL
|
||||
- 메일 상세: 5분 TTL
|
||||
- 읽음/삭제/이동 시 해당 캐시 무효화
|
||||
|
||||
### 5. POP3 미구현
|
||||
- `node-pop3` 패키지 설치됨
|
||||
- 서비스 파일 미작성
|
||||
- 팀장 지시 후 구현 예정
|
||||
|
||||
---
|
||||
|
||||
## 변경 이력
|
||||
|
||||
| 날짜 | 버전 | 내용 |
|
||||
|------|------|------|
|
||||
| 2026-03-27 | v1.0 | 초안 작성 |
|
||||
| 2026-03-30 | v2.0 | IMAP 전 기능 구현 완료 (메일 조회/삭제/이동/첨부/발송/답장/전달/폴더/진행바) |
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [UML[계획]-user-mail.md](./UML[계획]-user-mail.md): 아키텍처 및 설계
|
||||
@@ -0,0 +1,275 @@
|
||||
# 탭 시스템 아키텍처 및 구현 계획
|
||||
|
||||
## 1. 개요
|
||||
|
||||
사이드바 메뉴 클릭 시 `router.push()` 페이지 이동 방식에서 **탭 기반 멀티 화면 시스템**으로 전환한다.
|
||||
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ Tab Data Layer (중앙) │
|
||||
API 응답 ────────→│ │
|
||||
│ 탭별 상태 저장소 │
|
||||
│ ├─ formData │
|
||||
│ ├─ selectedRows │
|
||||
│ ├─ scrollPosition │
|
||||
│ ├─ modalState │
|
||||
│ ├─ sortState │
|
||||
│ └─ cacheState │
|
||||
│ │
|
||||
│ 공통 규칙 엔진 │
|
||||
│ ├─ 날짜 포맷 규칙 │
|
||||
│ ├─ 숫자/통화 포맷 규칙 │
|
||||
│ ├─ 로케일 처리 규칙 │
|
||||
│ ├─ 유효성 검증 규칙 │
|
||||
│ └─ 데이터 타입 변환 규칙 │
|
||||
│ │
|
||||
│ F5 복원 / 캐시 관리 │
|
||||
│ (sessionStorage 중앙관리) │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
가공 완료된 데이터
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
화면 A (경량) 화면 B (경량) 화면 C (경량)
|
||||
렌더링만 담당 렌더링만 담당 렌더링만 담당
|
||||
```
|
||||
|
||||
## 2. 레이어 구조
|
||||
|
||||
| 레이어 | 책임 |
|
||||
|---|---|
|
||||
| **Tab Data Layer** | 탭별 상태 보관, 캐시, 복원, 데이터 가공 |
|
||||
| **공통 규칙 엔진** | 날짜/숫자/로케일 포맷, 유효성 검증 |
|
||||
| **화면 컴포넌트** | 가공된 데이터를 받아서 렌더링만 담당 |
|
||||
|
||||
## 3. 파일 구성
|
||||
|
||||
| 파일 | 역할 |
|
||||
|---|---|
|
||||
| `stores/tabStore.ts` | Zustand 기반 탭 상태 관리 |
|
||||
| `components/layout/TabBar.tsx` | 탭 바 UI (드래그, 우클릭, 오버플로우) |
|
||||
| `components/layout/TabContent.tsx` | 탭별 콘텐츠 렌더링 (컨테이너) |
|
||||
| `components/layout/EmptyDashboard.tsx` | 탭 없을 때 안내 화면 |
|
||||
| `components/layout/AppLayout.tsx` | 전체 레이아웃 (사이드바 + 탭 + 콘텐츠) |
|
||||
| `lib/tabStateCache.ts` | 탭별 상태 캐싱 엔진 |
|
||||
| `lib/formatting/rules.ts` | 포맷 규칙 정의 |
|
||||
| `lib/formatting/index.ts` | formatDate, formatNumber, formatCurrency |
|
||||
| `app/(main)/screens/[screenId]/page.tsx` | 화면별 렌더링 |
|
||||
|
||||
## 4. 기술 스택
|
||||
|
||||
- Next.js 15, React 19, Zustand
|
||||
- Tailwind CSS, shadcn/ui
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase 1: 탭 껍데기
|
||||
|
||||
### 5-1. Zustand 탭 Store (`stores/tabStore.ts`)
|
||||
- [ ] zustand 직접 의존성 추가
|
||||
- [ ] Tab 인터페이스: id, type, title, screenId, menuObjid, adminUrl
|
||||
- [ ] 탭 목록, 활성 탭 ID
|
||||
- [ ] openTab, closeTab, switchTab, refreshTab
|
||||
- [ ] closeOtherTabs, closeTabsToLeft, closeTabsToRight, closeAllTabs
|
||||
- [ ] updateTabOrder (드래그 순서 변경)
|
||||
- [ ] 중복 방지: 같은 탭이면 해당 탭으로 이동
|
||||
- [ ] 닫기 후 왼쪽 탭으로 이동, 왼쪽 없으면 오른쪽
|
||||
- [ ] sessionStorage 영속화 (persist middleware)
|
||||
- [ ] 탭 ID 생성 규칙: V2 화면 `tab-{screenId}-{menuObjid}`, URL 탭 `tab-url-{menuObjid}`
|
||||
|
||||
### 5-2. TabBar 컴포넌트 (`components/layout/TabBar.tsx`)
|
||||
- [ ] 고정 너비 탭, 화면 너비에 맞게 동적 개수
|
||||
- [ ] 활성 탭: 새로고침 버튼 + X 버튼
|
||||
- [ ] 비활성 탭: X 버튼만
|
||||
- [ ] 오버플로우 시 +N 드롭다운 (ResizeObserver 감시)
|
||||
- [ ] 드래그 순서 변경 (mousedown/move/up, DOM transform 직접 조작)
|
||||
- [ ] 사이드바 메뉴 드래그 드롭 수신 (`application/tab-menu` 커스텀 데이터, 마우스 위치에 삽입)
|
||||
- [ ] 우클릭 컨텍스트 메뉴 (새로고침/왼쪽닫기/오른쪽닫기/다른탭닫기/모든탭닫기)
|
||||
- [ ] 휠 클릭: 탭 즉시 닫기
|
||||
|
||||
### 5-3. TabContent 컴포넌트 (`components/layout/TabContent.tsx`)
|
||||
- [ ] display:none 방식 (비활성 탭 DOM 유지, 상태 보존)
|
||||
- [ ] 지연 마운트 (한 번 활성화된 탭만 마운트)
|
||||
- [ ] 안정적 순서 유지 (탭 순서 변경 시 리마운트 방지)
|
||||
- [ ] 탭별 모달 격리 (DialogPortalContainerContext)
|
||||
- [ ] tab.type === "screen" -> ScreenViewPageWrapper 임베딩
|
||||
- [ ] tab.type === "admin" -> 동적 import로 관리자 페이지 렌더링
|
||||
|
||||
### 5-4. EmptyDashboard 컴포넌트 (`components/layout/EmptyDashboard.tsx`)
|
||||
- [ ] 탭이 없을 때 "사이드바에서 메뉴를 선택하여 탭을 추가하세요" 표시
|
||||
|
||||
### 5-5. AppLayout 수정 (`components/layout/AppLayout.tsx`)
|
||||
- [ ] handleMenuClick: router.push -> tabStore.openTab 호출
|
||||
- [ ] 레이아웃: main 영역을 TabBar + TabContent로 교체
|
||||
- [ ] children prop 제거 (탭이 콘텐츠 관리)
|
||||
- [ ] 사이드바 메뉴 드래그 가능하게 (draggable)
|
||||
|
||||
### 5-6. 라우팅 연동
|
||||
- [ ] `app/(main)/layout.tsx` 수정 - children 대신 탭 시스템
|
||||
- [ ] URL 직접 접근 시 탭으로 열기 (북마크/공유 링크 대응)
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 2: F5 최대 복원
|
||||
|
||||
### 6-1. 탭 상태 캐싱 엔진 (`lib/tabStateCache.ts`)
|
||||
- [ ] 탭별 상태 저장/복원 (sessionStorage)
|
||||
- [ ] 저장 대상: formData, selectedRows, sortState, scrollPosition, modalState, checkboxState
|
||||
- [ ] debounce 적용 (상태 변경마다 저장하지 않음)
|
||||
|
||||
### 6-2. 복원 로직
|
||||
- [ ] 활성 탭: fresh API 호출 (캐시 데이터 무시)
|
||||
- [ ] 비활성 탭: 캐시에서 복원
|
||||
- [ ] 탭 닫기 시 해당 탭의 캐시 키 일괄 삭제
|
||||
|
||||
### 6-3. 캐시 키 관리 (clearTabCache)
|
||||
|
||||
탭 닫기/새로고침 시 관련 sessionStorage 키 일괄 제거:
|
||||
- `tab-cache-{tabId}` (폼/스크롤 캐시)
|
||||
- `tableState_{tabId}_*` (컬럼 너비, 정렬, 틀고정, 그리드선, 헤더필터)
|
||||
- `pageSize_{tabId}_*` (표시갯수)
|
||||
- `filterSettings_{tabId}_*` (검색 필터 설정)
|
||||
- `groupSettings_{tabId}_*` (그룹 설정)
|
||||
|
||||
### 6-4. F5 새로고침 시 캐시 정책 (구현 완료)
|
||||
|
||||
| 탭 상태 | F5 시 동작 |
|
||||
|---------|-----------|
|
||||
| **활성 탭** | `clearTabCache(activeTabId)` → 캐시 전체 삭제 → fresh API 호출 |
|
||||
| **비활성 탭** | 캐시 유지 → 탭 전환 시 복원 |
|
||||
|
||||
**구현 방식**: `TabContent.tsx`에 모듈 레벨 플래그(`hasHandledPageLoad`)를 사용.
|
||||
전체 페이지 로드 시 모듈이 재실행되어 플래그가 `false`로 리셋.
|
||||
SPA 내비게이션에서는 모듈이 유지되므로 `true`로 남아 중복 실행 방지.
|
||||
|
||||
### 6-5. 탭 바 새로고침 버튼 (구현 완료)
|
||||
|
||||
`tabStore.refreshTab(tabId)` 호출 시:
|
||||
1. `clearTabCache(tabId)` → 해당 탭의 모든 sessionStorage 캐시 삭제
|
||||
2. `refreshKey` 증가 → 컴포넌트 리마운트 → 기본값으로 초기화
|
||||
|
||||
### 6-6. 저장소 분류 기준 (구현 완료)
|
||||
|
||||
| 데이터 성격 | 저장소 | 키 구조 | 비고 |
|
||||
|------------|--------|---------|------|
|
||||
| 탭별 캐시 | sessionStorage | `{prefix}_{tabId}_{tableName}` | 탭 닫으면 소멸 |
|
||||
| 사용자 설정 | localStorage | `{prefix}_{tableName}_{userId}` | 세션 간 보존 |
|
||||
|
||||
**탭별 캐시 (sessionStorage)**:
|
||||
- tableState: 컬럼 너비, 정렬, 틀고정, 그리드선, 헤더필터
|
||||
- pageSize: 표시갯수
|
||||
- filterSettings: 검색 필터 설정
|
||||
- groupSettings: 그룹 설정
|
||||
|
||||
**사용자 설정 (localStorage)**:
|
||||
- table_column_visibility: 컬럼 표시/숨김
|
||||
- table_sort_state: 정렬 상태
|
||||
- table_column_order: 컬럼 순서
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase 3: 포맷팅 중앙화
|
||||
|
||||
### 7-1. 포맷팅 규칙 엔진
|
||||
|
||||
```typescript
|
||||
// lib/formatting/rules.ts
|
||||
|
||||
interface FormatRules {
|
||||
date: {
|
||||
display: string; // "YYYY-MM-DD"
|
||||
datetime: string; // "YYYY-MM-DD HH:mm:ss"
|
||||
input: string; // "YYYY-MM-DD"
|
||||
};
|
||||
number: {
|
||||
locale: string; // 사용자 로케일 기반
|
||||
decimals: number; // 기본 소수점 자릿수
|
||||
};
|
||||
currency: {
|
||||
code: string; // 회사 설정 기반
|
||||
locale: string;
|
||||
};
|
||||
}
|
||||
|
||||
export function formatValue(value: any, dataType: string, rules: FormatRules): string;
|
||||
export function formatDate(value: any, format?: string): string;
|
||||
export function formatNumber(value: any, locale?: string): string;
|
||||
export function formatCurrency(value: any, currencyCode?: string): string;
|
||||
```
|
||||
|
||||
### 7-2. 하드코딩 교체 대상
|
||||
- [ ] V2DateRenderer.tsx
|
||||
- [ ] EditModal.tsx
|
||||
- [ ] InteractiveDataTable.tsx
|
||||
- [ ] FlowWidget.tsx
|
||||
- [ ] AggregationWidgetComponent.tsx
|
||||
- [ ] aggregation.ts (피벗)
|
||||
- [ ] 기타 하드코딩 파일들
|
||||
|
||||
---
|
||||
|
||||
## 8. Phase 4: ScreenViewPage 경량화
|
||||
- [ ] 탭 데이터 레이어에서 받은 데이터로 렌더링만 담당
|
||||
- [ ] API 호출, 캐시, 복원 로직 제거 (탭 레이어가 담당)
|
||||
- [ ] 관리자 페이지도 동일한 데이터 레이어 패턴 적용
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## 구현 완료: 다중 스크롤 영역 F5 복원
|
||||
|
||||
### 개요
|
||||
|
||||
split panel 등 한 탭 안에 **스크롤 영역이 여러 개**인 화면에서, F5 새로고침 후에도 각 영역의 스크롤 위치가 복원된다.
|
||||
|
||||
탭 전환 시에는 `display: none` 방식으로 DOM이 유지되므로 브라우저가 스크롤을 자연 보존한다. 이 기능은 **F5 새로고침** 전용이다.
|
||||
|
||||
### 동작 방식
|
||||
|
||||
탭 내 모든 스크롤 가능한 요소를 DOM 경로(`"0/1/0/2"` 형태)와 함께 저장한다.
|
||||
|
||||
```
|
||||
scrollPositions: [
|
||||
{ path: "0/1/0/2", top: 150, left: 0 }, // 예: 좌측 패널
|
||||
{ path: "0/1/1/3/1", top: 420, left: 0 }, // 예: 우측 패널
|
||||
]
|
||||
```
|
||||
|
||||
- **실시간 추적**: 스크롤 이벤트 발생 시 해당 요소의 경로와 위치를 Map에 기록
|
||||
- **저장 시점**: 탭 전환 시 + `beforeunload`(F5/닫기) 시 sessionStorage에 저장
|
||||
- **복원 시점**: 탭 활성화 시 경로를 기반으로 각 요소를 찾아 개별 복원
|
||||
|
||||
### 관련 파일 및 주요 함수
|
||||
|
||||
| 파일 | 역할 |
|
||||
|---|---|
|
||||
| `lib/tabStateCache.ts` | 스크롤 캡처/복원 핵심 로직 |
|
||||
| `components/layout/TabContent.tsx` | 스크롤 이벤트 감지, 저장/복원 호출 |
|
||||
|
||||
**`tabStateCache.ts` 핵심 함수**:
|
||||
|
||||
| 함수 | 설명 |
|
||||
|---|---|
|
||||
| `getElementPath(element, container)` | 요소의 DOM 경로를 자식 인덱스 문자열로 생성 |
|
||||
| `captureAllScrollPositions(container)` | TreeWalker로 컨테이너 하위 모든 스크롤 요소의 위치를 일괄 캡처 |
|
||||
| `restoreAllScrollPositions(container, positions)` | 경로 기반으로 각 요소를 찾아 스크롤 위치 복원 (콘텐츠 렌더링 대기 폴링 포함) |
|
||||
|
||||
**`TabContent.tsx` 핵심 Ref**:
|
||||
|
||||
| Ref | 설명 |
|
||||
|---|---|
|
||||
| `lastScrollMapRef` | `Map<tabId, Map<path, {top, left}>>` - 탭 내 요소별 최신 스크롤 위치 |
|
||||
| `pathCacheRef` | `WeakMap<HTMLElement, string>` - 동일 요소의 경로 재계산 방지용 캐시 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 참고 파일
|
||||
|
||||
| 파일 | 비고 |
|
||||
|---|---|
|
||||
| `frontend/components/layout/AppLayout.tsx` | 사이드바 + 콘텐츠 레이아웃 |
|
||||
| `frontend/app/(main)/screens/[screenId]/page.tsx` | 화면 렌더링 (건드리지 않음) |
|
||||
| `frontend/stores/modalDataStore.ts` | Zustand store 참고 패턴 |
|
||||
| `frontend/lib/adminPageRegistry.tsx` | 관리자 페이지 레지스트리 |
|
||||
@@ -0,0 +1,231 @@
|
||||
# 모달 필수 입력 검증 설계
|
||||
|
||||
## 1. 목표
|
||||
|
||||
모든 모달에서 필수 입력값이 빈 상태로 저장 버튼을 클릭하면:
|
||||
- 첫 번째 빈 필수 필드로 포커스 이동 + 하이라이트
|
||||
- 우측 상단에 토스트 알림 ("○○ 항목을 입력해주세요")
|
||||
- 버튼은 항상 활성 상태 (비활성화하지 않음)
|
||||
|
||||
---
|
||||
|
||||
## 2. 전체 구조
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DialogContent (모든 모달의 공통 래퍼) │
|
||||
│ │
|
||||
│ useDialogAutoValidation(contentRef) │
|
||||
│ │ │
|
||||
│ ├─ 0단계: 모드 확인 │
|
||||
│ │ └─ useTabStore.mode === "user" 일 때만 실행 │
|
||||
│ │ │
|
||||
│ ├─ 1단계: 필수 필드 탐지 │
|
||||
│ │ └─ Label 내부 <span> 안에 * 문자 존재 여부 │
|
||||
│ │ (라벨 텍스트 직접 매칭 X → span 태그 안의 * 만 감지) │
|
||||
│ │ │
|
||||
│ └─ 2단계: 저장 버튼 클릭 인터셉트 │
|
||||
│ │ │
|
||||
│ ├─ 저장/수정/확인 버튼 클릭 감지 │
|
||||
│ │ (data-action-type="save"/"submit" │
|
||||
│ │ 또는 data-variant="default") │
|
||||
│ │ │
|
||||
│ ├─ 빈 필수 필드 있음: │
|
||||
│ │ ├─ 클릭 이벤트 차단 (stopPropagation + preventDefault) │
|
||||
│ │ ├─ 첫 번째 빈 필드로 포커스 이동 │
|
||||
│ │ ├─ 해당 필드 빨간 테두리 + 하이라이트 애니메이션 │
|
||||
│ │ └─ 토스트 알림: "{필드명} 항목을 입력해주세요" │
|
||||
│ │ │
|
||||
│ └─ 모든 필수 필드 입력됨: │
|
||||
│ └─ 클릭 이벤트 통과 (정상 저장 진행) │
|
||||
│ │
|
||||
│ 제외 조건: │
|
||||
│ └─ 필수 필드가 0개인 모달 → 인터셉트 없음 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 필수 필드 감지: span 기반 * 감지
|
||||
|
||||
### 원리
|
||||
|
||||
화면 관리에서 필드를 "필수"로 체크하면 `component.required = true`가 저장된다.
|
||||
V2 컴포넌트가 렌더링할 때 `required = true`이면 Label 안에 `<span>*</span>`을 추가한다.
|
||||
훅은 이 span 안의 `*`를 감지하여 필수 필드를 식별한다.
|
||||
|
||||
### 오탐 방지
|
||||
|
||||
관리자가 라벨 텍스트에 직접 `*`를 입력해도 span 안에 들어가지 않으므로 오탐이 발생하지 않는다.
|
||||
|
||||
```
|
||||
required = true → <label>품목코드<span class="text-orange-500">*</span></label>
|
||||
→ span 안에 * 있음 → 감지 O
|
||||
|
||||
required = false → <label>품목코드</label>
|
||||
→ span 없음 → 감지 X
|
||||
|
||||
라벨에 * 직접 입력 → <label>품목코드*</label>
|
||||
→ span 없이 텍스트에 * → 감지 X (오탐 방지)
|
||||
```
|
||||
|
||||
### 지원 필드 타입
|
||||
|
||||
| V2 컴포넌트 | 렌더링 요소 | 빈값 판정 |
|
||||
|---|---|---|
|
||||
| V2Input | `<input>`, `<textarea>` | `value.trim() === ""` |
|
||||
| V2Select | `<button role="combobox">` | `querySelector("[data-placeholder]")` 존재 |
|
||||
| V2Date | `<input>` (날짜/시간) | `value.trim() === ""` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 저장 버튼 클릭 인터셉트
|
||||
|
||||
### 원리
|
||||
|
||||
버튼을 비활성화하지 않고, 클릭 이벤트를 캡처링 단계에서 가로챈다.
|
||||
빈 필수 필드가 있으면 이벤트를 차단하고, 없으면 통과시킨다.
|
||||
|
||||
### 인터셉트 대상 버튼
|
||||
|
||||
| 조건 | 예시 |
|
||||
|------|------|
|
||||
| `data-action-type="save"` | ButtonPrimary 저장 버튼 |
|
||||
| `data-action-type="submit"` | ButtonPrimary 제출 버튼 |
|
||||
| `data-variant="default"` | shadcn Button 기본 (저장/확인/등록) |
|
||||
|
||||
### 인터셉트하지 않는 버튼
|
||||
|
||||
| 조건 | 예시 |
|
||||
|------|------|
|
||||
| `data-variant` = outline/ghost/destructive/secondary | 취소, 닫기, 삭제 |
|
||||
| `role` = combobox/tab/switch 등 | 폼 컨트롤 |
|
||||
| `data-action-type` != save/submit | 기타 액션 버튼 |
|
||||
| `data-dialog-close` | 모달 닫기 X 버튼 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 시각적 피드백
|
||||
|
||||
### 포커스 이동
|
||||
|
||||
첫 번째 빈 필수 필드로 커서를 이동한다.
|
||||
- `<input>`, `<textarea>`: `input.focus()`
|
||||
- `<button role="combobox">` (V2Select): `button.click()` → 드롭다운 열기
|
||||
|
||||
### 하이라이트 애니메이션
|
||||
|
||||
빈 필수 필드에 빨간 테두리 + 흔들림 효과를 준다.
|
||||
|
||||
```css
|
||||
@keyframes validationShake {
|
||||
0%, 100% { transform: translateX(0); }
|
||||
20%, 60% { transform: translateX(-4px); }
|
||||
40%, 80% { transform: translateX(4px); }
|
||||
}
|
||||
|
||||
[data-validation-highlight] {
|
||||
border-color: hsl(var(--destructive)) !important;
|
||||
animation: validationShake 400ms ease-in-out;
|
||||
}
|
||||
```
|
||||
|
||||
애니메이션 종료 후 `data-validation-highlight` 속성 제거 (일회성).
|
||||
|
||||
### 토스트 알림
|
||||
|
||||
우측 상단에 토스트 메시지를 표시한다.
|
||||
|
||||
```typescript
|
||||
toast.error(`${fieldLabel} 항목을 입력해주세요`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 동작 흐름
|
||||
|
||||
```
|
||||
모달 열림
|
||||
│
|
||||
▼
|
||||
DialogContent 마운트
|
||||
│
|
||||
▼
|
||||
useDialogAutoValidation 실행
|
||||
│
|
||||
▼
|
||||
모드 확인 (useTabStore.mode)
|
||||
│
|
||||
├─ mode !== "user"? → return
|
||||
│
|
||||
▼
|
||||
필수 필드 탐지 (Label 내 span에서 * 감지)
|
||||
│
|
||||
├─ 필수 필드 0개? → return
|
||||
│
|
||||
▼
|
||||
클릭 이벤트 리스너 등록 (캡처링 단계)
|
||||
│
|
||||
▼
|
||||
사용자가 저장 버튼 클릭
|
||||
│
|
||||
▼
|
||||
인터셉트 대상 버튼인가?
|
||||
│
|
||||
├─ 아니오 → 클릭 통과
|
||||
│
|
||||
▼
|
||||
빈 필수 필드 검사
|
||||
│
|
||||
├─ 모두 입력됨 → 클릭 통과 (정상 저장)
|
||||
│
|
||||
├─ 빈 필드 있음:
|
||||
│ ├─ e.stopPropagation() + e.preventDefault()
|
||||
│ ├─ 첫 번째 빈 필드에 포커스 이동
|
||||
│ ├─ 해당 필드에 data-validation-highlight 속성 추가
|
||||
│ ├─ 애니메이션 종료 후 속성 제거
|
||||
│ └─ toast.error("{필드명} 항목을 입력해주세요")
|
||||
│
|
||||
▼
|
||||
모달 닫힘
|
||||
│
|
||||
▼
|
||||
클린업
|
||||
├─ 이벤트 리스너 제거
|
||||
└─ 하이라이트 속성 제거
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 관련 파일
|
||||
|
||||
| 파일 | 역할 |
|
||||
|------|------|
|
||||
| `frontend/lib/hooks/useDialogAutoValidation.ts` | 검증 훅 본체 |
|
||||
| `frontend/components/ui/dialog.tsx` | DialogContent에서 훅 호출 |
|
||||
| `frontend/components/ui/button.tsx` | data-variant 속성 노출 |
|
||||
| `frontend/lib/registry/components/v2-button-primary/ButtonPrimaryComponent.tsx` | data-action-type 속성 노출 |
|
||||
| `frontend/app/globals.css` | 하이라이트 애니메이션 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 적용 범위
|
||||
|
||||
### 현재 (1단계): 사용자 모드만
|
||||
|
||||
| 모달 유형 | 동작 여부 | 이유 |
|
||||
|---------------------------------------|:---:|-------------------------------|
|
||||
| 사용자 모드 모달 (SaveModal 등) | O | mode === "user" + span * 있음 |
|
||||
| 관리자 모드 모달 (CodeFormModal 등) | X | mode !== "user" → return |
|
||||
| 확인/삭제 다이얼로그 (필수 필드 없음) | X | 필수 필드 0개 → 자동 제외 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 이전 방식과 비교
|
||||
|
||||
| 항목 | 이전 (버튼 비활성화) | 현재 (클릭 인터셉트) |
|
||||
|------|---|---|
|
||||
| 버튼 상태 | 빈 필드 있으면 비활성화 | 항상 활성 |
|
||||
| 피드백 시점 | 모달 열릴 때부터 | 저장 버튼 클릭 시 |
|
||||
| 피드백 방식 | 빨간 테두리 + 에러 문구 | 포커스 이동 + 하이라이트 + 토스트 |
|
||||
| 복잡도 | 높음 (MutationObserver, 폴링, CSS 지연) | 낮음 (클릭 이벤트 하나) |
|
||||
Reference in New Issue
Block a user