refactor(WEB): claudedocs 재정리 및 AuthContext/Zustand/유틸 코드 개선

- claudedocs 폴더 구조 재정리: archive/sessions, guides/migration·mobile·universal-list, refactoring 분류 - 오래된 세션 컨텍스트/체크리스트 문서 정리 (아카이브 이동 또는 삭제) - AuthContext → authStore(Zustand) 전환 시작, RootProvider 간소화 - GenericCRUDDialog 공통 다이얼로그 컴포넌트 추가 - PermissionDialog 삭제 → GenericCRUDDialog로 대체 - RankDialog/TitleDialog GenericCRUDDialog 기반으로 리팩토링 - toast-utils.ts 삭제 (미사용) - fileDownload.ts 개선, excel-download.ts 정리 - menuStore/themeStore Zustand 셀렉터 최적화 - useColumnSettings/useTableColumnStore 기능 보강 - 세금계산서/견적/작업자화면/결재 등 소규모 개선 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 17:17:13 +09:00
parent 6c3572e568
commit 07374c826c
75 changed files with 1704 additions and 1376 deletions
--- a/claudedocs/dev/[REPORT-2026-02-23]
+++ b/claudedocs/dev/[REPORT-2026-02-23]
@@ -0,0 +1,129 @@
+# E2E 잔여 버그 전달 사항
+
+**작성일**: 2026-02-23
+**근거**: `sam-hotfix/e2e/results/hotfix/HOTFIX-REPORT_dev-team_2026-02-20.md`
+
+---
+
+## 프론트엔드 수정 완료 (3건 + 1건)
+
+| Bug ID | 내용 | 수정 상태 |
+|--------|------|:---------:|
+| BUG-SORT-001 | 컬럼 정렬 미구현 (14개 페이지) | ✅ 완료 |
+| BUG-FILTER-001 | 매출관리 필터 미동작 | ✅ 완료 |
+| BUG-REDIRECT-001 | 어음/입금 등록 후 리다이렉트 | ✅ 완료 |
+| BUG-BATCH-DELETE-001 (입금) | 삭제 후 빈 페이지 표시 | ✅ 완료 (UniversalListPage 공통 수정) |
+
+---
+
+## QA팀 확인 요청 (1건)
+
+### BUG-BATCH-DELETE-001 (어음관리) — E2E 테스트 패턴 불일치
+
+**현상**: `batch-create-acc-bills` 시나리오에서 VERIFY 단계 FAIL (기대 3건, 실제 0건)
+
+**원인 분석**:
+- E2E 테스트가 `E2E_TEST_어음_{timestamp}` 패턴으로 데이터를 검색
+- 그러나 실제 어음번호는 프론트엔드에서 `E2E_TEST_EB` 접두사로 생성됨
+- **백엔드 API 확인 결과**: `BillService.php:106`에서 `bill_number`를 프론트가 보낸 그대로 저장 (변환 없음)
+- `StoreBillRequest.php` 검증: `nullable|string|max:50` — 접두사 제한 없음
+
+**결론**: API는 정상. **E2E 테스트 스크립트의 검색 패턴(`E2E_TEST_어음_`)이 실제 생성 데이터 패턴(`E2E_TEST_EB`)과 불일치**
+
+**요청 사항**:
+- E2E 테스트의 어음번호 검색 패턴을 실제 프론트엔드가 생성하는 패턴에 맞게 수정
+- 또는 프론트엔드 어음 등록 폼에서 E2E 테스트 시 사용하는 어음번호 필드값 확인
+
+---
+
+## 백엔드팀 수정 요청 (1건)
+
+### BUG-PERF-001 — 품목관리 API 성능 문제 (10초+ 지연)
+
+**현상**: 생산관리 > 품목관리 (`/api/v1/items`) 테이블 로드 10초 타임아웃
+
+**원인 분석** (sam-api 코드 확인):
+
+#### 병목 1: `getItemsWithInspectionTemplate()` — 전체 테이블 스캔 (5-8초)
+
+**파일**: `app/Services/ItemService.php` (lines 1024-1060)
+
+```php
+$templates = \DB::table('document_templates')
+    ->where('tenant_id', $tenantId)
+    ->where('is_active', true)
+    ->whereNotNull('linked_item_ids')
+    ->where(function ($q) use ($categoryCode, $categoryName) {
+        $q->where('category', $categoryCode)
+            ->orWhere('category', $categoryName)
+            ->orWhere('category', 'LIKE', "%{$categoryName}%");
+    })
+    ->get(['linked_item_ids']);  // ← limit 없이 전체 로드
+```
+
+- `linked_item_ids`는 JSON 컬럼 → 인덱스 불가
+- 페이지에 20개만 표시하는데 **모든 document_templates 로드** 후 PHP에서 수동 매칭
+- 템플릿 수가 많을수록 지연 증가
+
+#### 병목 2: N+1 쿼리 (2-3초)
+
+**파일**: `app/Services/ItemService.php` (lines 376-390)
+
+```php
+->with(['category:id,name', 'details', 'files']);
+```
+
+- `details` (hasOne): 아이템당 1쿼리 → 20개 = 20쿼리
+- `files` (hasMany + document_type 필터): 아이템당 1쿼리 → 20개 = 20쿼리
+- 합계: ~40개 추가 쿼리
+
+#### 병목 3: 누락 인덱스
+
+- `files` 테이블: `document_id` + `document_type` 복합 인덱스 없음
+- `document_templates` 테이블: `linked_item_ids` JSON 인덱스 없음
+
+**예상 총 지연**: ~9-11초 (E2E 10초 타임아웃과 일치)
+
+**수정 제안**:
+1. `getItemsWithInspectionTemplate()`에서 필요한 `item_id` 목록만 IN 조건으로 조회하도록 변경
+2. `files`, `item_details` 테이블에 적절한 인덱스 추가
+3. Eager loading 최적화 (`with` 절에 필요한 컬럼만 select)
+
+---
+
+## 백엔드팀 참고 — 신규 리그레션 2건 (API 서버 상태)
+
+리그레션 리포트(`REGRESSION-REPORT_dev-team_2026-02-20.md`)에서 발견된 신규 이슈.
+**3차 테스트에서 PASS → 4차(Pull 후) FAIL로 전환된 건**으로, 서버 상태 확인 필요.
+
+### BUG-REGRESSION-001: 입금관리 CRUD 실패 (API 500 에러)
+
+- **시나리오**: `create-delete-acc-deposit`
+- **증상**: 다수 API 500 에러 (Welfare, Calendar, TodayIssue API)
+- **API 평균 응답**: 3,574ms (통상 84ms의 42배)
+- **테이블**: 0건 로드 (데이터 로드 실패)
+
+### BUG-REGRESSION-002: 자유게시판 CRUD 실패 (API 극심한 지연)
+
+- **시나리오**: `create-delete-board`
+- **증상**: vendorId 옵션 로드 실패, 테이블 로드 5초 타임아웃
+- **API 평균 응답**: 7,752ms (통상 84ms의 92배)
+- **에러**: `Failed to load options for vendorId: TypeError: Failed to fetch`
+
+**공통 추정 원인**: Pull 이후 API 서버 불안정 (500 에러, fetch 실패 다수)
+
+---
+
+## 재검증 명령
+
+```bash
+# 전체 재검증
+node C:/Users/codeb/sam/e2e/runner/run-all.js
+
+# 버그별 개별 검증
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter pagination-sort    # BUG-SORT-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter search-filter      # BUG-FILTER-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter reload-persist     # BUG-REDIRECT-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter batch-create       # BUG-BATCH-DELETE-001 ← 프론트 일부 수정 + QA 테스트 패턴 확인
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter workflow           # BUG-PERF-001 ← 백엔드 수정 필요
+```
--- a/claudedocs/dev/[REVIEW]
+++ b/claudedocs/dev/[REVIEW]
@@ -0,0 +1,313 @@
+# MD 기반 MES/ERP 기획서 자동화 파이프라인 검토서
+
+> **작성일**: 2026-02-10
+> **작성**: 류병철 / Claude Code
+> **목적**: 회의록/인터뷰 → MD → PPTX → 프론트엔드 자동화 파이프라인의 실현 가능성 검증 및 팀 검토
+> **PoC 대상**: 주일기업 MES (자동방화셔터 시공 관리 시스템)
+
+---
+
+## 1. 배경 및 목적
+
+### 1.1 해결하려는 문제
+
+MES/ERP 프로젝트에서 반복되는 비효율:
+
+| 단계 | 현재 문제 |
+|------|----------|
+| 요구사항 수집 | 인터뷰/회의 내용이 구두로만 전달, 누락 빈번 |
+| 기획서 작성 | 수작업 PPTX 제작에 1~2주 소요 |
+| 고객 확인 | 기획서 수정 → PPTX 재작업의 반복 |
+| 개발 착수 | 기획서와 실제 구현 간 해석 차이 발생 |
+| 변경 관리 | 기획서-코드 간 동기화 안 됨 |
+
+### 1.2 제안 개념
+
+**MD 파일을 Single Source of Truth로** 사용하여, 하나의 문서에서 기획서(PPTX)와 코드(프론트엔드)를 모두 파생시키는 자동화 파이프라인.
+
+```
+인터뷰/녹음 → MD 명세서 → PPTX 기획서 (고객 확인용)
+                       → 프론트엔드 코드 (개발용)
+                       → API 구조 설계 (백엔드용)
+```
+
+---
+
+## 2. 파이프라인 설계
+
+### 2.1 전체 흐름
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1단계: 요구사항 수집                                             │
+│  인터뷰 / 현장 방문 / 녹음 → 녹취록 + 원본 자료                    │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2단계: MD 명세서 작성                                            │
+│  녹취록 + 업종 체크리스트 → 구조화된 MD 파일                        │
+│  (화면 구성, 데이터 모델, 상태 머신, API 엔드포인트 포함)             │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3단계: PPTX 기획서 자동 생성                                      │
+│  MD → Claude → python-pptx 스크립트 → 와이어프레임 PPTX             │
+│  고객과 화면 단위로 검토 및 승인                                     │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4단계: 프론트엔드 + API 구조 설계                                  │
+│  승인된 MD + 기존 컴포넌트 라이브러리 → 화면 코드 생성                │
+│  Mock API로 즉시 동작 가능한 프로토타입 구성                         │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5단계: 프로토타입 테스트                                          │
+│  Mock API 기반 프로토타입으로 고객/내부 테스트                       │
+│  피드백 → MD 역반영 → 영향 범위 파악                                │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  6단계: 실 API 연동 + 최종 검수                                    │
+│  Mock → 실제 API 교체 → 통합 테스트 → 고객 최종 검수                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 각 단계 상세
+
+#### 1단계: 요구사항 수집
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 고객 인터뷰, 현장 녹음, 기존 시스템 스크린샷, 업무 매뉴얼 |
+| 출력 | 녹취록 + 수집 자료 원본 |
+| 담당 | 기획자 / PM |
+| 도구 | 녹음 앱, 스크린샷 도구 |
+
+#### 2단계: MD 명세서 작성
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 녹취록 + 업종별 체크리스트 |
+| 출력 | 구조화된 MD 파일 (단일 파일) |
+| 담당 | 기획자 + Claude 보조 |
+| 도구 | Claude Code, 텍스트 에디터 |
+
+**MD에 포함되어야 할 섹션:**
+- 시스템 개요 (목적, 모듈 구성)
+- 역할/권한 시스템
+- 화면별 상세 명세 (레이아웃, 컴포넌트, 데이터)
+- 상태 머신 (비즈니스 흐름)
+- 데이터 모델
+- API 엔드포인트 목록
+- PPTX 레이아웃 규격 (색상, 치수, 컴포넌트 정의)
+
+#### 3단계: PPTX 자동 생성
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 2단계 MD 파일 |
+| 출력 | 와이어프레임 기반 PPTX (python-pptx) |
+| 담당 | Claude Code (자동) |
+| 도구 | Python + python-pptx |
+
+#### 4단계: 프론트엔드 + API 설계
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 승인된 MD + 기존 컴포넌트 라이브러리 |
+| 출력 | 동작하는 프론트엔드 코드 + Mock API |
+| 담당 | Claude Code + 개발자 검수 |
+| 도구 | Next.js, 기존 organisms/molecules 컴포넌트 |
+
+#### 5단계: 프로토타입 테스트
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | Mock API 기반 프로토타입 |
+| 출력 | 피드백 목록 + MD 수정 사항 |
+| 담당 | 고객 + QA + 기획자 |
+| 도구 | 브라우저, 피드백 시트 |
+
+#### 6단계: 실 API 연동 + 검수
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 테스트 완료된 프론트 + 백엔드 API |
+| 출력 | 운영 배포 가능한 시스템 |
+| 담당 | 프론트엔드 + 백엔드 개발자 |
+| 도구 | Laravel API, Next.js |
+
+---
+
+## 3. PoC 검증 결과 (주일기업 MES)
+
+### 3.1 검증 범위
+
+주일기업 MES(자동방화셔터 시공 관리 시스템)를 대상으로 **2단계 → 3단계** 구간을 검증.
+
+```
+실제 동작하는 화면 스크린샷 22장
+    → 역기획서 MD 작성 (역기획서_주일기업MES.md)
+    → python-pptx 스크립트 생성 (generate_pptx.py, 약 71KB)
+    → PPTX 기획서 자동 생성 (22슬라이드, 102KB)
+    → PPTX 내용을 독립 MD 명세서로 변환 (주일기업_MES_PPTX_명세서.md, 891줄)
+    → 새 세션에서 MD만으로 PPTX 재생성 시도 (진행 중)
+```
+
+### 3.2 검증된 사항
+
+| 검증 항목 | 결과 | 비고 |
+|-----------|------|------|
+| MD → Python 스크립트 생성 | 성공 | Claude가 MD를 읽고 python-pptx 코드 자동 생성 |
+| 와이어프레임 PPTX 출력 | 성공 | 도형 기반 UI를 22슬라이드로 렌더링 |
+| PPTX → MD 역변환 | 성공 | 891줄 명세서로 구조화 |
+| MD만으로 PPTX 재생성 (새 세션) | 진행 중 | 이전 컨텍스트 없이 MD만으로 동일 품질 생성 가능한지 검증 |
+
+### 3.3 생성된 산출물
+
+```
+~/Desktop/역기획서_스크린샷/
+├── 01~22_*.png                          # 원본 스크린샷 22장
+└── 역기획서_주일기업MES.md               # 역기획서 (439줄)
+
+~/Desktop/주일기업_MES_기획서/
+├── generate_pptx.py                      # PPTX 생성 스크립트 (71KB)
+├── 주일기업_MES_Storyboard_D1.0_260210.pptx  # 생성된 PPTX (102KB)
+├── preview/                              # 슬라이드 미리보기 PNG 17장
+└── preview_markers.py                    # 마커 미리보기 스크립트
+
+~/Desktop/주일 md to pptx test/
+└── 주일기업_MES_PPTX_명세서.md           # 독립 MD 명세서 (891줄)
+```
+
+---
+
+## 4. 비판적 분석
+
+### 4.1 강점
+
+| 강점 | 설명 |
+|------|------|
+| MD 중심 일관성 | 하나의 문서에서 기획서와 코드가 파생되므로 "기획서와 코드가 다른" 문제 원천 차단 |
+| 기획서 작업 시간 단축 | 수작업 1~2주 → MD 작성 후 자동 생성으로 수 시간 내 완료 가능 |
+| 기존 자산 재활용 | SAM 프로젝트의 organisms/molecules 컴포넌트를 그대로 활용 |
+| 반복 가능한 프로세스 | 동일 파이프라인을 다른 고객사에도 적용 가능 |
+| Mock-first 개발 | API 완성 전 프로토타입으로 빠른 피드백 가능 |
+
+### 4.2 리스크 및 대응 방안
+
+#### 리스크 1: 1→2단계 정보 손실 (심각도: 높음)
+
+**문제**: 인터뷰/녹음에서 MD로 변환할 때 정보 손실이 가장 큼. MES/ERP 현장에는 "당연히 그렇게 하는" 암묵적 프로세스가 많아 인터뷰에서 언급되지 않는 경우가 빈번함.
+
+**예시**: "납기일 변경 시 관련 공정 전체 재계산", "특정 조건에서만 나타나는 승인 단계" 등
+
+**대응 방안**:
+- 업종별 필수 프로세스 체크리스트 사전 준비
+- 인터뷰 후 체크리스트 대조 → 누락 항목 2차 확인
+- MD 초안을 고객에게 텍스트 레벨로 먼저 검토받는 단계 추가 (2.5단계)
+
+#### 리스크 2: 고객의 와이어프레임 이해도 (심각도: 중간)
+
+**문제**: MES/ERP 사용자는 대부분 비개발자. 정적 와이어프레임만으로는 동적 흐름(상태 전환, 조건부 UI)을 파악하지 못하고, "확인했습니다" 후 프로토타입을 보고 "이게 아닌데요"가 발생.
+
+**대응 방안**:
+- PPTX에 상태 머신, 시나리오 흐름을 명시 (PoC에서 이미 적용)
+- 3단계와 5단계를 가까이 배치하여 클릭 가능한 프로토타입으로 보완
+- 주요 흐름은 슬라이드 여러 장으로 상태 변화를 시각적으로 나열
+
+#### 리스크 3: API 설계 시점 (심각도: 중간)
+
+**문제**: API 구조 설계가 4단계에서 시작되면, 백엔드 제약사항(기존 DB 스키마, 외부 연동)이 프론트 설계를 뒤집을 수 있음.
+
+**대응 방안**:
+- 2단계 MD에 데이터 모델 + API 엔드포인트 목록을 포함 (PoC에서 이미 적용)
+- 백엔드 개발자가 2단계 MD 리뷰에 참여
+- API 제약사항을 3단계 이전에 확인
+
+#### 리스크 4: 변경의 역전파 (심각도: 중간)
+
+**문제**: 5단계 테스트에서 변경 요청 발생 시, MD → PPTX → 코드 전체가 연쇄 수정되어야 함. 현재 파이프라인은 단방향이라 역방향 반영 체계가 없음.
+
+**대응 방안**:
+- MD 버전 관리 (Git)
+- 변경 요청 시 MD 먼저 수정 → PPTX/코드 재생성 순서 준수
+- 변경 영향 범위를 MD 섹션 단위로 추적
+
+#### 리스크 5: 동시 다중 프로젝트 (심각도: 낮음, 현재)
+
+**문제**: 1~2단계(인터뷰 → MD)는 자동화가 어려워, 동시에 3~5개 고객 프로젝트를 진행하면 병목 발생.
+
+**대응 방안**:
+- 업종별 MD 템플릿 사전 구축으로 2단계 작업량 감소
+- 3단계 이후는 자동화 비율이 높으므로 병목은 1~2단계에 집중 → 기획 인력 확보
+
+---
+
+## 5. 개선된 파이프라인 (제안)
+
+기존 6단계에 검증 게이트를 추가한 버전:
+
+```
+1단계  인터뷰/녹음 → 녹취록 + 원본 자료
+          │
+2단계  녹취록 + 업종 체크리스트 → MD 명세서 (데이터 모델 + API 포함)
+          │
+  ┌───── 2.5단계  고객 + 백엔드 개발자 MD 텍스트 리뷰 ──────┐
+  │       (화면 만들기 전에 내용의 정확성 먼저 확인)            │
+  │       승인 ✓                    수정 요청 → 2단계로 복귀   │
+  └───────┬───────────────────────────────────────────────────┘
+          │
+3단계  MD → PPTX 와이어프레임 자동 생성
+          │
+  ┌───── 3.5단계  고객 화면 검토 (서명) ──────────────────────┐
+  │       승인 ✓                    수정 요청 → MD 수정 → 재생성│
+  └───────┬───────────────────────────────────────────────────┘
+          │
+4단계  MD + 기존 컴포넌트 → 프론트엔드 + Mock API 프로토타입
+          │
+5단계  프로토타입 테스트 (고객 + 내부)
+          │
+  ┌───── 5.5단계  피드백 반영 ────────────────────────────────┐
+  │       피드백 → MD 수정 → 영향 범위 확인 → 코드 반영         │
+  │       완료 ✓                                              │
+  └───────┬───────────────────────────────────────────────────┘
+          │
+6단계  Mock → 실 API 교체 → 통합 테스트 → 최종 검수
+```
+
+---
+
+## 6. 필요 사전 작업
+
+파이프라인을 실전에 적용하기 위해 준비해야 할 것:
+
+| 항목 | 설명 | 우선순위 |
+|------|------|----------|
+| MD 템플릿 표준화 | PPTX 레이아웃 규격, 색상, 컴포넌트 정의를 포함한 MD 작성 가이드 | 높음 |
+| 업종별 체크리스트 | MES/ERP 업종별 필수 프로세스 목록 (제조, 시공, 물류 등) | 높음 |
+| 컴포넌트 라이브러리 정리 | 4단계에서 활용할 organisms/molecules 카탈로그 | 중간 |
+| Mock API 규격 | 프론트 프로토타입에서 사용할 Mock 데이터 구조 표준 | 중간 |
+| 변경 관리 프로세스 | MD 수정 → 영향 범위 파악 → 재생성 절차 문서화 | 낮음 (초기) |
+
+---
+
+## 7. 검토 요청 사항
+
+팀원들에게 확인받고 싶은 사항:
+
+1. **기획자**: 1→2단계에서 인터뷰 내용을 MD로 구조화하는 과정이 현실적인가? 어떤 보조 도구가 필요한가?
+2. **프론트엔드 개발자**: 4단계에서 MD 명세서만으로 화면 구현이 가능한 수준인가? 기존 컴포넌트 재활용 범위는?
+3. **백엔드 개발자**: 2단계 MD에 포함된 데이터 모델/API 명세가 백엔드 설계에 충분한가? 추가로 필요한 정보는?
+4. **PM**: 이 파이프라인의 단계별 소요 시간 예측이 가능한가? 고객 커뮤니케이션 포인트는 적절한가?
+
+---
+
+## 8. 다음 단계
+
+- [ ] MD만으로 PPTX 재생성 PoC 완료 (현재 진행 중)
+- [ ] 팀 검토 미팅 일정 확정
+- [ ] 검토 결과 반영하여 파이프라인 확정
+- [ ] MD 템플릿 표준 초안 작성
+- [ ] 실 고객 프로젝트 파일럿 적용 대상 선정