docs: [rules] 공통 컴포넌트 우선 접근 규칙 + CurrencyInput 사용 규칙 추가

This commit is contained in:
유병철
2026-03-19 17:49:02 +09:00
parent e3b4cd8406
commit 70f7341e64

View File

@@ -542,6 +542,55 @@ url: `${API_URL}/api/v1/items?${params.toString()}`
- **IntegratedListTemplateV2 사용 시 → 컬럼 설정(`useColumnSettings` + `ColumnSettingsPopover`), 모바일 카드(`renderMobileCard`), 체크박스(`Set<string>`), 테이블 내 필터(`tableHeaderActions`) 필수 적용**
- 상세/폼 → Card + 기존 패턴 따르기
### 🔴 리스트 페이지 공통 기능은 공통 컴포넌트에서 해결
리스트 페이지 전체에 적용해야 하는 기능은 **개별 페이지 수정 금지**. 반드시 공통 레이어에서 처리.
| 기능 | 수정 위치 | 개별 페이지 수정 |
|------|----------|----------------|
| 검색 상태 보존 | `UniversalListPage` (내장 `useListSearchState`) | ❌ 금지 |
| 검색 X(클리어) 버튼 | `SearchFilter` + `IntegratedListTemplateV2` | ❌ 금지 |
| 검색 디바운스 | `UniversalListPage` 내부 300ms debounce | ❌ 금지 |
| 체크박스 선택 | `IntegratedListTemplateV2` | ❌ 금지 |
| 페이지네이션 | `IntegratedListTemplateV2` | ❌ 금지 |
| 모바일 카드/인피니티 | `IntegratedListTemplateV2` | ❌ 금지 |
| 컬럼 설정 | `useColumnSettings` + `ColumnSettingsPopover` | ❌ 금지 |
**원칙: "26개 페이지에 하나씩 적용" → 잘못된 접근. "공통 1곳 수정 → 전체 자동 적용" → 올바른 접근.**
### 🔴 목록 페이지 검색 — UniversalListPage + clientSideFiltering 필수
목록 페이지의 검색은 **반드시 `UniversalListPage` + `clientSideFiltering: true` + `searchFilter`** 패턴을 사용한다.
`IntegratedListTemplateV2`에 직접 `onSearchChange`를 연결하면 키입력마다 화면이 깜빡이며 한글 조합이 불가능해진다.
```typescript
// ✅ 올바른 패턴 — UniversalListPage + clientSideFiltering (품목관리, 수주관리와 동일)
const config: UniversalListConfig<MyItem> = {
clientSideFiltering: true,
searchFilter: (item, searchValue) => {
const q = searchValue.toLowerCase();
return item.name.toLowerCase().includes(q) || item.code.toLowerCase().includes(q);
},
searchPlaceholder: '이름, 코드 검색...',
};
// 데이터를 한 번 API로 로드 → 검색은 메모리에서 즉시 필터링 → 깜빡임 없음
```
```typescript
// ❌ 금지 패턴 — IntegratedListTemplateV2에 onSearchChange 직접 연결
<IntegratedListTemplateV2
searchValue={searchTerm}
onSearchChange={(q) => { setSearchTerm(q); }} // 키입력마다 state 변경 → re-render → 화면 깜빡임
/>
```
### 🔴 금액 입력 컴포넌트 선택 규칙
| 용도 | 컴포넌트 | 특징 |
|------|---------|------|
| **금액 입력** (경조사비, 비용 등) | `CurrencyInput` | 입력 중 실시간 천단위 콤마, ₩ 표시 |
| **수량 입력** (재고, BOM 등) | `NumberInput` | 소수점 허용, 포커스 해제 시 콤마(`useComma`) |
| **테이블 내 금액** (단가 등) | `NumberInput useComma` | 간결한 인라인용 |
`NumberInput useComma`는 포커스 해제 시에만 콤마 표시. 금액 전용 입력에는 반드시 `CurrencyInput` 사용.
---
## FormField 사용 규칙 (신규 폼 필수)