# MNG → API+React 이관 현황 및 로드맵

> **작성일**: 2026-03-12
> **상태**: 분석 완료, 로드맵 수립
> **담당**: R&D실

---

## 1. 개요

### 1.1 목적

MNG(관리자 웹)에서 API+React로 이관할 남은 항목을 식별하고, 멀티테넌시 적합도를 기준으로 실전 서비스 개발 우선순위를 수립한다.

### 1.2 현재 규모

| 프로젝트 | 규모 |
|----------|------|
| **MNG** | 컨트롤러 212개, 모델 227개, 서비스 113개 |
| **API** | 컨트롤러 100+, 모델 120+, 마이그레이션 130+ |
| **React** | 페이지 253개, 컴포넌트 36개 도메인 |

### 1.3 멀티테넌시 판단 기준

| 기준 | 이관 대상 | 이관 불필요 |
|------|----------|-----------|
| 2개+ 테넌트가 사용하는가? | 재무, 영업, 인사, 견적 | PMIS(특정 테넌트 전용) |
| `tenant_id` 격리가 의미 있는가? | 자금일정, 채번규칙, 수수료 | 신용평가, 개발도구 |
| SaaS 고객에게 제공 가치가 있는가? | 전자서명, 정산, VAT | 로드맵, R&D, 스크럼 |
| 관리자만 사용하는가? | 사용자도 씀 → 이관 | Dev Tools, 감사 추적 |

---

## 2. 이관 완료 도메인

API + React 모두 구현 완료된 기능이다.

| 도메인 | 완성도 | 비고 |
|--------|:------:|------|
| 인증/계정 | 100% | 로그인, 토큰, 회원가입 |
| 사용자/테넌트/부서 | 100% | 조직 관리 전체 |
| 역할/권한 | 100% | 3단계 권한 체계 |
| 메뉴 관리 | 100% | 글로벌/테넌트 메뉴 |
| 품목 관리 (Item) | 95% | BOM, 동적 필드 |
| 카테고리/공통코드 | 100% | 트리 구조, 동기화 |
| 거래처 (Client) | 95% | 그룹, OCR |
| 견적/수주/매출 | 90% | 견적서 PDF, 발송 |
| 입찰 (Bidding) | 90% | 상태 관리 |
| 단가 관리 (Pricing) | 90% | 일괄 등록 |
| 카드/계좌/입출금 | 90% | 바로빌 부분 연동 |
| 급여 (Payroll) | 85% | 계산, 확정, 지급 |
| 채권/거래처원장 | 85% | 조회, 메모 |
| 세금계산서 | 85% | 발행, 홈택스 |
| 근태/휴가/직원 | 85% | 출퇴근, 연차 |
| 전자결재 | 80% | 양식, 결재선, 위임 |
| 게시판 | 80% | 커스텀 필드, 댓글 |
| 파일/문서 관리 | 80% | 업로드, 공유, 버전 |
| 생산 (공정/작업지시) | 80% | 작업일지, 자재 투입 |
| 재고 (구매/입고/출하) | 80% | 배차, Lot 추적 |
| 설계/BOM | 75% | 모델 버전, 계산 엔진 |
| 대시보드 | 90% | CEO 포함 5가지 타입 |
| 현장관리 (Site) | 75% | 현장설명회, 계약 |
| 바로빌 (기본) | 70% | 카드/계좌 연동 |

---

## 3. 미이관 항목 분석

### 3.1 멀티테넌트 이관 대상 (P1~P2)

실전 서비스에서 복수 테넌트가 사용할 핵심 기능이다.

| # | 기능 | MNG 컨트롤러 | 적합도 | 우선순위 |
|---|------|-------------|:------:|:--------:|
| 1 | 자금일정 (Fund Schedule) | `FundScheduleController` | 높음 | P1 |
| 2 | 일일자금 (Daily Fund) | `DailyFundController` | 높음 | P1 |
| 3 | 미지급금 (Payable) | `PayableController` | 높음 | P1 |
| 4 | 부가세 (VAT) | `VatRecordController` | 높음 | P1 |
| 5 | 정산 (Settlement) | `SettlementController` | 높음 | P1 |
| 6 | 환불 (Refund) | `RefundController` | 높음 | P1 |
| 7 | 채번규칙 (Numbering Rule) | `NumberingRuleController` | 높음 | P1 |
| 8 | 견적수식 (Quote Formula) | `QuoteFormulaController` | 높음 | P1 |
| 9 | 전자서명 (eSign) | `EsignController` 외 2개 | 높음 | P1 |
| 10 | 분개기록 (Journal Entry) | `JournalEntryController` | 중간 | P2 |
| 11 | 구독관리 (Subscription) | `SubscriptionController` | 중간 | P2 |
| 12 | 판매수수료 | `SalesCommissionController` | 중간 | P2 |
| 13 | 휴가정책 (Leave Promotion) | `LeavePromotionController` | 중간 | P2 |
| 14 | 통합근태 | `AttendanceIntegratedController` | 중간 | P2 |
| 15 | 사업소득자 | `BusinessIncomeEarnerController` | 중간 | P2 |

> **참고**: API에 `ExpectedExpense`(미지급비용), `GeneralJournalEntry`(일반전표)가 이미 존재한다. MNG 버전과 기능 범위가 다르므로 비교 후 보강한다.

### 3.2 MNG 전용 (이관 불필요)

관리자 전용이거나 특정 테넌트에 국한되어 멀티테넌트 이관 가치가 낮은 기능이다.

