chore(WEB): PermissionManagement 오류 수정 및 claudedocs 폴더 정리

- PermissionManagement externalSelection 콜백 함수 오류 수정
  - setSelectedItems → onToggleSelection, onToggleSelectAll, getItemId 변경
- claudedocs 문서 폴더별 정리 (26개 파일)
  - dashboard/, guides/, settings/, construction/, sales/ 등

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
유병철
2026-01-17 13:11:35 +09:00
parent 736c29a007
commit b59150551e
29 changed files with 1189 additions and 1 deletions

View File

@@ -0,0 +1,674 @@
# IntegratedDetailTemplate 구현 체크리스트
> 브랜치: `feature/universal-detail-component`
> 작성일: 2026-01-17
> 최종 수정: 2026-01-17 (v2 - 심층 검토 반영)
---
## ⚠️ 예외 처리 프로세스
### 예외 상황 발생 시 절차
마이그레이션 중 예외 상황 발생 시 다음 절차를 따릅니다:
1. **즉시 중단**: 현재 모듈 작업 중단
2. **문서화**: 아래 예외 기록 섹션에 상황 기록
3. **분류**: 예외 유형 판단
- **Type A**: 템플릿 수정으로 해결 가능 → Phase 0 보완
- **Type B**: 해당 모듈만 특수 처리 필요 → `renderView/renderForm` 사용
- **Type C**: 완전 제외 필요 → 제외 목록에 추가
4. **계획 수정**: 체크리스트 업데이트
5. **재개**: 다음 모듈 또는 수정된 계획으로 진행
### 예외 기록
| 날짜 | 모듈 | 예외 유형 | 상황 설명 | 조치 |
|------|------|----------|----------|------|
| - | - | - | (예외 발생 시 여기에 기록) | - |
### 알려진 특수 케이스
| 모듈 | 특수 요소 | 처리 방안 |
|------|----------|----------|
| popup-management | RichTextEditor | Phase 0.3에서 richtext 타입 지원 후 진행 |
| process-management | RuleModal (분류규칙 배열) | renderForm으로 기존 컴포넌트 유지 또는 Phase 후반 |
| quote-management | QuoteDocument 모달 | renderView로 문서 모달 유지 |
| order-management-sales | OrderDocumentModal | renderView로 문서 모달 유지 |
| work-orders | WorkOrderDetail (카드 레이아웃) | renderView로 기존 상세 유지 |
| items (품목관리) | DynamicItemForm | **완전 제외** (동적 폼) |
---
## 🛡️ 롤백 전략
### 파일 관리 규칙
1. **기존 컴포넌트 보존**: 마이그레이션 완료 전까지 삭제 금지
2. **백업 위치**: `src/components/_legacy/[모듈명]/`
3. **정리 시점**: Phase 완료 후 전체 테스트 통과 시
### 롤백 절차
```bash
# 문제 발생 시
1. git stash (현재 작업 저장)
2. _legacy 폴더에서 원본 복원
3. page.tsx에서 import 경로 원복
4. 문제 분석 후 예외 기록
```
### Git 브랜치 전략
```
feature/universal-detail-component (메인 작업 브랜치)
├── phase-0-template (템플릿 구현)
├── phase-1-prototype (프로토타입 3개)
├── phase-2-settings (설정 모듈)
└── ... (Phase별 서브 브랜치)
```
- Phase 완료 시 메인 브랜치로 머지
- 문제 시 해당 Phase 브랜치만 롤백
---
## Phase 0 사전 준비: 분석 및 설계
### 0.0.1 필드 타입 인벤토리
> 템플릿 설계 전 사용되는 모든 필드 타입 파악
**기본 타입 (Phase 0.1 지원)**
- [ ] `text`: 일반 텍스트 입력
- [ ] `number`: 숫자 입력
- [ ] `select`: 드롭다운 선택
- [ ] `date`: 날짜 선택
- [ ] `textarea`: 여러 줄 텍스트
**확장 타입 (Phase 0.2 지원)**
- [ ] `radio`: 라디오 버튼 그룹
- [ ] `checkbox`: 체크박스
- [ ] `password`: 비밀번호 입력
- [ ] `email`: 이메일 입력
- [ ] `tel`: 전화번호 입력
**복합 타입 (Phase 0.3 지원)**
- [ ] `dateRange`: 시작일~종료일
- [ ] `richtext`: RichTextEditor (HTML)
- [ ] `file`: 파일 업로드
- [ ] `custom`: 커스텀 렌더러
**특수 타입 (renderForm으로 처리)**
- [ ] `arrayModal`: 배열 데이터 + 모달 편집 (RuleModal 등)
- [ ] `nestedForm`: 중첩 폼 구조
- [ ] `dynamicFields`: 동적 필드 생성
### 0.0.2 템플릿 인터페이스 설계
- [ ] `DetailConfig` 인터페이스 정의
- [ ] `FieldDefinition` 인터페이스 정의
- [ ] `ActionConfig` 인터페이스 정의
- [ ] `PermissionConfig` 인터페이스 정의
- [ ] props 타입 정의 (`IntegratedDetailTemplateProps`)
```typescript
// 예시 구조 (실제 구현 시 확정)
interface DetailConfig {
title: string;
icon?: LucideIcon;
description?: string;
fields: FieldDefinition[];
sections?: SectionDefinition[]; // 필드 그룹핑
actions?: ActionConfig;
permissions?: PermissionConfig;
}
interface FieldDefinition {
key: string;
label: string;
type: FieldType;
required?: boolean;
disabled?: boolean | ((mode: Mode) => boolean);
options?: Option[]; // for select, radio
placeholder?: string;
validation?: ValidationRule[];
gridSpan?: 1 | 2 | 3; // 그리드 차지 칸 수
hideInView?: boolean;
hideInForm?: boolean;
}
```
### 0.0.3 API 호출 패턴 결정
- [ ] 표준 패턴 결정: ~~컴포넌트 내부~~ vs **props 콜백**
- [ ] `onSubmit`, `onDelete` 콜백 인터페이스 정의
- [ ] 에러 처리 표준화 (toast 사용)
- [ ] 로딩 상태 관리 방식 결정
**결정된 표준 패턴**:
```typescript
// page.tsx에서 API 함수 전달
<IntegratedDetailTemplate
config={config}
mode="create"
onSubmit={async (data) => {
const result = await createSomething(data);
if (result.success) router.push('/list');
return result;
}}
onDelete={async (id) => {
const result = await deleteSomething(id);
if (result.success) router.push('/list');
return result;
}}
/>
```
### 0.0.4 기존 모듈 복잡도 재분류
> Phase 1~2 대상 모듈의 실제 복잡도 검증
| 모듈 | 예상 복잡도 | 실제 복잡도 | 특수 요소 | Phase 배치 |
|------|------------|------------|----------|-----------|
| accounts | 단순 | ✅ 단순 | 없음 | Phase 1 |
| card-management | 단순 | ✅ 단순 | 직원 API 조회 | Phase 1 |
| permissions | 단순 | ⬜ 미확인 | - | Phase 1 |
| popup-management | 단순 | ⚠️ 중간 | RichTextEditor | Phase 2 |
| process-management | 단순 | ❌ 복잡 | RuleModal | Phase 4 이후 |
| board-management | 단순 | ⬜ 미확인 | - | Phase 2 |
---
## Phase 0: 템플릿 기본 구조 구현
### 0.1 파일 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/index.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/types.ts` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/DetailHeader.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/DetailForm.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/DetailView.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/FieldRenderer.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/GridLayout.tsx` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/hooks/useDetailPage.ts` 생성
- [ ] `src/components/templates/IntegratedDetailTemplate/hooks/useFormHandler.ts` 생성
### 0.2 Phase 0.1 - 기본 타입 구현
- [ ] mode props 처리 (create/edit/view)
- [ ] 헤더 레이아웃 (제목, 아이콘, 뒤로가기 버튼)
- [ ] 액션 버튼 배치 (저장, 취소, 삭제, 수정)
- [ ] 그리드 레이아웃 (2열, 3열 지원)
- [ ] 필드 렌더링: `text`
- [ ] 필드 렌더링: `number`
- [ ] 필드 렌더링: `select`
- [ ] 필드 렌더링: `date`
- [ ] 필드 렌더링: `textarea`
- [ ] 폼 유효성 검사 기본 구조
- [ ] 로딩 상태 처리
- [ ] 에러 상태 처리
### 0.3 Phase 0.2 - 확장 타입 구현
- [ ] 필드 렌더링: `radio`
- [ ] 필드 렌더링: `checkbox`
- [ ] 필드 렌더링: `password`
- [ ] 필드 렌더링: `email`
- [ ] 필드 렌더링: `tel`
### 0.4 Phase 0.3 - 복합 타입 및 커스텀 지원
- [ ] 필드 렌더링: `dateRange` (시작~종료)
- [ ] 필드 렌더링: `richtext` (RichTextEditor 통합)
- [ ] 필드 렌더링: `file` (파일 업로드)
- [ ] `renderView` props 지원 (커스텀 상세 화면)
- [ ] `renderForm` props 지원 (커스텀 폼)
- [ ] `renderField` props 지원 (개별 필드 커스텀)
### 0.5 Phase 0 검증
- [ ] 모든 기본 타입 렌더링 확인
- [ ] view/create/edit 모드 전환 확인
- [ ] 반응형 그리드 확인
- [ ] 유효성 검사 동작 확인
- [ ] 버튼 배치/스타일 확인
---
## Phase 1: 프로토타입 (3개 모듈) - 단순 CRUD
> 목표: 가장 단순한 모듈로 템플릿 검증
### 1.1 settings/accounts (계좌관리) ✅ 권장
#### 1.1.1 현황 분석
- [ ] `settings/accounts/new/page.tsx` 분석
- [ ] `settings/accounts/[id]/page.tsx` 분석
- [ ] 기존 컴포넌트 구조 파악 (AccountDetail - 통합 모드)
- [ ] 필드 목록 정리:
- [ ] bankCode (select) - 은행 선택
- [ ] accountNumber (text) - 계좌번호
- [ ] accountHolder (text) - 예금주
- [ ] accountPassword (password) - 비밀번호
- [ ] accountName (text) - 계좌명
- [ ] status (select) - 상태
- [ ] API 연결 확인 (actions.ts)
- [ ] **예외 요소 확인**: 없음 ✅
#### 1.1.2 config 파일 작성
- [ ] `src/components/settings/AccountManagement/accountConfig.ts` 작성
- [ ] 필드 정의
- [ ] 권한 설정 (canEdit, canDelete)
#### 1.1.3 페이지 마이그레이션
- [ ] `new/page.tsx` → IntegratedDetailTemplate (mode="create")
- [ ] `[id]/page.tsx` → IntegratedDetailTemplate (mode="view")
- [ ] 기존 AccountDetail.tsx → `_legacy/` 이동 (삭제 X)
#### 1.1.4 기능 테스트
- [ ] **Happy Path**:
- [ ] 등록: 모든 필드 입력 → 저장 → 목록 이동
- [ ] 조회: 데이터 정상 표시
- [ ] 수정: 데이터 로드 → 수정 → 저장
- [ ] 삭제: 확인 다이얼로그 → 삭제 → 목록 이동
- [ ] **Error Path**:
- [ ] 필수 필드 누락 시 유효성 에러
- [ ] API 실패 시 에러 토스트
- [ ] **UI 검증**:
- [ ] 버튼 배치 확인 (좌: 취소/목록, 우: 삭제/수정/저장)
- [ ] 그리드 레이아웃 확인 (2열)
- [ ] 반응형 확인 (모바일 1열)
#### 1.1.5 정리
- [ ] import 경로 정리
- [ ] 불필요한 코드 제거
- [ ] **예외 발생 시**: 예외 기록 섹션에 문서화
---
### 1.2 hr/card-management (카드관리)
#### 1.2.1 현황 분석
- [ ] `hr/card-management/new/page.tsx` 분석
- [ ] `hr/card-management/[id]/page.tsx` 분석
- [ ] `hr/card-management/[id]/edit/page.tsx` 분석
- [ ] 기존 컴포넌트 구조 파악 (CardForm)
- [ ] 필드 목록 정리:
- [ ] cardCompany (select) - 카드사
- [ ] cardNumber (text) - 카드번호 (포맷팅)
- [ ] expiryDate (text) - 유효기간
- [ ] pinPrefix (password) - 비밀번호 앞자리
- [ ] cardName (text) - 카드명
- [ ] status (select) - 상태
- [ ] userId (select) - 사용자 (직원 API 조회)
- [ ] API 연결 확인 (actions.ts)
- [ ] **예외 요소 확인**:
- [ ] 직원 목록 API 호출 필요 → select options 동적 로드
#### 1.2.2 config 파일 작성
- [ ] `cardManagementConfig.ts` 작성
- [ ] 필드 정의
- [ ] **동적 options 로드 방식 결정**:
- Option A: config에서 `fetchOptions` 함수 정의
- Option B: page.tsx에서 미리 로드 후 config에 전달
- [ ] 권한 설정
#### 1.2.3 페이지 마이그레이션
- [ ] `new/page.tsx` → IntegratedDetailTemplate (mode="create")
- [ ] `[id]/page.tsx` → IntegratedDetailTemplate (mode="view")
- [ ] `[id]/edit/page.tsx` → IntegratedDetailTemplate (mode="edit")
- [ ] 기존 CardForm.tsx → `_legacy/` 이동
#### 1.2.4 기능 테스트
- [ ] **Happy Path**: 등록/조회/수정/삭제
- [ ] **Error Path**: 유효성/API 에러
- [ ] **특수 테스트**:
- [ ] 직원 select 동적 로드 확인
- [ ] 카드번호 포맷팅 확인
- [ ] **UI 검증**: 버튼/그리드/반응형
#### 1.2.5 정리
- [ ] import 경로 정리
- [ ] **예외 발생 시**: 문서화
---
### 1.3 settings/permissions (권한관리)
#### 1.3.1 현황 분석
- [ ] `settings/permissions/new/page.tsx` 분석
- [ ] `settings/permissions/[id]/page.tsx` 분석
- [ ] 기존 컴포넌트 구조 파악
- [ ] 필드 목록 정리
- [ ] API 연결 확인
- [ ] **예외 요소 확인**: (분석 후 기록)
#### 1.3.2 config 파일 작성
- [ ] `permissionsConfig.ts` 작성
- [ ] 필드 정의
- [ ] 권한 설정
#### 1.3.3 페이지 마이그레이션
- [ ] `new/page.tsx` → IntegratedDetailTemplate (mode="create")
- [ ] `[id]/page.tsx` → IntegratedDetailTemplate (mode="view")
- [ ] 기존 컴포넌트 → `_legacy/` 이동
#### 1.3.4 기능 테스트
- [ ] Happy Path / Error Path / UI 검증
#### 1.3.5 정리
- [ ] import 경로 정리
- [ ] **예외 발생 시**: 문서화
---
### 1.4 Phase 1 완료 검증
- [ ] 3개 모듈 모두 정상 동작 확인
- [ ] 발견된 예외 사항 정리
- [ ] 템플릿 구조 검토 및 개선점 도출
- [ ] **Phase 0 보완 필요 여부 판단**:
- [ ] 새로운 필드 타입 필요?
- [ ] 인터페이스 수정 필요?
- [ ] 공통 패턴 확인 및 리팩토링
- [ ] Phase 2 진행 여부 결정
---
## Phase 2: 설정/게시판 모듈 (4개) - RichTextEditor 포함
> Phase 0.3 (richtext 지원) 완료 후 진행
### 2.1 settings/popup-management (팝업관리) ⚠️ RichTextEditor
#### 2.1.1 현황 분석
- [ ] 기존 컴포넌트 분석 (PopupForm + PopupDetail 분리 구조)
- [ ] 필드 목록 정리:
- [ ] target (select) - 대상
- [ ] startDate, endDate (dateRange) - 기간
- [ ] title (text) - 제목
- [ ] content (richtext) - 내용 ⚠️
- [ ] status (radio) - 상태
- [ ] author (text, readonly) - 작성자
- [ ] **예외 요소**: RichTextEditor → Phase 0.3 richtext 타입 사용
#### 2.1.2 config 파일 작성
- [ ] `popupManagementConfig.ts` 작성
#### 2.1.3 페이지 마이그레이션
- [ ] `new/page.tsx` 마이그레이션
- [ ] `[id]/page.tsx` 마이그레이션
- [ ] `[id]/edit/page.tsx` 마이그레이션
#### 2.1.4 기능 테스트
- [ ] 특수: RichTextEditor 동작 확인
- [ ] 특수: dateRange 동작 확인
#### 2.1.5 정리
---
### 2.2 board/board-management (게시판관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 2.3 accounting/bad-debt-collection (악성채권추심)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 2.4 hr/documents (증명서류)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 정리
### 2.5 Phase 2 완료 검증
- [ ] 4개 모듈 모두 정상 동작 확인
- [ ] richtext, dateRange 필드 동작 확인
- [ ] 예외 사항 정리
- [ ] Phase 3 진행 여부 결정
---
## Phase 3: HR/판매 모듈 (6개) - 특수 상세 화면 포함
### 3.1 hr/employee-management (사원관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 3.2 sales/client-management-sales-admin (거래처관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 3.3 sales/quote-management (견적관리) ⚠️ 문서 모달
#### 특수 처리
- [ ] `[id]/page.tsx`: `renderView` prop으로 QuoteDocument 모달 유지
- [ ] 등록/수정은 일반 템플릿 적용
- [ ] 현황 분석
- [ ] config 작성 (renderView 포함)
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트 (문서 모달 동작 확인)
- [ ] 정리
### 3.4 sales/order-management-sales (수주관리) ⚠️ 문서 모달
#### 특수 처리
- [ ] `[id]/page.tsx`: `renderView` prop으로 OrderDocumentModal 유지
- [ ] 현황 분석
- [ ] config 작성 (renderView 포함)
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 정리
### 3.5 sales/pricing-management (단가관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 3.6 customer-center/qna (Q&A)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 3.7 Phase 3 완료 검증
- [ ] 6개 모듈 모두 정상 동작 확인
- [ ] **renderView 동작 확인** (문서 모달)
- [ ] 예외 사항 정리
- [ ] Phase 4 진행 여부 결정
---
## Phase 4: 생산/출고/품질 모듈 (4개) - 복잡한 상세 화면
### 4.1 production/work-orders (작업지시관리) ⚠️ 카드 레이아웃
#### 특수 처리
- [ ] `[id]/page.tsx`: `renderView` prop으로 WorkOrderDetail (카드 레이아웃) 유지
- [ ] 현황 분석
- [ ] config 작성 (renderView 포함)
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 정리
### 4.2 production/screen-production (스크린생산) ⚠️ 복합 레이아웃
#### 특수 처리
- [ ] `[id]/page.tsx`: `renderView` prop으로 ItemDetailClient 유지
- [ ] 현황 분석
- [ ] config 작성 (renderView 포함)
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 정리
### 4.3 outbound/shipments (출하관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 4.4 quality/inspections (검사관리)
- [ ] 현황 분석
- [ ] config 작성
- [ ] 페이지 마이그레이션 (new, [id], [id]/edit)
- [ ] 기능 테스트
- [ ] 정리
### 4.5 master-data/process-management (공정관리) ⚠️ RuleModal
#### 특수 처리
- [ ] **복잡도 재평가**: RuleModal (분류규칙 배열 관리)
- [ ] Option A: `renderForm`으로 기존 ProcessForm 유지
- [ ] Option B: 배열 필드 타입 추가 후 마이그레이션
- [ ] **결정 후 진행**
- [ ] 현황 분석
- [ ] 처리 방안 결정
- [ ] config 또는 renderForm 작성
- [ ] 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 정리
### 4.6 Phase 4 완료 검증
- [ ] 모듈 정상 동작 확인
- [ ] 복잡한 renderView 동작 확인
- [ ] 예외 사항 정리
- [ ] Phase 5 진행 여부 결정
---
## Phase 5: 건설 모듈 (6개)
### 5.1 construction/project/bidding/partners (거래처-입찰)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.2 construction/project/bidding/site-briefings (현장설명회)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.3 construction/project/contract (계약관리)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.4 construction/project/issue-management (이슈관리)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.5 construction/order/base-info/pricing (단가-건설)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.6 construction/order/base-info/labor (노임-건설)
- [ ] 현황 분석 / config 작성 / 마이그레이션 / 테스트 / 정리
### 5.7 Phase 5 완료 검증
- [ ] 6개 모듈 모두 정상 동작 확인
- [ ] 예외 사항 정리
- [ ] Phase 6 진행 여부 결정
---
## Phase 6: 나머지 패턴 (B, C, D)
### 6.1 패턴 B (등록+상세, mode로 수정)
> accounting/bills, accounting/sales, accounting/vendors
- [ ] accounting/bills 마이그레이션
- [ ] accounting/sales 마이그레이션
- [ ] accounting/vendors 마이그레이션
- [ ] 기능 테스트
### 6.2 패턴 C (상세+수정, 등록 없음)
> construction 모듈 대부분
- [ ] construction/billing/progress-billing-management
- [ ] construction/order/order-management
- [ ] construction/order/site-management
- [ ] construction/order/structure-review
- [ ] construction/project/bidding
- [ ] construction/project/bidding/estimates
- [ ] construction/project/construction-management
- [ ] construction/project/contract/handover-report
- [ ] sales/quote-management/test
- [ ] 기능 테스트
### 6.3 패턴 D (상세만, 조회 전용)
> 10개 모듈
- [ ] accounting/deposits
- [ ] accounting/purchase
- [ ] accounting/vendor-ledger
- [ ] accounting/withdrawals
- [ ] customer-center/notices
- [ ] customer-center/events
- [ ] material/receiving-management
- [ ] material/stock-status
- [ ] construction/project/management
- [ ] sales/order-management-sales/production-orders
- [ ] 기능 테스트
### 6.4 Phase 6 완료 검증
- [ ] 모든 패턴 정상 동작 확인
- [ ] 예외 사항 최종 정리
---
## 🚫 제외 대상
| 모듈 | 제외 사유 |
|------|----------|
| items (품목관리) 3개 페이지 | DynamicItemForm 사용 (동적 폼) |
| (추가 발견 시 기록) | - |
---
## 최종 검증
- [ ] 전체 마이그레이션 완료 페이지 수 확인
- [ ] 제외 대상 확인 및 문서화
- [ ] 전체 기능 회귀 테스트
- [ ] 성능 테스트 (로딩 속도)
- [ ] 반응형 레이아웃 전체 확인
- [ ] `_legacy` 폴더 정리 (최종 삭제)
- [ ] 예외 기록 최종 검토
---
## 통계
| Phase | 모듈 수 | 예상 페이지 수 | 상태 |
|-------|--------|--------------|------|
| Phase 0 사전준비 | - | - | ⬜ 대기 |
| Phase 0 템플릿 | - | - | ⬜ 대기 |
| Phase 1 | 3 | 7 | ⬜ 대기 |
| Phase 2 | 4 | 12 | ⬜ 대기 |
| Phase 3 | 6 | 18 | ⬜ 대기 |
| Phase 4 | 5 | 15 | ⬜ 대기 |
| Phase 5 | 6 | 16 | ⬜ 대기 |
| Phase 6 | 22 | 38 | ⬜ 대기 |
| **합계** | **46** | **~106** | - |
> 제외: 품목관리(items) 3개 페이지 (동적 폼)
---
## 변경 이력
| 날짜 | 버전 | 내용 |
|------|------|------|
| 2026-01-17 | v1 | 체크리스트 초기 작성 |
| 2026-01-17 | v2 | 심층 검토 반영 - Phase 1 모듈 변경, 예외 처리 프로세스 추가, 롤백 전략 추가, Phase 0 사전준비 추가, 필드 타입 인벤토리 추가 |

