From f456e7bee00a38c0fe52ce512bb17388988d8e0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9C=A0=EB=B3=91=EC=B2=A0?= Date: Fri, 6 Feb 2026 17:52:02 +0900 Subject: [PATCH] =?UTF-8?q?chore(WEB):=20=EA=B2=AC=EC=A0=81=20=EC=95=A1?= =?UTF-8?q?=EC=85=98=20=EC=A0=95=EB=A6=AC=20=EB=B0=8F=20=EC=95=84=ED=82=A4?= =?UTF-8?q?=ED=85=8D=EC=B2=98=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - quotes/actions.ts 중복 코드 제거 및 간소화 - quotes/types.ts 타입 확장 - claudedocs/_index.md 업데이트 - 멀티테넌시 최적화 로드맵 문서 추가 - 리팩토링 로드맵 문서 추가 Co-Authored-By: Claude Opus 4.5 --- claudedocs/_index.md | 8 +- ...-06] multi-tenancy-optimization-roadmap.md | 666 ++++++++++++++++++ .../[PLAN-2026-02-06] refactoring-roadmap.md | 389 ++++++++++ src/components/quotes/actions.ts | 33 +- src/components/quotes/types.ts | 9 +- 5 files changed, 1071 insertions(+), 34 deletions(-) create mode 100644 claudedocs/architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md create mode 100644 claudedocs/architecture/[PLAN-2026-02-06] refactoring-roadmap.md diff --git a/claudedocs/_index.md b/claudedocs/_index.md index e66f8d7a..e73069c7 100644 --- a/claudedocs/_index.md +++ b/claudedocs/_index.md @@ -179,10 +179,12 @@ claudedocs/ | 파일 | 설명 | |------|------| -| `[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | 🔴 **NEW** - masterDataStore 캐시 테넌트 격리 수정 (page_config 키에 tenantId 추가, dead code 해소) | +| `[PLAN-2026-02-06] refactoring-roadmap.md` | 🔴 **NEW** - 리팩토링 종합 로드맵 (5 Phase, 공통훅~성능최적화, **전부 프론트 단독**) | +| `[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md` | 🔴 **NEW** - 멀티테넌시 공통화/최적화 종합 로드맵 (8 Phase, API 테넌트 주입~라우팅) | +| `[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | masterDataStore 캐시 테넌트 격리 수정 (page_config 키에 tenantId 추가, dead code 해소) | | `[PLAN-2025-12-29] dynamic-menu-refresh.md` | 동적 메뉴 갱신 시스템 (1단계: 폴링, 2단계: SSE) | -| `multi-tenancy-implementation.md` | 멀티테넌시 구현 | -| `multi-tenancy-test-guide.md` | 멀티테넌시 테스트 | +| `multi-tenancy-implementation.md` | ✅ **Phase 1-2 완료** - 초기 멀티테넌시 구현 (AuthContext, TenantAwareCache) | +| `multi-tenancy-test-guide.md` | 멀티테넌시 캐시 격리 테스트 가이드 | | `architecture-integration-risks.md` | 통합 리스크 | | `browser-support-policy.md` | 브라우저 지원 정책 | | `ssr-hydration-fix.md` | SSR 하이드레이션 수정 | diff --git a/claudedocs/architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md b/claudedocs/architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md new file mode 100644 index 00000000..e6c9c41b --- /dev/null +++ b/claudedocs/architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md @@ -0,0 +1,666 @@ +# 멀티테넌시 공통화 및 최적화 로드맵 + +**작성일**: 2026-02-06 +**목적**: 전체 프로젝트 멀티테넌시 준비 상태 점검 및 공통화/최적화 계획 수립 +**이전 문서**: `[REF-2025-11-19] multi-tenancy-implementation.md` (Phase 1-2 완료) + +--- + +## 현재 상태 요약 (2026-02-06 기준) + +### 완료된 항목 (이전 로드맵 Phase 1-2) + +| 항목 | 상태 | 파일 | +|------|------|------| +| User 타입에 Tenant 객체 포함 | ✅ 완료 | `src/contexts/AuthContext.tsx` | +| Tenant 인터페이스 정의 (id, company_name 등) | ✅ 완료 | `src/contexts/AuthContext.tsx` | +| TenantAwareCache 유틸리티 | ✅ 완료 | `src/lib/cache/TenantAwareCache.ts` | +| 테넌트 전환 감지 + 캐시 클리어 | ✅ 완료 | `src/contexts/AuthContext.tsx` | +| masterDataStore 테넌트 스코프 캐시 키 | ✅ 완료 | `src/stores/masterDataStore.ts` | +| sessionStorage/localStorage 테넌트 격리 | ✅ 완료 | `mes-{tenantId}-{key}` 패턴 | + +### 미완료 / 개선 필요 항목 + +| 영역 | 우선순위 | 현재 상태 | +|------|----------|-----------| +| API 프록시에 테넌트 컨텍스트 전달 | 🔴 | X-Tenant-ID 헤더 없음 | +| Server Actions 테넌트 인식 | 🔴 | 70+ actions.ts에 테넌트 미포함 | +| 포매터/유틸리티 다국어/다통화 | 🔴 | 한국어 하드코딩 | +| 브랜딩 동적화 (로고, 앱이름) | 🟡 | "SAM", sam-logo.png 하드코딩 | +| 상수/공휴일 외부화 | 🟡 | 한국 공휴일 하드코딩 | +| localStorage 직접 사용 잔재 | 🟡 | TenantAwareCache 미사용 곳 존재 | +| tenantId 타입 불일치 | 🟡 | string vs number 혼재 | +| 테넌트 라우팅 | 🟢 | 현재 없음 (필요 시 추가) | +| TenantContext Provider | 🟢 | 테넌트 설정 전용 Context 없음 | + +--- + +## 작업 영역 구분: 프론트 단독 vs 백엔드 협의 + +### 선행 확인 사항 + +> **핵심 질문**: "백엔드가 이미 JWT 토큰 안의 tenant_id로 데이터를 필터링하고 있는가?" +> +> - **Yes** → 프론트에서 별도 X-Tenant-ID 안 보내도 됨. Phase 1은 불필요하고 프론트 단독 Phase부터 진행 +> - **No** → 백엔드도 같이 수정 필요. Phase 1이 최우선 + +### 프론트 단독 가능 (백엔드 수정 불필요) + +| Phase | 작업 | 이유 | +|-------|------|------| +| **3** | 포매터 다국어/다통화 전환 | `formatAmount()`, `formatDate()` 등 프론트 유틸리티 내부 수정. 기본값을 한국어로 유지하면 하위 호환 | +| **6** | localStorage 잔재 정리 + tenantId 타입 통일 | 프론트 코드 정리. TenantAwareCache 미사용 곳 마이그레이션, `string` → `number` 통일 | +| **8** | 테넌트 라우팅 (필요 시) | Next.js App Router 구조 변경. 순수 프론트 라우팅 | + +> **즉시 착수 가능**: 백엔드 협의 결과를 기다리지 않고 바로 시작할 수 있음 + +### 백엔드 협의 필요 (프론트 + 백엔드 동시 수정) + +| Phase | 작업 | 백엔드 필요 이유 | +|-------|------|-----------------| +| **1** | API 테넌트 컨텍스트 주입 | 프론트에서 `X-Tenant-ID` 헤더를 보내도, **백엔드가 읽고 필터링**해줘야 의미 있음. 안 읽으면 보내봤자 무용지물 | +| **2** | Server Actions 마이그레이션 | Phase 1에 종속. 백엔드가 헤더 or URL로 테넌트를 구분 안 하면 프론트만 바꿔도 소용없음 | +| **4** | 브랜딩 동적화 | 테넌트별 로고/앱이름을 **어디서 가져오나?** → 백엔드 API 필요 (`GET /api/v1/tenant/config`) | +| **5** | 상수/공휴일 외부화 | 공휴일 데이터를 **DB에서 서빙**해야 함 → 백엔드 API 필요 (`GET /api/v1/holidays?year=2026`) | +| **7** | TenantConfigService | 테넌트 설정 통합 API 필요 → branding + regional + features를 한 번에 가져오는 엔드포인트 | + +### 추천 진행 순서 + +``` +[즉시 시작 - 프론트 단독] + Phase 3 (포매터) + Phase 6 (localStorage/타입) 병렬 진행 + +[백엔드 협의 후 시작] + Phase 1 (API 헤더) → Phase 2 (Actions) + +[백엔드 API 준비 후 시작] + Phase 7 (TenantConfigService) → Phase 4 (브랜딩) + Phase 5 (상수) +``` + +--- + +## Phase 1: API 레이어 테넌트 컨텍스트 주입 🔴 `백엔드 협의 필요` + +> **목표**: 모든 백엔드 API 호출에 테넌트 식별 정보가 전달되도록 함 +> **예상**: 3-5일 + +### 1-1. 로그인 시 tenant_id 쿠키 추가 + +**파일**: `src/app/api/auth/login/route.ts` + +**현재**: access_token, refresh_token 쿠키만 설정 +**변경**: tenant_id 쿠키 추가 (HttpOnly, API 프록시에서 읽기용) + +```typescript +// 로그인 성공 후 추가 +const tenantCookie = [ + `tenant_id=${data.tenant.id}`, + 'HttpOnly', + ...(isProduction ? ['Secure'] : []), + 'SameSite=Lax', + 'Path=/', + `Max-Age=${data.expires_in || 7200}`, +].join('; '); +response.headers.append('Set-Cookie', tenantCookie); +``` + +### 1-2. API 프록시에 X-Tenant-ID 헤더 추가 + +**파일**: `src/app/api/proxy/[...path]/route.ts` + +**현재**: +```typescript +const headers = { + 'Accept': 'application/json', + 'X-API-KEY': process.env.API_KEY || '', + 'Authorization': `Bearer ${token}`, +}; +``` + +**변경**: +```typescript +const tenantId = request.cookies.get('tenant_id')?.value; +const headers = { + 'Accept': 'application/json', + 'X-API-KEY': process.env.API_KEY || '', + 'Authorization': `Bearer ${token}`, + ...(tenantId && { 'X-Tenant-ID': tenantId }), +}; +``` + +### 1-3. serverFetch 래퍼에 테넌트 헤더 추가 + +**파일**: `src/lib/api/fetch-wrapper.ts` + +**현재**: Authorization 헤더만 전달 +**변경**: tenant_id 쿠키 읽어서 X-Tenant-ID 헤더 자동 추가 + +```typescript +export async function serverFetch(url: string, options?: RequestInit) { + const cookieStore = await cookies(); + const token = cookieStore.get('access_token')?.value; + const tenantId = cookieStore.get('tenant_id')?.value; + + const headers = { + ...options?.headers, + 'Authorization': `Bearer ${token}`, + ...(tenantId && { 'X-Tenant-ID': tenantId }), + }; + // ... +} +``` + +### 1-4. ApiClient 클래스에 테넌트 지원 + +**파일**: `src/lib/api/client.ts` + +**변경**: `getAuthHeaders()`에 X-Tenant-ID 포함 + +### 체크리스트 + +``` +- [ ] login/route.ts에 tenant_id 쿠키 Set-Cookie 추가 +- [ ] proxy/[...path]/route.ts에서 tenant_id 쿠키 읽기 + X-Tenant-ID 헤더 전달 +- [ ] fetch-wrapper.ts serverFetch에 X-Tenant-ID 자동 추가 +- [ ] client.ts ApiClient에 tenantId 옵션 추가 +- [ ] authenticated-fetch.ts에도 테넌트 헤더 전파 확인 +- [ ] 로그아웃 시 tenant_id 쿠키 삭제 확인 +- [ ] 토큰 갱신 시 tenant_id 쿠키 유지 확인 +- [ ] 백엔드와 X-Tenant-ID 헤더 수신 방식 협의 +``` + +--- + +## Phase 2: Server Actions 점진적 마이그레이션 🔴 `백엔드 협의 필요` + +> **목표**: 70+ actions.ts에서 테넌트 컨텍스트가 자동 전달되도록 함 +> **예상**: 1-2주 (Phase 1 완료 후 자동 적용되는 부분 다수) + +### 2-1. 현재 패턴 분석 + +대부분의 actions.ts가 이 패턴을 따름: +```typescript +const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/endpoint`; +const { response, error } = await serverFetch(url, { method: 'GET' }); +``` + +### 2-2. 자동 적용 범위 (Phase 1 완료 시) + +Phase 1에서 `serverFetch`에 X-Tenant-ID를 자동 추가하면, **기존 actions.ts 대부분은 수정 없이** 테넌트 헤더가 전달됨. + +### 2-3. 수동 확인 필요 케이스 + +`serverFetch`를 사용하지 않고 직접 `fetch()`를 호출하는 곳: +```bash +# 검색 대상 +grep -r "fetch(" src/components/*/actions.ts --include="*.ts" | grep -v serverFetch +``` + +### 2-4. 선택적 URL 테넌트 프리픽스 + +백엔드가 URL 경로에 테넌트를 요구하는 경우만: +```typescript +// 필요한 경우에만 적용 +function buildTenantUrl(endpoint: string, tenantId?: string): string { + if (endpoint.startsWith('http')) return endpoint; // 레거시 호환 + const base = process.env.NEXT_PUBLIC_API_URL; + return tenantId + ? `${base}/api/v1/tenant/${tenantId}/${endpoint}` + : `${base}/api/v1/${endpoint}`; +} +``` + +### 체크리스트 + +``` +- [ ] serverFetch 사용하지 않는 actions.ts 목록 확인 +- [ ] 직접 fetch() 호출하는 곳 serverFetch로 마이그레이션 +- [ ] 백엔드와 URL 패턴 vs 헤더 패턴 최종 협의 +- [ ] 고빈도 도메인 우선 검증: clients, items, production, sales +- [ ] 에러 시 테넌트 컨텍스트 누락 로그 추가 +``` + +--- + +## Phase 3: 포매터 & 유틸리티 테넌트 설정 기반 전환 🔴 `프론트 단독 가능` + +> **목표**: 한국어 하드코딩된 포매터를 테넌트 설정 기반으로 변경 +> **예상**: 3-5일 + +### 3-1. 영향받는 파일 목록 + +| 파일 | 함수 | 하드코딩 내용 | +|------|------|---------------| +| `src/utils/formatAmount.ts` | `formatAmount()` | "원", "만원" | +| `src/utils/formatAmount.ts` | `formatKoreanAmount()` | "억", "만" | +| `src/lib/formatters.ts` | `formatBusinessNumber()` | 한국 사업자번호 (XXX-XX-XXXXX) | +| `src/lib/formatters.ts` | `formatPhoneNumber()` | 한국 전화 (02-, 010-) | +| `src/utils/date.ts` | `formatDate()` | `'ko-KR'` 로케일 | + +### 3-2. TenantRegionalConfig 인터페이스 + +```typescript +// src/types/tenant-config.ts (신규) +export interface TenantRegionalConfig { + locale: string; // 'ko-KR' | 'en-US' | 'ja-JP' + timezone: string; // 'Asia/Seoul' | 'America/New_York' + currency: { + code: string; // 'KRW' | 'USD' | 'JPY' + symbol: string; // '원' | '$' | '¥' + locale: string; // Intl.NumberFormat 로케일 + largeUnitName?: string; // '만' (한국 전용) + largeUnitValue?: number; // 10000 + }; + phone: { + countryCode: string; // '+82' | '+1' | '+81' + format: string; // 'XXX-XXXX-XXXX' + }; + businessNumber: { + format: string; // 'XXX-XX-XXXXX' + label: string; // '사업자번호' | 'Business No.' | '法人番号' + }; +} +``` + +### 3-3. 마이그레이션 접근 (하위 호환) + +기존 함수를 바로 변경하지 않고, 오버로드 + 기본값 패턴 적용: + +```typescript +// 기존 호출 코드를 깨지 않는 방식 +export function formatAmount(amount: number, config?: TenantCurrencyConfig): string { + const cfg = config ?? DEFAULT_KR_CURRENCY_CONFIG; // 기본값: 한국 + // ... 테넌트 설정 기반 포매팅 +} +``` + +### 3-4. 기존 공통화 작업 참조 + +**이미 작성된 관련 문서**: +- `claudedocs/[IMPL-2026-02-05] formatter-commonization-plan.md` +- `claudedocs/[ANALYSIS-2026-01-20] 공통화-현황-분석.md` + +이 문서들의 포매터 공통화 계획과 병합하여 진행. + +### 체크리스트 + +``` +- [ ] TenantRegionalConfig 인터페이스 정의 +- [ ] DEFAULT_KR_CONFIG 기본값 생성 (하위 호환) +- [ ] formatAmount() 테넌트 설정 지원 추가 +- [ ] formatDate() 테넌트 로케일 지원 추가 +- [ ] formatBusinessNumber() 포맷 설정 지원 추가 +- [ ] formatPhoneNumber() 국가 코드 지원 추가 +- [ ] 기존 호출 코드 깨지지 않는지 검증 +- [ ] formatter-commonization-plan.md와 통합 +``` + +--- + +## Phase 4: 브랜딩 동적화 🟡 `백엔드 API 필요` + +> **목표**: 하드코딩된 회사명/로고를 테넌트 설정 기반으로 변경 +> **예상**: 2-3일 + +### 4-1. 영향받는 파일 목록 + +| 파일 | 하드코딩 | 변경 방향 | +|------|----------|-----------| +| `src/layouts/AuthenticatedLayout.tsx` | `APP_NAME = 'SAM'` | `tenant.company_name` 또는 테넌트 설정 | +| `src/layouts/AuthenticatedLayout.tsx` | `` | 테넌트별 로고 URL | +| `src/layouts/AuthenticatedLayout.tsx` | `MOCK_COMPANIES` 배열 | `user.tenant.other_tenants` 연동 | +| `src/app/[locale]/layout.tsx` | `APP_TITLE = 'SAM - 내 손안의 대시보드'` | 테넌트 설정 기반 | +| `src/app/[locale]/layout.tsx` | SEO 메타데이터 | 테넌트별 (단, 폐쇄형이므로 낮은 우선순위) | + +### 4-2. 테넌트 브랜딩 설정 구조 + +```typescript +// src/types/tenant-config.ts에 추가 +export interface TenantBrandingConfig { + appName: string; // 'SAM' | '주일 MES' | 커스텀 + appSubtitle?: string; // 'Smart Automation Management' + logoUrl: string; // '/sam-logo.png' | '/tenants/282/logo.png' + faviconUrl?: string; + primaryColor?: string; // 테마 주색상 + loginBackground?: string; // 로그인 페이지 배경 +} +``` + +### 4-3. 적용 방식 + +```typescript +// AuthenticatedLayout.tsx 내부 +const { currentUser } = useAuth(); +const branding = currentUser?.tenant?.branding ?? DEFAULT_BRANDING; + +// 로고 +{branding.appName} + +// 앱 이름 +

{branding.appName}

+``` + +### 4-4. MOCK_COMPANIES → other_tenants 연동 + +**현재**: 하드코딩 목업 +```typescript +const MOCK_COMPANIES = [ + { id: 'all', name: '전체' }, + { id: 'company1', name: '(주)삼성건설' }, + ... +]; +``` + +**변경**: 실제 테넌트 데이터 연동 +```typescript +const tenantOptions = useMemo(() => { + const current = currentUser?.tenant; + const others = current?.other_tenants ?? []; + return [current, ...others].filter(Boolean); +}, [currentUser]); +``` + +### 체크리스트 + +``` +- [ ] TenantBrandingConfig 인터페이스 정의 +- [ ] DEFAULT_BRANDING 기본값 (현재 SAM 설정) +- [ ] AuthenticatedLayout 로고/앱이름 동적화 +- [ ] MOCK_COMPANIES를 other_tenants 기반으로 교체 +- [ ] 로그인 페이지 브랜딩 동적화 +- [ ] favicon 동적 변경 (선택) +- [ ] 테넌트별 로고 파일 서빙 방식 결정 (public/ vs API) +``` + +--- + +## Phase 5: 상수 & 비즈니스 로직 외부화 🟡 `백엔드 API 필요` + +> **목표**: 한국 특화 상수를 테넌트/국가별 설정으로 외부화 +> **예상**: 3-5일 + +### 5-1. 영향받는 항목 + +| 항목 | 파일 | 현재 | 변경 | +|------|------|------|------| +| 공휴일 | `src/constants/calendarEvents.ts` | 한국 공휴일 하드코딩 | DB/API 기반 | +| 프로세스 타입 | `src/types/process.ts` | "생산", "검사" 등 | i18n 라벨 | +| 상태 라벨 | `src/lib/utils/status-config.ts` | "대기", "완료" 등 | i18n 라벨 | +| 품목 타입 | `src/types/item.ts` | "제품", "부품" 등 | i18n 라벨 | +| 근무일 | 관련 컴포넌트 | 월-금 하드코딩 | 테넌트 설정 | + +### 5-2. 외부화 전략 + +**공휴일**: 백엔드 API로 이동 (테넌트별 국가 설정에 따라 반환) +```typescript +// AS-IS: 하드코딩 +const HOLIDAYS_2026 = [ + { date: '2026-01-01', name: '신정', type: 'holiday' }, + ... +]; + +// TO-BE: API 호출 +const holidays = await getHolidays(tenantId, year); +``` + +**라벨/상태**: next-intl 다국어 시스템 활용 (이미 ko/en/ja 구조 있음) +```typescript +// AS-IS +const statusLabels = { pending: '대기', completed: '완료' }; + +// TO-BE +const t = useTranslations('status'); +const label = t('pending'); // 로케일에 따라 자동 변환 +``` + +### 체크리스트 + +``` +- [ ] calendarEvents.ts 공휴일 데이터 → API 엔드포인트로 이동 +- [ ] 프로세스 타입 라벨 → messages/ko.json, en.json, ja.json으로 이동 +- [ ] 상태 라벨 → i18n 키로 변환 +- [ ] 품목 타입 라벨 → i18n 키로 변환 +- [ ] 근무일 설정 → 테넌트 config로 이동 +- [ ] 백엔드에 공휴일 API 요청 +``` + +--- + +## Phase 6: localStorage 잔재 정리 & 타입 통일 🟡 `프론트 단독 가능` + +> **목표**: TenantAwareCache 미사용 곳 정리 + tenantId 타입 통일 +> **예상**: 2-3일 + +### 6-1. localStorage 직접 사용 감사 + +```bash +# 검색 대상 +grep -r "localStorage\.\(setItem\|getItem\)" src/ --include="*.ts" --include="*.tsx" +``` + +**알려진 비-테넌트-스코프 키**: +- `mes-users` → 사용자 목록 (테넌트 스코프 필요 여부 검토) +- `mes-currentUser` → 현재 사용자 (로그인 상태이므로 테넌트 무관) +- 기타 직접 사용 곳 → TenantAwareCache 또는 테넌트 프리픽스 적용 + +### 6-2. tenantId 타입 통일 + +**현재 상황**: +- `User.tenant.id` → `number` (AuthContext) +- `PageConfig.tenantId` → `string` (masterDataStore) +- TenantAwareCache → `number` + +**통일**: `number`로 표준화 (백엔드 응답 기준) + +```typescript +// 수정 대상 찾기 +grep -r "tenantId.*string" src/ --include="*.ts" +``` + +### 체크리스트 + +``` +- [ ] localStorage 직접 사용 전수 조사 +- [ ] TenantAwareCache로 마이그레이션 가능한 곳 목록화 +- [ ] 테넌트 스코프 불필요한 곳 명시 (mes-currentUser 등) +- [ ] tenantId: string → number 통일 +- [ ] PageConfig 타입 수정 +- [ ] 관련 타입 참조 전부 업데이트 +``` + +--- + +## Phase 7: TenantConfigService & TenantContext (선택) 🟢 `백엔드 API 필요` + +> **목표**: 테넌트 설정을 한곳에서 관리하는 서비스 레이어 +> **예상**: 3-5일 (Phase 3-5 진행 중 필요에 따라) + +### 7-1. TenantConfigService + +```typescript +// src/services/TenantConfigService.ts (신규) +export interface TenantConfiguration { + tenantId: number; + branding: TenantBrandingConfig; + regional: TenantRegionalConfig; + features: { + enabledModules: string[]; + customFields?: Record; + }; + calendar: { + workingDays: number[]; // [1,2,3,4,5] = 월-금 + holidays: HolidayEntry[]; + }; +} + +class TenantConfigService { + private cache: Map = new Map(); + + async getConfig(tenantId: number): Promise { + if (this.cache.has(tenantId)) return this.cache.get(tenantId)!; + const config = await this.fetchFromApi(tenantId); + this.cache.set(tenantId, config); + return config; + } +} +``` + +### 7-2. TenantContext Provider + +```typescript +// src/contexts/TenantContext.tsx (신규) +export function TenantProvider({ children }: { children: ReactNode }) { + const { currentUser } = useAuth(); + const [config, setConfig] = useState(); + + useEffect(() => { + if (currentUser?.tenant?.id) { + tenantConfigService.getConfig(currentUser.tenant.id) + .then(setConfig); + } + }, [currentUser?.tenant?.id]); + + return ( + + {children} + + ); +} + +// 사용 +const tenantConfig = useTenantConfig(); +const currencySymbol = tenantConfig.regional.currency.symbol; +``` + +### 체크리스트 + +``` +- [ ] TenantConfiguration 통합 인터페이스 설계 +- [ ] TenantConfigService 구현 (캐시 + API 호출) +- [ ] TenantContext Provider 구현 +- [ ] useTenantConfig() 훅 구현 +- [ ] Protected Layout에 TenantProvider 추가 +- [ ] 기존 코드에서 점진적 마이그레이션 +``` + +--- + +## Phase 8: 테넌트 라우팅 (필요 시) 🟢 `프론트 단독 가능` + +> **목표**: URL에 테넌트 식별자 포함 (필요한 경우에만) +> **예상**: 1주+ + +### 현재 라우팅 +``` +/[locale]/(protected)/dashboard +``` + +### 옵션 A: 경로 기반 (권장 - 필요 시) +``` +/[tenant]/[locale]/(protected)/dashboard +/acme/ko/dashboard +``` + +### 옵션 B: 서브도메인 기반 +``` +acme.sam.com/ko/dashboard +``` + +### 옵션 C: 현재 유지 (인증 기반만) +``` +/[locale]/(protected)/dashboard ← 테넌트는 JWT/쿠키로만 식별 +``` + +**결정**: 현재는 **옵션 C 유지**. 다중 테넌트 URL 분리가 필요해지면 옵션 A 도입. + +--- + +## 백엔드 협의 사항 + +### 필수 협의 (Phase 1 시작 전) + +| 항목 | 질문 | 결정 사항 | +|------|------|-----------| +| 테넌트 식별 방식 | `X-Tenant-ID` 헤더 vs URL 경로 vs JWT만? | TBD | +| X-Tenant-ID 수신 | 백엔드가 이 헤더를 읽고 필터링하는지? | TBD | +| JWT 내 tenant_id | 토큰에 tenant_id가 포함되어 있는지? | TBD | +| 공휴일 API | `GET /api/v1/holidays?year=2026` 지원? | TBD | +| 테넌트 설정 API | `GET /api/v1/tenant/config` 지원? | TBD | + +### 선택 협의 (Phase 4-5 시작 전) + +| 항목 | 질문 | 결정 사항 | +|------|------|-----------| +| 테넌트 로고 | 로고 URL을 어디서 제공? (API vs 파일서버) | TBD | +| 브랜딩 설정 | 테넌트별 앱이름/테마 API 제공 가능? | TBD | +| 다국어 라벨 | 백엔드 코드 라벨이 다국어 지원? | TBD | + +--- + +## 실행 우선순위 요약 + +``` +[프론트 단독] Phase 3: 포매터 테넌트 설정 기반 🔴 3-5일 ← 즉시 시작 가능 +[프론트 단독] Phase 6: localStorage 정리/타입 통일 🟡 2-3일 ← 즉시 시작 가능 +[프론트 단독] Phase 8: 테넌트 라우팅 🟢 필요시 ← 당분간 불필요 + +[백엔드 협의] Phase 1: API 테넌트 컨텍스트 주입 🔴 3-5일 ← 백엔드 확인 후 +[백엔드 협의] Phase 2: Server Actions 마이그레이션 🔴 1-2주 ← Phase 1 후 자동 적용 범위 큼 + +[백엔드 API] Phase 4: 브랜딩 동적화 🟡 2-3일 ← 테넌트 설정 API 필요 +[백엔드 API] Phase 5: 상수/공휴일 외부화 🟡 3-5일 ← 공휴일 API 필요 +[백엔드 API] Phase 7: TenantConfigService 🟢 3-5일 ← 통합 설정 API 필요 +``` + +### 병렬 진행 가능 조합 + +``` +[즉시 시작 - 프론트 단독] +├─ Phase 3 (포매터) ─────────→ 독립 완료 +└─ Phase 6 (localStorage) ──→ 독립 완료 + +[백엔드 협의 후 - 프론트+백엔드] +└─ Phase 1 (API 헤더) ──────→ Phase 2 (Actions 자동 적용) + +[백엔드 API 준비 후 - 프론트+백엔드] +└─ Phase 7 (TenantConfig) ──→ Phase 4 (브랜딩) + Phase 5 (상수) +``` + +--- + +## 위험 요소 & 대응 + +| 위험 | 확률 | 영향 | 대응 | +|------|------|------|------| +| 70+ actions.ts 수동 마이그레이션 | 높음 | 중간 | serverFetch 자동 주입으로 대부분 해결 | +| 백엔드 X-Tenant-ID 미지원 | 중간 | 높음 | Phase 1 시작 전 백엔드 팀 협의 필수 | +| 포매터 변경 시 기존 UI 깨짐 | 낮음 | 중간 | 기본값 패턴으로 하위 호환 유지 | +| 캐시 무효화 누락 | 낮음 | 높음 | TenantAwareCache 이미 검증됨 | +| 다국어 번역 리소스 부족 | 중간 | 낮음 | 한국어 기본값 유지, 점진 추가 | + +--- + +## 관련 문서 + +| 문서 | 설명 | +|------|------| +| `architecture/[REF-2025-11-19] multi-tenancy-implementation.md` | 이전 멀티테넌시 구현 (Phase 1-2 → 완료됨) | +| `architecture/[TEST-2025-11-19] multi-tenancy-test-guide.md` | 캐시 격리 테스트 가이드 | +| `architecture/[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | masterDataStore 캐시 테넌트 격리 수정 | +| `[IMPL-2026-02-05] formatter-commonization-plan.md` | 포매터 공통화 계획 (Phase 3과 병합) | +| `[ANALYSIS-2026-01-20] 공통화-현황-분석.md` | 공통화 현황 분석 | +| `[ANALYSIS-2026-02-05] list-page-commonization-status.md` | 리스트 페이지 공통화 현황 | +| `auth/[IMPL-2025-11-07] jwt-cookie-authentication-final.md` | JWT 쿠키 인증 구현 | +| `api/[REF] api-requirements.md` | API 요구사항 | + +--- + +## 변경 이력 + +| 날짜 | 변경 내용 | +|------|-----------| +| 2026-02-06 | 초기 작성 - 전체 코드베이스 분석 기반 8 Phase 로드맵 | + +--- + +**다음 액션**: Phase 1 시작 전 백엔드 팀과 `X-Tenant-ID` 헤더 수신 방식 협의 diff --git a/claudedocs/architecture/[PLAN-2026-02-06] refactoring-roadmap.md b/claudedocs/architecture/[PLAN-2026-02-06] refactoring-roadmap.md new file mode 100644 index 00000000..b399dcd5 --- /dev/null +++ b/claudedocs/architecture/[PLAN-2026-02-06] refactoring-roadmap.md @@ -0,0 +1,389 @@ +# 리팩토링 로드맵 + +**작성일**: 2026-02-06 +**목적**: 전체 코드베이스 리팩토링 포인트 점검 및 실행 계획 +**상태**: 분석 완료, 실행 대기 + +--- + +## 현재 코드베이스 수치 (2026-02-06 기준) + +| 지표 | 수치 | 비고 | +|------|------|------| +| 전체 코드 | ~301,000줄 | TS/TSX | +| 컴포넌트 파일 | ~551개 | | +| 페이지 파일 | ~253개 | | +| action.ts 파일 | 80개 | 거의 동일 CRUD 패턴 | +| types.ts 파일 | 94개 | 중복 타입 다수 | +| 모달 컴포넌트 | 42개 | 유사 패턴 반복 | +| 2000줄+ 파일 | 4개 | God 컴포넌트 | +| 1000~2000줄 파일 | 25+개 | 분리 대상 | +| 500~1000줄 파일 | 50+개 | 검토 대상 | + +--- + +## God 컴포넌트 / 대형 파일 목록 + +### 🔴 2000줄 이상 (즉시 분리 필요) + +| 파일 | 줄수 | 핵심 문제 | 분리 방향 | +|------|------|-----------|-----------| +| `components/business/MainDashboard.tsx` | 2,651 | CEO/영업/생산/품질 대시보드 한 파일 | 역할별 섹션 컴포넌트 분리 | +| `contexts/ItemMasterContext.tsx` | 2,406 | useState 17개, useEffect 15개, 함수 50+개 | 도메인별 5개 Context 분리 | +| `lib/api/item-master.ts` | 2,232 | 모든 품목 API 한 파일 | 도메인별 API 모듈 분리 | +| `lib/api/dashboard/transformers.ts` | 1,576 | 전체 대시보드 변환 로직 | 섹션별 transformer 분리 | + +### 🟡 1000~2000줄 (우선 검토) + +| 파일 | 줄수 | 도메인 | 분리 방향 | +|------|------|--------|-----------| +| `components/orders/actions.ts` | 1,394 | 수주 | 서비스 레이어 분리 | +| `components/accounting/ExpectedExpenseManagement/index.tsx` | 1,299 | 회계 | 서브 컴포넌트 추출 | +| `layouts/AuthenticatedLayout.tsx` | 1,289 | 레이아웃 | 훅 24개 → 섹션별 분리 | +| `components/quotes/QuoteRegistration.tsx` | 1,268 | 견적 | 폼 섹션 추출, useState 13개 | +| `components/quotes/actions.ts` | 1,266 | 견적 | API 레이어 분리 | +| `components/business/construction/management/actions.ts` | 1,222 | 건설 | 도메인 서비스 추출 | +| `components/business/construction/estimates/actions.ts` | 1,222 | 건설 | 도메인 서비스 추출 | +| `components/production/WorkerScreen/index.tsx` | 1,198 | 생산 | 화면 섹션 분리 | +| `hooks/useCEODashboard.ts` | 1,172 | 대시보드 | useState 18개 → 섹션별 훅 분리 | +| `components/material/ReceivingManagement/actions.ts` | 1,152 | 자재 | API 서비스 레이어 | +| `components/quotes/types.ts` | 1,149 | 견적 | 타입 조직화 | +| `components/quality/InspectionManagement/InspectionDetail.tsx` | 1,125 | 품질 | 컴포넌트 추출 | +| `components/hr/VacationManagement/actions.ts` | 1,125 | HR | 서비스 레이어 분리 | +| `components/orders/OrderRegistration.tsx` | 1,123 | 수주 | 폼 섹션 추출, useState 12개 | +| `components/items/DynamicItemForm/index.tsx` | 1,073 | 품목 | 복합 폼 로직 추출 | +| `components/templates/IntegratedListTemplateV2.tsx` | 1,066 | 템플릿 | 템플릿 특화 | +| `components/hr/EmployeeManagement/EmployeeForm.tsx` | 1,051 | HR | 폼 섹션 분리 | +| `components/quotes/QuoteRegistrationV2.tsx` | 1,020 | 견적 | 폼 리팩토링 | +| `components/templates/UniversalListPage/index.tsx` | 1,007 | 템플릿 | 템플릿 최적화 | +| `components/items/ItemMasterDataManagement.tsx` | 1,005 | 품목 | 도메인 로직 추출 | + +--- + +## 중복 패턴 분석 + +### 1. 액션 파일 80개 동일 패턴 (~24,000줄 중복) + +**현재**: 모든 도메인이 이 구조를 복붙 +```typescript +'use server'; +import { serverFetch } from '@/lib/api/fetch-wrapper'; + +interface Api[Domain]Data { ... } // 타입 정의 100~300줄 +function transform(data) { ... } // API→프론트 변환 50~100줄 + +export async function getList(params) { // 목록 조회 + const url = `${API_URL}/api/v1/endpoint`; + const { response } = await serverFetch(url, { method: 'GET' }); + return transform(response); +} +export async function getById(id) { ... } // 상세 조회 +export async function create(data) { ... } // 생성 +export async function update(id, data) { ... } // 수정 +export async function delete(id) { ... } // 삭제 +export async function bulkDelete(ids) { ... } // 일괄 삭제 +``` + +**해당 도메인**: orders, quotes, clients, accounting(13모듈), hr(6모듈), production(4모듈), material(2모듈), quality(2모듈), construction(17모듈), settings(14모듈) + +**해결 방향**: 제네릭 API 서비스 팩토리 +```typescript +// lib/api/createCrudService.ts +function createCrudService(config: { + endpoint: string; + transform: (api: TApi) => TFront; + reverseTransform: (front: TFront) => Partial; +}) { + return { + getList: async (params) => { ... }, + getById: async (id) => { ... }, + create: async (data) => { ... }, + update: async (id, data) => { ... }, + delete: async (id) => { ... }, + bulkDelete: async (ids) => { ... }, + }; +} + +// 사용: 10줄로 끝 +const orderService = createCrudService({ + endpoint: 'orders', + transform: transformOrder, + reverseTransform: reverseTransformOrder, +}); +``` + +### 2. 데이터 페칭 패턴 3가지 혼재 + +| 패턴 | 사용 비율 | 위치 | +|------|-----------|------| +| useEffect + .then() 직접 호출 | ~75% (99+ 컴포넌트) | 대부분의 도메인 | +| 커스텀 훅 (useDetailData 등) | ~15% (~15 컴포넌트) | 신규 구현 | +| ApiClient 클래스 | ~10% (15 컴포넌트) | 건설 도메인만 | + +**수동 로딩 상태 관리**: 262곳에서 반복 +```typescript +// 이 패턴이 262번 반복됨 +const [data, setData] = useState([]); +const [isLoading, setIsLoading] = useState(true); +const [error, setError] = useState(null); + +useEffect(() => { + setIsLoading(true); + fetchData() + .then(result => setData(result)) + .catch(err => setError(err)) + .finally(() => setIsLoading(false)); +}, []); +``` + +### 3. 폼 검증 3가지 방식 혼재 + +| 방식 | 사용 파일 수 | 비율 | +|------|-------------|------| +| Zod 스키마 (정석) | 3개 (로그인, 회원가입, 품목) | 5% | +| 수동 if문 검증 | 50+개 | 60% | +| 검증 없음 | ~30개 | 35% | + +### 4. 리스트 페이지 템플릿 이중화 + +| 방식 | 사용 | 비율 | +|------|------|------| +| `UniversalListPage` (신규 표준) | 20개 페이지 | 25% | +| 수동 구현 (레거시) | 60+ 페이지 | 75% | + +### 5. 모달/다이얼로그 42개 유사 패턴 + +**검색/선택 모달 5개+ 거의 동일**: +- `quotes/ItemSearchModal.tsx` +- `production/WorkOrders/AssigneeSelectModal.tsx` +- `material/ReceivingManagement/SupplierSearchModal.tsx` +- `quality/InspectionManagement/OrderSelectModal.tsx` +- `production/WorkOrders/SalesOrderSelectModal.tsx` + +전부 "검색 입력 → API 호출 → 목록 표시 → 체크박스 선택 → 확인" 동일 구조 +→ `SearchableSelectionModal` 하나로 통합 가능 + +--- + +## 성능 최적화 포인트 + +| 항목 | 현재 상태 | 영향도 | 해결 방향 | +|------|-----------|--------|-----------| +| React.memo | 551개 컴포넌트 중 **1개만** 사용 | 🔴 높음 | 리스트 아이템/카드 컴포넌트에 적용 | +| 인라인 화살표 함수 | **746곳** `onClick={() => ...}` | 🟡 중간 | 대형 컴포넌트에서 useCallback 적용 | +| useMemo 미사용 | 대용량 배열 필터링/정렬 곳곳 | 🟡 중간 | 비용 높은 계산에 적용 | + +**React.memo 우선 적용 대상** (리스트 내 반복 렌더링 컴포넌트): +- `production/WorkerScreen/WorkItemCard.tsx` +- `board/CommentSection/CommentItem.tsx` +- `business/construction/management/ProjectCard.tsx` +- 기타 *Row, *Item, *Card 컴포넌트 30+개 + +--- + +## 타입 시스템 문제 + +| 항목 | 수치 | 영향 | +|------|------|------| +| `any` 타입 사용 | 102곳 (29개 파일) | 타입 안전성 저하 | +| 동일 엔티티 다중 타입 정의 | Vendor, Item, Order 등 | 변환 코드 ~800줄 중복 | +| types.ts 파일 | 94개 | 정규 타입 찾기 어려움 | +| @ts-ignore/eslint-disable | 25개 파일 | 숨겨진 타입 에러 | + +--- + +## 추출 가능한 공통 훅 목록 + +### 즉시 생성 가능 (프론트 단독) + +| 훅 이름 | 대체 범위 | 예상 절감 | 기존 참고 | +|---------|-----------|-----------|-----------| +| `useListData` | 60+ 리스트 페이지 | ~4,000줄 | hooks/useDetailData.ts 패턴 확장 | +| `useFormSubmit` | 80+ 폼 | ~3,000줄 | 신규 | +| `usePagination` | 60+ 컴포넌트 | ~1,000줄 | 신규 | +| `useModal` | 42 모달 | ~500줄 | 신규 | +| `useClientSideFiltering` | 55+ 컴포넌트 | ~800줄 | 신규 | + +### 기존 훅 (활용 확대 필요) + +| 훅 | 현재 사용 | 전체 적용 시 | +|----|-----------|-------------| +| `useDetailData` | ~15 컴포넌트 | 100+ 상세 페이지 | +| `useDetailPageState` | ~10 컴포넌트 | 100+ 상세 페이지 | +| `useCRUDHandlers` | ~10 컴포넌트 | 80+ CRUD 페이지 | + +--- + +## 실행 계획 + +### Phase 1: 공통 훅 추출 (1-2주) `프론트 단독` `ROI 최고` + +> 새 훅 생성 + 고빈도 페이지 20개 우선 적용 + +**작업 항목**: +``` +- [ ] useListData 훅 생성 (페칭 + 페이지네이션 + 필터 통합) +- [ ] useFormSubmit 훅 생성 (제출 + 로딩 + 에러 + 토스트) +- [ ] usePagination 훅 생성 +- [ ] useModal 훅 생성 +- [ ] 고빈도 리스트 페이지 10개 마이그레이션 + - vendors, clients, items, orders, quotes + - production, quality, material, hr, accounting 각 1개 +- [ ] 고빈도 폼 페이지 10개 마이그레이션 + - 위 도메인의 등록/수정 폼 각 1개 +``` + +**예상 효과**: ~8,500줄 절감, 패턴 일관성 +60% + +--- + +### Phase 2: God 컴포넌트 분리 (2-3주) `프론트 단독` + +> 2000줄+ 파일 4개 + 핵심 1000줄+ 파일 우선 분리 + +**작업 항목**: +``` +- [ ] MainDashboard.tsx (2,651줄) 분리 + → sections/CEOSection, SalesSection, ProductionSection, QualitySection + → hooks/useDashboardData + → utils/calculations +- [ ] ItemMasterContext.tsx (2,406줄) 분리 + → ItemContext, SpecificationContext, MaterialContext + → TemplateContext, AttributeContext +- [ ] useCEODashboard.ts (1,172줄) 분리 + → useDailyReport, useReceivables, useMonthlyExpense 등 개별 훅 + → 훅 팩토리 패턴 적용 +- [ ] lib/api/item-master.ts (2,232줄) 분리 + → 도메인별 API 모듈 (items, specifications, materials, templates) +- [ ] AuthenticatedLayout.tsx (1,289줄) + → useLayoutState, useNavigation, useTenantBranding 훅 추출 +``` + +**예상 효과**: 유지보수성 +50%, 단위 테스트 가능성 확보 + +--- + +### Phase 3: 액션 파일 제네릭화 (2-3주) `프론트 단독` `최대 코드 감소` + +> CRUD 서비스 팩토리 생성 + 80개 actions.ts 점진적 마이그레이션 + +**작업 항목**: +``` +- [ ] createCrudService 팩토리 함수 구현 + - getList, getById, create, update, delete, bulkDelete + - transform / reverseTransform 자동 적용 + - 에러 핸들링 표준화 +- [ ] 공통 transform 유틸리티 (lib/transformers/) + - API snake_case → 프론트 camelCase 자동 변환 + - 날짜 문자열 파싱 공통화 +- [ ] 고빈도 도메인 마이그레이션 (10개) + - orders, quotes, clients, vendors + - production, quality, material + - hr/employee, hr/vacation, accounting +- [ ] 나머지 70개 점진적 마이그레이션 +``` + +**예상 효과**: ~24,000줄 → ~8,000줄 (67% 감소) + +--- + +### Phase 4: 템플릿/패턴 통일 (2-3주) `프론트 단독` + +> UniversalListPage 확대 + 검증 표준화 + 모달 통합 + +**작업 항목**: +``` +- [ ] UniversalListPage 기능 보강 + - 고급 필터 UI + - 컬럼 커스터마이징 + - 내보내기 기능 +- [ ] 레거시 리스트 페이지 → UniversalListPage 마이그레이션 (우선 20개) +- [ ] SearchableSelectionModal 공통 컴포넌트 생성 + - ItemSearchModal, AssigneeSelectModal 등 5개 통합 +- [ ] Zod 검증 스키마 라이브러리 구축 + - lib/validations/common.ts (이메일, 전화, 사업자번호) + - lib/validations/vendor.ts, order.ts, item.ts 등 +- [ ] 수동 검증 50+ 폼 → Zod 마이그레이션 (우선 10개) +``` + +**예상 효과**: ~5,000줄 절감, UX 일관성 +80% + +--- + +### Phase 5: 성능 + 타입 정리 (1-2주) `프론트 단독` + +> React.memo 적용 + any 제거 + 타입 통합 + +**작업 항목**: +``` +- [ ] React.memo 적용 (리스트 아이템 컴포넌트 30+개) + - WorkItemCard, CommentItem, ProjectCard 등 + - *Row, *Item, *Card 패턴 전수 조사 +- [ ] 대형 컴포넌트 useCallback 적용 + - MainDashboard, WorkerScreen, DynamicItemForm +- [ ] any 타입 제거 (102곳) + - Phase 1: types/ 파일 (4개) + - Phase 2: action error handler (50+ 파일) + - Phase 3: 컴포넌트 props (20개) +- [ ] 공통 타입 라이브러리 정리 + - types/shared/ 폴더 생성 + - ApiResponse, PaginatedResponse, FormState 등 + - 엔티티별 정규 타입 단일화 +- [ ] @ts-ignore / eslint-disable 제거 (25개 파일) +``` + +**예상 효과**: 리스트 렌더링 30-50% 개선, 타입 안전성 +60% + +--- + +## 전체 예상 효과 요약 + +| 지표 | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | 합계 | +|------|---------|---------|---------|---------|---------|------| +| 코드 절감 | ~8,500줄 | (구조 개선) | ~16,000줄 | ~5,000줄 | (품질 개선) | **~29,500줄** | +| 패턴 일관성 | +60% | +50% | +40% | +80% | +60% | 종합 개선 | +| 유지보수성 | 높음 | 매우 높음 | 높음 | 중간 | 중간 | 종합 개선 | +| 위험도 | 낮음 | 중간 | 중간 | 낮음 | 낮음 | - | + +--- + +## 병렬 진행 가능 조합 + +``` +[독립 진행 가능] +├─ Phase 1 (공통 훅) ──→ 즉시 시작 +├─ Phase 5 (성능/타입) ─→ 즉시 시작 (Phase 1과 병렬) +│ +[Phase 1 완료 후] +├─ Phase 2 (God 컴포넌트 분리) ──→ 훅 활용하여 분리 +├─ Phase 3 (액션 제네릭화) ────→ 독립 진행 가능 +│ +[Phase 1+3 완료 후] +└─ Phase 4 (템플릿 통일) ─────→ 훅 + 서비스 활용 +``` + +--- + +## 관련 문서 + +| 문서 | 설명 | +|------|------| +| `[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md` | 멀티테넌시 공통화 로드맵 (별도 트랙) | +| `[ANALYSIS-2026-01-20] 공통화-현황-분석.md` | 공통화 현황 분석 | +| `[ANALYSIS-2026-02-05] list-page-commonization-status.md` | 리스트 페이지 공통화 현황 | +| `[IMPL-2026-02-05] detail-hooks-migration-plan.md` | 상세 페이지 훅 마이그레이션 계획 | +| `[IMPL-2026-02-05] formatter-commonization-plan.md` | 포매터 공통화 계획 | +| `[PLAN-2026-01-22] ui-component-abstraction.md` | UI 컴포넌트 추상화 계획 | +| `guides/[PLAN-2025-12-23] common-component-extraction-plan.md` | 공통 컴포넌트 추출 계획 | + +--- + +## 변경 이력 + +| 날짜 | 변경 내용 | +|------|-----------| +| 2026-02-06 | 초기 작성 - 전체 코드베이스 분석 기반 5 Phase 로드맵 | + +--- + +**모든 Phase 프론트 단독 가능** - 백엔드 의존성 없음 diff --git a/src/components/quotes/actions.ts b/src/components/quotes/actions.ts index 000f1964..e73672b7 100644 --- a/src/components/quotes/actions.ts +++ b/src/components/quotes/actions.ts @@ -30,6 +30,7 @@ import type { QuoteStatus, ProductCategory, BomCalculationResultItem, + BomCalculationResult, } from './types'; import { transformApiToFrontend, transformFrontendToApi } from './types'; @@ -901,36 +902,8 @@ export interface BomCalculateItem { inspectionFee?: number; } -export interface BomCalculationResult { - success?: boolean; - finished_goods: { - code: string; - name: string; - item_category?: string; - }; - variables?: Record; - items: Array<{ - item_code: string; - item_name: string; - item_category?: string; - specification?: string; - unit?: string; - quantity: number; - quantity_formula?: string; - base_price?: number; - multiplier?: number; - unit_price: number; - total_price: number; - calculation_note?: string; - category_group?: string; - process_group?: string; - process_group_key?: string; - }>; - grouped_items?: Record; - subtotals: Record; - grand_total: number; - debug_steps?: Array<{ step: number; name: string; data: Record }>; // 10단계 계산 과정 -} +// BomCalculationResult는 types.ts에서 import하고 re-export +export type { BomCalculationResult } from './types'; // API 서버 응답 구조 (QuoteCalculationService::calculateBomBulk) export interface BomBulkResponse { diff --git a/src/components/quotes/types.ts b/src/components/quotes/types.ts index 5ea304ce..6abcd537 100644 --- a/src/components/quotes/types.ts +++ b/src/components/quotes/types.ts @@ -411,11 +411,17 @@ export interface BomMaterial { export interface BomCalculationResultItem { item_code: string; item_name: string; + item_category?: string; // 품목 카테고리 specification?: string; unit?: string; - quantity: number; // 1개당 BOM 수량 (base_quantity) + quantity: number; // 1개당 BOM 수량 (base_quantity) + quantity_formula?: string; // 수량 계산 공식 + base_price?: number; // 기본 단가 + multiplier?: number; // 승수 unit_price: number; total_price: number; + calculation_note?: string; // 계산 메모 + category_group?: string; // 카테고리 그룹 process_group?: string; process_group_key?: string; // Legacy 공정 그룹 키 category_code?: string; // 아이템 카테고리 코드 (동적 카테고리 시스템) @@ -431,6 +437,7 @@ export interface BomDebugStep { // BOM 계산 결과 타입 export interface BomCalculationResult { + success?: boolean; // API 응답 시 성공 여부 finished_goods: { code: string; name: string;