| # | 기능 | MNG 컨트롤러 수 | 사유 |
|---|------|:--------------:|------|
| 1 | PMIS 시공관리 | 12개 | 특정 테넌트 건설 전용, `Juil/` 네임스페이스 |
| 2 | 신용평가 (Credit) | 1개 | 외부 API 연동, 관리자 전용 |
| 3 | Dev Tools | 2개 | API Explorer, Flow Tester (개발자 전용) |
| 4 | 추가 기능 | 5개 | Kiosk, Notion, RAG, Docx, Pptx (유틸리티) |
| 5 | 튜토리얼 비디오 | 1개 | 관리자 콘텐츠 관리 |
| 6 | 로드맵/R&D | 2개 | 내부 기획 도구 |
| 7 | 일일 스크럼 | 1개 | 내부 개발팀 도구 |
| 8 | 감사 로그/트리거 추적 | 3개 | 관리자 감사 도구 (API 읽기전용 API만 검토) |

**후순위** (규모별 차이가 커서 범용성 낮음):

| # | 기능 | 비고 |
|---|------|------|
| 9 | 경조사비/회사차량/차량일지 | 회사 규모별 차이 큼 |
| 10 | 명함 요청 | 마이너 기능 |
| 11 | 면접 시나리오 | 영업 내부 도구 |

### 3.3 React UI 보강 대상

API는 완료되었으나 React 화면이 미구현 또는 부분 구현된 기능이다.

| # | 기능 | API | React | 우선순위 |
|---|------|:---:|:-----:|:--------:|
| 1 | 품질관리 (QMS) | 완료 | 개발중 | P1 |
| 2 | 설비/장비 (Equipment) | 완료 | 개발중 | P1 |
| 3 | 어음 관리 (Bill) | 완료 | 미구현 | P2 |
| 4 | 가지급금 (Loan) | 완료 | 미구현 | P2 |
| 5 | 요금제/결제 | 완료 | 부분 | P1 |
| 6 | 캘린더 일정 | 완료 | 부분 | P2 |
| 7 | AI 보고서 | 완료 | 부분 | P2 |
| 8 | 팝업 관리 | 완료 | 부분 | P3 |

---

## 4. 실전 서비스 이관 로드맵

### Phase 1: 핵심 재무 (즉시 착수)

테넌트가 실제 업무에 필수적으로 사용하는 재무 기능이다.

| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 1-1 | 자금일정 + 일일자금 | API 신규 + React 신규 | 높음 |
| 1-2 | 정산 (Settlement) | API 신규 + React 신규 | 높음 |
| 1-3 | 환불 (Refund) | API 신규 + React 신규 | 중간 |
| 1-4 | 부가세 (VAT) | API 신규 + React 신규 | 높음 |
| 1-5 | 채번규칙 | API 신규 + React 설정화면 | 중간 |

### Phase 2: 영업/견적 고도화

견적 자동화와 수수료 체계를 구축한다.

| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 2-1 | 견적수식 (Quote Formula) | API 신규 + React 신규 | 매우 높음 |
| 2-2 | 판매수수료 | API 신규 + React 신규 | 높음 |
| 2-3 | 전자서명 (eSign) | API 신규 + React 신규 | 매우 높음 |

### Phase 3: React UI 보강

API는 완료되어 있으므로 React 화면만 구현한다.

| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 3-1 | 품질관리 (QMS) | React 신규 | 높음 |
| 3-2 | 설비/장비 | React 신규 | 중간 |
| 3-3 | 어음/가지급금 | React 신규 | 중간 |
| 3-4 | 요금제/결제 화면 | React 보강 | 중간 |

### Phase 4: 인사 고도화

기본 HR은 완료되어 있으며, 정책/통합 기능을 추가한다.

| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 4-1 | 휴가정책 자동부여 | API 보강 + React | 중간 |
| 4-2 | 통합근태 | API 신규 + React | 높음 |
| 4-3 | 사업소득자/지급 | API 신규 + React | 중간 |

---

## 5. 이관 작업 시 공통 체크리스트

### API 이관 시

- [ ] `tenant_id` 기반 멀티테넌트 격리 적용
- [ ] MNG HTMX 코드 → REST API로 분리
- [ ] 마이그레이션 소유 기준 확인 (API 전용/공용 → API, MNG 전용 → MNG)
- [ ] `options` JSON 컬럼 정책 준수
- [ ] Service-First 아키텍처 (Controller → Service → Model)
- [ ] FormRequest 검증 적용
- [ ] Swagger 문서 작성

### React 이관 시

- [ ] Server Actions 패턴 사용 (`executePaginatedAction`, `executeServerAction`)
- [ ] `createCrudService` 팩토리 활용 (반복 코드 제거)
- [ ] Zod 스키마 검증 적용
- [ ] `FormField` molecule 사용
- [ ] 기존 `UniversalListPage` 템플릿 활용
- [ ] 모바일 반응형 고려 (`MobileCard`)

---

## 6. 수량 요약

| 분류 | 항목 수 | 비고 |
|------|:-------:|------|
| 이관 완료 | 24개 도메인 | API + React 모두 존재 |
| 이관 대상 (P1) | 9개 기능 | Phase 1~2 |
| 이관 대상 (P2) | 6개 기능 | Phase 2~4 |
| MNG 유지 | 11개 기능 | 관리자/특정 테넌트 전용 |
| React UI 보강 | 8개 기능 | API 완료, UI 미구현 |

---

## 관련 문서

- [system/overview.md](overview.md) — 전체 시스템 아키텍처
- [system/api-structure.md](api-structure.md) — API 서버 구조
- [system/react-structure.md](react-structure.md) — React 프론트엔드 구조
- [system/mng-structure.md](mng-structure.md) — MNG 관리자 패널 구조
- [dev/standards/api-rules.md](../dev/standards/api-rules.md) — API 개발 규칙
- [dev/standards/options-column-policy.md](../dev/standards/options-column-policy.md) — options JSON 정책

---

**최종 업데이트**: 2026-03-12