View File

@@ -0,0 +1,495 @@
# 상세/등록/수정 페이지 통합 컴포넌트 계획
> 브랜치: `feature/universal-detail-component`
> 작성일: 2026-01-17
> 상태: 계획 수립 완료
## 1. 개요
### 1.1 목표
- 등록/상세/수정 페이지를 **IntegratedDetailTemplate** 통합 컴포넌트로 정리
- 기존 API 연결 코드는 그대로 유지 (actions.ts)
- UI/레이아웃만 통합하여 **유지보수성 향상**
- **미래 동적 폼 전환에 대비한 확장 가능한 설계**
### 1.2 기대 효과
- 코드 중복 제거
- UI/UX 일관성 확보 (버튼 위치, 입력필드 스타일, 그리드 레이아웃)
- 유지보수 용이성 증가 (한 파일에서 전체 스타일 관리)
- 새 페이지 추가 시 개발 시간 단축
- 동적 폼 전환 시 껍데기(레이아웃) 재사용 가능
### 1.3 미래 동적 폼 전환 대비
> ⚠️ **중요**: 최종 목표는 모든 페이지가 **품목기준관리**처럼 동적 폼으로 전환되는 것
#### 현재 vs 미래 구조
```
┌─────────────────────────────────────────────────┐
│ IntegratedDetailTemplate (껍데기 - 재사용) │
│ ├── 헤더 레이아웃 ← 동적 폼에서도 사용 │
│ ├── 버튼 배치/위치 ← 동적 폼에서도 사용 │
│ ├── 그리드 시스템 ← 동적 폼에서도 사용 │
│ └── 공통 스타일 ← 동적 폼에서도 사용 │
├─────────────────────────────────────────────────┤
│ 내부 폼 영역 (교체 가능) │
│ │
│ 현재: 정적 config 기반 폼 ← 나중에 폐기 │
│ 미래: 동적 폼 (기준관리 기반) ← 교체 │
└─────────────────────────────────────────────────┘
```
#### 재사용률 분석
| 작업 | 동적 폼 전환 시 |
|------|----------------|
| 헤더/버튼 레이아웃 | ✅ 재사용 (70%) |
| 그리드 시스템 | ✅ 재사용 |
| 공통 스타일 | ✅ 재사용 |
| 정적 config 정의 | ❌ 폐기 (30%) |
#### 동적 폼 지원 설계
```tsx
// 현재 (정적 폼)
<IntegratedDetailTemplate
mode="edit"
config={popupConfig} // 필드 정의
onSubmit={updatePopup}
/>
// 미래 (동적 폼) - 껍데기는 그대로, 내부만 교체
<IntegratedDetailTemplate
mode="edit"
renderForm={(props) => (
<DynamicForm
기준관리ID={123}
{...props}
/>
)}
onSubmit={updatePopup}
/>
```
---
## 2. 현황 분석
### 2.1 전체 통계
| 항목 | 개수 |
|------|------|
| 전체 페이지 (page.tsx) | 205개 |
| 등록 페이지 (new/create) | 32개 |
| 수정 페이지 ([id]/edit) | 30개 |
| 상세 페이지 ([id]) | 47개 |
| **통합 대상** | **109개** |
| **제외 (동적 폼)** | **3개** (품목관리) |
### 2.2 테스트 URL 페이지
- 일반 모듈: http://localhost:3000/dev/test-urls (60개)
- 건설 모듈: http://localhost:3000/dev/construction-test-urls (19개)
---
## 3. 패턴 분류
### 3.1 패턴 A: 완전 CRUD (19개 모듈, 57개 페이지)
> 구성: `/new` + `/[id]` + `/[id]/edit`
| 모듈 | 경로 |
|------|------|
| 사원관리 | hr/employee-management |
| 카드관리 | hr/card-management |
| 거래처관리 | sales/client-management-sales-admin |
| 견적관리 | sales/quote-management |
| 수주관리 | sales/order-management-sales |
| 단가관리 | sales/pricing-management |
| 작업지시관리 | production/work-orders |
| 스크린생산 | production/screen-production |
| 팝업관리 | settings/popup-management |
| 공정관리 | master-data/process-management |
| 출하관리 | outbound/shipments |
| 검사관리 | quality/inspections |
| Q&A | customer-center/qna |
| 게시판관리 | board/board-management |
| 악성채권추심 | accounting/bad-debt-collection |
| 거래처(입찰) | construction/project/bidding/partners |
| 현장설명회 | construction/project/bidding/site-briefings |
| 계약관리 | construction/project/contract |
| 이슈관리 | construction/project/issue-management |
### 3.2 패턴 B: 등록+상세 (8개 모듈, 16개 페이지)
> 구성: `/new` + `/[id]` (수정은 상세에서 mode로 처리)
| 모듈 | 경로 | 비고 |
|------|------|------|
| 어음관리 | accounting/bills | mode=edit |
| 매출관리 | accounting/sales | mode=edit |
| 거래처(회계) | accounting/vendors | mode=edit |
| 계좌관리 | settings/accounts | |
| 권한관리 | settings/permissions | |
| 품목(건설) | construction/order/base-info/items | |
| 노임(건설) | construction/order/base-info/labor | |
| 단가(건설) | construction/order/base-info/pricing | |
### 3.3 패턴 C: 상세+수정 (9개 모듈, 18개 페이지)
> 구성: `/[id]` + `/[id]/edit` (등록은 리스트에서 처리)
| 모듈 | 경로 |
|------|------|
| 기성청구관리 | construction/billing/progress-billing-management |
| 발주관리 | construction/order/order-management |
| 현장관리 | construction/order/site-management |
| 구조검토관리 | construction/order/structure-review |
| 입찰관리 | construction/project/bidding |
| 견적관리(건설) | construction/project/bidding/estimates |
| 시공관리 | construction/project/construction-management |
| 인수인계보고서 | construction/project/contract/handover-report |
| 견적테스트 | sales/quote-management/test |
### 3.4 패턴 D: 상세만 (10개 모듈, 10개 페이지)
> 구성: `/[id]` only (조회 전용)
| 모듈 | 경로 | 비고 |
|------|------|------|
| 입금관리 | accounting/deposits | 조회 전용 |
| 매입관리 | accounting/purchase | 조회 전용 |
| 거래처원장 | accounting/vendor-ledger | 조회 전용 |
| 출금관리 | accounting/withdrawals | 조회 전용 |
| 공지사항 | customer-center/notices | 조회 전용 |
| 이벤트 | customer-center/events | 조회 전용 |
| 입고관리 | material/receiving-management | 조회 전용 |
| 재고현황 | material/stock-status | 조회 전용 |
| 프로젝트관리 | construction/project/management | 조회 전용 |
| 생산주문 | sales/order-management-sales/production-orders | 조회 전용 |
---
## 4. 통합 제외 대상
### 4.1 동적 폼 사용 모듈 (완전 제외)
> 🔴 **품목관리**는 이미 동적 폼(`DynamicItemForm`)을 사용하므로 **통합 대상에서 완전 제외**
| 모듈 | 경로 | 제외 이유 |
|------|------|----------|
| 품목관리 | items | `DynamicItemForm` 사용 (품목기준관리 기반 동적 폼) |
#### 품목관리 특수성
```
items/
├── create/page.tsx → DynamicItemForm (mode="create") ← 동적 폼
├── [id]/page.tsx → ItemDetailClient (카드형 조회) ← 특수 UI
└── [id]/edit/page.tsx → DynamicItemForm (mode="edit") ← 동적 폼
```
**제외 이유:**
1. **동적 폼 구조**: 필드가 품목기준관리 API 설정에 따라 동적 생성
2. **복잡한 비즈니스 로직**: FG/PT/SM/RM/CS 각각 다른 코드 생성 규칙
3. **BOM 관리**: 부품표(BOM) 별도 API 호출 및 관리
4. **데이터 변환**: 400줄+ 변환 로직 (`mapApiResponseToFormData`)
> 💡 **미래 방향**: 다른 페이지들도 품목관리처럼 동적 폼으로 전환 예정
### 4.2 특수 상세 UI 모듈 (상세만 제외)
> 🟡 상세 페이지가 문서 모달/카드형 등 특수 UI → **상세는 유지, 등록/수정만 통합**
#### 문서 모달 기반 상세
| 모듈 | 경로 | 사용 컴포넌트 | 문서 유형 |
|------|------|--------------|----------|
| 기안함 | approval/draft | `DocumentDetailModal` | 품의서, 지출결의서, 지출예상내역서 |
| 수주관리 | sales/order-management-sales | `OrderDocumentModal` | 계약서, 거래명세서, 발주서 |
| 견적관리 | sales/quote-management | `QuoteDocument`, `PurchaseOrderDocument` | 견적서, 산출내역서, 발주서 |
#### 특수 상세 UI
| 모듈 | 경로 | 사용 컴포넌트 | 특수 요소 |
|------|------|--------------|----------|
| 작업지시관리 | production/work-orders | `WorkOrderDetail` | 공정 진행 단계(`ProcessSteps`) + `WorkLogModal` |
| 스크린생산 | production/screen-production | `ItemDetailClient` | 카드형 조회 (품목 상세) |
### 4.3 특수 패턴 처리 방안
```tsx
// 특수 상세 UI가 필요한 경우 → renderView prop 사용
<IntegratedDetailTemplate
mode="view"
id={params.id}
config={quoteManagementConfig}
fetchData={getQuote}
// 🔑 커스텀 상세 UI 렌더링
renderView={(data) => <QuoteDocumentView data={data} />}
/>
// 등록/수정은 통합 템플릿 사용
<IntegratedDetailTemplate
mode="create"
config={quoteManagementConfig}
onSubmit={createQuote}
// 기본 폼 UI 사용
/>
```
### 4.4 통합 방향 요약
| 구분 | 상세(view) | 등록(create) | 수정(edit) |
|------|-----------|-------------|-----------|
| 일반 패턴 | ✅ 통합 | ✅ 통합 | ✅ 통합 |
| 특수 상세 UI | ❌ 기존 유지 | ✅ 통합 | ✅ 통합 |
| 동적 폼 (품목관리) | ❌ 제외 | ❌ 제외 | ❌ 제외 |
---
## 5. 기존 Mode 패턴 분석
> 이미 mode 파라미터를 사용하는 페이지들 → **디자인만 통일** 필요
### 5.1 회계 모듈 (URL 파라미터 방식)
| 모듈 | 경로 | 컴포넌트 | mode 처리 |
|------|------|----------|----------|
| 어음관리 | accounting/bills | `BillDetail` | `?mode=edit` |
| 매출관리 | accounting/sales | `SalesDetail` | `?mode=edit` |
| 입금관리 | accounting/deposits | `DepositDetail` | `?mode=view` (조회 전용) |
| 매입관리 | accounting/purchase | `PurchaseDetail` | `?mode=view` (조회 전용) |
| 거래처관리 | accounting/vendors | `VendorDetail` | `?mode=edit` |
| 출금관리 | accounting/withdrawals | `WithdrawalDetail` | `?mode=view` (조회 전용) |
### 5.2 건설 모듈 (Props 방식)
| 모듈 | 경로 | 컴포넌트 | mode 처리 |
|------|------|----------|----------|
| 기성청구관리 | construction/billing | `ProgressBillingDetailForm` | `mode="view"` |
| 발주관리 | construction/order | `OrderDetailForm` | `mode="view"` |
| 현장관리 | construction/site | `SiteDetailForm` | `mode="view"` |
| 구조검토 | construction/structure-review | `StructureReviewDetailForm` | `mode="view"` |
| 입찰관리 | construction/bidding | `BiddingDetailForm` | `mode="view"` |
| 견적관리(건설) | construction/estimates | `EstimateDetailForm` | `mode="view"` |
| 계약관리 | construction/contract | `ContractDetailForm` | `mode="view"` |
| 이슈관리 | construction/issue | `IssueDetailForm` | `mode="view"` |
| 인수인계 | construction/handover | `HandoverReportDetailForm` | `mode="view"` |
### 5.3 통합 시 고려사항
- URL 파라미터 방식 → Props 방식으로 통일 권장
- 기존 컴포넌트 내부 로직은 유지
- IntegratedDetailTemplate이 mode를 관리하고 하위 컴포넌트에 전달
---
## 6. 통합 컴포넌트 설계
### 6.1 기본 구조
```tsx
// IntegratedDetailTemplate
interface IntegratedDetailTemplateProps {
mode: 'create' | 'edit' | 'view';
id?: string;
config: DetailPageConfig;
// API 연결 (기존 actions.ts 그대로 사용)
fetchData?: (id: string) => Promise<any>;
onSubmit?: (data: any) => Promise<any>;
onDelete?: (id: string) => Promise<any>;
// 🔑 커스텀 렌더링 (특수 케이스 & 미래 동적 폼 대비)
renderView?: (data: any) => React.ReactNode;
renderForm?: (data: any, mode: 'create' | 'edit') => React.ReactNode;
}
interface DetailPageConfig {
title: string;
backUrl: string;
fields: FieldConfig[];
permissions?: {
canEdit?: boolean;
canDelete?: boolean;
};
}
```
### 6.2 사용 예시
#### 기본 사용 (정적 폼)
```tsx
// 통합 방식 (1개 설정 + 3개 라우트)
<IntegratedDetailTemplate
mode="create"
config={popupManagementConfig}
onSubmit={createPopup} // 기존 actions.ts
/>
<IntegratedDetailTemplate
mode="view"
id={params.id}
config={popupManagementConfig}
fetchData={getPopup} // 기존 actions.ts
/>
<IntegratedDetailTemplate
mode="edit"
id={params.id}
config={popupManagementConfig}
fetchData={getPopup} // 기존 actions.ts
onSubmit={updatePopup} // 기존 actions.ts
/>
```
#### 커스텀 상세 UI
```tsx
<IntegratedDetailTemplate
mode="view"
id={params.id}
config={quoteConfig}
fetchData={getQuote}
renderView={(data) => <QuoteDocumentView data={data} />}
/>
```
#### 미래: 동적 폼 사용
```tsx
<IntegratedDetailTemplate
mode="edit"
id={params.id}
fetchData={getData}
onSubmit={updateData}
renderForm={(data, mode) => (
<DynamicForm
기준관리ID={123}
mode={mode}
initialData={data}
/>
)}
/>
```
### 6.3 핵심 원칙
- ✅ API 연결 코드 변경 없음 (actions.ts 그대로)
- ✅ 기존 기능 100% 유지
- ✅ UI/레이아웃만 통합
- ✅ 설정(config)만 다르게 전달
-`renderView`/`renderForm`으로 커스텀 렌더링 지원
- ✅ 미래 동적 폼 전환 대비 확장 가능한 구조
---
## 7. 구현 계획
### Phase 1: 프로토타입 (3개 모듈)
> 목표: 통합 템플릿 구조 검증
| 순서 | 모듈 | 복잡도 | 선정 이유 |
|------|------|--------|----------|
| 1 | settings/popup-management | 낮음 | 단순 폼 구조 |
| 2 | hr/card-management | 낮음 | 기본 CRUD |
| 3 | master-data/process-management | 낮음 | 공정 기본 정보 |
### Phase 2: 설정 모듈 확장 (4개)
```
settings/accounts
settings/permissions
board/board-management
accounting/bad-debt-collection
```
### Phase 3: HR/판매 모듈 (6개)
```
hr/employee-management
sales/client-management-sales-admin
sales/quote-management (등록/수정만, 상세는 renderView)
sales/order-management-sales (등록/수정만, 상세는 renderView)
sales/pricing-management
customer-center/qna
```
### Phase 4: 생산/출고/품질 모듈 (4개)
```
production/work-orders (등록/수정만, 상세는 renderView)
production/screen-production (등록/수정만, 상세는 renderView)
outbound/shipments
quality/inspections
```
### Phase 5: 건설 모듈 (6개)
```
construction/project/bidding/partners
construction/project/bidding/site-briefings
construction/project/contract
construction/project/issue-management
construction/order/base-info/pricing
construction/order/base-info/labor
```
### Phase 6: 나머지 패턴 (B, C, D)
- 패턴 B: mode 파라미터 처리 추가
- 패턴 C: 등록 없는 케이스 처리
- 패턴 D: 조회 전용 모드
---
## 8. 파일 구조 계획
```
src/components/templates/
├── IntegratedListTemplateV2/ # 기존 리스트 템플릿
│ ├── index.tsx
│ ├── types.ts
│ └── ...
└── IntegratedDetailTemplate/ # 새 상세 템플릿
├── index.tsx # 메인 컴포넌트
├── types.ts # 타입 정의
├── DetailHeader.tsx # 헤더 (제목, 뒤로가기, 액션버튼)
├── DetailForm.tsx # 폼 렌더링 (정적 config 기반)
├── DetailView.tsx # 조회 모드 렌더링
├── FieldRenderer.tsx # 필드 타입별 렌더링
├── GridLayout.tsx # 그리드 레이아웃 (2열, 3열)
└── hooks/
├── useDetailPage.ts # 공통 로직 훅
└── useFormHandler.ts # 폼 제출 처리 훅
```
---
## 9. 마이그레이션 체크리스트
### 모듈별 마이그레이션 단계
- [ ] 기존 컴포넌트 분석
- [ ] config 파일 작성
- [ ] 등록 페이지 마이그레이션
- [ ] 상세 페이지 마이그레이션
- [ ] 수정 페이지 마이그레이션
- [ ] 기능 테스트
- [ ] 기존 파일 정리
### Phase 1 체크리스트
- [ ] IntegratedDetailTemplate 기본 구조 구현
- [ ] settings/popup-management 마이그레이션
- [ ] hr/card-management 마이그레이션
- [ ] master-data/process-management 마이그레이션
- [ ] 템플릿 구조 검증 및 수정
---
## 10. 참고 자료
### 관련 파일
- 리스트 템플릿: `src/components/templates/IntegratedListTemplateV2/`
- 테스트 URL 목록: `claudedocs/[REF] all-pages-test-urls.md`
- 건설 테스트 URL: `claudedocs/[REF] construction-pages-test-urls.md`
- 동적 폼 참고: `src/components/items/DynamicItemForm/`
### 기존 mode 패턴 참고
- `accounting/vendors/[id]/page.tsx` → VendorDetail (mode 파라미터)
- `accounting/bills/[id]/page.tsx` → BillDetail (mode 파라미터)
- `hr/employee-management/[id]/page.tsx` → EmployeeForm (mode 파라미터)
---
## 11. 변경 이력
| 날짜 | 내용 |
|------|------|
| 2026-01-17 | 초기 계획 수립 |
| 2026-01-17 | 특이 패턴 분석 추가 (문서 모달, 특수 상세 UI) |
| 2026-01-17 | 품목관리(items) 동적 폼으로 인한 완전 제외 결정 |
| 2026-01-17 | 미래 동적 폼 전환 대비 설계 추가 (renderForm prop) |

View File

@@ -512,7 +512,26 @@ export function PermissionManagement() {
initialTotalCount={roles.length}
externalSelection={{
selectedItems,
setSelectedItems,
onToggleSelection: (id: string) => {
setSelectedItems(prev => {
const newSet = new Set(prev);
if (newSet.has(id)) {
newSet.delete(id);
} else {
newSet.add(id);
}
return newSet;
});
},
onToggleSelectAll: (ids: string[]) => {
setSelectedItems(prev => {
if (prev.size === ids.length) {
return new Set();
}
return new Set(ids);
});
},
getItemId: (item: Role) => item.id,
}}
externalTab={{
activeTab,