# [Master Plan] 프론트엔드 모노레포 통합 및 공용 모듈 마이그레이션

## 1. 개요 (Overview)
현재 `adminfront`, `devfront`, `orgfront` 세 개의 프론트엔드 프로젝트는 동일한 기술 스택을 사용함에도 불구하고 코드가 각자 복제되어 관리되고 있습니다. 이를 **NPM Workspaces 기반의 모노레포** 구조로 개편하여 중복을 제거하고, 기술적 일관성을 확보하는 것이 본 설계의 목적입니다.

---

## 2. 아키텍처 설계 (Architecture)

### 2.1. 디렉토리 구조
프로젝트 루트를 Workspace로 설정하고, 모든 앱과 공용 모듈을 `packages/` 하위로 통합 관리합니다.

```text
baron-sso/
├── package.json               # [New] 루트 레벨 Workspace 및 의존성 관리
├── packages/                  # 재사용 가능한 내부 패키지
│   ├── shared-ui/             # Shadcn UI, 제네릭 AppLayout, 브랜드 자산(로고/아이콘)
│   ├── shared-utils/          # apiClient 팩토리, i18n 엔진, 공용 로케일(사전 병합)
│   ├── shared-auth/           # OIDC 설정, AuthGuard 본체, 세션 관리(Sliding Session)
│   ├── shared-types/          # 도메인 모델 및 API TypeScript 타입
│   └── shared-config/         # Tailwind, Biome, TSConfig 공통 설정
├── adminfront/                # Feature 중심 유지 + Shared 패키지 참조
├── devfront/                  # App Shell 공유 + Shared 패키지 참조
└── orgfront/                  # App Shell 공유 + Shared 패키지 참조
```

### 2.2. 모노레포 도입의 이유 (Why Workspaces?)
1.  **깔끔한 임포트**: `../../common` 같은 상대 경로 대신 `@shared/ui`와 같은 패키지 이름으로 참조 가능.
2.  **의존성 단일화**: 모든 앱이 동일한 라이브러리 버전을 사용하여 런타임 에러 방지.
3.  **설정 자동화**: Vite와 TypeScript가 로컬 패키지를 자동으로 인식하여 HMR 및 타입 체킹 지원.

---

## 3. 핵심 기술 설계 (Technical Governance)

### 3.1. 의존성 관리 (Single Version Policy)
- `react`, `react-router-dom`, `tailwindcss`, `@tanstack/react-query` 등 핵심 라이브러리 버전을 루트 `package.json`에서 고정 관리합니다.
- 각 패키지는 필요한 경우에만 별도 의존성을 가지며, 가능한 루트 버전을 따릅니다.

### 3.2. i18n 및 에셋 전략
- **동적 병합(Dictionary Merge)**: 공용 문구(Shared)를 먼저 로드하고, 앱별 특화 문구를 그 위에 덮어쓰는(Merge) 로직을 `shared-utils`에서 제공합니다.
- **자산 중앙화**: 브랜드 로고, 파비콘 등 공통 정적 자산은 `shared-ui/assets`에서 관리합니다.

### 3.3. 제네릭 AppLayout 엔진
- `AppLayout.tsx`는 더 이상 하드코딩된 메뉴를 갖지 않습니다.
- 메뉴(`navItems`), 브랜드 로고, 역할 스위처 표시 여부 등을 **설정 객체(Config)**로 주입받아 렌더링하는 범용 엔진으로 리팩토링합니다.

---

## 4. 실행 로드맵 (Execution Roadmap)

### **[1단계] 인프라 구축 (Infrastructure)**
- 루트 `package.json` Workspace 설정.
- `shared-config` 패키지 생성 및 Tailwind/Biome 설정 중앙화.
- 각 앱에서 `@shared/config`를 참조하도록 설정 변경.

### **[2단계] 기초 모듈 추출 (Base Migration)**
- 중복도가 가장 높은 `components/ui/*`를 `shared-ui`로 이동.
- `apiClient`, `i18n`, `utils` 등 순수 유틸리티 코드를 `shared-utils`로 이동.
- 각 앱의 임포트 경로를 `@shared/*`로 일괄 치환.

### **[3단계] 플랫폼 레이어 통합 (Platform)**
- `AppLayout.tsx`를 제네릭하게 리팩토링하여 `shared-ui`로 이동.
- `AuthGuard`, `LoginPage`, `sessionSliding` 등 인증 관련 핵심 로직을 `shared-auth`로 통합.

### **[4단계] 앱별 적용 및 최적화 (Optimization)**
- `devfront`와 `orgfront`를 우선적으로 공용 레이아웃 기반으로 전환.
- `adminfront`는 비즈니스 로직(Feature)은 유지하되 기반 레이어만 교체.
- 빌드 테스트 및 트리쉐이킹(번들 최적화) 확인.

---

## 5. 기대 효과 (Expected Benefits)
- **관리 비용 절감**: 공통 UI 수정 시 3개 앱에 동시 반영.
- **개발 가속화**: 신규 프론트엔드 프로젝트 시작 시 인프라 세팅 시간 단축.
- **기술적 일관성**: 모든 프론트엔드가 동일한 기술 표준과 디자인 시스템을 공유.